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 : Expression¶

The transpose of the expression.

Type:¶

Expression

__add__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Expression[source]¶

Expression : Sum two expressions.

__div__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Expression[source]¶

Expression : One expression divided by another.

__eq__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Equality[source]¶

Equality : Creates a constraint self == other.

__ge__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Inequality[source]¶

Return self>=value.

__le__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Inequality[source]¶

Inequality : Creates an inequality constraint self <= other.

__lshift__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → PSD[source]¶

PSD : Creates a negative semidefinite inequality.

__matmul__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Expression[source]¶

Expression : Matrix multiplication of two expressions.

__mul__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → 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:¶

Expression

__radd__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Expression[source]¶

Expression : Sum two expressions.

__rdiv__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Expression[source]¶

Expression : Called for Number / Expression.

__rlshift__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → PSD[source]¶

PSD : Creates a negative semidefinite inequality.

__rmatmul__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Expression[source]¶

Expression : Called for matrix @ Expression.

__rmul__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Expression[source]¶

Expression : Called for Number * Expression.

__rrshift__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → PSD[source]¶

PSD : Creates a positive semidefinite inequality.

__rshift__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → PSD[source]¶

PSD : Creates a positive semidefinite inequality.

__rsub__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Expression[source]¶

Expression : The difference of two expressions.

__rtruediv__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Expression[source]¶

Expression : Called for Number / Expression.

__sub__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Expression[source]¶

Expression : The difference of two expressions.

__truediv__(other: Expression | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → 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_affine() → bool[source]¶

Is the expression affine?

abstractmethod is_concave() → bool[source]¶

Is the expression concave?

is_constant() → bool[source]¶

Is the expression constant?

abstractmethod is_convex() → bool[source]¶

Is the expression convex?

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

abstractmethod 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

is_log_log_affine() → bool[source]¶

Is the expression affine?

abstractmethod is_log_log_concave() → bool[source]¶

Is the expression log-log concave?

abstractmethod is_log_log_convex() → bool[source]¶

Is the expression log-log convex?

abstractmethod is_nonneg() → bool[source]¶

Is the expression positive?

abstractmethod is_nonpos() → bool[source]¶

Is the expression negative?

is_zero() → bool[source]¶

Is the expression all zero?

abstractmethod name() → str[source]¶

str : The string representation of the expression.

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 : ndarray | None¶

The numeric value of the expression.

Type:¶

Returns

Leaf¶

class cvxpy.expressions.leaf.Leaf(shape: int | tuple[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: Iterable | bool = False, integer: Iterable | bool = False, sparsity: Iterable | bool = False, 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 and nonneg or both boolean in some indices and integer 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 : int or tuple of ints¶

Shape of the leaf, e.g., (3, 2) or 2.

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 Iterable¶

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 Iterable¶

Is the variable integer? The semantics are the same as the boolean argument.

sparsity : Iterable¶

Is the variable sparse?

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 : Expression¶

The transpose of the expression.

Type:¶

Expression

property ndim : int¶

The number of dimensions in the expression’s shape.

Type:¶

int

project(val, sparse_path=False)[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

project_and_assign(val) → None[source]¶

Project and assign a value to the variable.

property shape : tuple[int, ...]¶

The dimensions of the expression.

property size : int¶

The number of entries in the expression.

Type:¶

int

property value : ndarray | None¶

The numeric value of the expression.

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 : Expression¶

The transpose of the expression.

Type:¶

Expression

name() → str[source]¶

The name of the variable.

property ndim : int¶

The number of dimensions in the expression’s shape.

Type:¶

int

project(val, sparse_path=False)¶

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.

property size : int¶

The number of entries in the expression.

Type:¶

int

property value : ndarray | None¶

The numeric value of the expression.

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 : Expression¶

The transpose of the expression.

Type:¶

Expression

property ndim : int¶

The number of dimensions in the expression’s shape.

Type:¶

int

project(val, sparse_path=False)¶

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.

property size : int¶

The number of entries in the expression.

Type:¶

int

property value : ndarray | None¶

The numeric value of the expression.

Constant¶

class cvxpy.expressions.constants.Constant(value, name: str | None = None)[source]¶

Bases: Leaf

A constant value.

Raw numerical constants such as Python primitive types or NumPy ndarrays are implicitly cast to constants via Expression operator overloading. For example, if x is an expression and``c`` is a raw constant, then x + c creates an expression by casting c to a Constant.

property T : Expression¶

The transpose of the expression.

Type:¶

Expression

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 : Expression¶

The transpose of the expression.

Type:¶

Expression

property ndim : int¶

The number of dimensions in the expression’s shape.

Type:¶

int

project(val, sparse_path=False)¶

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.

property size : int¶

The number of entries in the expression.

Type:¶

int

property value¶

Evaluate the callback to get the value.