# Affine Atoms¶

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

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]

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 = 0)[source]

Bases: AffAtom, AxisAtom

Cumulative sum.

expr

The expression being summed.

Type:

CVXPY expression

axis

The axis to sum across if 2D.

Type:

int

## 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]

Vector of kth order differences.

Takes in a vector of length n and returns a vector of length n-k of the kth order differences.

diff(x) returns the vector of differences between adjacent elements in the vector, that is

[x[2] - x[1], x[3] - x[2], …]

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

diff(x, 0) returns the vector x unchanged

## 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]]).

## kron¶

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

Bases: AffAtom

Kronecker product.

## matmul¶

cvxpy.matmul(lh_exp, rh_exp) [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 (Expression) – 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 (Expression) – 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: str = 'F')[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 promote.

• shape (tuple or int) – The shape to promote 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: int | None = None, keepdims: bool = False) None[source]

Sum the entries of an expression.

Parameters:
• expr (Expression) – The expression to sum the entries of.

• axis (int) – The axis along which to sum.

• keepdims (bool) – Whether to drop dimensions after summing.

## trace¶

class cvxpy.trace(expr)[source]

Bases: AffAtom

The sum of the diagonal entries of a matrix.

Parameters:

expr (Expression) – The expression to sum the diagonal of.

## transpose¶

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

Bases: AffAtom

Transpose an expression.

## 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-triagonal 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: str = 'F')[source]

Flattens the matrix X into a vector.

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.