Atoms

An atom (with a lower-case “a”) is a mathematical function that can be applied to Expression objects and returns an Expression object.

Atoms and compositions thereof are precisely the mechanisms that allow you to build up mathematical expression trees in CVXPY.

Every atom is tagged with information about its domain, sign, curvature, log-log curvature, and monotonicity; this information lets atom instances reason about whether or not they are DCP or DGP. See the Atomic Functions page for a compact, accessible summary of each atom’s attributes.

Representation of atoms

From an implementation perspective, an atom might be the constructor for some class. For example, the atom \(X \mapsto \lambda_{\max}(X)\) is applied by constructing an instance of the lambda_max class, which inherits directly from Atom and indirectly from Expression. Most atoms are implemented this way.

Alternatively, an atom be a wrapper that initializes and returns an Atom of some other class. For example, running

import cvxpy as cp
X = cp.Variable(shape=(2,2), symmetric=True)
expr = cp.lambda_min(X)
print(type(expr))

shows

<class 'cvxpy.atoms.affine.unary_operators.NegExpression'>

This happens because (1) CVXPY implements lambda_min() as

\[\lambda_{\min}(X) = -\lambda_{\max}(-X),\]

(2) the negation operator is a class-based atom, and (3) the precise type of an Expression is based on the last class-based atom applied to it (if any such atom has been applied).

Atom

class cvxpy.atoms.atom.Atom(*args)[source]

Bases: Expression

Abstract base class for atoms.

property domain : list[Constraint]

A list of constraints describing the closure of the region where the expression is finite.

property grad

Gives the (sub/super)gradient of the expression w.r.t. each variable.

Matrix expressions are vectorized, so the gradient is a matrix. None indicates variable values unknown or outside domain.

Returns:

A map of variable to SciPy CSC sparse matrix or None.

is_atom_affine() → bool[source]

Is the atom affine?

abstractmethod is_atom_concave() → bool[source]

Is the atom concave?

abstractmethod is_atom_convex() → bool[source]

Is the atom convex?

is_atom_log_log_affine() → bool[source]

Is the atom log-log affine?

is_atom_log_log_concave() → bool[source]

Is the atom log-log concave?

is_atom_log_log_convex() → bool[source]

Is the atom log-log convex?

abstractmethod is_decr(idx) → bool[source]

Is the composition non-increasing in argument idx?

abstractmethod is_incr(idx) → bool[source]

Is the composition non-decreasing in argument idx?