ADMM

class deepinv.optim.ADMM(data_fidelity=None, prior=None, lambda_reg=1.0, stepsize=1.0, beta=1.0, g_param=None, sigma_denoiser=None, max_iter=100, crit_conv='residual', thres_conv=1e-5, early_stop=False, custom_metrics=None, custom_init=None, unfold=False, trainable_params=None, g_first=False, cost_fn=None, params_algo=None, device=torch.device('cpu'), **kwargs)

Bases: BaseOptim

ADMM module for solving the problem

\[\begin{equation} \label{eq:min_prob} \tag{1} \underset{x}{\arg\min} \quad \datafid{x}{y} + \lambda \reg{x}, \end{equation}\]

where \(\datafid{x}{y}\) is the data-fidelity term, \(\reg{x}\) is the regularization term. If the attribute g_first is set to False (by default), the ADMM iterations write (see Boyd et al.[1] for more details):

\[\begin{split}\begin{equation*} \begin{aligned} u_{k+1} &= \operatorname{prox}_{\gamma f}(x_k - z_k) \\ x_{k+1} &= \operatorname{prox}_{\gamma \lambda \regname}(u_{k+1} + z_k) \\ z_{k+1} &= z_k + \beta (u_{k+1} - x_{k+1}) \end{aligned} \end{equation*}\end{split}\]

where \(\gamma>0\) is a stepsize and \(\beta>0\) is a relaxation parameter. If the attribute g_first is set to True, the functions \(f\) and \(\regname\) are inverted in the previous iterations. The ADMM iterations are defined in the iterator class deepinv.optim.optim_iterators.ADMMIteration. For using early stopping or stepsize backtracking, see the documentation of the deepinv.optim.BaseOptim class.

If the attribute unfold is set to True, the algorithm is unfolded and the algorithmic parameters (stepsize, regularization parameter, etc.) of the algorithm are trainable. By default (if the attribute unfold is set to True) all the algorithm parameters are trainable: the stepsize \(\gamma\), the regularization parameter \(\lambda\), the prior parameter and the relaxation parameter \(\beta\). Use the trainable_params argument to adjust the list of trainable parameters. Note also that by default, if the prior has trainable parameters (e.g. a neural network denoiser), these parameters are learnable by default. If the model is used for inference only, use the with torch.no_grad(): context when calling the model in order to avoid unnecessary gradient computations.

Parameters:

• data_fidelity (list, deepinv.optim.DataFidelity) – data-fidelity term \(\datafid{x}{y}\). Either a single instance (same data-fidelity for each iteration) or a list of instances of deepinv.optim.DataFidelity (distinct data fidelity for each iteration). Default: None corresponding to \(\datafid{x}{y} = 0\).

• prior (list, deepinv.optim.Prior) – regularization prior \(\reg{x}\). Either a single instance (same prior for each iteration) or a list of instances of deepinv.optim.Prior (distinct prior for each iteration). Default: None corresponding to \(\reg{x} = 0\).

• lambda_reg (float) – regularization parameter \(\lambda\). Default: 1.0.

• stepsize (float) – stepsize parameter \(\gamma\). Default: 1.0.

• beta (float) – ADMM relaxation parameter \(\beta\). Default: 1.0.

• g_param (float) – parameter of the prior function. For example the noise level for a denoising prior. Default: None.

• sigma_denoiser (float) – same as g_param. If both g_param and sigma_denoiser are provided, g_param is used. Default: None.

• max_iter (int) – maximum number of iterations of the optimization algorithm. Default: 100.

• crit_conv (str) – convergence criterion to be used for claiming convergence, either "residual" (residual of the iterate norm) or "cost" (on the cost function). Default: "residual"

• thres_conv (float) – convergence threshold for the chosen convergence criterion. Default: 1e-5.

• early_stop (bool) – whether to stop the algorithm as soon as the convergence criterion is met. Default: False.

• custom_metrics (dict) – dictionary of custom metric functions to be computed along the iterations. The keys of the dictionary are the names of the metrics, and the values are functions that take as input the current and previous iterates, and return a scalar value. Default: None.

• custom_init (Callable) –

  Custom initialization of the algorithm. The callable function custom_init(y, physics) takes as input the measurement \(y\) and the physics physics and returns the initialization in the form of either:

  • a tuple \((x_0, z_0)\) (where x_0 and z_0 are the initial primal and dual variables),

  • a torch.Tensor \(x_0\) (if no dual variables \(z_0\) are used), or

  • a dictionary of the form X = {'est': (x_0, z_0)}.

  Note that custom initialization can also be directly defined via the init argument in the forward method.

  If None (default value), the algorithm is initialized with the adjoint \(A^{\top}y\) when the adjoint is defined, and with the observation y if the adjoint is not defined. Default: None.

• g_first (bool) – whether to perform the proximal step on \(\reg{x}\) before that on \(\datafid{x}{y}\), or the opposite. Default: False.

• unfold (bool) – whether to unfold the algorithm or not. Default: False.

• trainable_params (list) – list of ADMM parameters to be trained if unfold is True. To choose between ["lambda", "stepsize", "g_param", "beta"]. Default: None, which means that all parameters are trainable if unfold is True. For no trainable parameters, set to an empty list.

• cost_fn (Callable) – Custom user input cost function. cost_fn(x, data_fidelity, prior, cur_params, y, physics) takes as input the current primal variable (torch.Tensor), the current data-fidelity (deepinv.optim.DataFidelity), the current prior (deepinv.optim.Prior), the current parameters (dict), and the measurement (torch.Tensor). Default: None.

• params_algo (dict) – optionally, directly provide the ADMM parameters in a dictionary. This will overwrite the parameters in the arguments stepsize, lambda_reg, g_param and beta.

• device (torch.device) – device to use for the algorithm. Default: torch.device("cpu").

---

References:

[1]

Stephen Boyd, Neal Parikh, Eric Chu, Borja Peleato, Jonathan Eckstein, and others. Distributed optimization and statistical learning via the alternating direction method of multipliers. Foundations and Trends® in Machine learning, 3(1):1–122, 2011.

Examples using ADMM:

Image deblurring with custom deep explicit prior.

Image deblurring with custom deep explicit prior.

Spatial unwrapping and modulo imaging

Spatial unwrapping and modulo imaging

Pattern Ordering in a Compressive Single Pixel Camera

Pattern Ordering in a Compressive Single Pixel Camera

PnP with custom optimization algorithm (Primal-Dual Condat-Vu)

PnP with custom optimization algorithm (Primal-Dual Condat-Vu)