约束

约束是限制优化问题域的等式或不等式。CVXPY有七种类型的约束:非正数、等式或零、正半定、二阶锥、指数锥、三维幂锥和N维幂锥。绝大多数 用户只需要创建前三种类型的约束。此外,大多数用户无需了解关于约束的更多信息,只需知道如何创建它们即可。约束API仍然提供了一些高级用户可能会发现有用的方法;例如,一些API允许您检查对偶变量值和残差。

约束

class cvxpy.constraints.constraint.Constraint(args, constr_id=None)[source]

Bases: Canonical

The 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:
  • args (list) – A list of expression trees.

  • constr_id (int) – A unique id for the constraint.

abstract is_dcp(dpp: bool = False) bool[source]

Checks whether the constraint is DCP.

Returns:

True if the constraint is DCP, False otherwise.

Return type:

bool

value(tolerance: float = 1e-08)[source]

Checks whether the constraint violation is less than a tolerance.

Parameters:

tolerance (float) – The absolute tolerance to impose on the violation.

Returns:

True if the violation is less than tolerance, False otherwise.

Return type:

bool

Raises:

ValueError – If the constrained expression does not have a value associated with it.

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 .

Returns:

The residual value.

Return type:

NumPy.ndarray

Raises:

ValueError – If the constrained expression does not have a value associated with it.

非正数

class cvxpy.constraints.nonpos.NonPos(expr, constr_id=None)[source]

Bases: Constraint

An inequality constraint of the form \(x \leq 0\).

The preferred way of creating an inequality constraint is through operator overloading. To constrain an expression x to be nonpositive, write x <= 0; to constrain x to be nonnegative, write x >= 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.

property dual_value

The value of the dual variable.

Type:

NumPy.ndarray

is_dcp(dpp: bool = False) bool[source]

A NonPos constraint is DCP if its argument is convex.

property shape

The shape of the constrained expression.

Type:

int

property size

The size of the constrained expression.

Type:

int

value(tolerance: float = 1e-08)

Checks whether the constraint violation is less than a tolerance.

Parameters:

tolerance (float) – The absolute tolerance to impose on the violation.

Returns:

True if the violation is less than tolerance, False otherwise.

Return type:

bool

Raises:

ValueError – If the constrained expression does not have a value associated with it.

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 .

Returns:

The residual value.

Return type:

NumPy.ndarray

Raises:

ValueError – If the constrained expression does not have a value associated with it.

class cvxpy.constraints.zero.Zero(expr, constr_id=None)[source]

Bases: Constraint

A constraint of the form \(x = 0\).

The preferred way of creating a Zero constraint is through operator overloading. To constrain an expression x to be zero, simply write x == 0. The former creates a Zero constraint with x as its argument.

is_dcp(dpp: bool = False) bool[source]

A zero constraint is DCP if its argument is affine.

value(tolerance: float = 1e-08)

Checks whether the constraint violation is less than a tolerance.

Parameters:

tolerance (float) – The absolute tolerance to impose on the violation.

Returns:

True if the violation is less than tolerance, False otherwise.

Return type:

bool

Raises:

ValueError – If the constrained expression does not have a value associated with it.

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 .

Returns:

The residual value.

Return type:

NumPy.ndarray

Raises:

ValueError – If the constrained expression does not have a value associated with it.

半正定约束(PSD)

class cvxpy.constraints.psd.PSD(expr, constr_id=None)[source]

Bases: Cone

A constraint of the form \(\frac{1}{2}(X + X^T) \succcurlyeq_{S_n^+} 0\)

Applying a PSD constraint to a two-dimensional expression X constrains its symmetric part to be positive semidefinite: i.e., it constrains X to be such that

\[z^T(X + X^T)z \geq 0,\]

for all \(z\).

The preferred way of creating a PSD constraint is through operator overloading. To constrain an expression X to be PSD, write X >> 0; to constrain it to be negative semidefinite, write X << 0. Strict definiteness constraints are not provided, as they do not make sense in a numerical setting.

Parameters:
  • expr (Expression.) – The expression to constrain; must be two-dimensional.

  • constr_id (int) – A unique id for the constraint.

is_dcp(dpp: bool = False) bool[source]

A PSD constraint is DCP if the constrained expression is affine.

value(tolerance: float = 1e-08)

Checks whether the constraint violation is less than a tolerance.

Parameters:

tolerance (float) – The absolute tolerance to impose on the violation.

Returns:

True if the violation is less than tolerance, False otherwise.

Return type:

bool

Raises:

ValueError – If the constrained expression does not have a value associated with it.

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 .

Returns:

The residual value.

Return type:

NumPy.ndarray

Raises:

ValueError – If the constrained expression does not have a value associated with it.

SOC

class cvxpy.constraints.second_order.SOC(t, X, axis: int = 0, constr_id=None)[source]

Bases: Cone

A second-order cone constraint for each row/column.

Assumes t is a vector the same length as X’s columns (rows) for axis == 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.

value(tolerance: float = 1e-08)

Checks whether the constraint violation is less than a tolerance.

Parameters:

tolerance (float) – The absolute tolerance to impose on the violation.

Returns:

True if the violation is less than tolerance, False otherwise.

Return type:

bool

Raises:

ValueError – If the constrained expression does not have a value associated with it.

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 .

Returns:

The residual value.

Return type:

NumPy.ndarray

Raises:

ValueError – If the constrained expression does not have a value associated with it.

指数锥(ExpCone)

class cvxpy.constraints.exponential.ExpCone(x: Expression, y: Expression, z: Expression, constr_id=None)[source]

Bases: Cone

A 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:
is_dcp(dpp: bool = False) bool[source]

An exponential constraint is DCP if each argument is affine.

value(tolerance: float = 1e-08)

Checks whether the constraint violation is less than a tolerance.

Parameters:

tolerance (float) – The absolute tolerance to impose on the violation.

Returns:

True if the violation is less than tolerance, False otherwise.

Return type:

bool

Raises:

ValueError – If the constrained expression does not have a value associated with it.

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 .

Returns:

The residual value.

Return type:

NumPy.ndarray

Raises:

ValueError – If the constrained expression does not have a value associated with it.

RelEntrConeQuad

class cvxpy.constraints.exponential.RelEntrConeQuad(x: Expression, y: Expression, z: Expression, m: int, k: int, constr_id=None)[source]

Bases: Cone

An 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.

value(tolerance: float = 1e-08)

Checks whether the constraint violation is less than a tolerance.

Parameters:

tolerance (float) – The absolute tolerance to impose on the violation.

Returns:

True if the violation is less than tolerance, False otherwise.

Return type:

bool

Raises:

ValueError – If the constrained expression does not have a value associated with it.

PowCone3D

class cvxpy.constraints.power.PowCone3D(x, y, z, alpha, constr_id=None)[source]

Bases: Cone

An 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.

is_dcp(dpp: bool = False) bool[source]

Checks whether the constraint is DCP.

Returns:

True if the constraint is DCP, False otherwise.

Return type:

bool

value(tolerance: float = 1e-08)

Checks whether the constraint violation is less than a tolerance.

Parameters:

tolerance (float) – The absolute tolerance to impose on the violation.

Returns:

True if the violation is less than tolerance, False otherwise.

Return type:

bool

Raises:

ValueError – If the constrained expression does not have a value associated with it.

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 .

Returns:

The residual value.

Return type:

NumPy.ndarray

Raises:

ValueError – If the constrained expression does not have a value associated with it.

PowConeND

class cvxpy.constraints.power.PowConeND(W, z, alpha, axis: int = 0, constr_id=None)[source]

Bases: Cone

Represents 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.

is_dcp(dpp: bool = False) bool[source]

A power cone constraint is DCP if each argument is affine.

value(tolerance: float = 1e-08)

Checks whether the constraint violation is less than a tolerance.

Parameters:

tolerance (float) – The absolute tolerance to impose on the violation.

Returns:

True if the violation is less than tolerance, False otherwise.

Return type:

bool

Raises:

ValueError – If the constrained expression does not have a value associated with it.

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 .

Returns:

The residual value.

Return type:

NumPy.ndarray

Raises:

ValueError – If the constrained expression does not have a value associated with it.

FiniteSet

class cvxpy.constraints.finite_set.FiniteSet(expre, vec, ineq_form: bool = False, constr_id=None)[source]

Bases: Constraint

Constrain 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 expre has 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 expre is 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 - 1 inequality constraints, one equality constraint, and vec.size - 1 binary variables for each element of expre.

    If False, then we use a formulation with vec.size binary variables and two equality constraints for each element of expre.

    Defaults to False. The case ineq_form=True may 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=False while working with Parameter types.

is_dcp(dpp: bool = False) bool[source]

A FiniteSet constraint is DCP if the constrained expression is affine.

property shape

The shape of the constrained expression.

Type:

int

property size

The size of the constrained expression.

Type:

int

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 .

Returns:

The residual value.

Return type:

NumPy.ndarray

Raises:

ValueError – If the constrained expression does not have a value associated with it.

OpRelEntrConeQuad

class cvxpy.constraints.exponential.OpRelEntrConeQuad(X: Expression, Y: Expression, Z: Expression, m: int, k: int, constr_id=None)[source]

Bases: Cone

An 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

value(tolerance: float = 1e-08)

Checks whether the constraint violation is less than a tolerance.

Parameters:

tolerance (float) – The absolute tolerance to impose on the violation.

Returns:

True if the violation is less than tolerance, False otherwise.

Return type:

bool

Raises:

ValueError – If the constrained expression does not have a value associated with it.