3.11. Supported Building Blocks¶

Note

Read Objective and Constraints first. Then use this page as a compact catalog when you know what role a term should play in the model and need the right built-in atom or declaration.

This page is easiest to use after you can already separate a model into three questions:

what measures mismatch to the data?
what kind of solution do you prefer among many plausible ones?
what must hold exactly, with no trade-off allowed?

Once you know which question you are answering, jump to the matching section below and then use the compact tables near the end as a lookup reference.

How this reference is organized¶
Modeling role	Typical object family	Where it appears
fit or likelihood	elementwise losses	scalar objective after aggregation
regularization or structure	vector and matrix penalties	scalar objective
hard feasibility	domain constraints and structural declarations	explicit constraints or variable attributes

3.11.1. Three Modeling Roles¶

Most models mix all three roles, but it helps to keep them conceptually separate:

fit measures how well the current variables explain the observations. It is usually built from elementwise losses on residuals, margins, or probabilities, then aggregated into one scalar.
regularization or soft structure expresses a preference rather than a rule. It can encourage sparsity, small norm, smoothness, or low rank, but the solver may accept some of the unwanted behavior if that improves the overall trade-off.
hard feasibility defines the admissible set. Bounds, cone membership, symmetry, nonnegativity, and exact conservation laws belong here. Violating one of these conditions makes the point infeasible.

3.11.2. Worked Example: One Model, Three Roles¶

Suppose you want a nonnegative sparse weight vector that fits data robustly and stays within a hard budget:

model = admm.Model()
x = admm.Var("x", n, nonneg=True)
lam = 0.1
tau = 3.0

fit = admm.sum(admm.huber(A @ x - b, 1.0))
regularization = lam * admm.norm(x, ord=1)

model.setObjective(fit + regularization)
model.addConstr(admm.sum(x) <= tau)

Read this model by role:

admm.sum(admm.huber(A @ x - b, 1.0)) is the fit term: it matches data while softening the effect of outliers.
lam * admm.norm(x, ord=1) is a soft structural preference: it encourages sparsity, but does not require exact zeros.
nonneg=True and admm.sum(x) <= tau are hard feasibility: every accepted solution must stay nonnegative and respect the budget.

A useful modeling habit is to ask whether a structure should be soft or hard. Sparsity often starts as an L1 penalty, while sign, interval, and cone restrictions are usually cleaner as feasibility conditions.

3.11.3. Elementwise Atoms¶

Elementwise atoms are the usual starting point for fit terms. They act entrywise on residuals, scores, or probabilities and are then aggregated into a scalar objective. The table examples below show the expression of the atoms.

Elementwise atoms¶
Example	Application
`admm.abs(r)`	robust fitting
`admm.square(r)`	least squares regression
`admm.huber(r, 1.0)`	outlier-robust regression
`admm.logistic(z, 1)`	sparse logistic regression
`admm.squared_hinge(t)`	large-margin learning
`admm.entropy(p)`	probabilistic modeling
`admm.kl_div(p, q)`	distribution matching

Wrap with sum() when you need a scalar objective.

admm.sum(admm.square(A @ x - b))
admm.sum(admm.huber(A @ x - b, 1.0))
admm.sum(admm.logistic(-y * (X @ w + v), 1))  # logistic(z, 1) = log(exp(z) + 1)
admm.sum(admm.kl_div(p, q))

3.11.4. Vector and Matrix Atoms¶

These atoms act on whole vectors or matrices and usually define the regularization or soft-structure part of the objective.

Typical examples include \(\|x\|_1\), \(\|x\|_2^2\), \(\|X\|_*\), and \(-\log\det(X)\).

Vector and matrix atoms¶
Example	Application
`lam * admm.norm(x, ord=1)`	l1 regularization
`lam * admm.sum(admm.square(x))`	ridge regularization
`admm.norm(A @ X - B, ord="fro")`	matrix fitting
`admm.norm(L, ord="nuc")`	low-rank matrix completion
`admm.trace(S @ X)`	covariance matrix estimation
`-admm.log_det(X) + admm.trace(S @ X)`	precision-matrix estimation

Representative examples:

admm.sum(admm.square(A @ x - b)) + lam * admm.norm(x, ord=1)    # Lasso
admm.norm(L, ord="nuc") + mu * admm.sum(admm.abs(S))            # Robust PCA
-admm.log_det(X) + admm.trace(S @ X)                            # Sparse covariance

3.11.5. Structural Variable Attributes and Domain Constraints¶

Use this section when the property must hold exactly rather than be traded off in the objective. Some structure is best written directly as a feasible set rather than as an atom. Typical examples are sign restrictions, symmetry, diagonal structure, and PSD or NSD cones, e.g. \(x \in \mathbb{R}_+^n\) or \(X \in \mathbb{S}_+^p\). These are hard constraints. For example, instead of penalizing violations of \(1 \le x + 1 \le 3\), model the interval directly:

x = admm.Var("x")
model.addConstr(admm.inrange(x + 1, 1, 3))  # enforce 1 <= x + 1 <= 3

This is zero on the admissible interval and infeasible outside it, so it is a hard constraint.

Structural variable attributes and domain constraints¶
Structure	Syntax
nonnegativity	`x = admm.Var("x", n, nonneg=True)` or `model.addConstr(x >= 0)`
nonpositivity	`x = admm.Var("x", n, nonpos=True)` or `model.addConstr(x <= 0)`
symmetry	`S = admm.Var("S", n, n, symmetric=True)`
diagonal structure	`D = admm.Var("D", n, n, diag=True)`
PSD structure	`X = admm.Var("X", n, n, PSD=True)` or `model.addConstr(X >> 0)`
NSD structure	`X = admm.Var("X", n, n, NSD=True)` or `model.addConstr(X << 0)`
interval restriction	`admm.inrange(x, lb, ub)`

Representative example:

model = admm.Model()
x = admm.Var("x", n, nonneg=True)   # Nonnegative vector
X = admm.Var("X", n, n, PSD=True)   # PSD matrix variable

model.addConstr(admm.sum(x) == 1)   # Probability-simplex constraint
model.addConstr(admm.trace(X) == 1) # Normalize matrix scale

3.11.6. Compact Atom Reference¶

The tables below provide a compact lookup view when you want to check the output type, the typical usage syntax, and the corresponding mathematical expression of the atoms.

Elementwise Atoms

Elementwise atoms¶
Example	Output	Meaning
`admm.abs(x)`	same shape	\(f(x)=\lvert x\rvert\)
`admm.exp(x)`	same shape	\(f(x)=e^x\)
`admm.power(x, p)`	same shape	\(f(x)=x^p\)
`admm.square(x)`	same shape	\(f(x)=x^2\)
`admm.sqrt(x)`	same shape	\(f(x)=\sqrt{x}\)
`admm.log(x)`	same shape	\(f(x)=\log(x)\)
`admm.logistic(x, b)`	same shape	\(f(x,b)=\log(e^x+b)\)
`admm.huber(x, delta)`	same shape	\(f(x,d)=\begin{cases}\tfrac12 x^2,&\lvert x\rvert\le d\\d\lvert x\rvert-\tfrac12 d^2,&\text{otherwise}\end{cases}\)
`admm.squared_hinge(x)`	same shape	\(f(x)=\max(1-x,0)^2\)
`admm.entropy(x)`	same shape	\(f(x)=x\log(x)\) (Shannon entropy is `-admm.sum(admm.entropy(x))`)
`admm.kl_div(x, y)`	same shape	\(f(x,y)=x\log(x/y)\)
`admm.maximum(x, y)`	same shape	\(f_{\max}(x,y)=\max(x,y)\)
`admm.minimum(x, y)`	same shape	\(f_{\min}(x,y)=\min(x,y)\)
`admm.inrange(x, lb, ub)`	same shape	\(f(x)=\begin{cases}0,&x\in[\mathrm{lb},\mathrm{ub}]\\+\infty,&\text{otherwise}\end{cases}\)
`admm.bathtub(x, d)`	same shape	\(f(x,d)=\max(\lvert x\rvert-d,0)\)
`admm.squared_bathtub(x, d)`	same shape	\(f(x,d)=\tfrac12\max(\lvert x\rvert-d,0)^2\)
`admm.scalene(x, a, b)`	same shape	\(f(x,a,b)=a\min(x,0)+b\max(x,0)\)

Aggregation and Norm Atoms

Aggregation and norm atoms¶
Example	Output	Meaning
`admm.sum(x)`	scalar	\(f(x)=\sum_i x_i\)
`admm.max(x)`	scalar	\(f(x)=\max_i x_i\)
`admm.min(x)`	scalar	\(f(x)=\min_i x_i\)
`admm.norm(x, ord=1)`	scalar	\(f(x)=\lVert x\rVert_1\)
`admm.norm(X, ord=1)`	scalar	\(f(X)=\max_j \sum_i \lvert X_{ij}\rvert\)
`admm.norm(x, ord=2)`	scalar	\(f(x)=\lVert x\rVert_2\)
`admm.norm(X, ord=2)`	scalar	\(f(X)=\lVert X\rVert_2\)
`admm.norm(x, ord=inf)`	scalar	\(f(x)=\lVert x\rVert_\infty\)
`admm.norm(X, ord=inf)`	scalar	\(f(X)=\max_i \sum_j \lvert X_{ij}\rvert\)
`admm.norm(X, ord="fro")`	scalar	\(f(X)=\lVert X\rVert_F\)
`admm.norm(X, ord="nuc")`	scalar	\(f(X)=\lVert X\rVert_*\)
`x @ Q @ x`	scalar	\(f(x)=x^\top Qx\)
`admm.vapnik(x, eps)`	scalar	\(f(x)=\max(\lVert x\rVert_2-\epsilon,0)\)

Note

When ord is omitted, admm.norm returns the L2 norm for vectors and the Frobenius norm for matrices.

Matrix, Cone, and Structure Atoms

Matrix, cone, and structure atoms¶
Example	Output	Meaning
`admm.trace(X)`	scalar	\(f(X)=\operatorname{tr}(X)\)
`admm.log_det(X)`	scalar	\(f(X)=\log(\det(X)),\ X \succ 0\)
`admm.diag(x)`	vector or matrix	\(\operatorname{diag}(\cdot)\ \text{extraction/construction}\)
`admm.Var("X", n, n, PSD=True)`	variable	create a PSD matrix variable \(X\)
`model.addConstr(X >> 0)`	constraint	add a PSD cone constraint \(X \succeq 0\)
`model.addConstr(admm.norm(x) <= r)`	constraint	add a L2-ball constraint \(\lVert x\rVert_2 \le r\)
`model.addConstr(admm.norm(x) <= s)`	constraint	add a second-order cone constraint \((x,s)\in\{(x,s): \lVert x\rVert_2 \le s\}\)

TV and Convolution Atoms

TV and Convolution atoms¶
Example	Output	Meaning
`admm.tv1d(x)`	scalar	\(f(x)=\sum_i \lvert x_{i+1}-x_i\rvert\)
`admm.tv2d(X)`	scalar	\(f(X)=\sum\lvert \partial_i X\rvert+\sum\lvert \partial_j X\rvert\) for the default case `p=1`
`admm.conv2d(x, k, mode)`	array	\(\text{2D convolution}\)
`admm.corr2d(x, k, mode)`	array	\(\text{2D cross-correlation}\)

For advanced rewrite behavior over these atoms, see Symbolic Canonicalization. For extensions beyond the built-in catalog, see User-Defined Proximal Extensions.