# 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` (Z, S, dsz[, opt, dimK, dimN]) |
Base class for the ADMM algorithms for Convolutional Constrained MOD problem [38], including support for multi-channel signals/images [36]. |

`ConvCnstrMOD_IterSM` (Z, S, dsz[, opt, dimK, dimN]) |
ADMM algorithm for Convolutional Constrained MOD problem with the \(\mathbf{x}\) step solved via iterated application of the Sherman-Morrison equation [38]. |

`ConvCnstrMOD_CG` (Z, S, dsz[, opt, dimK, dimN]) |
ADMM algorithm for the Convolutional Constrained MOD problem with the \(\mathbf{x}\) step solved via Conjugate Gradient (CG) [38]. |

`ConvCnstrMOD_Consensus` (Z, S, dsz[, opt, …]) |
ADMM algorithm for the Convolutional Constrained MOD problem with the \(\mathbf{x}\) step solved via an ADMM consensus problem [6] (Ch. |

## Function Descriptions¶

`sporco.admm.ccmod.`

`ConvCnstrMOD`

(*args,**kwargs)[source]¶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')[source]¶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`

(Z,S,dsz,opt=None,dimK=1,dimN=2)[source]¶Bases:

`sporco.admm.admm.ADMMEqual`

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

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 timeThis 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:

Z: array_likeCoefficient map array

S: array_likeSignal array

dsz: tupleFilter support size(s)

opt: ccmod.Options objectAlgorithm options

dimK: int, optional (default 1)Number of dimensions for multiple signals in input S

dimN: int, optional (default 2)Number of spatial dimensions

class`Options`

(opt=None)[source]¶Bases:

`sporco.admm.admm.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:

opt: dict or None, optional (default None)ConvCnstrMODBase algorithm options

`getdict`

(self,crop=True)[source]¶Get final dictionary. If

`crop`

is`True`

, apply`cnvrep.bcrop`

to returned array.

`xstep_check`

(self,b)[source]¶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.

`obfn_fvarf`

(self)[source]¶Variable to be evaluated in computing data fidelity term, depending on ‘fEvalX’ option value.

`eval_objfn`

(self)[source]¶Compute components of objective function as well as total contribution to objective function.

class`sporco.admm.ccmod.`

`ConvCnstrMOD_IterSM`

(Z,S,dsz,opt=None,dimK=1,dimN=2)[source]¶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 [38].

Multi-channel signals/images are supported [36]. See

`ConvCnstrMODBase`

for interface details.

Call graph

class`Options`

(opt=None)[source]¶Bases:

`sporco.admm.ccmod.Options`

ConvCnstrMOD_IterSM algorithm options

Options are the same as those defined in

`ConvCnstrMODBase.Options`

.

Parameters:

opt: dict or None, optional (default None)ConvCnstrMOD_IterSM algorithm options

`solve`

(*args)¶

Call graph

class`sporco.admm.ccmod.`

`ConvCnstrMOD_CG`

(Z,S,dsz,opt=None,dimK=1,dimN=2)[source]¶Bases:

`sporco.admm.ccmod.ConvCnstrMODBase`

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

Multi-channel signals/images are supported [36]. See

`ConvCnstrMODBase`

for interface details.

Call graph

class`Options`

(opt=None)[source]¶Bases:

`sporco.admm.ccmod.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:

opt: dict or None, optional (default None)ConvCnstrMOD_CG algorithm options

`solve`

(*args)¶

Call graph

class`sporco.admm.ccmod.`

`ConvCnstrMOD_Consensus`

(Z,S,dsz,opt=None,dimK=1,dimN=2)[source]¶Bases:

`sporco.admm.admm.ADMMConsensus`

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

Multi-channel signals/images are supported [36]. See

`ConvCnstrMODBase`

for interface details.

Call graph

class`Options`

(opt=None)[source]¶Bases:

`sporco.admm.admm.Options`

,`sporco.admm.ccmod.Options`

ConvCnstrMOD_Consensus algorithm options

Available options are the same as those defined in

`ADMMConsensus.Options`

and`ConvCnstrMODBase.Options`

.

Parameters:

opt: dict or None, optional (default None)ConvCnstrMOD_Consensus algorithm options

`swapaxes`

(self,x)[source]¶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`

(self)[source]¶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`

(self,i)[source]¶Minimise Augmented Lagrangian with respect to \(\mathbf{x}\) component \(\mathbf{x}_i\).

`getdict`

(self,crop=True)[source]¶Get final dictionary. If

`crop`

is`True`

, apply`cnvrep.bcrop`

to returned array.

`eval_objfn`

(self)[source]¶Compute components of objective function as well as total contribution to objective function.

`obfn_fvarf`

(self)[source]¶Variable to be evaluated in computing data fidelity term, depending on ‘fEvalX’ option value.

`obfn_dfd`

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

`solve`

(*args)¶

Call graph