API documentation¶

Here, we document the main classes and methods in cvxstoc.

NormalRandomVariable(mean, cov, shape=1)

• Creates one (or more) normal random variable(s).

• Parameters:

  • mean: either a scalar or a NumPy ndarray describing the mean of the random variable(s).
  • cov: either a scalar or a NumPy ndarray describing the covariance (matrix) of the random variable(s). If mean is a scalar, then cov should be a scalar. If mean is a vector, then cov should be a positive definite matrix with number of rows/columns matching the dimension of mean.
  • shape (optional): a tuple. If specified (as a tuple), then mean and cov should be scalars, and shape determines the shape of the returned object comprising i.i.d. normal random variables.

• Returns:

  • one (or more) cvxstoc RandomVariable object(s) (cvxstoc’s RandomVariable object inherits from cvxpy’s Parameter object).

CategoricalRandomVariable(vals, probs, shape=1)

• Creates one (or more) categorical random variable(s).

• Parameters:

  • vals: a list of values.
  • probs: a list of probabilities (one for each value).
  • shape (optional): a tuple that determines the shape of the returned object comprising i.i.d. categorical random variables.

• Returns:

  • one (or more) cvxstoc RandomVariable object(s) (cvxstoc’s RandomVariable object inherits from cvxpy’s Parameter object).

UniformRandomVariable(lower, upper, cont=True, shape=1)

• Creates one (or more) uniform random variable(s).

• Parameters:

  • lower: the lower endpoint of the uniform distribution.
  • upper: the upper endpoint of the uniform distribution.
  • cont (optional): a Boolean. If True, then a continuous uniform distribution is used, else a discrete distribution is used.
  • shape (optional): a tuple that determines the shape of the returned object comprising i.i.d. uniform random variables.

• Returns:

  • one (or more) cvxstoc RandomVariable object(s) (cvxstoc’s RandomVariable object inherits from cvxpy’s Parameter object).

RandomVariable(rv, name=None)

• Creates a cvxstoc RandomVariable object.

• Parameters:

  • rv: a PyMC Model object.
  • name (optional): a string describing the (friendly) name of the returned object.

• Returns:

  • one (or more) cvxstoc RandomVariable object(s) (cvxstoc’s RandomVariable object inherits from cvxpy’s Parameter object).

expectation(expr, num_samples, num_burnin_samples=0)

• Constructs a Monte Carlo approximation to the expected value of expr.

• Parameters:

  • expr: a cvxpy Expression (usually) containing one (or more) cvxstoc RandomVariable object(s).
  • num_samples: the number of Monte Carlo samples to use when constructing the approximation.
  • num_burnin_samples (optional): the number of samples to use for burn-in (this is only useful if sampling from the distribution of expr requires Markov chain Monte Carlo methods).

• Returns:

  • a cvxpy Expression. Accessing the value property on this returned object actually instantiates the object with samples, and returns the (numerical) expected value.

prob(constr, num_samples)

• Constructs a (Monte Carlo) approximation to the chance constraint described by constr.

• Parameters:

  • constr: a cvxpy Constraint (usually) containing one (or more) cvxstoc RandomVariable object(s).
  • num_samples: the number of Monte Carlo samples to use when constructing the approximation.

• Returns:

  • when combined with an inequality, e.g., prob(constr=my_constr, num_samples=my_num_samples) <= my_prob: a cvxpy Constraint. Accessing the value property on this returned object actually instantiates the constraint with samples, and returns the fraction of times the constraint is satisfied.
  • when not combined with an inequality: a cvxstoc prob object (which is not so useful on its own).

partial_optimize(prob, opt_vars, dont_opt_vars)

• Creates a second stage (convex) optimization problem.

• Parameters:

  • prob: a cvxpy Problem object (usually) containing one (or more) cvxstoc RandomVariable object(s) describing the second stage (convex) optimization problem.
  • opt_vars: a list of second stage optimization cvxpy Variables.
  • dont_opt_vars: a list of first stage optimization cvxpy Variables.

• Returns:

  • a cvxstoc PartialProblem object (which inherits from cvxpy’s Expression object).