其他原子

这里列出的原子既不是仿射的，也不是逐元素的。

cummax

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

Bases: AxisAtom

Cumulative maximum.

diff_pos

cvxpy.atoms.one_minus_pos.diff_pos(x, y)

The difference \(x - y\) with domain {x, y : x > y > 0}.

This atom is log-log concave.

Parameters:

• x (Expression) – An Expression.

• y (Expression) – An Expression.

排序点

class cvxpy.atoms.dotsort.dotsort(X, W)

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

逆矩阵减去单位矩阵

class cvxpy.atoms.eye_minus_inv.eye_minus_inv(X)

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.

几何平均

class cvxpy.atoms.geo_mean.geo_mean(x, p: List[int] | None = None, max_denom: int = 1024)

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

广义矩阵相乘

class cvxpy.atoms.gmatmul.gmatmul(A, X)

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.

调和平均

cvxpy.atoms.harmonic_mean.harmonic_mean(x)

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

逆积

cvxpy.atoms.inv_prod.inv_prod(value)

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

最大特征值

class cvxpy.atoms.lambda_max.lambda_max(A)

Bases: Atom

Maximum eigenvalue; \(\lambda_{\max}(A)\).

lambda_min

cvxpy.atoms.lambda_min.lambda_min(X)

Minimum eigenvalue; \(\lambda_{\min}(A)\).

lambda_sum_largest

cvxpy.atoms.lambda_sum_largest.lambda_sum_largest(X, k) → None

Sum of the largest k eigenvalues.

lambda_sum_smallest

cvxpy.atoms.lambda_sum_smallest.lambda_sum_smallest(X, k)

Sum of the largest k eigenvalues.

log_det

class cvxpy.atoms.log_det.log_det(A)

Bases: Atom

\(\log\det A\)

log_sum_exp

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

Bases: AxisAtom

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

matrix_frac

cvxpy.atoms.matrix_frac.matrix_frac(X, P) → None

tr X.T*P^-1*X

max

class cvxpy.atoms.max.max(x, axis: int | None = None, keepdims: bool = False)

Bases: AxisAtom

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

最小值

cvxpy.atoms.min.min(x, axis: int | None = None, keepdims: bool = False) → None

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

混合范数

cvxpy.atoms.mixed_norm.mixed_norm(X, p: int | str = 2, q: int | str = 1)

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

范数

cvxpy.atoms.norm.norm(x, p: int | str = 2, axis=None, keepdims: bool = False)

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

• keepdims (If this is set to True, the axes which are reduced are left) – in the result as dimensions with size one.

Returns:

An Expression representing the norm.

Return type:

Expression

norm1

class cvxpy.atoms.norm1.norm1(expr, axis: int | None = None, keepdims: bool = False)

Bases: AxisAtom

norm2

cvxpy.atoms.norm.norm2(x, axis=None)

The 2-norm of x.

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.

Returns:

An Expression representing the norm.

Return type:

Expression

norm_inf

class cvxpy.atoms.norm_inf(expr, axis: int | None = None, keepdims: bool = False)

Bases: AxisAtom

normNuc

class cvxpy.atoms.norm_nuc.normNuc(A)

Bases: Atom

Sum of the singular values.

one_minus_pos

class cvxpy.atoms.one_minus_pos(x)

Bases: Atom

The difference \(1 - x\) with domain {x : 0 < x < 1}.

This atom is log-log concave.

Parameters:

x (Expression) – An Expression.

透视

class cvxpy.atoms.perspective.perspective(f: Expression, s: Variable, f_recession: Expression | None = None)

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 \},\)

(see https://web.stanford.edu/~boyd/papers/pdf/sw_aff_ctrl.pdf).

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)

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)

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)

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

ptp

cvxpy.atoms.ptp.ptp(x, axis=None, keepdims=False)

Range of values (maximum - minimum) along an axis.

The name of the function comes from the acronym for ‘peak to peak’.

prod

cvxpy.atoms.prod.prod(expr, axis=None, keepdims: bool = False) → Prod

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.

quad_form

cvxpy.atoms.quad_form.quad_form(x, P, assume_PSD: bool = False)

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

Parameters:

• x (vector argument.) –

• P (matrix argument.) –

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

quad_over_lin

class cvxpy.atoms.quad_over_lin.quad_over_lin(x, y)

Bases: Atom

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

resolvent

cvxpy.atoms.eye_minus_inv.resolvent(X, s: float)

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)

Bases: Atom

Maximum singular value.

std

cvxpy.atoms.stats.std(x, axis=None, keepdims=False, ddof=0)

Returns the standard deviation of x.

ddof is the quantity to use in the Bessel correction.

sum_largest

class cvxpy.atoms.sum_largest.sum_largest(x, k)

Bases: Atom

Sum of the largest k values in the matrix X.

sum_smallest

cvxpy.atoms.sum_smallest.sum_smallest(x, k)

Sum of the smallest k values.

sum_squares

cvxpy.atoms.sum_squares.sum_squares(expr)

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)

tr_inv

cvxpy.atoms.tr_inv.tr_inv(X) → None

\(\mathrm{tr}\left(X^{-1} \right),\) where \(X\) is positive definite.

tv（总变差）

cvxpy.atoms.total_variation.tv(value, *args)

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

var

cvxpy.atoms.stats.var(x, axis=None, keepdims=False, ddof=0)

Returns the variance of x.

ddof is the quantity to use in the Bessel correction.

von_neumann_entr

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

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