# sporco.admm.cbpdntv¶

Classes for ADMM algorithms for convolutional sparse coding with Total Variation regularisation terms

Classes

 ConvBPDNScalarTV(D, S, lmbda[, mu, opt, …]) ADMM algorithm for an extension of Convolutional BPDN including terms penalising the total variation of each coefficient map . ConvBPDNVectorTV(D, S, lmbda[, mu, opt, …]) ADMM algorithm for an extension of Convolutional BPDN including a term penalising the vector total variation of the coefficient maps . ConvBPDNRecTV(D, S, lmbda[, mu, opt, dimK, dimN]) ADMM algorithm for an extension of Convolutional BPDN including terms penalising the total variation of the reconstruction from the sparse representation .

## Class Descriptions¶

class sporco.admm.cbpdntv.ConvBPDNScalarTV(D, S, lmbda, mu=0.0, opt=None, dimK=None, dimN=2)[source]

ADMM algorithm for an extension of Convolutional BPDN including terms penalising the total variation of each coefficient map .

Solve the optimisation problem

$\mathrm{argmin}_\mathbf{x} \; \frac{1}{2} \left\| \sum_m \mathbf{d}_m * \mathbf{x}_m - \mathbf{s} \right\|_2^2 + \lambda \sum_m \| \mathbf{x}_m \|_1 + \mu \sum_m \left\| \sqrt{\sum_i (G_i \mathbf{x}_m)^2} \right\|_1 \;\;,$

where $$G_i$$ is an operator computing the derivative along index $$i$$, via the ADMM problem

$\begin{split}\mathrm{argmin}_\mathbf{x} \; (1/2) \left\| D \mathbf{x} - \mathbf{s} \right\|_2^2 + \lambda \| \mathbf{y}_L \|_1 + \mu \sum_m \left\| \sqrt{\sum_{i=0}^{L-1} \mathbf{y}_i^2} \right\|_1 \quad \text{ such that } \quad \left( \begin{array}{c} \Gamma_0 \\ \Gamma_1 \\ \vdots \\ I \end{array} \right) \mathbf{x} = \left( \begin{array}{c} \mathbf{y}_0 \\ \mathbf{y}_1 \\ \vdots \\ \mathbf{y}_L \end{array} \right) \;\;,\end{split}$

where

$\begin{split}D = \left( \begin{array}{ccc} D_0 & D_1 & \ldots \end{array} \right) \qquad \mathbf{x} = \left( \begin{array}{c} \mathbf{x}_0 \\ \mathbf{x}_1 \\ \vdots \end{array} \right) \qquad \Gamma_i = \left( \begin{array}{ccc} G_i & 0 & \ldots \\ 0 & G_i & \ldots \\ \vdots & \vdots & \ddots \end{array} \right) \;\;.\end{split}$

For multi-channel signals with a single-channel dictionary, scalar TV is applied independently to each coefficient map for channel $$c$$ and filter $$m$$. Since multi-channel signals with a multi-channel dictionary also have one coefficient map per filter, the behaviour is the same as for single-channel signals.

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

ObjFun : Objective function value

DFid : Value of data fidelity term $$(1/2) \| \sum_m \mathbf{d}_m * \mathbf{x}_m - \mathbf{s} \|_2^2$$

RegL1 : Value of regularisation term $$\sum_m \| \mathbf{x}_m \|_1$$

RegTV : Value of regularisation term $$\sum_m \left\| \sqrt{\sum_i (G_i \mathbf{x}_m)^2} \right\|_1$$

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

Call graph Parameters: D : array_like Dictionary matrix S : array_like Signal vector or matrix lmbda : float Regularisation parameter (l1) mu : float Regularisation parameter (gradient) opt : Algorithm options dimK : 0, 1, or None, optional (default None) Number of dimensions in input signal corresponding to multiple independent signals dimN : int, optional (default 2) Number of spatial dimensions
class Options(opt=None)[source]

Bases: sporco.admm.cbpdn.Options

ConvBPDNScalarTV algorithm options

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

TVWeight : An array of weights $$w_m$$ for the term penalising the gradient of the coefficient maps. If this option is defined, the regularization term is $$\sum_m w_m \left\| \sqrt{\sum_i (G_i \mathbf{x}_m)^2} \right\|_1$$ where $$w_m$$ is the weight for filter index $$m$$. The array should be an $$M$$-vector where $$M$$ is the number of filters in the dictionary.

Parameters: opt : dict or None, optional (default None) ConvBPDNScalarTV algorithm options
setdict(self, D=None)[source]

Set dictionary array.

rhochange(self)[source]

Updated cached c array when rho changes.

xstep(self)[source]

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

ystep(self)[source]

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

obfn_fvarf(self)[source]

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

var_y0(self)[source]

Get $$\mathbf{y}_0$$ variable, consisting of all blocks of $$\mathbf{y}$$ corresponding to a gradient operator.

var_y1(self)[source]

Get $$\mathbf{y}_1$$ variable, the block of $$\mathbf{y}$$ corresponding to the identity operator.

var_yx(self)[source]

Get component block of $$\mathbf{y}$$ that is constrained to be equal to $$\mathbf{x}$$.

var_yx_idx(self)[source]

Get index expression for component block of $$\mathbf{y}$$ that is constrained to be equal to $$\mathbf{x}$$.

getmin(self)[source]

Get minimiser after optimisation.

getcoef(self)[source]

Get final coefficient array.

obfn_g0var(self)[source]

Variable to be evaluated in computing the TV regularisation term, depending on the gEvalY option value.

obfn_g1var(self)[source]

Variable to be evaluated in computing the $$\ell_1$$ regularisation term, depending on the gEvalY option value.

obfn_gvar(self)[source]

Method providing compatibility with the interface of admm.cbpdn.ConvBPDN and derived classes in order to make this class compatible with classes such as AddMaskSim.

eval_objfn(self)[source]

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

obfn_dfd(self)[source]

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

obfn_reg(self)[source]

Compute regularisation term and contribution to objective function.

itstat_extra(self)[source]

Non-standard entries for the iteration stats record tuple.

cnst_A0(self, X, Xf=None)[source]

Compute $$A_0 \mathbf{x}$$ component of ADMM problem constraint. In this case $$A_0 \mathbf{x} = (\Gamma_0^T \;\; \Gamma_1^T \;\; \ldots )^T \mathbf{x}$$.

cnst_A0T(self, X)[source]

Compute $$A_0^T \mathbf{x}$$ where $$A_0 \mathbf{x}$$ is a component of the ADMM problem constraint. In this case $$A_0^T \mathbf{x} = (\Gamma_0^T \;\; \Gamma_1^T \;\; \ldots ) \mathbf{x}$$.

cnst_A1(self, X)[source]

Compute $$A_1 \mathbf{x}$$ component of ADMM problem constraint. In this case $$A_1 \mathbf{x} = \mathbf{x}$$.

cnst_A1T(self, X)[source]

Compute $$A_1^T \mathbf{x}$$ where $$A_1 \mathbf{x}$$ is a component of the ADMM problem constraint. In this case $$A_1^T \mathbf{x} = \mathbf{x}$$.

cnst_A(self, X, Xf=None)[source]

Compute $$A \mathbf{x}$$ component of ADMM problem constraint. In this case $$A \mathbf{x} = (\Gamma_0^T \;\; \Gamma_1^T \;\; \ldots \;\; I)^T \mathbf{x}$$.

cnst_AT(self, X)[source]

Compute $$A^T \mathbf{x}$$ where $$A \mathbf{x}$$ is a component of ADMM problem constraint. In this case $$A^T \mathbf{x} = (\Gamma_0^T \;\; \Gamma_1^T \;\; \ldots \;\; I) \mathbf{x}$$.

cnst_B(self, Y)[source]

Compute $$B \mathbf{y}$$ component of ADMM problem constraint. In this case $$B \mathbf{y} = -\mathbf{y}$$.

cnst_c(self)[source]

Compute constant component $$\mathbf{c}$$ of ADMM problem constraint. In this case $$\mathbf{c} = \mathbf{0}$$.

relax_AX(self)[source]

Implement relaxation if option RelaxParam != 1.0.

reconstruct(self, X=None)[source]

Reconstruct representation.

solve(*args)

Call graph class sporco.admm.cbpdntv.ConvBPDNVectorTV(D, S, lmbda, mu=0.0, opt=None, dimK=None, dimN=2)[source]

ADMM algorithm for an extension of Convolutional BPDN including a term penalising the vector total variation of the coefficient maps .

Solve the optimisation problem

$\mathrm{argmin}_\mathbf{x} \; \frac{1}{2} \left\| \sum_m \mathbf{d}_m * \mathbf{x}_m - \mathbf{s} \right\|_2^2 + \lambda \sum_m \| \mathbf{x}_m \|_1 + \mu \left\| \sqrt{\sum_m \sum_i (G_i \mathbf{x}_m)^2} \right\|_1 \;\;,$

where $$G_i$$ is an operator computing the derivative along index $$i$$, via the ADMM problem

$\begin{split}\mathrm{argmin}_\mathbf{x} \; (1/2) \left\| D \mathbf{x} - \mathbf{s} \right\|_2^2 + \lambda \| \mathbf{y}_L \|_1 + \mu \left\| \sqrt{\sum_{i=0}^{L-1} I_B \mathbf{y}_i^2} \right\|_1 \quad \text{ such that } \quad \left( \begin{array}{c} \Gamma_0 \\ \Gamma_1 \\ \vdots \\ I \end{array} \right) \mathbf{x} = \left( \begin{array}{c} \mathbf{y}_0 \\ \mathbf{y}_1 \\ \vdots \\ \mathbf{y}_L \end{array} \right) \;\;,\end{split}$

where

$\begin{split}D = \left( \begin{array}{ccc} D_0 & D_1 & \ldots \end{array} \right) \qquad \mathbf{x} = \left( \begin{array}{c} \mathbf{x}_0 \\ \mathbf{x}_1 \\ \vdots \end{array} \right) \qquad \Gamma_i = \left( \begin{array}{ccc} G_i & 0 & \ldots \\ 0 & G_i & \ldots \\ \vdots & \vdots & \ddots \end{array} \right) \qquad I_B = \left( \begin{array}{ccc} I & I & \ldots \end{array} \right) \;\;.\end{split}$

For multi-channel signals with a single-channel dictionary, vector TV is applied jointly over the coefficient maps for channel $$c$$ and filter $$m$$. Since multi-channel signals with a multi-channel dictionary also have one coefficient map per filter, the behaviour is the same as for single-channel signals.

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

ObjFun : Objective function value

DFid : Value of data fidelity term $$(1/2) \| \sum_m \mathbf{d}_m * \mathbf{x}_m - \mathbf{s} \|_2^2$$

RegL1 : Value of regularisation term $$\sum_m \| \mathbf{x}_m \|_1$$

RegTV : Value of regularisation term $$\left\| \sqrt{\sum_m \sum_i (G_i \mathbf{x}_m)^2} \right\|_1$$

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

Call graph Parameters: D : array_like Dictionary matrix S : array_like Signal vector or matrix lmbda : float Regularisation parameter (l1) mu : float Regularisation parameter (gradient) opt : Algorithm options dimK : 0, 1, or None, optional (default None) Number of dimensions in input signal corresponding to multiple independent signals dimN : int, optional (default 2) Number of spatial dimensions
ystep(self)[source]

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

obfn_reg(self)[source]

Compute regularisation term and contribution to objective function.

solve(*args)

Call graph class sporco.admm.cbpdntv.ConvBPDNRecTV(D, S, lmbda, mu=0.0, opt=None, dimK=None, dimN=2)[source]

ADMM algorithm for an extension of Convolutional BPDN including terms penalising the total variation of the reconstruction from the sparse representation .

Solve the optimisation problem

$\mathrm{argmin}_\mathbf{x} \; \frac{1}{2} \left\| \sum_m \mathbf{d}_m * \mathbf{x}_m - \mathbf{s} \right\|_2^2 + \lambda \sum_m \| \mathbf{x}_m \|_1 + \mu \left\| \sqrt{\sum_i \left( G_i \left( \sum_m \mathbf{d}_m * \mathbf{x}_m \right) \right)^2} \right\|_1 \;\;,$

where $$G_i$$ is an operator computing the derivative along index $$i$$, via the ADMM problem

$\begin{split}\mathrm{argmin}_\mathbf{x} \; (1/2) \left\| D \mathbf{x} - \mathbf{s} \right\|_2^2 + \lambda \| \mathbf{y}_0 \|_1 + \mu \left\| \sqrt{\sum_{i=1}^L \mathbf{y}_i^2} \right\|_1 \quad \text{ such that } \quad \left( \begin{array}{c} I \\ \Gamma_0 \\ \Gamma_1 \\ \vdots \\ \Gamma_{L-1} \end{array} \right) \mathbf{x} = \left( \begin{array}{c} \mathbf{y}_0 \\ \mathbf{y}_1 \\ \mathbf{y}_2 \\ \vdots \\ \mathbf{y}_L \end{array} \right) \;\;,\end{split}$

where

$\begin{split}D = \left( \begin{array}{ccc} D_0 & D_1 & \ldots \end{array} \right) \qquad \mathbf{x} = \left( \begin{array}{c} \mathbf{x}_0 \\ \mathbf{x}_1 \\ \vdots \end{array} \right) \qquad \Gamma_i = \left( \begin{array}{ccc} G_{i,0} & G_{i,1} & \ldots \end{array} \right) \;\;,\end{split}$

and linear operator $$G_{i,m}$$ is defined such that

$G_{i,m} \mathbf{x} = \mathbf{g}_i * \mathbf{d}_m * \mathbf{x} \;\;,$

where $$\mathbf{g}_i$$ is the filter corresponding to $$G_i$$, i.e. $$G_i \mathbf{x} = \mathbf{g}_i * \mathbf{x}$$.

For multi-channel signals, vector TV is applied jointly over the reconstructions of all channels.

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

ObjFun : Objective function value

DFid : Value of data fidelity term $$(1/2) \| \sum_m \mathbf{d}_m * \mathbf{x}_m - \mathbf{s} \|_2^2$$

RegL1 : Value of regularisation term $$\sum_m \| \mathbf{x}_m \|_1$$

RegTV : Value of regularisation term $$\left\| \sqrt{\sum_i \left( G_i \left( \sum_m \mathbf{d}_m * \mathbf{x}_m \right) \right)^2} \right\|_1$$

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

Call graph Parameters: D : array_like Dictionary matrix S : array_like Signal vector or matrix lmbda : float Regularisation parameter (l1) mu : float Regularisation parameter (gradient) opt : Algorithm options dimK : 0, 1, or None, optional (default None) Number of dimensions in input signal corresponding to multiple independent signals dimN : int, optional (default 2) Number of spatial dimensions
class Options(opt=None)[source]

Bases: sporco.admm.cbpdn.Options

ConvBPDNRecTV algorithm options

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

TVWeight : An array of weights $$w_m$$ for the term penalising the gradient of the coefficient maps. If this option is defined, the regularization term is $$\left\| \sqrt{\sum_i \left( G_i \left( \sum_m w_m (\mathbf{d}_m * \mathbf{x}_m) \right) \right)^2} \right\|_1$$ where $$w_m$$ is the weight for filter index $$m$$. The array should be an $$M$$-vector where $$M$$ is the number of filters in the dictionary.

Parameters: opt : dict or None, optional (default None) ConvBPDNRecTV algorithm options
setdict(self, D=None)[source]

Set dictionary array.

block_sep0(self, Y)[source]

Separate variable into component corresponding to Y0 in Y.

block_sep1(self, Y)[source]

Separate variable into component corresponding to Y1 in Y.

block_cat(self, Y0, Y1)[source]

Concatenate components corresponding to Y0 and Y1 blocks into Y.

xstep(self)[source]

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

ystep(self)[source]

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

obfn_fvarf(self)[source]

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

var_y0(self)[source]

Get $$\mathbf{y}_0$$ variable, the block of $$\mathbf{y}$$ corresponding to the identity operator.

var_y1(self)[source]

Get $$\mathbf{y}_1$$ variable, consisting of all blocks of $$\mathbf{y}$$ corresponding to a gradient operator.

var_yx(self)[source]

Get component block of $$\mathbf{y}$$ that is constrained to be equal to $$\mathbf{x}$$

var_yx_idx(self)[source]

Get index expression for component block of $$\mathbf{y}$$ that is constrained to be equal to $$\mathbf{x}$$.

getmin(self)[source]

Get minimiser after optimisation.

getcoef(self)[source]

Get final coefficient array.

obfn_g0var(self)[source]

Variable to be evaluated in computing the TV regularisation term, depending on the gEvalY option value.

obfn_g1var(self)[source]

Variable to be evaluated in computing the $$\ell_1$$ regularisation term, depending on the gEvalY option value.

obfn_gvar(self)[source]

Method providing compatibility with the interface of admm.cbpdn.ConvBPDN and derived classes in order to make this class compatible with classes such as AddMaskSim.

eval_objfn(self)[source]

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

obfn_dfd(self)[source]

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

obfn_reg(self)[source]

Compute regularisation term and contribution to objective function.

itstat_extra(self)[source]

Non-standard entries for the iteration stats record tuple.

cnst_A0(self, X)[source]

Compute $$A_0 \mathbf{x}$$ component of ADMM problem constraint. In this case $$A_0 \mathbf{x} = \mathbf{x}$$.

cnst_A0T(self, Y0)[source]

Compute $$A_0^T \mathbf{y}_0$$ component of $$A^T \mathbf{y}$$. In this case $$A_0^T \mathbf{y}_0 = \mathbf{y}_0$$, i.e. $$A_0 = I$$.

cnst_A1(self, X, Xf=None)[source]

Compute $$A_1 \mathbf{x}$$ component of ADMM problem constraint. In this case $$A_1 \mathbf{x} = (\Gamma_0^T \;\; \Gamma_1^T \;\; \ldots )^T \mathbf{x}$$.

cnst_A1T(self, Y1)[source]

Compute $$A_1^T \mathbf{y}_1$$ component of $$A^T \mathbf{y}$$. In this case $$A_1^T \mathbf{y}_1 = (\Gamma_0^T \;\; \Gamma_1^T \;\; \ldots) \mathbf{y}_1$$.

cnst_A(self, X, Xf=None)[source]

Compute $$A \mathbf{x}$$ component of ADMM problem constraint. In this case $$A \mathbf{x} = (I \;\; \Gamma_0^T \;\; \Gamma_1^T \;\; \ldots)^T \mathbf{x}$$.

cnst_AT(self, Y)[source]

Compute $$A^T \mathbf{y}$$. In this case $$A^T \mathbf{y} = (I \;\; \Gamma_0^T \;\; \Gamma_1^T \;\; \ldots) \mathbf{y}$$.

cnst_B(self, Y)[source]

Compute $$B \mathbf{y}$$ component of ADMM problem constraint. In this case $$B \mathbf{y} = -\mathbf{y}$$.

solve(*args)

Call graph cnst_c(self)[source]

Compute constant component $$\mathbf{c}$$ of ADMM problem constraint. In this case $$\mathbf{c} = \mathbf{0}$$.

relax_AX(self)[source]

Implement relaxation if option RelaxParam != 1.0.

reconstruct(self, X=None)[source]

Reconstruct representation.