Other Atoms¶
The atoms listed here are neither affine nor elementwise.
 cummax
 diff_pos
 eye_minus_inv
 geo_mean
 harmonic_mean
 lambda_max
 lambda_min
 lambda_sum_largest
 lambda_sum_smallest
 log_det
 log_sum_exp
 matrix_frac
 max
 min
 mixed_norm
 norm
 norm1
 norm2
 norm_inf
 normNuc
 one_minus_pos
 pf_eigenvalue
 pnorm
 Pnorm
 prod
 quad_form
 quad_over_lin
 resolvent
 sigma_max
 sum_largest
 sum_smallest
 sum_squares
 tv
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, …) of
int
,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 approximating
p/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
¶ tuple of
Fractions
– A rational approximation ofp/sum(p)
.

approx_error
¶ float – The error in approximating
p/sum(p)
withw
, given by \(\p/\mathbf{1}^T p  w \_\infty\)
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
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 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:
norm¶

cvxpy.atoms.norm.
norm
(x, p=2, axis=None)[source]¶ Wrapper on the different norm atoms.
Parameters:  x (Expression or numeric constant) – The value to take the norm of.
 p (int or str, optional) – The type of norm.
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.
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 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=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, 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_denom : int
 The maximum denominator considered in forming a rational approximation
for
p
.  axis : 0 or 1
 The axis to apply the norm to.
Returns: An Expression representing the norm. Return type: Expression
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\)
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¶

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: