Affine Atoms¶

All of the atoms listed here are affine in their arguments.

AddExpression ¶

class cvxpy.atoms.affine.add_expr.AddExpression(arg_groups: Iterable[Expression])[source]¶

Bases: AffAtom

The sum of any number of expressions.

MulExpression ¶

class cvxpy.atoms.affine.binary_operators.MulExpression(lh_exp, rh_exp)[source]¶

Bases: BinaryOperator

Matrix multiplication.

The semantics of multiplication are exactly as those of NumPy’s matmul function, except here multiplication by a scalar is permitted. MulExpression objects can be created by using the ‘*’ operator of the Expression class.

Parameters:¶

lh_exp : Expression¶: The left-hand side of the multiplication.
rh_exp : Expression¶: The right-hand side of the multiplication.

DivExpression ¶

class cvxpy.atoms.affine.binary_operators.DivExpression(lh_expr, rh_expr)[source]¶

Bases: BinaryOperator

Division by scalar.

Can be created by using the / operator of expression.

bmat ¶

cvxpy.bmat(block_lists)[source]¶

Constructs a block matrix.

Takes a list of lists. Each internal list is stacked horizontally. The internal lists are stacked vertically.

Parameters:¶

block_lists : list of lists¶: The blocks of the block matrix.

Returns:¶

The CVXPY expression representing the block matrix.

Return type:¶

CVXPY expression

conj ¶

class cvxpy.conj(expr)[source]¶: Elementwise complex conjugate.

convolve ¶

class cvxpy.convolve(*args)[source]¶

Bases: AffAtom

1D discrete convolution of two vectors.

The discrete convolution \(c\) of vectors \(a\) and \(b\) of lengths \(n\) and \(m\), respectively, is a length-\((n+m-1)\) vector where

\[c_k = \sum_{i+j=k} a_ib_j, \quad k=0, \ldots, n+m-2.\]

Matches numpy.convolve

Parameters:¶

lh_expr : Constant: A constant scalar or 1D vector.
rh_expr : Expression: A scalar or 1D vector.

cumsum ¶

class cvxpy.cumsum(expr: Expression, axis: int | None = 0)[source]¶

Bases: AffAtom, AxisAtom

Cumulative sum of the elements of an expression.

expr¶

The expression being summed.

Type:¶: CVXPY expression

axis¶

The axis to sum across. If None, the array is flattened before cumsum. Note: NumPy’s default is axis=None, while CVXPY defaults to axis=0.

Type:¶: int, optional

diag ¶

cvxpy.diag(expr, k: int = 0) → diag_mat | diag_vec[source]¶

Extracts the diagonal from a matrix or makes a vector a diagonal matrix.

Parameters:¶

expr : Expression or numeric constant¶: A vector or square matrix.
k : int¶: Diagonal in question. The default is 0. Use k>0 for diagonals above the main diagonal, and k<0 for diagonals below the main diagonal.

Returns:¶

An Expression representing the diagonal vector/matrix.

Return type:¶

Expression

diff ¶

cvxpy.diff(x, k: int = 1, axis: int = 0)[source]¶

Computes kth order differences along the specified axis.

Takes in an array and returns an array with the kth order differences along the given axis. The output shape is the same as the input except the size along the specified axis is reduced by k.

diff(x) returns the differences between adjacent elements along axis 0:: [x[1] - x[0], x[2] - x[1], …]

diff(x, 2) is the second-order differences, equivalently diff(diff(x))

diff(x, 0) returns the array x unchanged

Parameters:¶

x : Expression or array-like¶: Input array.
k : int, optional¶: The number of times values are differenced. Default is 1.
axis : int, optional¶: The axis along which the difference is taken. Default is 0. Note: NumPy’s np.diff uses axis=-1 as default.

Returns:¶

The kth order differences along the specified axis.

Return type:¶

Expression

einsum ¶

cvxpy.einsum(subscripts, *exprs, optimize='greedy')[source]¶

Evaluates the Einstein summation convention on the given expressions.

This atom is the CVXPY analog of NumPy’s einsum function numpy.einsum [1], and it maintains the same syntax and semantics.

The einsum operation is evaluated by contracting pairs of expressions by elementwise multiplication and summation. The order in which the contractions are performed affects both the memory usage and the FLOP count required.

The optimize parameter determines whether to contract expressions using the optimal or greedy ordering. The cost to compute the optimal path is exponential in the number of distinct subscripts, while the cost to compute the greedy path is cubic in the number of distinct subscripts. We typically expect the greedy search to produce the optimal path for most problems.

Examples

>>> import cvxpy as cp
>>> A = cp.Variable((3, 4))
>>> B = cp.Variable((4, 5))
>>> # Matrix multiplication
>>> result = cp.einsum('ij,jk->ik', A, B)
>>>
>>> # Trace of a matrix
>>> C = cp.Variable((3, 3))
>>> trace = cp.einsum('ii->', C)

References

[1] https://numpy.org/doc/stable/reference/generated/numpy.einsum.html

Parameters:¶

subscripts : str¶: The subscripts for the einsum operation.
exprs : Expression¶: The expressions to contract.
optimize : {bool, 'greedy', 'optimal'}, optional¶: Whether to contract the expressions using the optimal or greedy ordering. Defaults to “greedy”.

Returns:¶

The contracted expression.

Return type:¶

Expression

hstack ¶

cvxpy.hstack(arg_list) → Hstack[source]¶

Horizontal concatenation of an arbitrary number of Expressions.

Parameters:¶

arg_list : list of Expression¶: The Expressions to concatenate.

imag ¶

class cvxpy.imag(expr)[source]¶: Extracts the imaginary part of an expression.

index ¶

class cvxpy.atoms.affine.index.index(expr, key, orig_key=None)[source]¶

Bases: AffAtom

Indexing/slicing into an Expression.

CVXPY supports NumPy-like indexing semantics via the Expression class’ overloading of the [] operator. This is a low-level class constructed by that operator, and it should not be instantiated directly.

Parameters:¶

expr : Expression¶: The expression indexed/sliced into.
key¶: The index/slicing key (i.e. expr[key[0],key[1]])

Examples

>>> import cvxpy as cp
>>> import numpy as np
>>> x = cp.Variable((2, 3, 4))
>>> x[..., 2].shape
(2, 3)
>>> x[..., np.newaxis].shape
(2, 3, 4, 1)
>>> x[1, 2].shape
(4,)

kron ¶

class cvxpy.kron(lh_expr, rh_expr)[source]¶

Bases: AffAtom

Kronecker product.

matmul ¶

cvxpy.matmul(lh_exp, rh_exp) → MulExpression[source]¶: Matrix multiplication.

mean ¶

cvxpy.atoms.stats.mean(x, axis=None, keepdims=False)[source]¶: Returns the mean of x.

multiply ¶

class cvxpy.multiply(lh_expr, rh_expr)[source]¶

Bases: MulExpression

Multiplies two expressions elementwise.

outer ¶

cvxpy.outer(x, y)[source]¶

Return the outer product of (x,y).

Parameters:¶

x : Expression, int, float, NumPy ndarray, or nested list thereof.¶: Input is flattened if not already a vector. The linear argument to the outer product.
y : Expression, int, float, NumPy ndarray, or nested list thereof.¶: Input is flattened if not already a vector. The transposed-linear argument to the outer product.

Returns:¶

expr – The outer product of (x,y), linear in x and transposed-linear in y.

Return type:¶

Expression

partial_trace ¶

cvxpy.partial_trace(expr, dims: tuple[int], axis: int | None = 0)[source]¶

Assumes \(\texttt{expr} = X_1 \otimes \cdots \otimes X_n\) is a 2D Kronecker product composed of \(n = \texttt{len(dims)}\) implicit subsystems. Letting \(k = \texttt{axis}\), the returned expression represents the partial trace of \(\texttt{expr}\) along its \(k^{\text{th}}\) implicit subsystem:

\[\text{tr}(X_k) (X_1 \otimes \cdots \otimes X_{k-1} \otimes X_{k+1} \otimes \cdots \otimes X_n).\]

Parameters:¶

expr¶: The 2D expression to take the partial trace of.
dims : tuple of ints.¶: A tuple of integers encoding the dimensions of each subsystem.
axis : int¶: The index of the subsystem to be traced out from the tensor product that defines expr.

partial_transpose ¶

cvxpy.partial_transpose(expr, dims: tuple[int, ...], axis: int | None = 0)[source]¶

Assumes \(\texttt{expr} = X_1 \otimes ... \otimes X_n\) is a 2D Kronecker product composed of \(n = \texttt{len(dims)}\) implicit subsystems. Letting \(k = \texttt{axis}\), the returned expression is a partial transpose of \(\texttt{expr}\), with the transpose applied to its \(k^{\text{th}}\) implicit subsystem:

\[X_1 \otimes ... \otimes X_k^T \otimes ... \otimes X_n.\]

Parameters:¶

expr¶: The 2D expression to take the partial transpose of.
dims : tuple of ints.¶: A tuple of integers encoding the dimensions of each subsystem.
axis : int¶: The index of the subsystem to be transposed from the tensor product that defines expr.

promote ¶

cvxpy.atoms.affine.promote.promote(expr: Expression, shape: tuple[int, ...])[source]¶

Promote a scalar expression to a vector/matrix.

Parameters:¶

expr : Expression¶: The expression to promote.
shape : tuple¶: The shape to promote to.

Raises:¶

ValueError – If expr is not a scalar.

psd_wrap ¶

class cvxpy.atoms.affine.wraps.psd_wrap(arg)[source]¶: Asserts that a square matrix is PSD.

real ¶

cvxpy.real(expr) → None[source]¶: Extracts the real part of an expression.

reshape ¶

class cvxpy.reshape(expr, shape: int | tuple[int, ...], order: 'F' | 'C' | None = None)[source]¶

Bases: AffAtom

Reshapes the expression.

Vectorizes the expression then unvectorizes it into the new shape. The entries are reshaped and stored in column-major order, also known as Fortran order.

Parameters:¶

expr : Expression¶: The expression to reshape
shape : tuple or int¶: The shape to reshape to
order : F(ortran) or C¶

vdot ¶

cvxpy.vdot(x, y)[source]¶

Return the standard inner product (or “scalar product”) of (x,y).

Parameters:¶

x : Expression, int, float, NumPy ndarray, or nested list thereof.¶: The conjugate-linear argument to the inner product.
y : Expression, int, float, NumPy ndarray, or nested list thereof.¶: The linear argument to the inner product.

Returns:¶

expr – The standard inner product of (x,y), conjugate-linear in x. We always have expr.shape == ().

Return type:¶

Expression

Notes

The arguments x and y can be nested lists; these lists will be flattened independently of one another.

For example, if x = [[a],[b]] and y = [c, d] (with a,b,c,d real scalars), then this function returns an Expression representing a * c + b * d.

sum ¶

cvxpy.sum(expr, axis=None, keepdims=False) → None[source]¶

Sum the entries of an expression over a given axis.

Parameters:¶

expr : Expression¶

The expression to sum the entries of.

axis : None or int or tuple of ints, optional¶

The axis or axes along which to sum. The default (axis=None) will sum all of the elements of the expression.

Added in version 1.6.0.

If axis is a tuple of ints, a sum is performed on all of the axes specified in the tuple.

keepdims : bool, optional¶

If set to true, the axes which are summed over remain in the output as dimensions with size one.

Examples

>>> import cvxpy as cp
>>> x = cp.Variable((2, 3, 4))
>>> expr = cp.sum(x)
>>> expr.shape
()
>>> expr = cp.sum(x, axis=0)
>>> expr.shape
(3, 4)
>>> expr = cp.sum(x, axis=(1, 2))
>>> expr.shape
(2,)

trace ¶

class cvxpy.trace(expr)[source]¶

Bases:

TLDR: Use alternate formulation for trace(A@B) for more efficient computation. trace(A@B) normally is O(n^3) because of the A@B operation. However, trace(A@B) only requires diagonal entries of A@B, which can be computed by taking the sum of element-wise product of A.T * B in O(n^2) time. In fact, vdot does this operation more robustly, using conj(A) instead of transpose.

transpose ¶

class cvxpy.transpose(expr, axes=None)[source]¶

Bases: AffAtom

Transpose an expression.

For an n-D expression, if axes are given, the order indicates the permutation of axes.

broadcast_to ¶

class cvxpy.broadcast_to(expr, shape)[source]¶

Bases: AffAtom

Broadcast the expression given a shape input

swapaxes ¶

class cvxpy.swapaxes(expr, axis1: int, axis2: int)[source]¶

Bases:

Swap two axes of the expression.

Parameters:¶

expr : AffAtom¶: The expression to swap axes of.
axis1 : int¶: The first axis to swap.
axis2 : int¶: The second axis to swap.

Returns:¶

A transpose atom with the axes swapped.

Return type:¶

AffAtom

moveaxis ¶

class cvxpy.moveaxis(expr, source: list[int], destination: list[int])[source]¶

Bases:

Move axes of the expression to new positions.

Parameters:¶

expr : AffAtom¶: The expression to move axes of.
source : list of int¶: The original positions of the axes to move.
destination : list of int¶: The new positions for the moved axes.

Returns:¶

A new transpose atom with the axes moved.

Return type:¶

AffAtom

permute_dims ¶

class cvxpy.permute_dims(expr, axes: list[int])[source]¶

Bases:

Permute the dimensions of the expression.

Alias for transpose with specified axes.

Parameters:¶

expr : AffAtom¶: The expression to permute dimensions of.
axes : list or tuple of int¶: The new order of the axes.

Returns:¶

A transpose atom with the specified axes.

Return type:¶

AffAtom

NegExpression ¶

class cvxpy.atoms.affine.unary_operators.NegExpression(expr)[source]¶

Bases: UnaryOperator

Negation of an expression.

upper_tri ¶

class cvxpy.upper_tri(expr)[source]¶

Bases: AffAtom

The vectorized strictly upper-triangular entries.

The vectorization is performed by concatenating (partial) rows. For example, if

A = np.array([[10, 11, 12, 13],
              [14, 15, 16, 17],
              [18, 19, 20, 21],
              [22, 23, 24, 25]])

then we have

upper_tri(A).value == np.array([11, 12, 13, 16, 17, 21])

vec ¶

cvxpy.vec(X, order: 'F' | 'C' | None = None)[source]¶

Flattens the matrix X into a 1-d array.

Parameters:¶

X : Expression or numeric constant¶: The matrix to flatten.
order : column-major ('F') or row-major ('C') order.¶

Returns:¶

An Expression representing the flattened matrix.

Return type:¶

Expression

vec_to_upper_tri ¶

cvxpy.atoms.affine.upper_tri.vec_to_upper_tri(expr, strict: bool = False)[source]¶: Reshapes a vector into an upper triangular matrix in row-major order. The strict argument specifies whether an upper or a strict upper triangular matrix should be returned. Inverts cp.upper_tri.

vstack ¶

cvxpy.vstack(arg_list) → Vstack[source]¶: Wrapper on vstack to ensure list argument.

stack ¶

cvxpy.stack(arrays: Sequence[object] | Iterable[object], axis: int = 0) → Expression[source]¶

Join a sequence of expressions along a new axis.

Parameters:¶

arrays: Sequence[object] | Iterable[object]¶: Sequence of expressions (or array-likes) that all have the same shape.
axis: int = 0¶: Index of the new axis in the result. Values in [-(ndim + 1), ndim + 1) are accepted, following numpy.stack.

Returns:¶

Expression whose shape equals the common input shape with the new axis inserted at axis and length len(arrays) along that axis.

Return type:¶

Expression

Raises:¶

TypeError – If axis is not an integer.
ValueError – If arrays is empty, shapes differ, or axis is out of bounds.