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

## 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: List[int] | None = None, max_denom: int = 1024)[source]

Bases: Atom

The (weighted) geometric mean of vector x, with optional powers given by p:

$\left(x_1^{p_1} \cdots x_n^{p_n} \right)^{\frac{1}{\mathbf{1}^Tp}}$

The powers p can be a list, tuple, or numpy.array of nonnegative int, float, or Fraction objects with nonzero sum.

If not specified, p defaults to a vector of all ones, giving the unweighted geometric mean

$x_1^{1/n} \cdots x_n^{1/n}.$

The geometric mean includes an implicit constraint that $$x_i \geq 0$$ whenever $$p_i > 0$$. If $$p_i = 0$$, $$x_i$$ will be unconstrained.

The only exception to this rule occurs when p has exactly one nonzero element, say, p_i, in which case geo_mean(x, p) is equivalent to x_i (without the nonnegativity constraint). A specific case of this is when $$x \in \mathbf{R}^1$$.

Note

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

Internally, geo_mean immediately computes an approximate normalized weight vector $$w \approx p/\mathbf{1}^Tp$$ and the geo_mean atom is represented as

$x_1^{w_1} \cdots x_n^{w_n},$

where the elements of w are Fraction objects that sum to exactly 1.

The maximum denominator used in forming the rational approximation is given by max_denom, which defaults to 1024, but can be adjusted to modify the accuracy of the approximations.

The approximating w and the approximation error can be found through the attributes geo_mean.w and geo_mean.approx_error.

Examples

The weights w can be seen from the string representation of the geo_mean object, or through the w attribute.

>>> from cvxpy import Variable, geo_mean, Problem, Maximize
>>> x = Variable(3, name='x')
>>> print(geo_mean(x))
geo_mean(x, (1/3, 1/3, 1/3))
>>> g = geo_mean(x, [1, 2, 1])
>>> g.w
(Fraction(1, 4), Fraction(1, 2), Fraction(1, 4))


Floating point numbers with few decimal places can sometimes be represented exactly. The approximation error between w and p/sum(p) is given by the approx_error attribute.

>>> import numpy as np
>>> x = Variable(4, name='x')
>>> p = np.array([.12, .34, .56, .78])
>>> g = geo_mean(x, p)
>>> g.w
(Fraction(1, 15), Fraction(17, 90), Fraction(14, 45), Fraction(13, 30))
>>> g.approx_error
0.0


In general, the approximation is not exact.

>>> p = [.123, .456, .789, .001]
>>> g = geo_mean(x, p)
>>> g.w
(Fraction(23, 256), Fraction(341, 1024), Fraction(295, 512), Fraction(1, 1024))
>>> 1e-4 <= g.approx_error <= 1e-3
True


The weight vector p can contain combinations of int, float, and Fraction objects.

>>> from fractions import Fraction
>>> x = Variable(4, name='x')
>>> g = geo_mean(x, [.1, Fraction(1,3), 0, 2])
>>> print(g)
geo_mean(x, (3/73, 10/73, 0, 60/73))
>>> g.approx_error <= 1e-10
True


Sequences of Fraction and int powers can often be represented exactly.

>>> p = [Fraction(1,17), Fraction(4,9), Fraction(1,3), Fraction(25,153)]
>>> x = Variable(4, name='x')
>>> print(geo_mean(x, p))
geo_mean(x, (1/17, 4/9, 1/3, 25/153))


Terms with a zero power will not have an implicit nonnegativity constraint.

>>> p = [1, 0, 1]
>>> x = Variable(3, name='x')
>>> obj = Maximize(geo_mean(x,p))
>>> constr = [sum(x) <= 1, -1 <= x, x <= 1]
>>> val = Problem(obj, constr).solve()
>>> x = np.array(x.value).flatten()
>>> print(x)
[ 1. -1.  1.]

Parameters:
• x (Variable) – A column or row vector whose elements we will take the geometric mean of.

• p (Sequence (list, tuple, …) of int, float, or Fraction objects) –

A vector of weights for the weighted geometric mean

When p is a sequence of int and/or Fraction objects, w can often be an exact representation of the weights. An exact representation is sometimes possible when p has float elements with only a few decimal places.

• max_denom (int) – The maximum denominator to use in approximating p/sum(p) with geo_mean.w. If w is not an exact representation, increasing max_denom may offer a more accurate representation, at the cost of requiring more convex inequalities to represent the geometric mean.

w

A rational approximation of p/sum(p).

Type:

tuple of Fractions

approx_error

The error in approximating p/sum(p) with w, given by $$\|p/\mathbf{1}^T p - w \|_\infty$$

Type:

float

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

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 largest 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)[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.) –

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

## 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 (Expression) – An Expression.

## perspective¶

class cvxpy.atoms.perspective.perspective(f: Expression, s: Variable)[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 \},$$

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)[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

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

Alias for $$x^T P x$$.

Parameters:
• x (vector argument.) –

• P (matrix argument.) –

• assume_PSD (P is assumed to be PSD without checking.) –

Bases: Atom

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

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

## sum_largest¶

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

Bases: Atom

Sum of the largest k values in the matrix 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)[source]

The sum of the squares of the entries.

Parameters:

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

Returns:

An expression representing the sum of squares.

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

## von_neumann_entr¶

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

Bases: Atom

Computes the Von Neumann Entropy of the positive-definite matrix $$X\in\mathbb{S}^n_{+}$$

$-\operatorname{tr}(X \operatorname{logm}(X))$

where $$\operatorname{tr}$$ is the trace and $$\operatorname{logm}$$ is the matrix logarithm

May alternatively be expressed as:
$\texttt{von_neumann_entr}(X) = -\textstyle\sum_{i=1}^n \lambda_i \log \lambda_i$
where $$\lambda_{i}$$ are the eigenvalues of $$X$$

This atom does not enforce $$\operatorname{tr}(X) = 1$$ as is expected in applications from quantum mechanics.

Parameters:

X (Expression or numeric) – A PSD matrix