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 = 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 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]])

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

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.