Other Atoms¶
The atoms listed here are neither affine nor elementwise.
eye_minus_inv¶

class
cvxpy.atoms.eye_minus_inv.
eye_minus_inv
(X)[source]¶ Bases:
cvxpy.atoms.atom.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 loglog convex.
 Parameters
X (
cvxpy.Expression
) – A positive square matrix.
geo_mean¶

class
cvxpy.atoms.geo_mean.
geo_mean
(x, p=None, max_denom=1024)[source]¶ Bases:
cvxpy.atoms.atom.Atom
The (weighted) geometric mean of vector
x
, with optional powers given byp
:\[\left(x_1^{p_1} \cdots x_n^{p_n} \right)^{\frac{1}{\mathbf{1}^Tp}}\]The powers
p
can be alist
,tuple
, ornumpy.array
of nonnegativeint
,float
, orFraction
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 casegeo_mean(x, p)
is equivalent tox_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 thegeo_mean
atom is represented as\[x_1^{w_1} \cdots x_n^{w_n},\]where the elements of
w
areFraction
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 attributesgeo_mean.w
andgeo_mean.approx_error
.Examples
The weights
w
can be seen from the string representation of thegeo_mean
object, or through thew
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
andp/sum(p)
is given by theapprox_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)) >>> 1e4 <= g.approx_error <= 1e3 True
The weight vector
p
can contain combinations ofint
,float
, andFraction
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 <= 1e10 True
Sequences of
Fraction
andint
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
,)
ofint
,float
, orFraction
objects) –A vector of weights for the weighted geometric mean
When
p
is a sequence ofint
and/orFraction
objects,w
can often be an exact representation of the weights. An exact representation is sometimes possible whenp
hasfloat
elements with only a few decimal places.max_denom (
int
) – The maximum denominator to use in approximatingp/sum(p)
withgeo_mean.w
. Ifw
is not an exact representation, increasingmax_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
ofFractions

approx_error
¶ The error in approximating
p/sum(p)
withw
, given by \(\p/\mathbf{1}^T p  w \_\infty\) Type
float
gmatmul¶

class
cvxpy.atoms.gmatmul.
gmatmul
(A, X)[source]¶ Bases:
cvxpy.atoms.atom.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 loglog 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
ornumeric
) – 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
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
ornumeric
) – 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
lambda_max¶

class
cvxpy.atoms.lambda_max.
lambda_max
(A)[source]¶ Bases:
cvxpy.atoms.atom.Atom
Maximum eigenvalue; \(\lambda_{\max}(A)\).
log_det¶

class
cvxpy.atoms.log_det.
log_det
(A)[source]¶ Bases:
cvxpy.atoms.atom.Atom
\(\log\det A\)
mixed_norm¶

cvxpy.atoms.mixed_norm.
mixed_norm
(X, p=2, q=1)[source]¶ Lp,q norm; \((\sum_k (\sum_l \lvert x_{k,l} \rvert^p)^{q/p})^{1/q}\).
 Parameters
X (
Expression
ornumeric constant
) – The matrix to take the l_{p,q} norm of.p (
int
orstr
, optional) – The type of inner norm.q (
int
orstr
, optional) – The type of outer norm.
 Returns
An Expression representing the mixed norm.
 Return type
norm¶

cvxpy.atoms.norm.
norm
(x, p=2, axis=None)[source]¶ Wrapper on the different norm atoms.
 Parameters
x (
Expression
ornumeric constant
) – The value to take the norm of. If x is 2D and axis is None, this function constructs a matrix norm.p (
int
orstr
, 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
toapply the norm
,if any.
) –
 Returns
An Expression representing the norm.
 Return type
normNuc¶

class
cvxpy.atoms.norm_nuc.
normNuc
(A)[source]¶ Bases:
cvxpy.atoms.atom.Atom
Sum of the singular values.
one_minus_pos¶

class
cvxpy.atoms.
one_minus_pos
(x)[source]¶ Bases:
cvxpy.atoms.atom.Atom
The difference \(1  x\) with domain {x : 0 < x < 1}.
This atom is loglog concave.
 Parameters
x (
Expression
) – An Expression.
pf_eigenvalue¶

class
cvxpy.atoms.pf_eigenvalue.
pf_eigenvalue
(X)[source]¶ Bases:
cvxpy.atoms.atom.Atom
The PerronFrobenius 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 loglog convex.
 Parameters
X (
cvxpy.Expression
) – A positive square matrix.
pnorm¶

cvxpy.atoms.pnorm.
pnorm
(x, p=2, axis=None, keepdims=False, max_denom=1024)[source]¶ Factory function for a mathematical pnorm.
 Parameters
p (
numeric type
orstring
) – 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
Pnorm¶

class
cvxpy.atoms.pnorm.
Pnorm
(x, p=2, axis=None, keepdims=False, max_denom=1024)[source]¶ The vector pnorm, for p not equal to 1 or infinity.
If given a matrix variable,
pnorm
will treat it as a vector, and compute the pnorm 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 pnorm 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 pnorm is given by
\[\x\_p = \left(\sum_i x_i^p \right)^{1/p},\]with domain \(x \in \mathbf{R}^n_+\).
Note that the “pnorm” 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 tomax_denom
. The resulting approximation can be found through the attributepnorm.p
. The approximation error is given by the attributepnorm.approx_error
. Increasingmax_denom
can give better approximations.When
p
is anint
orFraction
object, the approximation is usually exact. Parameters
x (
cvxpy.Variable
) – The value to take the norm of.p (
int
,float
, orFraction
) – 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
prod¶

cvxpy.atoms.prod.
prod
(expr, axis=None, keepdims=False)[source]¶ Multiply the entries of an expression.
The semantics of this atom are the same as np.prod.
This atom is loglog affine, but it is neither convex nor concave.
 Parameters
expr (
Expression
orlist[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_over_lin¶

class
cvxpy.atoms.quad_over_lin.
quad_over_lin
(x, y)[source]¶ Bases:
cvxpy.atoms.atom.Atom
\((sum_{ij}X^2_{ij})/y\)
resolvent¶

cvxpy.atoms.eye_minus_inv.
resolvent
(X, s)[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 loglog convex.
 Parameters
X (
cvxpy.Expression
) – A positive square matrix.s (
cvxpy.Expression
ornumeric
) – A positive scalar.
sigma_max¶

class
cvxpy.atoms.sigma_max.
sigma_max
(A)[source]¶ Bases:
cvxpy.atoms.atom.Atom
Maximum singular value.
sum_largest¶

class
cvxpy.atoms.sum_largest.
sum_largest
(x, k)[source]¶ Bases:
cvxpy.atoms.atom.Atom
Sum of the largest k values in the matrix X.
sum_squares¶
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
ornumeric 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