Constraints¶
A constraint is an equality or inequality that restricts the domain of an optimization problem. CVXPY has seven types of constraints: non-positive, equality or zero, positive semidefinite, second-order cone, exponential cone, 3-dimensional power cones, and N-dimensional power cones. The vast majority of users will need only create constraints of the first three types. Additionally, most users need not know anything more about constraints other than how to create them. The constraint APIs do nonetheless provide methods that advanced users may find useful; for example, some of the APIs allow you to inspect dual variable values and residuals.
Constraint¶
-
class cvxpy.constraints.constraint.Constraint(args, constr_id=
None)[source]¶ Bases:
CanonicalThe base class for constraints.
A constraint is an equality, inequality, or more generally a generalized inequality that is imposed upon a mathematical expression or a list of thereof.
- Parameters:¶
-
value(tolerance: float =
1e-08)[source]¶ Checks whether the constraint violation is less than a tolerance.
- violation()[source]¶
The numeric residual of the constraint.
The violation is defined as the distance between the constrained expression’s value and its projection onto the domain of the constraint:
\[||\Pi(v) - v||_2^2\]where \(v\) is the value of the constrained expression and \(\Pi\) is the projection operator onto the constraint’s domain .
NonPos¶
-
class cvxpy.constraints.nonpos.NonPos(expr, constr_id=
None)[source]¶ Bases:
ConstraintAn inequality constraint of the form \(x \leq 0\).
The preferred way of creating an inequality constraint is through operator overloading. To constrain an expression
xto be nonpositive, writex <= 0; to constrainxto be nonnegative, writex >= 0.Dual variables associated with this constraint are nonnegative, rather than nonpositive. As such, dual variables to this constraint belong to the polar cone rather than the dual cone.
Note: strict inequalities are not supported, as they do not make sense in a numerical setting.
- Parameters:¶
- expr : Expression¶
The expression to constrain.
- constr_id : int¶
A unique id for the constraint.
- violation()[source]¶
The numeric residual of the constraint.
The violation is defined as the distance between the constrained expression’s value and its projection onto the domain of the constraint:
\[||\Pi(v) - v||_2^2\]where \(v\) is the value of the constrained expression and \(\Pi\) is the projection operator onto the constraint’s domain .
Zero¶
-
class cvxpy.constraints.zero.Zero(expr, constr_id=
None)[source]¶ Bases:
ConstraintA constraint of the form \(x = 0\).
The preferred way of creating a
Zeroconstraint is through operator overloading. To constrain an expressionxto be zero, simply writex == 0. The former creates aZeroconstraint withxas its argument.- violation()¶
The numeric residual of the constraint.
The violation is defined as the distance between the constrained expression’s value and its projection onto the domain of the constraint:
\[||\Pi(v) - v||_2^2\]where \(v\) is the value of the constrained expression and \(\Pi\) is the projection operator onto the constraint’s domain .
PSD¶
-
class cvxpy.constraints.psd.PSD(expr, constr_id=
None)[source]¶ Bases:
ConeA constraint of the form \(\frac{1}{2}(X + X^T) \succcurlyeq_{S_n^+} 0\)
Applying a
PSDconstraint to a two-dimensional expressionXconstrains its symmetric part to be positive semidefinite: i.e., it constrainsXto be such that\[z^T(X + X^T)z \geq 0,\]for all \(z\).
The preferred way of creating a
PSDconstraint is through operator overloading. To constrain an expressionXto be PSD, writeX >> 0; to constrain it to be negative semidefinite, writeX << 0. Strict definiteness constraints are not provided, as they do not make sense in a numerical setting.- Parameters:¶
-
is_dcp(dpp: bool =
False) bool[source]¶ A PSD constraint is DCP if the constrained expression is affine.
- violation()¶
The numeric residual of the constraint.
The violation is defined as the distance between the constrained expression’s value and its projection onto the domain of the constraint:
\[||\Pi(v) - v||_2^2\]where \(v\) is the value of the constrained expression and \(\Pi\) is the projection operator onto the constraint’s domain .
SOC¶
-
class cvxpy.constraints.second_order.SOC(t, X, axis: int =
0, constr_id=None)[source]¶ Bases:
ConeA second-order cone constraint for each row/column.
Assumes
tis a vector the same length asX’s columns (rows) foraxis == 0(1).- t¶
The scalar part of the second-order constraint.
- X¶
A matrix whose rows/columns are each a cone.
- axis¶
Slice by column 0 or row 1.
-
is_dcp(dpp: bool =
False) bool[source]¶ An SOC constraint is DCP if each of its arguments is affine.
- violation()¶
The numeric residual of the constraint.
The violation is defined as the distance between the constrained expression’s value and its projection onto the domain of the constraint:
\[||\Pi(v) - v||_2^2\]where \(v\) is the value of the constrained expression and \(\Pi\) is the projection operator onto the constraint’s domain .
ExpCone¶
-
class cvxpy.constraints.exponential.ExpCone(x: Expression, y: Expression, z: Expression, constr_id=
None)[source]¶ Bases:
ConeA reformulated exponential cone constraint.
Operates elementwise on \(x, y, z\).
Original cone:
\[K = \{(x,y,z) \mid y > 0, ye^{x/y} <= z\} \cup \{(x,y,z) \mid x \leq 0, y = 0, z \geq 0\}\]Reformulated cone:
\[K = \{(x,y,z) \mid y, z > 0, y\log(y) + x \leq y\log(z)\} \cup \{(x,y,z) \mid x \leq 0, y = 0, z \geq 0\}\]- Parameters:¶
- x : Expression¶
x in the exponential cone.
- y : Expression¶
y in the exponential cone.
- z : Expression¶
z in the exponential cone.
-
is_dcp(dpp: bool =
False) bool[source]¶ An exponential constraint is DCP if each argument is affine.
- violation()¶
The numeric residual of the constraint.
The violation is defined as the distance between the constrained expression’s value and its projection onto the domain of the constraint:
\[||\Pi(v) - v||_2^2\]where \(v\) is the value of the constrained expression and \(\Pi\) is the projection operator onto the constraint’s domain .
RelEntrConeQuad¶
-
class cvxpy.constraints.exponential.RelEntrConeQuad(x: Expression, y: Expression, z: Expression, m: int, k: int, constr_id=
None)[source]¶ Bases:
ConeAn approximate construction of the scalar relative entropy cone
Definition:
\[K_{re}=\text{cl}\{(x,y,z)\in\mathbb{R}_{++}\times \mathbb{R}_{++}\times\mathbb{R}_{++}\:x\log(x/y)\leq z\}\]Since the above definition is very similar to the ExpCone, we provide a conversion method.
More details on the approximation can be found in Theorem-3 on page-10 in the paper: Semidefinite Approximations of the Matrix Logarithm.
- Parameters:¶
- x : Expression¶
x in the (approximate) scalar relative entropy cone
- y : Expression¶
y in the (approximate) scalar relative entropy cone
- z : Expression¶
z in the (approximate) scalar relative entropy cone
- m : Parameter directly related to the number of generated nodes for the quadrature¶
- algorithm : approximation used in the
- k : Another parameter controlling the approximation¶
-
is_dcp(dpp: bool =
False) bool[source]¶ An exponential constraint is DCP if each argument is affine.
PowCone3D¶
-
class cvxpy.constraints.power.PowCone3D(x, y, z, alpha, constr_id=
None)[source]¶ Bases:
ConeAn object representing a collection of 3D power cone constraints
x[i]**alpha[i] * y[i]**(1-alpha[i]) >= |z[i]| for all i x >= 0, y >= 0
If the parameter alpha is a scalar, it will be promoted to a vector matching the (common) sizes of x, y, z. The numeric value of alpha (or its components, in the vector case) must be a number in the open interval (0, 1).
We store flattened representations of the arguments (x, y, z, and alpha) as Expression objects. We construct dual variables with respect to these flattened representations.
- violation()¶
The numeric residual of the constraint.
The violation is defined as the distance between the constrained expression’s value and its projection onto the domain of the constraint:
\[||\Pi(v) - v||_2^2\]where \(v\) is the value of the constrained expression and \(\Pi\) is the projection operator onto the constraint’s domain .
PowConeND¶
-
class cvxpy.constraints.power.PowConeND(W, z, alpha, axis: int =
0, constr_id=None)[source]¶ Bases:
ConeRepresents a collection of N-dimensional power cone constraints that is mathematically equivalent to the following code snippet (which makes incorrect use of numpy functions on cvxpy objects):
np.prod(np.power(W, alpha), axis=axis) >= np.abs(z), W >= 0
All arguments must be Expression-like, and z must satisfy z.ndim <= 1. The columns (rows) of alpha must sum to 1 when axis=0 (axis=1).
Note: unlike PowCone3D, we make no attempt to promote alpha to the appropriate shape. The dimensions of W and alpha must match exactly.
Note: Dual variables are not currently implemented for this type of constraint.
- violation()¶
The numeric residual of the constraint.
The violation is defined as the distance between the constrained expression’s value and its projection onto the domain of the constraint:
\[||\Pi(v) - v||_2^2\]where \(v\) is the value of the constrained expression and \(\Pi\) is the projection operator onto the constraint’s domain .
FiniteSet¶
-
class cvxpy.constraints.finite_set.FiniteSet(expre, vec, ineq_form: bool =
False, constr_id=None)[source]¶ Bases:
ConstraintConstrain each entry of an Expression to take a value in a given set of real numbers.
- Parameters:¶
- expre : Expression¶
The given expression to be constrained. This Expression must be affine. If
exprehas multiple elements, then the constraint is applied separately to each element. I.e., after solving a problem with this constraint, we should have:for e in expre.flatten(): print(e.value in vec) # => True- vec : Union[Expression, np.ndarray, set]¶
The finite collection of values to which each entry of
expreis to be constrained.- ineq_form : bool¶
Controls how this constraint is canonicalized into mixed integer linear constraints.
If True, then we use a formulation with
vec.size - 1inequality constraints, one equality constraint, andvec.size - 1binary variables for each element ofexpre.If False, then we use a formulation with
vec.sizebinary variables and two equality constraints for each element ofexpre.Defaults to False. The case
ineq_form=Truemay speed up some mixed-integer solvers that use simple branch and bound methods.
- property ineq_form : bool¶
Choose between two constraining methodologies, use
ineq_form=Falsewhile working withParametertypes.
-
is_dcp(dpp: bool =
False) bool[source]¶ A FiniteSet constraint is DCP if the constrained expression is affine.
- violation()¶
The numeric residual of the constraint.
The violation is defined as the distance between the constrained expression’s value and its projection onto the domain of the constraint:
\[||\Pi(v) - v||_2^2\]where \(v\) is the value of the constrained expression and \(\Pi\) is the projection operator onto the constraint’s domain .
OpRelEntrConeQuad¶
-
class cvxpy.constraints.exponential.OpRelEntrConeQuad(X: Expression, Y: Expression, Z: Expression, m: int, k: int, constr_id=
None)[source]¶ Bases:
ConeAn approximate construction of the operator relative entropy cone
Definition:
\[K_{re}^n=\text{cl}\{(X,Y,T)\in\mathbb{H}^n_{++}\times \mathbb{H}^n_{++}\times\mathbb{H}^n_{++}\:D_{\text{op}}\succeq T\}\]More details on the approximation can be found in Theorem-3 on page-10 in the paper: Semidefinite Approximations of the Matrix Logarithm.
- Parameters:¶
- X : Expression¶
x in the (approximate) operator relative entropy cone
- Y : Expression¶
y in the (approximate) operator relative entropy cone
- Z : Expression¶
Z in the (approximate) operator relative entropy cone
- m : int¶
Must be positive. Controls the number of quadrature nodes used in a local approximation of the matrix logarithm. Increasing this value results in better local approximations, but does not significantly expand the region of inputs for which the approximation is effective.
- k : int¶
Must be positive. Sets the number of scaling points about which the quadrature approximation is performed. Increasing this value will expand the region of inputs over which the approximation is effective.
:param This approximation uses \(m + k\) semidefinite constraints.:
-
is_dcp(dpp: bool =
False) bool[source]¶ An operator relative conic constraint is DCP when (A, b, C) is affine