sporco.admm.ccmod

ADMM algorithms for the Convolutional Constrained MOD problem

Functions

ConvCnstrMOD(*args, **kwargs)	A wrapper function that dynamically defines a class derived from one of the implementations of the Convolutional Constrained MOD problems, and returns an object instantiated with the provided parameters.
ConvCnstrMODOptions([opt, method])	A wrapper function that dynamically defines a class derived from the Options class associated with one of the implementations of the Convolutional Constrained MOD problem, and returns an object instantiated with the provided parameters.

Classes

ConvCnstrMODBase(*args, **kwargs)	Base class for the ADMM algorithms for Convolutional Constrained MOD problem [53], including support for multi-channel signals/images [51].
ConvCnstrMOD_IterSM(*args, **kwargs)	ADMM algorithm for Convolutional Constrained MOD problem with the \(\mathbf{x}\) step solved via iterated application of the Sherman-Morrison equation [53].
ConvCnstrMOD_CG(*args, **kwargs)	ADMM algorithm for the Convolutional Constrained MOD problem with the \(\mathbf{x}\) step solved via Conjugate Gradient (CG) [53].
ConvCnstrMOD_Consensus(*args, **kwargs)	ADMM algorithm for the Convolutional Constrained MOD problem with the \(\mathbf{x}\) step solved via an ADMM consensus problem [9] (Ch.

Function Descriptions

sporco.admm.ccmod.ConvCnstrMOD(*args, **kwargs)

A wrapper function that dynamically defines a class derived from one of the implementations of the Convolutional Constrained MOD problems, and returns an object instantiated with the provided parameters. The wrapper is designed to allow the appropriate object to be created by calling this function using the same syntax as would be used if it were a class. The specific implementation is selected by use of an additional keyword argument ‘method’. Valid values are:

• 'ism' : Use the implementation defined in ConvCnstrMOD_IterSM. This method works well for a small number of training images, but is very slow for larger training sets.

• 'cg' : Use the implementation defined in ConvCnstrMOD_CG. This method is slower than 'ism' for small training sets, but has better run time scaling as the training set grows.

• 'cns' : Use the implementation defined in ConvCnstrMOD_Consensus. This method is the best choice for large training sets.

The default value is 'cns'.

sporco.admm.ccmod.ConvCnstrMODOptions(opt=None, method='cns')

A wrapper function that dynamically defines a class derived from the Options class associated with one of the implementations of the Convolutional Constrained MOD problem, and returns an object instantiated with the provided parameters. The wrapper is designed to allow the appropriate object to be created by calling this function using the same syntax as would be used if it were a class. The specific implementation is selected by use of an additional keyword argument ‘method’. Valid values are as specified in the documentation for ConvCnstrMOD.

Class Descriptions

class sporco.admm.ccmod.ConvCnstrMODBase(*args, **kwargs)

Bases: sporco.admm.admm.ADMMEqual

Base class for the ADMM algorithms for Convolutional Constrained MOD problem [53], including support for multi-channel signals/images [51].

Solve the optimisation problem

\[\mathrm{argmin}_\mathbf{d} \; (1/2) \sum_k \left\| \sum_m \mathbf{d}_m * \mathbf{x}_{k,m} - \mathbf{s}_k \right\|_2^2 \quad \text{such that} \quad \mathbf{d}_m \in C \;\; \forall m\]

where \(C\) is the feasible set consisting of filters with unit norm and constrained support, via the ADMM problem

\[\mathrm{argmin}_\mathbf{d} \; (1/2) \sum_k \left\| \sum_m \mathbf{d}_m * \mathbf{x}_{k,m} - \mathbf{s}_k \right\|_2^2 + \sum_m \iota_C(\mathbf{g}_m) \quad \text{such that} \quad \mathbf{d}_m = \mathbf{g}_m \;\;,\]

where \(\iota_C(\cdot)\) is the indicator function of feasible set \(C\). Multi-channel problems with input image channels \(\mathbf{s}_{c,k}\) are also supported, either as

\[\mathrm{argmin}_\mathbf{d} \; (1/2) \sum_c \sum_k \left\| \sum_m \mathbf{d}_m * \mathbf{x}_{c,k,m} - \mathbf{s}_{c,k} \right\|_2^2 \quad \text{such that} \quad \mathbf{d}_m \in C \;\; \forall m\]

with single-channel dictionary filters \(\mathbf{d}_m\) and multi-channel coefficient maps \(\mathbf{x}_{c,k,m}\), or

\[\mathrm{argmin}_\mathbf{d} \; (1/2) \sum_c \sum_k \left\| \sum_m \mathbf{d}_{c,m} * \mathbf{x}_{k,m} - \mathbf{s}_{c,k} \right\|_2^2 \quad \text{such that} \quad \mathbf{d}_{c,m} \in C \;\; \forall c, m\]

with multi-channel dictionary filters \(\mathbf{d}_{c,m}\) and single-channel coefficient maps \(\mathbf{x}_{k,m}\). In this latter case, normalisation of filters \(\mathbf{d}_{c,m}\) is performed jointly over index \(c\) for each filter \(m\).

After termination of the solve method, attribute itstat is a list of tuples representing statistics of each iteration. The fields of the named tuple IterationStats are:

Iter : Iteration number

DFid : Value of data fidelity term \((1/2) \sum_k \| \sum_m \mathbf{d}_m * \mathbf{x}_{k,m} - \mathbf{s}_k \|_2^2\)

Cnstr : Constraint violation measure

PrimalRsdl : Norm of primal residual

DualRsdl : Norm of dual residual

EpsPrimal : Primal residual stopping tolerance \(\epsilon_{\mathrm{pri}}\)

EpsDual : Dual residual stopping tolerance \(\epsilon_{\mathrm{dua}}\)

Rho : Penalty parameter

XSlvRelRes : Relative residual of X step solver

Time : Cumulative run time

This class supports an arbitrary number of spatial dimensions, dimN, with a default of 2. The input coefficient map array Z (usually labelled X, but renamed here to avoid confusion with the X and Y variables in the ADMM base class) is expected to be in standard form as computed by the ConvBPDN class.

The input signal set S is either dimN dimensional (no channels, only one signal), dimN +1 dimensional (either multiple channels or multiple signals), or dimN +2 dimensional (multiple channels and multiple signals). Parameter dimK, with a default value of 1, indicates the number of multiple-signal dimensions in S:

Default dimK = 1, i.e. assume input S is of form
  S(N0,  N1,   C,   K)  or  S(N0,  N1,   K)
If dimK = 0 then input S is of form
  S(N0,  N1,   C,   K)  or  S(N0,  N1,   C)

The internal data layout for S, D (X here), and X (Z here) is:

dim<0> - dim<Nds-1> : Spatial dimensions, product of N0,N1,... is N
dim<Nds>            : C number of channels in S and D
dim<Nds+1>          : K number of signals in S
dim<Nds+2>          : M number of filters in D

  sptl.      chn  sig  flt
S(N0,  N1,   C,   K,   1)
D(N0,  N1,   C,   1,   M)   (X here)
X(N0,  N1,   1,   K,   M)   (Z here)

The dsz parameter indicates the desired filter supports in the output dictionary, since this cannot be inferred from the input variables. The format is the same as the dsz parameter of cnvrep.bcrop.

Parameters

Zarray_like

Coefficient map array

Sarray_like

Signal array

dsztuple

Filter support size(s)

optccmod.Options object

Algorithm options

dimKint, optional (default 1)

Number of dimensions for multiple signals in input S

dimNint, optional (default 2)

Number of spatial dimensions

class Options(opt=None)

Bases: sporco.admm.admm.ADMMEqual.Options

ConvCnstrMODBase algorithm options

Options include all of those defined in admm.ADMMEqual.Options, together with additional options:

AuxVarObj : Flag indicating whether the objective function should be evaluated using variable X (False) or Y (True) as its argument. Setting this flag to True often gives a better estimate of the objective function, but at additional computational cost.

LinSolveCheck : If True, compute relative residual of X step solver.

ZeroMean : Flag indicating whether the solution dictionary \(\{\mathbf{d}_m\}\) should have zero-mean components.

Parameters

optdict or None, optional (default None)

ConvCnstrMODBase algorithm options

uinit(ushape)

Return initialiser for working variable U

setcoef(Z)

Set coefficient array.

getdict(crop=True)

Get final dictionary. If crop is True, apply cnvrep.bcrop to returned array.

xstep_check(b)

Check the minimisation of the Augmented Lagrangian with respect to \(\mathbf{x}\) by method xstep defined in derived classes. This method should be called at the end of any xstep method.

ystep()

Minimise Augmented Lagrangian with respect to \(\mathbf{y}\).

obfn_fvarf()

Variable to be evaluated in computing data fidelity term, depending on ‘fEvalX’ option value.

eval_objfn()

Compute components of objective function as well as total contribution to objective function.

obfn_dfd()

Compute data fidelity term \((1/2) \| \sum_m \mathbf{d}_m * \mathbf{x}_m - \mathbf{s} \|_2^2\).

obfn_cns()

Compute constraint violation measure \(\| P(\mathbf{y}) - \mathbf{y}\|_2\).

itstat_extra()

Non-standard entries for the iteration stats record tuple.

reconstruct(D=None)

Reconstruct representation.

class sporco.admm.ccmod.ConvCnstrMOD_IterSM(*args, **kwargs)

Bases: sporco.admm.ccmod.ConvCnstrMODBase

ADMM algorithm for Convolutional Constrained MOD problem with the \(\mathbf{x}\) step solved via iterated application of the Sherman-Morrison equation [53].

Multi-channel signals/images are supported [51]. See ConvCnstrMODBase for interface details.

Call graph

class Options(opt=None)

Bases: sporco.admm.ccmod.ConvCnstrMODBase.Options

ConvCnstrMOD_IterSM algorithm options

Options are the same as those defined in ConvCnstrMODBase.Options.

Parameters

optdict or None, optional (default None)

ConvCnstrMOD_IterSM algorithm options

xstep()

Minimise Augmented Lagrangian with respect to \(\mathbf{x}\).

solve()

Call graph

class sporco.admm.ccmod.ConvCnstrMOD_CG(*args, **kwargs)

Bases: sporco.admm.ccmod.ConvCnstrMODBase

ADMM algorithm for the Convolutional Constrained MOD problem with the \(\mathbf{x}\) step solved via Conjugate Gradient (CG) [53].

Multi-channel signals/images are supported [51]. See ConvCnstrMODBase for interface details.

Call graph

class Options(opt=None)

Bases: sporco.admm.ccmod.ConvCnstrMODBase.Options

ConvCnstrMOD_CG algorithm options

Options include all of those defined in ConvCnstrMODBase.Options, together with additional options:

CG : CG solver options

MaxIter : Maximum CG iterations.

StopTol : CG stopping tolerance.

Parameters

optdict or None, optional (default None)

ConvCnstrMOD_CG algorithm options

xstep()

Minimise Augmented Lagrangian with respect to \(\mathbf{x}\).

itstat_extra()

Non-standard entries for the iteration stats record tuple.

solve()

Call graph

class sporco.admm.ccmod.ConvCnstrMOD_Consensus(*args, **kwargs)

Bases: sporco.admm.admm.ADMMConsensus

ADMM algorithm for the Convolutional Constrained MOD problem with the \(\mathbf{x}\) step solved via an ADMM consensus problem [9] (Ch. 7), [1].

Multi-channel signals/images are supported [51]. See ConvCnstrMODBase for interface details.

Call graph

class Options(opt=None)

Bases: sporco.admm.admm.ADMMConsensus.Options, sporco.admm.ccmod.ConvCnstrMODBase.Options

ConvCnstrMOD_Consensus algorithm options

Available options are the same as those defined in ADMMConsensus.Options and ConvCnstrMODBase.Options.

Parameters

optdict or None, optional (default None)

ConvCnstrMOD_Consensus algorithm options

uinit(ushape)

Return initialiser for working variable U.

setcoef(Z)

Set coefficient array.

swapaxes(x)

Class admm.ADMMConsensus, from which this class is derived, expects the multiple blocks of a consensus problem to be stacked on the final axis. For compatibility with this requirement, axisK of the variables used in this algorithm is swapped with a new final axis. This method undoes the swap and removes the final axis for compatibility with functions that expect the variables in standard layout.

xstep()

Minimise Augmented Lagrangian with respect to block vector \(\mathbf{x} = \left( \begin{array}{ccc} \mathbf{x}_0^T & \mathbf{x}_1^T & \ldots \end{array} \right)^T\;\).

xistep(i)

Minimise Augmented Lagrangian with respect to \(\mathbf{x}\) component \(\mathbf{x}_i\).

prox_g(X, rho)

Proximal operator of \(g\)

getdict(crop=True)

Get final dictionary. If crop is True, apply cnvrep.bcrop to returned array.

eval_objfn()

Compute components of objective function as well as total contribution to objective function.

obfn_fvarf()

Variable to be evaluated in computing data fidelity term, depending on ‘fEvalX’ option value.

obfn_dfd()

Compute data fidelity term \((1/2) \| \sum_m \mathbf{d}_m * \mathbf{x}_m - \mathbf{s} \|_2^2\).

solve()

Call graph

obfn_cns()

Compute constraint violation measure \(\| P(\mathbf{y}) - \mathbf{y}\|_2\).

itstat_extra()

Non-standard entries for the iteration stats record tuple.