LION.reconstructors.PnP

class LION.reconstructors.PnP(operator, model=None, parameters=None)

Bases: LIONReconstructor

Plug-and-Play reconstruction with a denoiser (model) as the prior.

PnP(operator, model, parameters), with parameters from PnP.default_parameters(algorithm):

• algorithm: “ADMM” (Alternating Direction Method of Multipliers), “HQS” (Half Quadratic Splitting) or “FBS” (Forward-Backward Splitting);

• that algorithm’s settings (see admm_algorithm, hqs_algorithm, forward_backward_splitting). A setting missing from the parameters has its default.

model: the denoiser. A LIONmodel prior is called on a batch of one image (with its normalisation, and the noise level if it uses one). Any other callable is called on the image as it is (the operator’s domain shape) and must return the same shape.

noise_level: in the units of the data the denoiser sees, after its normalisation, as in training (GaussianDenoiserSolver): for images in [0, 1], the literature’s k/255.

The algorithms run without gradients (torch.no_grad): the reconstruction can’t be differentiated, and the iterations don’t keep their autograd graph. (A gradient-step denoiser still computes its own gradient.)

__init__(operator, model=None, parameters=None)

Methods

__init__(operator[, model, parameters])
admm_algorithm(measurement[, eta, max_iter, ...])	ADMM with the prior as the proximal step.
cite([cite_format])	Where Plug-and-Play comes from: its citation, BibTeX ("bib") or "MLA".
default_parameters([algorithm])	algorithm and its settings, with their defaults.
forward_backward_splitting(y[, step_size, ...])	Forward-backward splitting: x = prior(x - step_size Aᵀ(A x - y)), max_iter times.
hqs_algorithm(y, *[, lambda_, mu, max_iter, ...])	Half Quadratic Splitting (Zhang, Li, Zuo, Zhang, Van Gool and Timofte, "Plug-and-Play Image Restoration with Deep Denoiser Prior", IEEE TPAMI 44(10), 2022): alternates.
initial_guess(y)	Where the algorithm starts for measurements y: the parameters' initial_reconstruction(y, op).
instantiate(source[, model, allow])	The reconstructor source describes: its file (save), its spec, or a test record (LION.evaluation) of it, or that record's file.
load(fname, *[, allow])	The reconstructor fname (a file save wrote) describes, with its model loaded from the recorded file (a warning if its weights changed since).
parameters_from_file(source, *[, allow])	What default_parameters() gives, as source (as in instantiate) recorded it: the algorithm's settings, to change and make the reconstructor with (PnP(operator, model, parameters)).
reconstruct(y[, x0, verbose])	Reconstruct measurements y: one sample (the operator's range shape) or a batch of them, each on its own.
reconstruct_sample(y[, x0, verbose])	Reconstruct one measurement (e.g. a (C, angles, detectors) sinogram) with the algorithm and settings in self.parameters.
save(fname)	Write this reconstructor's record to fname (.json): its spec (operator and parameters), its model by the file it was loaded from and its weights hash (a model made in the script: only the hash; a function: its spec), and the environment.
setting(name)	A setting of the algorithm: from the parameters, or its default.
spec_kwargs()	The spec's arguments: the operator and the parameters, not the model (a model's spec would make it with new weights; see the module docstring).

static default_parameters(algorithm='ADMM')

algorithm and its settings, with their defaults.

setting(name)

A setting of the algorithm: from the parameters, or its default.

reconstruct_sample(y, x0=None, verbose=1)

Reconstruct one measurement (e.g. a (C, angles, detectors) sinogram) with the algorithm and settings in self.parameters.

hqs_algorithm(y, *, lambda_=0.23, mu=0.1, max_iter=100, noise_level=None, cg_max_iter=100, cg_tol=1e-07, x0=None, verbose=1)

Half Quadratic Splitting (Zhang, Li, Zuo, Zhang, Van Gool and Timofte, “Plug-and-Play Image Restoration with Deep Denoiser Prior”, IEEE TPAMI 44(10), 2022): alternates:

x = argmin ||A x - y||² / 2 + mu ||x - z||² / 2   (conjugate gradient)
z = prior(x)

and returns z. lambda_: the regularisation weight; mu: the weight of the coupling term; noise_level: if given, mu = lambda_ / noise_level², else the prior’s noise level is sqrt(lambda_ / mu); max_iter: the iterations; cg_max_iter, cg_tol: the conjugate gradient’s; x0: the start (initial_guess(y), the operator’s default reconstruction, FDK for CT, if None); verbose: 0 nothing, 1 a progress bar.

forward_backward_splitting(y, step_size=None, max_iter=10, noise_level=None, x0=None, verbose=1)

Forward-backward splitting: x = prior(x - step_size Aᵀ(A x - y)), max_iter times. step_size: 1 / ||A||² if None (||A|| computed once per reconstructor, on the first call); noise_level: the prior’s; x0: the start (initial_guess(y), the operator’s default reconstruction, FDK for CT, if None); verbose: 0 nothing, 1 a progress bar.

admm_algorithm(measurement, eta=None, max_iter=10, cg_max_iter=100, cg_tol=1e-07, noise_level=None, x0=None, verbose=1)

ADMM with the prior as the proximal step:

x = argmin ||A x - y||² / 2 + eta ||x - (v - u)||² / 2   (conjugate gradient)
v = prior(x + u)
u = u + x - v

max_iter times, returning x. measurement: y; eta: the coupling weight (None: ADMM_ETA ||A||², 1e-2 of it, ||A|| computed once per reconstructor, on the first call; a larger weight trusts the prior more); cg_max_iter, cg_tol: the conjugate gradient’s; noise_level: the prior’s; x0: the start of x and v (initial_guess(measurement), the operator’s default reconstruction, FDK for CT, if None); verbose: 0 nothing, 1 a progress bar.

static cite(cite_format='bib')

Where Plug-and-Play comes from: its citation, BibTeX (“bib”) or “MLA”. The denoiser has its own.