PyTorch, JAX and PyProximal reference¶
Any operator as a differentiable function in PyTorch and JAX, and image TV on the input's device (CUDA, MPS or the CPU). See the API guide for how gradients are computed.
fastprox.torch¶
PyTorch wrappers (since 0.3): the operators as torch.autograd.Function
s, differentiated by the library's own JVP and VJP rather than through any
iterations::
import fastprox as fp
import fastprox.torch as fpt
z = fpt.prox(fp.TV1D(), x, gamma) # gradients for x and gamma
z = fpt.prox(fp.TV1D, x, gamma, weights=w) # and for the weights
op is an operator, or an operator class with its constructor arguments
as keywords: float tensors among them that require grad receive the
gradient of the parameter of that name (Grads fields, see
:meth:fastprox.Operator.vjp); other arguments are constants. Reverse mode
(backward, torch.autograd.grad) and forward mode
(torch.autograd.forward_ad) are supported; not the torch.func
transforms, which hand the derivatives wrapped tensors that cannot be read as
NumPy arrays. Second-order reverse mode (create_graph=True, as in
torch.autograd.functional.hvp and hessian) raises RuntimeError
until 1.0.x, rather than returning a Hessian without the prox's own second
derivatives. The
computation runs on the CPU in float32 or float64; tensors on another device
are copied to the CPU and the result back.
:func:tv_iso and :func:tv_aniso instead solve isotropic and anisotropic
TV in tensor operations on the input's device, GPU included, with a backward
on the flat regions of the solution (see fastprox._tv_torch).
Spectral operators (since 1.0) go through :func:prox too, as an operator
(fp.NuclearNorm(0.5)) or a class with its parameter
(fp.NuclearNorm, lam=t). The SVD or eigendecomposition and the matrix
products run in torch on the input's device; the prox of the spectrum and the
k x k core of the derivative run on the CPU.
prox(op, x, gamma=1.0, *, axis=None, threads=0, tol=None, ztol=None, max_iter=None, deriv_tol=None, deriv_max_iter=10000, **params)
¶
\(\operatorname{prox}_{\gamma g}(x)\) as a differentiable tensor. gamma may be a tensor
that requires grad: 0-d, or (since 1.0) one step per row, image or
matrix, broadcasting to the batch shape (x's shape without axis,
the image axes or the matrix axes); each step's gradient is
\(\langle g, \partial z / \partial \gamma \rangle\) over its rows, at the cost of one more JVP.
axis (row operators), tol, ztol and max_iter (iterative
operators) are passed on when given. deriv_tol and deriv_max_iter
(since 1.0) are the tol and max_iter of the derivatives'
:meth:fastprox.Operator.vjp and jvp: they control isotropic TV's
conjugate gradients, as in :func:tv_iso, and are ignored elsewhere.
prox_conj(op, y, sigma=1.0, *, axis=None, threads=0, tol=None, ztol=None, max_iter=None, deriv_tol=None, deriv_max_iter=10000, **params)
¶
\(\operatorname{prox}_{\sigma g^*}(y)\) as a differentiable tensor (Moreau's identity);
sigma as gamma in :func:prox, but a scalar.
tv_iso(x, gamma=1.0, *, ndim=2, weights=None, pixel_weights=None, tol=None, ztol=None, max_iter=1000, warm_start=None, return_info=False, deriv_tol=None, deriv_max_iter=10000, warn=True)
¶
Isotropic TV of TVIso(ndim, weights) on the last ndim axes of
x, computed in tensor operations on x's device and differentiable
in x, gamma and weights (tensors that require grad), forward
and reverse. gamma is a number or one step per image: a tensor that
broadcasts to the batch shape x.shape[:-ndim]. Each image stops when its duality gap is at most
\(\mathrm{tol} \cdot \lVert x \rVert_2^2 / 2\) (tol defaults to 1e-6), which certifies
\(\lVert z - z^* \rVert_2 \le \sqrt{\mathrm{tol}}\,\lVert x \rVert_2\); ztol (since 1.0)
asks for that relative error of \(z\) instead (tol \(= \mathrm{ztol}^2\)). Without either,
:func:fastprox.inner_accuracy sets ztol. A solve that stops at max_iter raises
:class:fastprox.ConvergenceWarning unless warn=False. warm_start takes the dual of an earlier
call (shape (ndim, *x.shape), the C kernel's form). With
return_info=True returns (z, info), an :class:IterInfo whose
dual is a tensor. The derivatives are the C kernel's: one unknown per
flat region, solved by conjugate gradients to relative residual
deriv_tol; by default each image's solve stops at the relative error
of \(z\) that its gap certifies, \(\sqrt{2\,\mathrm{gap}} / \lVert x \rVert_2\), and at
\(\max(10^{-10}, 100\,\varepsilon)\) at the tightest. pixel_weights (since
0.3): \(\alpha \ge 0\) in \(\gamma \sum_p \alpha_p \lVert (w D z)_p \rVert_2\), a
tensor that broadcasts to x.shape (one map for every image, or one per image, e.g. predicted by a network),
differentiable like gamma.
tv_aniso(x, gamma=1.0, *, ndim=2, weights=None, edge_weights=None, tol=None, ztol=None, max_iter=1000, warm_start=None, return_info=False, deriv_tol=None, deriv_max_iter=10000, warn=True)
¶
Anisotropic TV of TVAniso(ndim, weights), as :func:tv_iso. A plain
dual method on the device (the C kernel's exact 1D steps and polish stay
on the CPU), so tight tolerances take more iterations than TVAniso;
the dual is in the C kernel's form (\(q_a\) with \(x - z = \sum_a q_a\)). Its
derivatives are exact region averages. edge_weights (since 0.3):
\(\beta \ge 0\) in
\(\gamma \sum_a w_a \sum_p \beta[a, \dots, p] \lvert z_{p + e_a} - z_p \rvert\), a
tensor that broadcasts to (ndim, *x.shape) (\(\beta[a]\) at the last entry
along \(a\) unused), differentiable like gamma.
fastprox.jax¶
JAX wrappers (since 0.3): the operators as jax.custom_vjp functions
over jax.pure_callback, differentiated by the library's own VJP rather
than through any iterations::
import fastprox as fp
import fastprox.jax as fpj
z = fpj.prox(fp.TV1D(), x, gamma) # gradients for x and gamma
z = fpj.prox(fp.TV1D, x, gamma, weights=w) # and for the weights
op is an operator, or an operator class with its constructor arguments
as keywords: JAX float arrays among them are traced and receive the
gradient of the parameter of that name (Grads fields, see
:meth:fastprox.Operator.vjp), NaN for a parameter without one (L0's
lam, for instance); Python and NumPy values are constants, and integer
arrays (groups, edges) must be concrete under jit. Works under
jit, grad and vmap (one call per batch element); reverse mode
only. The backward pass recomputes the prox to keep its structure, so a
gradient costs one prox and one VJP. Float64 needs jax_enable_x64.
:func:tv_iso and :func:tv_aniso instead solve isotropic and anisotropic
TV in JAX operations on the input's device, GPU included, under jit and
vmap, with a backward on the flat regions of the solution (see
fastprox._tv_jax).
Spectral operators (since 1.0) go through :func:prox too, as in
fastprox.torch. The decomposition and the matrix products run in JAX on
the input's device; the prox of the spectrum and the k x k core of the
derivative run in callbacks on the CPU.
prox(op, x, gamma=1.0, *, axis=None, threads=0, tol=None, ztol=None, max_iter=None, deriv_tol=None, deriv_max_iter=10000, **params)
¶
\(\operatorname{prox}_{\gamma g}(x)\). gamma is a scalar or (since 1.0) one step per
row, image or matrix, broadcasting to the batch shape, as in
:func:fastprox.torch.prox. axis (row operators), tol, ztol
and max_iter (iterative operators) are passed on when given;
deriv_tol and deriv_max_iter (since 1.0) as in
:func:fastprox.torch.prox.
prox_conj(op, y, sigma=1.0, *, axis=None, threads=0, tol=None, ztol=None, max_iter=None, deriv_tol=None, deriv_max_iter=10000, **params)
¶
\(\operatorname{prox}_{\sigma g^*}(y)\) (Moreau's identity), with a scalar sigma.
tv_iso(x, gamma=1.0, *, ndim=2, weights=None, pixel_weights=None, tol=None, ztol=None, max_iter=1000, warm_start=None, return_info=False, deriv_tol=None, deriv_max_iter=10000, warn=True)
¶
Isotropic TV of TVIso(ndim, weights) on the last ndim axes of
x, in JAX operations on x's device; differentiable (reverse
mode) in x, gamma and weights. gamma is a number or one
step per image, broadcasting to the batch shape x.shape[:-ndim]. Each image stops when its
duality gap is at most \(\mathrm{tol} \cdot \lVert x \rVert_2^2 / 2\) (tol defaults to
1e-6), which certifies \(\lVert z - z^* \rVert_2 \le \sqrt{\mathrm{tol}}\,\lVert x \rVert_2\);
ztol (since 1.0) asks for that relative error of \(z\) instead (tol \(= \mathrm{ztol}^2\)).
Without either, :func:fastprox.inner_accuracy sets ztol (read when traced). A solve that
stops at max_iter raises :class:fastprox.ConvergenceWarning from the host unless
warn=False.
tol, ztol and max_iter are static under jit. warm_start takes the dual of an earlier
call (shape (ndim, *x.shape)). With return_info=True returns
(z, info), an :class:IterInfo of JAX arrays. The backward is the C
kernel's: one unknown per flat region, solved by conjugate gradients to
relative residual deriv_tol; by default each image's solve stops at
the relative error of \(z\) that its gap certifies,
\(\sqrt{2\,\mathrm{gap}} / \lVert x \rVert_2\), and at
\(\max(10^{-10}, 100\,\varepsilon)\) at the tightest. pixel_weights (since
0.3), as in :func:fastprox.torch.tv_iso: \(\alpha \ge 0\) broadcasting to x.shape,
differentiable.
tv_aniso(x, gamma=1.0, *, ndim=2, weights=None, edge_weights=None, tol=None, ztol=None, max_iter=1000, warm_start=None, return_info=False, deriv_tol=None, deriv_max_iter=10000, warn=True)
¶
Anisotropic TV of TVAniso(ndim, weights), as :func:tv_iso: a
plain dual method, with the dual in the C kernel's form; its derivatives
are exact region averages. edge_weights (since 0.3), as in
:func:fastprox.torch.tv_aniso: \(\beta \ge 0\) of shape (ndim, ...)
broadcasting to (ndim, *x.shape), differentiable.
fastprox.pyproximal¶
PyProximal adapter (since 0.5): a fastprox operator as a
pyproximal.ProxOperator, for PyProximal's solvers (proximal gradient,
ADMM, primal-dual, ...).
import pyproximal
import fastprox as fp
from fastprox.pyproximal import ProxOp
g = ProxOp(fp.TVIso(), dims=(64, 64), tol=1e-8) # isotropic TV of an image
x = pyproximal.optimization.primal.ProximalGradient(f, g, x0, tau=1.0, epsg=0.1)
PyProximal passes flat vectors; dims gives the array shape the operator
acts on (by default the vector itself: one row). The operator is then
applied as it would be to an array of that shape, so dims=(B, n) is a
batch of B rows of length n for a row operator, and (B, H, W) a
batch of images for an image operator. The value \(g(x)\) is the sum over the
batch.
PyProximal is a separate package (LGPL-3.0), not a dependency of fastprox: install it to use this module. The adapter is written against PyProximal's documented interface.
ProxOp(op: Operator, dims=None, *, warm: bool = False, value_tol: float = 1e-06, **prox_kwargs)
¶
Bases: ProxOperator
op as a PyProximal operator.
op(x)is \(g(x)\) (op.value, summed over the batch), with the indicator of a set taken to tolerancevalue_tol.prox(x, tau)is \(\operatorname{prox}_{\tau g}(x)\) andproxdual(x, tau)is \(\operatorname{prox}_{\tau g^\ast}(x)\) (fastprox'sprox_conj, by the Moreau identity), both for a scalartau > 0.
dims: the shape of the array the operator acts on (default: the
flat vector). warm: for the iterative image operators, start each
solve from the dual of the previous one, which saves iterations when a
solver calls the prox at nearby points. The other keywords (axis,
tol, max_iter, threads, ...) are passed to op.prox and
op.prox_conj; axis also to op.value.