cvxRiskOpt package¶

Submodules¶

cvxRiskOpt.cclp_risk_opt module¶

Reformulates a DRO CC of the type \(\inf_{\mathbb{P} \in \mathcal{P}} \mathbb{P}(a^T \xi_1 + b + \xi_2 \leq 0) \geq 1-\epsilon\) where \(\mathcal{P}\) is a moment-based ambiguity set.

This function reformulates a distributionally robust optimization (DRO) chance constraint (CC) where the distribution is unknown but belongs to a moment based ambiguity set with known mean and covariance:

\[\begin{split}\begin{align*} \xi &= [\xi_1^T \xi_2]^T \\ \text{Expect}(\xi) &= [\hat{\xi_1}^T \hat{\xi_2}]^T \\ \text{Cov}(\xi) &= \begin{bmatrix} \text{gam11} & \text{gam12} \\ \text{gam12}^T & \text{gam22} \end{bmatrix} \end{align*}\end{split}\]

Arguments:¶

epsint | float:
The epsilon risk bound in the chance constraint.

aint | float | list | np.ndarray | cp.Variable | cp.Expression, optional:
The coefficient vector/scalar “a” in the chance constraint.

bint | float | cp.Variable | cp.Expression, optional:
The scalar term “b” in the chance constraint.

xi1_hatint | float | list | np.ndarray | cp.Variable | cp.Expression, optional:
The expected value of xi1.

xi2_hatint | float, optional:
The expected value of xi2.

gam11int | float | list | np.ndarray, optional:
The covariance matrix of xi1.

gam12int | float | list | np.ndarray, optional:
The cross-covariance matrix between xi1 and xi2.

gam22int | float, optional:
The covariance matrix of xi2.

assume_symbool, optional:
Whether to assume the covariance matrix is symmetric (otherwise, it is checked).

assume_psdbool, optional:
Whether to assume the covariance matrix is positive semi-definite (otherwise, it is checked).

centrally_symmetric: bool, optional:
Flag if distribution is centrally symmetric (Def 3.1 in “On Distributionally Robust Chance-Constrained Linear Programs”).

Returns:¶

cvxpy.Constraint or cp.Expression:
The reformulated deterministic chance constraint.

Reformulates a CC of the type \(\mathbb{P}(a^T \xi_1 + b + \xi_2 \leq 0) \geq 1-\epsilon\) where the distribution is Gaussian.

This function reformulates a chance constraint (CC) where the distribution is known to be a Gaussian distribution with:

\[\begin{split}\begin{align*} \xi &= [\xi_1^T \xi_2]^T \\ \text{Expect}(\xi) &= [\hat{\xi_1}^T \hat{\xi_2}]^T \\ \text{Cov}(\xi) &= \begin{bmatrix} \text{gam11} & \text{gam12} \\ \text{gam12}^T & \text{gam22} \end{bmatrix} \end{align*}\end{split}\]

Arguments:¶

epsint | float:
The epsilon risk bound in the chance constraint.

aint | float | list | np.ndarray | cp.Variable | cp.Expression, optional:
The coefficient vector/scalar “a” in the chance constraint.

bint | float | cp.Variable | cp.Expression, optional:
The scalar term “b” in the chance constraint.

xi1_hatint | float | list | np.ndarray | cp.Variable | cp.Expression, optional:
The expected value of xi1.

xi2_hatint | float, optional:
The expected value of xi2.

gam11int | float | list | np.ndarray, optional:
The covariance matrix of xi1.

gam12int | float | list | np.ndarray, optional:
The cross-covariance matrix between xi1 and xi2.

gam22int | float, optional:
The covariance matrix of xi2.

assume_symbool, optional:
Whether to assume the covariance matrix is symmetric (otherwise, it is checked).

assume_psdbool, optional:
Whether to assume the covariance matrix is positive semi-definite (otherwise, it is checked).

Returns:¶

cvxpy.Constraint or cp.Expression:
The reformulated deterministic chance constraint.

cvxRiskOpt.mpc_helpers module¶

cvxRiskOpt.mpc_helpers.cp_var_mat_to_list(mat: Variable | Parameter, horizon: int)[source]¶

Converts a 1D or 2D cp.Variable/Parameter matrix to a list of cp.Variable/Parameter vectors.

Some functions, such as lin_mpc_expect_xQx, require lists or arrays of variables/parameters over time as inputs. This function splits a variable/parameter into a list of variables/parameters. e.g.

(3, 4) matrix where the horizon is 4 –> turns into [(3,), (3,), (3,), (3,)].

(3,) of horizon 1 –> turns into [(3,)]

(4,) where 4 is horizon –> turns into [(), (), (), ()]

Arguments:¶

mat: cp.Variable | cp.Parameter:
(m, horizon), (horizon, m), (m,), or (horizon,) cp.Variable

horizon: int:
mat horizon, e.g. MPC horizon (to identify the “horizon” dimension in mat)

Returns:¶

list:
List of cp.Variables or cp.Parameters

Computes the expressions for the expected next state \(\mathbb{E}(x_{t})\) and its covariance \(\text{Cov}(x_t)\) for a linear system \(x_{t+1} = Ax_t + Bu_t + w_t\).

The expected value and covariance are found by recursively applying the dynamics stating from an initial state \(x_0\) whose mean \(\overline{x}_0\) and covariance \(\Sigma_{x_0}\) are known. The mean \(\overline{w}\) and covariance \(\Sigma_{w}\) of the noise must also be known. The terms are computed as follows:

\[\begin{split}\begin{align*} \mathbb{E}(x_{t}) &= A^{t} \overline{x}_0 + \sum_{i=0}^{t-1} (A^i B u_{t-1-i} + A^i \overline{w}_{t-1-i}) \\ \text{Cov}(x_{t}) &= A^{t} \Sigma_{x_0} {A^{t}}^T + \sum_{i=0}^{t-1} (A^i \Sigma_{w_{t-1-i}} {A^i}^T) \end{align*}\end{split}\]

Arguments:¶

t: int:
Current time step for x_t (t >= 1)

A: int | float | np.ndarray:
Dynamics matrix

B: int | float | np.ndarray:
Input matrix

x0_mean: cp.Variable | cp.Parameter | cp.Expression:
Mean state at t=0

x0_cov: np.ndarray:
Covariance of state at t=0

u: list:
List of control decision variables

w_mean: list:
List of noise mean value

w_cov: list:
List of noise covariance values

Returns:¶

cp.Expression:
Expected value expression of the state at time t (xt_mean)

cp.Expression:
Covariance expression of the state at time t (xt_cov)

Finds the expression for \(\mathbb{E}(x_t^T Q x_t)\), the weighted quadratic state cost at time \(t\).

Finds the expression for \(\mathbb{E}(x_t^T Q x_t)\) where \(x_t\) is a random variable (due to the noise) representing the state at timestep \(t\) in the MPC horizon and the dynamics are: \(x_{t+1} = Ax_t + Bu_t + w_t\).

Arguments:¶

t: int:
Control time step (starting from 0)

horizon: int:
MPC horizon length

A: int | float | np.ndarray:
Dynamics matrix

B: int | float | np.ndarray:
Input matrix

u: list | cp.Variable
List of control decision variables (or cp Variable)

Q: int | float | np.ndarray:
State cost matrix

x0_mean: cp.Parameter | cp.Variable | cp.Expression:
Mean state at \(t=0\)

x0_cov: np.ndarray, optional:
Covariance of state at \(t=0\). If not passed, assumed to be zero.

w_mean: list | np.ndarray, optional:
List of noise mean value (or single noise mean). If not passed, assumed to be zero.

w_cov: list | np.ndarray, optional:
List of noise covariance values (or single noise covar). If not passed, assumed to be zero.

Returns:¶

cp.Expression:
Expression for \(\mathbb{E}(x_t^T Q x_t)\)

dict:
dictionary containing the expressions for the mean and covariance of the state at time \(t\) (“x_mean”, “x_cov”)

cvxRiskOpt.wass_risk_opt_pb module¶

Bases: WassWCEMaxAffine

Provides a high-level implementation of the DR-CVaR with a Wasserstein-based ambiguity set.

Implements

\[\sup_{\mathbb{P} \in \mathcal{P}} \quad \text{CVaR}_{\alpha}^\mathbb{P}\left[ \langle a, \xi \rangle + b \right]\]

where \(a, b\) may contain decision variables and \(\langle \cdot, \cdot \rangle\) is the inner product. \(\alpha\) is the CVaR level (average in alpha * 100% of the worst/highest cases)

Alternatively, this can also implement the CVaR reformulated form as a max of two affine terms:

\[\sup_{\mathbb{P} \in \mathcal{P}} \quad \mathbb{E}^{\mathbb{P}} \max_{k \in \{1, 2\}} \left[ \langle a_k, \xi \rangle + b_k \right].\]

Note

Either “a” and “b” must be passed or “a_k_list” and “b_k_list”, but not both nor neither.

Arguments:¶

num_samples: int:
The number of samples.

xi_length: int:
Size of a sample. If \(\xi\) is m x 1 –> xi_length = m

a: int | float | cp.Variable | cp.Parameter | cp.Expression, optional:
The “a” term in \(\langle a, xi \rangle + b\). If this is passed, the “b” term is expected. This should not be passed if “a_k_list” and “b_k_list” are passed.

b: int | float | cp.Variable | cp.Parameter | cp.Expression, optional, optional:
The “b” term in \(\langle a, xi \rangle + b\). If not assigned, 0 is used. This should not be passed if “a_k_list” and “b_k_list” are passed.

a_k_list: Number | array_like, optional:
A list of vectors that are either constant vectors or scalars times a decision variable. If this is passed, the “b_k_list” term is expected. This should not be passed if “a” and “b” are passed.

b_k_list: array_like, optional:
A list of scalars or 1-dimensional cvxpy affine expressions. This should not be passed if “a” and “b” are passed.

alpha: float, optional:
CVaR level (average in alpha * 100% of the worst/highest cases)

support_C: np.ndarray, optional
The support matrix C. If None passed, the support is considered to be the real space.

support_d: np.ndarray, optional
The support vector d. If None passed, the support is considered to be the real space.

used_norm: int | np.inf, optional
The norm to be used. Either 1, 2, or infinity (np.inf). Default is 2.

vp_suffix: str, optional
The suffix for the variable/parameter names.

instance_counter = 0¶

Bases: WassWCEMaxAffine

Provides a high-level implementation of the DR Expectation with a Wasserstein-based ambiguity set.

Implements

\[\sup_{\mathbb{P} \in \mathcal{P}} \quad \mathbb{E}^\mathbb{P} \left[ \langle a, \xi \rangle + b \right]\]

where \(a, b\) may contain decision variables and \(\langle \cdot, \cdot \rangle\) is the inner product.

Arguments:¶

num_samples: int:
The number of samples.

a: int | float | cp.Variable | cp.Parameter | cp.Expression:
The “a” term in \(\langle a, xi \rangle + b\).

b: int | float | cp.Variable | cp.Parameter | cp.Expression, optional”
The “b” term in \(\langle a, xi \rangle + b\). If not assigned, 0 is used.

support_C: np.ndarray, optional
The support matrix C. If None passed, the support is considered to be the real space.

support_d: np.ndarray, optional
The support vector d. If None passed, the support is considered to be the real space.

used_norm: int | np.inf, optional
The norm to be used. Either 1, 2, or infinity (np.inf). Default is 2.

vp_suffix: str, optional
The suffix for the variable/parameter names.

instance_counter = 0¶

class cvxRiskOpt.wass_risk_opt_pb.WassWCEMaxAffine(num_samples: int, a_k_list: list, b_k_list: list | None = None, support_C=None, support_d=None, used_norm=2, vp_suffix: str | None = None)[source]¶

Bases: Problem

Wasserstein Worst Case Expectation Problem with Max of Affine Terms.

This class implements a generic solution for Cor 5.1 (i), eq (15a) with affine loss functions:

\[\ell = \max_k \{ \langle a_k, \xi \rangle + b_k \}\]

where

xi (m x 1): the random variable for which we have samples
a_k (m x 1): a vector that is either a constant vector or a scalar times a decision variable (cvxpy affine expression)
b_k (1 x 1): a scalar or a 1-dimensional cvxpy affine expression
\(\langle \cdot, \cdot \rangle\) is the inner product

Note

Currently, this is only implemented for the 1-, 2-, and inf-norm cases.

Arguments:¶

num_samples: int:
The number of samples.

a_k_list: Number | array_like
A list of vectors that are either constant vectors or scalars times a decision variable.

b_k_list: array_like
A list of scalars or 1-dimensional cvxpy affine expressions.

support_C: np.ndarray, optional
The support matrix C. If None passed, the support is considered to be the real space.

support_d: np.ndarray, optional
The support vector d. If None passed, the support is considered to be the real space.

used_norm: int | np.inf, optional
The norm to be used. Either 1, 2, or infinity (np.inf). Default is 2.

vp_suffix: str, optional
The suffix for the variable/parameter names.

instance_counter = 0¶

cvxRiskOpt.wass_risk_opt_pb.update_wass_wce_params(prob, eps, samples) → None[source]¶

Update the parameters associated with the WassWCEMaxAffine problem.

Arguments:¶

prob: WassWCEMaxAffine:
WassWCEMaxAffine problem

eps: int:
Wasserstein ball radius

samples: np.ndarray:
Data samples

cvxRiskOpt package¶

Submodules¶

cvxRiskOpt.cclp_risk_opt module¶

Arguments:¶

Returns:¶

Arguments:¶

Returns:¶

cvxRiskOpt.mpc_helpers module¶

Arguments:¶

Returns:¶

Arguments:¶

Returns:¶

Arguments:¶

Returns:¶

cvxRiskOpt.wass_risk_opt_pb module¶

Arguments:¶

Arguments:¶

Arguments:¶

Arguments:¶

Module contents¶

cvxRiskOpt

Navigation