Expressions¶
CVXPY represents mathematical objects as expression trees. An expression
tree is a collection of mathematical expressions linked together by one or more
atoms. Expression trees are encoded as instances of the
Expression
class, and each
Leaf
in a tree is a
Variable
,
Parameter
, or
Constant
.
Expression¶
- class cvxpy.expressions.expression.Expression[source]¶
Bases:
Canonical
A mathematical expression in a convex optimization problem.
Overloads many operators to allow for convenient creation of compound expressions (e.g., the sum of two expressions) and constraints.
- property T¶
The transpose of the expression.
- Type:
- __add__(other: Expression | np.typing.ArrayLike) Expression [source]¶
Expression : Sum two expressions.
- __div__(other: Expression | np.typing.ArrayLike) Expression [source]¶
Expression : One expression divided by another.
- __eq__(other: Expression | np.typing.ArrayLike)[source]¶
Equality : Creates a constraint
self == other
.
- __ge__(other: Expression | np.typing.ArrayLike)[source]¶
Return self>=value.
- __le__(other: Expression | np.typing.ArrayLike)[source]¶
Inequality : Creates an inequality constraint
self <= other
.
- __lshift__(other: Expression | np.typing.ArrayLike) PSD [source]¶
PSD : Creates a negative semidefinite inequality.
- __matmul__(other: Expression | np.typing.ArrayLike) Expression [source]¶
Expression : Matrix multiplication of two expressions.
- __mul__(other: Expression | np.typing.ArrayLike) Expression [source]¶
Expression : The product of two expressions.
- __pow__(power: float) Expression [source]¶
Raise expression to a power.
- Parameters:
power (float) – The power to which to raise the expression.
- Returns:
The expression raised to
power
.- Return type:
- __radd__(other: Expression | np.typing.ArrayLike) Expression [source]¶
Expression : Sum two expressions.
- __rdiv__(other: Expression | np.typing.ArrayLike) Expression [source]¶
Expression : Called for Number / Expression.
- __rlshift__(other: Expression | np.typing.ArrayLike) PSD [source]¶
PSD : Creates a negative semidefinite inequality.
- __rmatmul__(other: Expression | np.typing.ArrayLike) Expression [source]¶
Expression : Called for matrix @ Expression.
- __rmul__(other: Expression | np.typing.ArrayLike) Expression [source]¶
Expression : Called for Number * Expression.
- __rrshift__(other: Expression | np.typing.ArrayLike) PSD [source]¶
PSD : Creates a positive semidefinite inequality.
- __rshift__(other: Expression | np.typing.ArrayLike) PSD [source]¶
PSD : Creates a positive semidefinite inequality.
- __rsub__(other: Expression | np.typing.ArrayLike) Expression [source]¶
Expression : The difference of two expressions.
- __rtruediv__(other: Expression | np.typing.ArrayLike) Expression [source]¶
Expression : Called for Number / Expression.
- __sub__(other: Expression | np.typing.ArrayLike) Expression [source]¶
Expression : The difference of two expressions.
- __truediv__(other: Expression | np.typing.ArrayLike) Expression [source]¶
Expression : One expression divided by another.
- property curvature: str¶
The curvature of the expression.
- Type:
str
- abstract property domain¶
The constraints describing the closure of the region where the expression is finite.
- Type:
list
- abstract property grad¶
Gives the (sub/super)gradient of the expression w.r.t. each variable.
Matrix expressions are vectorized, so the gradient is a matrix.
- Returns:
A map of variable to SciPy CSC sparse matrix; None if a variable value is missing.
- Return type:
dict
- is_dcp(dpp: bool = False) bool [source]¶
Checks whether the Expression is DCP.
- Parameters:
dpp (bool, optional) – If True, enforce the disciplined parametrized programming (DPP) ruleset; only relevant when the problem involves Parameters.
- Returns:
True if the Expression is DCP, False otherwise.
- Return type:
bool
- is_dgp(dpp: bool = False) bool [source]¶
Checks whether the Expression is log-log DCP.
- Returns:
True if the Expression is log-log DCP, False otherwise.
- Return type:
bool
- abstract is_dpp(context: str = 'dcp') bool [source]¶
The expression is a disciplined parameterized expression.
- is_dqcp() bool [source]¶
Checks whether the Expression is DQCP.
- Returns:
True if the Expression is DQCP, False otherwise.
- Return type:
bool
- property ndim: int¶
The number of dimensions in the expression’s shape.
- Type:
int
- abstract property shape: Tuple[int, ...]¶
The expression dimensions.
- Type:
tuple
- property sign: str¶
The sign of the expression.
- Type:
str
- property size: int¶
The number of entries in the expression.
- Type:
int
- abstract property value¶
The numeric value of the expression.
- Type:
NumPy.ndarray or None
Leaf¶
- class cvxpy.expressions.leaf.Leaf(shape: int | Iterable[int, ...], value=None, nonneg: bool = False, nonpos: bool = False, complex: bool = False, imag: bool = False, symmetric: bool = False, diag: bool = False, PSD: bool = False, NSD: bool = False, hermitian: bool = False, boolean: bool = False, integer: bool = False, sparsity=None, pos: bool = False, neg: bool = False, bounds: Iterable | None = None)[source]¶
Bases:
Expression
A leaf node of an expression tree; i.e., a Variable, Constant, or Parameter.
A leaf may carry attributes that constrain the set values permissible for it. Leafs can have no more than one attribute, with the exception that a leaf may be both
nonpos
andnonneg
or bothboolean
in some indices andinteger
in others.An error is raised if a leaf is assigned a value that contradicts one or more of its attributes. See the
project
method for a convenient way to project a value onto a leaf’s domain.- Parameters:
shape (Iterable of ints or int) – The leaf dimensions. Either an integer n for a 1D shape, or an iterable where the semantics are the same as NumPy ndarray shapes. Shapes cannot be more than 2D.
value (numeric type) – A value to assign to the leaf.
nonneg (bool) – Is the variable constrained to be nonnegative?
nonpos (bool) – Is the variable constrained to be nonpositive?
complex (bool) – Is the variable complex valued?
symmetric (bool) – Is the variable symmetric?
diag (bool) – Is the variable diagonal?
PSD (bool) – Is the variable constrained to be positive semidefinite?
NSD (bool) – Is the variable constrained to be negative semidefinite?
Hermitian (bool) – Is the variable Hermitian?
boolean (bool or list of tuple) – Is the variable boolean? True, which constrains the entire Variable to be boolean, False, or a list of indices which should be constrained as boolean, where each index is a tuple of length exactly equal to the length of shape.
integer (bool or list of tuple) – Is the variable integer? The semantics are the same as the boolean argument.
sparsity (list of tuplewith) – Fixed sparsity pattern for the variable.
pos (bool) – Is the variable positive?
neg (bool) – Is the variable negative?
bounds (Iterable) – An iterable of length two specifying lower and upper bounds.
- property T¶
The transpose of the expression.
- Type:
- property ndim: int¶
The number of dimensions in the expression’s shape.
- Type:
int
- project(val)[source]¶
Project value onto the attribute set of the leaf.
A sensible idiom is
leaf.value = leaf.project(val)
.- Parameters:
val (numeric type) – The value assigned.
- Returns:
The value rounded to the attribute type.
- Return type:
numeric type
- property shape: tuple[int, ...]¶
The dimensions of the expression.
- Type:
tuple
- property size: int¶
The number of entries in the expression.
- Type:
int
- property value¶
The numeric value of the parameter.
- Type:
NumPy.ndarray or None
Variable¶
- class cvxpy.expressions.variable.Variable(shape: int | Iterable[int, ...] = (), name: str | None = None, var_id: int | None = None, **kwargs: Any)[source]¶
Bases:
Leaf
The optimization variables in a problem.
- property T¶
The transpose of the expression.
- Type:
- property ndim: int¶
The number of dimensions in the expression’s shape.
- Type:
int
- project(val)¶
Project value onto the attribute set of the leaf.
A sensible idiom is
leaf.value = leaf.project(val)
.- Parameters:
val (numeric type) – The value assigned.
- Returns:
The value rounded to the attribute type.
- Return type:
numeric type
- project_and_assign(val) None ¶
Project and assign a value to the variable.
- property shape: tuple[int, ...]¶
The dimensions of the expression.
- Type:
tuple
- property size: int¶
The number of entries in the expression.
- Type:
int
- property value¶
The numeric value of the parameter.
- Type:
NumPy.ndarray or None
Parameter¶
- class cvxpy.expressions.constants.parameter.Parameter(shape: int | tuple[int, ...] = (), name: str | None = None, value=None, id=None, **kwargs)[source]¶
Bases:
Leaf
Parameters in optimization problems.
Parameters are constant expressions whose value may be specified after problem creation. The only way to modify a problem after its creation is through parameters. For example, you might choose to declare the hyper-parameters of a machine learning model to be Parameter objects; more generally, Parameters are useful for computing trade-off curves.
- property T¶
The transpose of the expression.
- Type:
- property ndim: int¶
The number of dimensions in the expression’s shape.
- Type:
int
- project(val)¶
Project value onto the attribute set of the leaf.
A sensible idiom is
leaf.value = leaf.project(val)
.- Parameters:
val (numeric type) – The value assigned.
- Returns:
The value rounded to the attribute type.
- Return type:
numeric type
- project_and_assign(val) None ¶
Project and assign a value to the variable.
- property shape: tuple[int, ...]¶
The dimensions of the expression.
- Type:
tuple
- property size: int¶
The number of entries in the expression.
- Type:
int
- property value¶
The numeric value of the parameter.
- Type:
NumPy.ndarray or None
Constant¶
- class cvxpy.expressions.constants.Constant(value, name: str | None = None)[source]¶
Bases:
Leaf
A constant value.
Raw numerical constants (Python primite types, NumPy ndarrays, and NumPy matrices) are implicitly cast to constants via Expression operator overloading. For example, if
x
is an expression andc
is a raw constant, thenx + c
creates an expression by castingc
to a Constant.- property T¶
The transpose of the expression.
- Type:
- property ndim: int¶
The number of dimensions in the expression’s shape.
- Type:
int
- property shape: Tuple[int, ...]¶
Returns the (row, col) dimensions of the expression.
- property size: int¶
The number of entries in the expression.
- Type:
int
- property value¶
The numeric value of the constant.
- Type:
NumPy.ndarray or None
CallbackParam¶
- class cvxpy.expressions.constants.callback_param.CallbackParam(callback: Callable, shape: int | tuple[int, ...] = (), **kwargs)[source]¶
Bases:
Parameter
A parameter whose value is derived from a callback function.
Enables writing replacing expression that would not be DPP by a new parameter that automatically updates its value.
Example: With p and q parameters, p * q is not DPP, but pq = CallbackParameter(callback=lambda: p.value * q.value) is DPP.
This is useful when only p and q should be exposed to the user, but pq is needed internally.
- property T¶
The transpose of the expression.
- Type:
- property ndim: int¶
The number of dimensions in the expression’s shape.
- Type:
int
- project(val)¶
Project value onto the attribute set of the leaf.
A sensible idiom is
leaf.value = leaf.project(val)
.- Parameters:
val (numeric type) – The value assigned.
- Returns:
The value rounded to the attribute type.
- Return type:
numeric type
- project_and_assign(val) None ¶
Project and assign a value to the variable.
- property shape: tuple[int, ...]¶
The dimensions of the expression.
- Type:
tuple
- property size: int¶
The number of entries in the expression.
- Type:
int
- property value¶
Evaluate the callback to get the value.