Other Atoms¶

The atoms listed here are neither affine nor elementwise.

cummax¶

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

Bases: cvxpy.atoms.axis_atom.AxisAtom

Cumulative maximum.

eye_minus_inv¶

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

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

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]

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]

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]

$$\log\det A$$

log_sum_exp¶

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

Bases: cvxpy.atoms.axis_atom.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=None, keepdims: bool = False)[source]

Bases: cvxpy.atoms.axis_atom.AxisAtom

$$\max_{i,j}\{X_{i,j}\}$$.

min¶

cvxpy.atoms.min.min(x, axis=None, keepdims: bool = False) → None[source]

$$\min{i,j}\{X_{i,j}\}$$.

mixed_norm¶

cvxpy.atoms.mixed_norm.mixed_norm(X, p: Union[int, str] = 2, q: Union[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: Union[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=None, keepdims: bool = False)[source]

Bases: cvxpy.atoms.axis_atom.AxisAtom

norm_inf¶

class cvxpy.atoms.norm_inf(expr, axis=None, keepdims: bool = False)[source]

Bases: cvxpy.atoms.axis_atom.AxisAtom

normNuc¶

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

Sum of the singular values.

one_minus_pos¶

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

The difference $$1 - x$$ with domain {x : 0 < x < 1}.

This atom is log-log concave.

Parameters

x (Expression) – An Expression.

pf_eigenvalue¶

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

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: Union[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) → cvxpy.atoms.prod.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.

cvxpy.atoms.quad_form.quad_form(x, P)[source]

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

class cvxpy.atoms.quad_over_lin.quad_over_lin(x, y)[source]

$$(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]

Maximum singular value.

sum_largest¶

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

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

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