nlop.IRGNMBlock

nlop.IRGNMBlock#

class bartorch.nlop.IRGNMBlock#

Bases: Module

One iteratively regularized Gauss-Newton step, as a torch.nn.Module.

Without inner the step is BART’s irgnm form (noir’s Gauss-Newton step),

x = xn + (DF^H DF + alpha)^-1 [DF^H (y - F(xn)) - alpha (xn - xref)],

with the inverse computed by conjugate gradients inside the library and differentiated implicitly. With inner it is the irgnm2 form: the solver minimizes ||DF u - r||^2 + alpha ||u||^2 + R(u) with DF taken at xn and r = y - F(xn) + DF (xn - xref), and x = u + xref.

state = block.start(y, F, x0, xref) prepares a run, state = block(state, F) takes one step, and block.output(state, F) returns the unknowns. Step k (counted from zero in the state) uses alpha decayed k times by alpha <- (alpha - alpha_min) / redu + alpha_min, so a looped block, or a stack of blocks with equal alpha, follows BART’s schedule.

Parameters:

  • alpha (float, default=1.0) – Tikhonov weight of the first step.

  • alpha_min (float, default=0.0) – Limit the weight decays towards.

  • alpha_min0 (float, default=0.0) – Lower bound on the decayed weight; irgnm2 form only.

  • redu (float, default=2.0) – Decay factor of the weight per step.

  • cg_maxiter (int, default=30) – Conjugate-gradient iterations of the irgnm form (iter_conjgrad_conf.maxiter).

  • cg_tol (float, default=0.0) – Their tolerance (iter_conjgrad_conf.tol); BART refuses a nonzero value when the step is differentiated.

  • cg_lambda (float, default=0.0) – Their Tikhonov weight (iter_conjgrad_conf.l2lambda).

  • inner (solver, default=None) – Configured solver from bartorch.optim for the linearized problem, selecting the irgnm2 form; its regularizers are R.

  • fuse (bool, default=True) – Apply the encoding of a coil model (a product of two unknowns before a linear encoding) as its normal operator; see plan().

Raises:

  • ValueError – If alpha_min0 is nonzero without inner.

  • TypeError – If inner is not a solver from bartorch.optim.

Notes

F must supply its derivative as a function of the point; an operator from from_callbacks() does not, and is refused with TypeError. A leading batch axis on y holds independent items, each stepped on its own; a model that holds its items, such as CoilSense(..., items=True), is applied to all at once, with each item’s inner problem solved on its own.

alpha and redu are torch.nn.Parameter objects, frozen until requires_grad_(). The irgnm form is differentiable by the data, the iterate, xref and alpha. The irgnm2 form is differentiable by the data, the iterate, xref and the inner solver’s settings and priors, and passes alpha to the solver as a number.

plan()#

Report how the steps apply F.

Parameters:

F (NonlinearOperator or LinearOperator) – Forward model.

Returns:

plan.derivative: where the derivative comes from ('declared', 'chain rule', 'linear' or 'torch'); plan.domain: 'normal' when the step applies the encoding as E^H E to data taken through E^H, 'paired' when it applies E and E^H; plan.encoding: the linear encoding’s own plan, or None; plan.fused: whether the coil model was rewritten.

Return type:

Plan

start()#

Prepare a run.

Parameters:

  • y (torch.Tensor) – Data of the model’s output shape, with an optional leading batch axis.

  • F (NonlinearOperator or LinearOperator) – Forward model.

  • x0 (torch.Tensor or tuple of torch.Tensor, default=None) – Start and regularization centre: a tuple with one tensor per input, the inputs flattened and concatenated, or for a model of one input that input at its shape. x0=None starts as nlinv does, with the first input ones and the others zero; xref=None regularizes towards zero.

  • xref (torch.Tensor or tuple of torch.Tensor, default=None) – Start and regularization centre: a tuple with one tensor per input, the inputs flattened and concatenated, or for a model of one input that input at its shape. x0=None starts as nlinv does, with the first input ones and the others zero; xref=None regularizes towards zero.

Returns:

Iterate, centre, prepared data and step count k = 0.

Return type:

IRGNMBlock.State

Raises:

ValueError – If inner is set and the model holds several items.

forward()#

Take one Gauss-Newton step.

Parameters:
Returns:

The new iterate, with k incremented.

Return type:

IRGNMBlock.State

output()#

Return the unknowns of a state.

Parameters:
Returns:

One tensor per input of F, with the batch axis of the data.

Return type:

torch.Tensor or tuple of torch.Tensor