Other Atoms¶

The atoms listed here are neither affine nor elementwise.

cummax ¶

class cvxpy.atoms.cummax.cummax(x, axis: int = 0)[source]¶

Bases: AxisAtom

Cumulative maximum.

cumprod ¶

class cvxpy.atoms.cumprod.cumprod(expr: Expression, axis: int = 0)[source]¶

Bases: AffAtom, AxisAtom

Cumulative product of the elements of an expression.

expr¶

The expression being multiplied.

Type:¶: CVXPY expression

axis¶

The axis to multiply across.

Type:¶: int

cvar ¶

cvxpy.atoms.cvar.cvar(x, beta)[source]¶

The conditional value at risk (CVaR) of a random variable represented by the vector of samples x.

For a probability level \(\beta \in [0,1)\), CVaR is the expected value of x in the worst \((1-\beta)\) fraction of cases. Equivalently, it is the average of the \((1-\beta)\) fraction of largest values in x.

Parameters:¶

x : Expression or numeric constant¶: A vector of samples representing the distribution. Must be one-dimensional.
beta : float¶: The probability level. Must be in the range \([0, 1)\). For example, \(\beta = 0.95\) gives the average of the worst 5% of outcomes.

Returns:¶

\[\frac{1}{(1-\beta)m} \sum\nolimits_{\text{largest } (1-\beta)m} x_i\]

where \(m\) is the length of \(x\). When \((1-\beta)m\) is not an integer, the fractional part is handled via linear interpolation.

Return type:¶

Expression

diff_pos ¶

cvxpy.atoms.one_minus_pos.diff_pos(x, y)[source]¶

The difference \(x - y\) with domain {x, y : x > y > 0}.

This atom is log-log concave.

Parameters:¶

x¶: An Expression.
y¶: An Expression.

dotsort ¶

class cvxpy.atoms.dotsort.dotsort(X, W)[source]¶

Bases: Atom

Computes \(\langle sort\left(vec(X)\right), sort\left(vec(W)\right) \rangle\), where \(X\) is an expression and \(W\) is constant.

Both arguments are flattened, i.e., we define \(x=vec(X)\), \(w=vec(W)\).
If the length of \(w\) is less than the length of \(x\),
it is conceptually padded with zeros.
When the length of \(w\) is larger than the length of \(x\), an exception is raised.

dotsort is a generalization of sum_largest and sum_smallest:

sum_largest(x, 3) is equivalent to dotsort(x,[1,1,1])
sum_largest(x, 3.5) is equivalent to dotsort(x,[1,1,1,0.5])
sum_smallest(x,3) is equivalent to -dotsort(x, [-1,-1,-1])

When the constant argument is not a boolean vector, dotsort can be considered as a weighted sum of \(x\), where the largest weight is assigned to the largest entry in \(x\), etc..

eye_minus_inv ¶

class cvxpy.atoms.eye_minus_inv.eye_minus_inv(X)[source]¶

Bases: Atom

The unity resolvent of a positive matrix, \((I - X)^{-1}\).

For an elementwise positive matrix \(X\), this atom represents

\[(I - X)^{-1},\]

and it enforces the constraint that the spectral radius of \(X\) is at most \(1\).

This atom is log-log convex.

Parameters:¶

X : cvxpy.Expression¶: A positive square matrix.

geo_mean ¶

class cvxpy.atoms.geo_mean.geo_mean(x, p=None, max_denom=1024, approx=True)[source]¶

Bases:

Factory function for (weighted) geometric mean.

Parameters:¶

x : Expression¶: The value to take the geometric mean of.
p : Sequence, optional¶: Weights for the weighted geometric mean.
max_denom : int¶: Maximum denominator for rational approximation.
approx : bool¶: When True (default), uses SOC approximation. When False, uses power cone (exact).

Return type:¶

GeoMean or GeoMeanApprox

gmatmul ¶

class cvxpy.atoms.gmatmul.gmatmul(A, X)[source]¶

Bases: Atom

Geometric matrix multiplication; \(A \mathbin{\diamond} X\).

For \(A \in \mathbf{R}^{m \times n}\) and \(X \in \mathbf{R}^{n \times p}_{++}\), this atom represents

\[\begin{split}\left[\begin{array}{ccc} \prod_{j=1}^n X_{j1}^{A_{1j}} & \cdots & \prod_{j=1}^n X_{pj}^{A_{1j}} \\ \vdots & & \vdots \\ \prod_{j=1}^n X_{j1}^{A_{mj}} & \cdots & \prod_{j=1}^n X_{pj}^{A_{mj}} \end{array}\right]\end{split}\]

This atom is log-log affine (in \(X\)).

Parameters:¶

A : cvxpy.Expression¶: A constant matrix.
X : cvxpy.Expression¶: A positive matrix.

harmonic_mean ¶

cvxpy.atoms.harmonic_mean.harmonic_mean(x)[source]¶

The harmonic mean of x.

Parameters:¶

x : Expression or numeric¶: The expression whose harmonic mean is to be computed. Must have positive entries.

Returns:¶

\[\frac{n}{\left(\sum_{i=1}^{n} x_i^{-1} \right)},\]

where \(n\) is the length of \(x\).

Return type:¶

Expression

inv_prod ¶

cvxpy.atoms.inv_prod.inv_prod(value, approx=True)[source]¶

The reciprocal of a product of the entries of a vector x.

Parameters:¶

x : Expression or numeric: The expression whose reciprocal product is to be computed. Must have positive entries.
approx : bool¶: When True (default), uses SOC approximation. When False, uses power cone (exact).

Returns:¶

\[\left(\prod_{i=1}^n x_i\right)^{-1},\]

where \(n\) is the length of \(x\).

Return type:¶

Expression

lambda_max ¶

class cvxpy.atoms.lambda_max.lambda_max(A)[source]¶

Bases: Atom

Maximum eigenvalue; \(\lambda_{\max}(A)\).

lambda_min ¶

cvxpy.atoms.lambda_min.lambda_min(X)[source]¶: Minimum eigenvalue; \(\lambda_{\min}(A)\).

lambda_sum_largest ¶

cvxpy.atoms.lambda_sum_largest.lambda_sum_largest(X, k) → None[source]¶: Sum of the largest k eigenvalues.

lambda_sum_smallest ¶

cvxpy.atoms.lambda_sum_smallest.lambda_sum_smallest(X, k)[source]¶: Sum of the smallest k eigenvalues.

log_det ¶

class cvxpy.atoms.log_det.log_det(A)[source]¶

Bases: Atom

\(\log\det A\)

log_sum_exp ¶

class cvxpy.atoms.log_sum_exp.log_sum_exp(x, axis=None, keepdims: bool = False)[source]¶

Bases: AxisAtom

\(\log\sum_i e^{x_i}\)

matrix_frac ¶

cvxpy.atoms.matrix_frac.matrix_frac(X, P) → None[source]¶: tr X.T*P^-1*X

max ¶

class cvxpy.atoms.max.max(x, axis: int | None = None, keepdims: bool = False)[source]¶

Bases: AxisAtom

\(\max_{i,j}\{X_{i,j}\}\).

min ¶

cvxpy.atoms.min.min(x, axis: int | None = None, keepdims: bool = False) → None[source]¶: \(\min{i,j}\{X_{i,j}\}\).

mixed_norm ¶

cvxpy.atoms.mixed_norm.mixed_norm(X, p: int | str = 2, q: int | str = 1)[source]¶

Lp,q norm; \((\sum_k (\sum_l \lvert x_{k,l} \rvert^p)^{q/p})^{1/q}\).

Parameters:¶

X : Expression or numeric constant¶: The matrix to take the l_{p,q} norm of.
p : int or str, optional¶: The type of inner norm.
q : int or str, optional¶: The type of outer norm.

Returns:¶

An Expression representing the mixed norm.

Return type:¶

Expression

norm ¶

cvxpy.atoms.norm.norm(x, p: int | str = 2, axis=None, keepdims: bool = False)[source]¶

Wrapper on the different norm atoms.

Parameters:¶

x : Expression or numeric constant¶: The value to take the norm of. If x is 2D and axis is None, this function constructs a matrix norm.
p : int or str, optional¶: The type of norm. Valid options include any positive integer, ‘fro’ (for frobenius), ‘nuc’ (sum of singular values), np.inf or ‘inf’ (infinity norm).
axis : The axis along which to apply the norm, if any.¶
keepdims : If this is set to True, the axes which are reduced are left¶: in the result as dimensions with size one.

Returns:¶

An Expression representing the norm.

Return type:¶

Expression

norm1 ¶

class cvxpy.atoms.norm1.norm1(expr, axis: int | None = None, keepdims: bool = False)[source]¶: Bases: AxisAtom

norm2 ¶

cvxpy.atoms.norm.norm2(x, axis=None)[source]¶

The 2-norm of x.

Parameters:¶

x : Expression or numeric constant¶: The value to take the norm of. If x is 2D and axis is None, this function constructs a matrix norm.

Returns:¶

An Expression representing the norm.

Return type:¶

Expression

norm_inf ¶

class cvxpy.atoms.norm_inf(expr, axis: int | None = None, keepdims: bool = False)[source]¶: Bases: AxisAtom

normNuc ¶

class cvxpy.atoms.norm_nuc.normNuc(A)[source]¶

Bases: Atom

Sum of the singular values.

one_minus_pos ¶

class cvxpy.atoms.one_minus_pos(x)[source]¶

Bases: Atom

The difference \(1 - x\) with domain {x : 0 < x < 1}.

This atom is log-log concave.

Parameters:¶

x¶: An Expression.

perspective ¶

class cvxpy.atoms.perspective.perspective(f: Expression, s: Variable, f_recession: Expression = None)[source]¶

Bases: Atom

Implements the perspective transform of a convex or concave scalar expression. Uses the fact that given a cone form for the epigraph of \(f\) via

\(\{ (t, x) \in \mathbb{R}^{n+1} : t \geq f(x) \}\) \(= \{ (t,x) : Fx + gt + e \in K \},\)

the epigraph of the perspective transform of f can be given by

\(\{ (t, x, s) \in \mathbb{R}^{n+2} : t \geq sf(x/s) \}\) \(= \{ (t,x,s) : Fx + gt + se \in K \},\)

(see https://web.stanford.edu/~boyd/papers/pdf/sw_aff_ctrl.pdf).

Note that this is the perspective transform of a scalar expression viewed as a function of its underlying variables. The perspective atom does not return a Callable, so you cannot create compositions such as \(p(g(x),s)\), where \(p(z,s) = sf(z/s)\) is the perpective transform of \(f\).

pf_eigenvalue ¶

class cvxpy.atoms.pf_eigenvalue.pf_eigenvalue(X)[source]¶

Bases: Atom

The Perron-Frobenius eigenvalue of a positive matrix.

For an elementwise positive matrix \(X\), this atom represents its spectral radius, i.e., the magnitude of its largest eigenvalue. Because \(X\) is positive, the spectral radius equals its largest eigenvalue, which is guaranteed to be positive.

This atom is log-log convex.

Parameters:¶

X : cvxpy.Expression¶: A positive square matrix.

pnorm ¶

cvxpy.atoms.pnorm.pnorm(x, p: int | str = 2, axis=None, keepdims: bool = False, max_denom: int = 1024, approx: bool = True)[source]¶

Factory function for a mathematical p-norm.

Parameters:¶

p : numeric type or string¶: The type of norm to construct; set this to np.inf or ‘inf’ to construct an infinity norm.

Returns:¶

A norm1, norm_inf, or Pnorm object.

Return type:¶

Atom

Pnorm ¶

class cvxpy.atoms.pnorm.Pnorm(x, p: int = 2, axis=None, keepdims: bool = False, max_denom: int = 1024)[source]¶

The vector p-norm, for p not equal to 1 or infinity.

If given a matrix variable, pnorm will treat it as a vector, and compute the p-norm of the concatenated columns. Only accepts p values that are not equal to 1 or infinity; the norm1 and norm_inf classes handle those norms.

For \(p > 1\), the p-norm is given by

\[\|x\|_p = \left(\sum_i |x_i|^p \right)^{1/p},\]

with domain \(x \in \mathbf{R}^n\).

For \(p < 1,\ p \neq 0\), the p-norm is given by

\[\|x\|_p = \left(\sum_i x_i^p \right)^{1/p},\]

with domain \(x \in \mathbf{R}^n_+\).

Note that the “p-norm” is actually a norm only when \(p > 1\). For these cases, it is convex.
The expression is not defined when \(p = 0\).
Otherwise, when \(p < 1\), the expression is concave, but it is not a true norm.

Note

Generally, p cannot be represented exactly, so a rational, i.e., fractional, approximation must be made.

Internally, pnorm computes a rational approximation to the reciprocal \(1/p\) with a denominator up to max_denom. The resulting approximation can be found through the attribute pnorm.p. The approximation error is given by the attribute pnorm.approx_error. Increasing max_denom can give better approximations.

When p is an int or Fraction object, the approximation is usually exact.

Parameters:¶

x : cvxpy.Variable¶: The value to take the norm of.
p : int, float, or Fraction¶: We require that \(p > 1\), but \(p \neq \infty\). See the norm1 and norm_inf classes for these norms, or use the pnorm function wrapper to instantiate them.

max_denomint: The maximum denominator considered in forming a rational approximation for p.
axis0 or 1: The axis to apply the norm to.

Returns:¶: An Expression representing the norm.
Return type:¶: Expression

ptp ¶

cvxpy.atoms.ptp.ptp(x, axis=None, keepdims=False)[source]¶

Range of values (maximum - minimum) along an axis.

The name of the function comes from the acronym for ‘peak to peak’.

prod ¶

cvxpy.atoms.prod.prod(expr, axis=None, keepdims: bool = False) → Prod[source]¶

Multiply the entries of an expression.

The semantics of this atom are the same as np.prod.

This atom is log-log affine, but it is neither convex nor concave.

Parameters:¶

expr : Expression or list[Expression, Numeric]¶: The expression to multiply the entries of, or a list of Expressions and numeric types.
axis : int¶: The axis along which to take the product; ignored if expr is a list.
keepdims : bool¶: Whether to drop dimensions after taking the product; ignored if expr is a list.

quad_form ¶

cvxpy.atoms.quad_form.quad_form(x, P, assume_PSD: bool = False)[source]¶

Alias for \(x^T P x\).

Parameters:¶

x : vector argument.¶
P : matrix argument.¶
assume_PSD : P is assumed to be PSD without checking.¶

quad_over_lin ¶

class cvxpy.atoms.quad_over_lin.quad_over_lin(x, y, axis: int | tuple[int, ...] | None = None, keepdims: bool = False)[source]¶

Bases: AxisAtom

\((sum_{ij}X^2_{ij})/y\)

When axis is specified, computes the sum of squares along that axis, returning a vector instead of a scalar.

resolvent ¶

cvxpy.atoms.eye_minus_inv.resolvent(X, s: float)[source]¶

The resolvent of a positive matrix, \((sI - X)^{-1}\).

For an elementwise positive matrix \(X\) and a positive scalar \(s\), this atom computes

\[(sI - X)^{-1},\]

and it enforces the constraint that the spectral radius of \(X/s\) is at most \(1\).

This atom is log-log convex.

Parameters:¶

X : cvxpy.Expression¶: A positive square matrix.
s : cvxpy.Expression or numeric¶: A positive scalar.

sigma_max ¶

class cvxpy.atoms.sigma_max.sigma_max(A)[source]¶

Bases: Atom

Maximum singular value.

std ¶

cvxpy.atoms.stats.std(x, axis=None, keepdims=False, ddof=0)[source]¶

Returns the standard deviation of x.

ddof is the quantity to use in the Bessel correction.

sum_largest ¶

class cvxpy.atoms.sum_largest.sum_largest(x, k)[source]¶

Bases: Atom

Sum of the largest k values in the expression X

sum_smallest ¶

cvxpy.atoms.sum_smallest.sum_smallest(x, k)[source]¶: Sum of the smallest k values.

sum_squares ¶

cvxpy.atoms.sum_squares.sum_squares(expr, axis: int | tuple[int, ...] | None = None, keepdims: bool = False)[source]¶

The sum of the squares of the entries.

Parameters:¶

expr : Expression¶: The expression to take the sum of squares of.
axis : int or tuple of int, optional¶: The axis or axes along which to compute the sum of squares. If None (default), sums over all elements and returns a scalar. If an int, sums over that axis. If a tuple, sums over multiple axes.
keepdims : bool, optional¶: If True, the reduced axes are retained as dimensions with size 1. Default is False.

Returns:¶

An expression representing the sum of squares. Scalar if axis is None, otherwise a vector/array (or with keepdims=True, retains shape with reduced dimensions as 1).

Return type:¶

Expression

SuppFuncAtom ¶

class cvxpy.atoms.suppfunc.SuppFuncAtom(y, parent)[source]¶

tr_inv ¶

cvxpy.atoms.tr_inv.tr_inv(X) → None[source]¶: \(\mathrm{tr}\left(X^{-1} \right),\) where \(X\) is positive definite.

tv ¶

cvxpy.atoms.total_variation.tv(value, *args)[source]¶

Total variation of a vector, matrix, or list of matrices.

Uses L1 norm of discrete gradients for vectors and L2 norm of discrete gradients for matrices.

Parameters:¶

value : Expression or numeric constant¶: The value to take the total variation of.
args : Matrix constants/expressions¶: Additional matrices extending the third dimension of value.

Returns:¶

An Expression representing the total variation.

Return type:¶

Expression

var ¶

cvxpy.atoms.stats.var(x, axis=None, keepdims=False, ddof=0)[source]¶

Returns the variance of x.

ddof is the quantity to use in the Bessel correction.

von_neumann_entr ¶

class cvxpy.von_neumann_entr(X, quad_approx: tuple[int, ...] = ())[source]¶

Bases: Atom

Represents the von Neumann Entropy of the positive-definite matrix \(X,\)

\[-\operatorname{tr}(X \log X).\]

Mathematically, this is equivalent to

\[\texttt{von_neumann_entr}(X) = -\textstyle\sum_{i=1}^n \lambda_i \log \lambda_i\]

where \(\lambda_{i}\) are the eigenvalues of \(X.\)

Parameters:¶

X : Expression or numeric¶: A PSD matrix
quad_approx : Tuple[int,...]¶: This is either an empty tuple (default) or a 2-tuple. If a 2-tuple, then this atom is approximately canonicalized. The approximations replace ExpCone constraints with SOC constraints based on a quadrature scheme from https://arxiv.org/abs/1705.00812; quad_approx[0] is the number of quadrature nodes and quad_approx[1] is the number of scaling points in the quadrature scheme.

Notes

This function does not assume \(\operatorname{tr}(X)=1,\) which would be required for most uses of this function in the context of quantum information theory.