Other Atoms

The atoms listed here are neither affine nor elementwise.

cummax

class cvxpy.atoms.cummax.cummax(x, axis=None)[source]

Bases: cvxpy.atoms.axis_atom.AxisAtom

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

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

tuple of Fractions – A rational approximation of p/sum(p).

approx_error

float – The error in approximating p/sum(p) with w, 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)\).

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)[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: cvxpy.atoms.atom.Atom

\(\log\det A\)

log_sum_exp

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

Bases: cvxpy.atoms.axis_atom.AxisAtom

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

matrix_frac

cvxpy.atoms.matrix_frac.matrix_frac(X, P)[source]

tr X.T*P^-1*X

max

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

Bases: cvxpy.atoms.axis_atom.AxisAtom

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

min

cvxpy.atoms.min.min(x, axis=None)[source]

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

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:

Expression

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:

Expression

norm1

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

Bases: cvxpy.atoms.axis_atom.AxisAtom

norm_inf

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

Bases: cvxpy.atoms.axis_atom.AxisAtom

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 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=2, axis=None, keepdims=False, max_denom=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_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_form

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

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

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_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