scico.functional¶

Functionals and functionals classes.

Classes

`AnisotropicTVNorm`([circular, axes, ...])	The anisotropic total variation (TV) norm.
`BM3D`([is_rgb, profile])	Pseudo-functional whose prox applies the BM3D denoising algorithm.
`BM4D`([profile])	Pseudo-functional whose prox applies the BM4D denoising algorithm.
`BoxIndicator`([lb, ub])	Box indicator function..
`ComposedFunctional`(functional, linop)	A functional constructed by composition.
`DnCNN`([variant])	Pseudo-functional whose prox applies the DnCNN denoising algorithm.
`Functional`()	Base class for functionals.
`FunctionalSum`(functional1, functional2)	A sum of two functionals.
`HuberNorm`([delta, separable])	Huber norm.
`IsotropicTVNorm`([circular, axes, ...])	The isotropic total variation (TV) norm.
`L0Norm`()	The \(\ell_0\) 'norm'.
`L1MinusL2Norm`([beta])	Difference of \(\ell_1\) and \(\ell_2\) norms.
`L1Norm`()	The \(\ell_1\) norm.
`L21Norm`([l2_axis])	The \(\ell_{2,1}\) norm.
`L2BallIndicator`([radius])	Indicator function for \(\ell_2\) ball of given radius.
`L2Norm`()	The \(\ell_2\) norm.
`NonNegativeIndicator`()	Indicator function for non-negative orthant.
`NuclearNorm`()	Nuclear norm.
`ProximalAverage`(func_list[, alpha_list, ...])	Weighted average of functionals.
`ScaledFunctional`(functional, scale)	A functional multiplied by a scalar.
`SeparableFunctional`(functional_list)	A functional that is separable in its arguments.
`SetDistance`(proj[, args])	Distance to a closed convex set.
`SquaredL2Norm`()	The squared \(\ell_2\) norm.
`SquaredSetDistance`(proj[, args])	Squared \(\ell_2\) distance to a closed convex set.
`TVNorm`(norm[, circular, axes, input_shape, ...])	Generic total variation (TV) norm.
`ZeroFunctional`()	Zero functional, \(f(\mb{x}) = 0 \in \mbb{R}\) for any input.

class scico.functional.Functional¶

Bases: object

Base class for functionals.

A functional maps an array-like to a scalar; abstractly, a functional is a mapping from \(\mathbb{R}^n\) or \(\mathbb{C}^n\) to \(\mathbb{R}\).

__call__(x)[source]¶

Evaluate this functional at point \(\mb{x}\).

Parameters:: x (Union[Array, BlockArray]) – Point at which to evaluate this functional.
Return type:: float
Returns:: Result of evaluating the functional at x.

conj_prox(v, lam=1.0, **kwargs)[source]¶

Scaled proximal operator of convex conjugate of functional.

Evaluate scaled proximal operator of convex conjugate (Fenchel conjugate) of this functional, with scaling \(\lambda\) = lam, and evaluated at point \(\mb{v}\) = v. Denoting this functional by \(f\) and its convex conjugate by \(f^*\), the proximal operator of \(f^*\) is computed as follows by exploiting the extended Moreau decomposition (see Sec. 6.6 of [7])

\[\prox_{\lambda f^*}(\mb{v}) = \mb{v} - \lambda \, \prox_{\lambda^{-1} f}(\mb{v / \lambda}) \;.\]

Parameters:

v (Union[Array, BlockArray]) – Point at which to evaluate prox function.
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional keyword args, passed directly to self.prox.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

grad(x)[source]¶

Evaluate the gradient of this functional at \(\mb{x}\).

Parameters:: x (Union[Array, BlockArray]) – Point at which to evaluate gradient.
Returns:: The gradient at x.

prox(v, lam=1.0, **kwargs)[source]¶

Scaled proximal operator of functional.

Evaluate scaled proximal operator of this functional, with scaling \(\lambda\) = lam and evaluated at point \(\mb{v}\) = v. The scaled proximal operator is defined as

\[\prox_{\lambda f}(\mb{v}) = \argmin_{\mb{x}} \lambda f(\mb{x}) + \frac{1}{2} \norm{\mb{v} - \mb{x}}_2^2\;,\]

where \(\lambda f(\mb{x})\) represents this functional evaluated at \(\mb{x}\) multiplied by \(\lambda\).

Parameters:

v (Union[Array, BlockArray]) – Point at which to evaluate prox function.
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes. These include x0, an initial guess for the minimizer in the definition of \(\prox\).

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.FunctionalSum(functional1, functional2)¶

Bases: Functional

A sum of two functionals.

__call__(x)[source]¶

Evaluate this functional at point \(\mb{x}\).

Parameters:: x (Union[Array, BlockArray]) – Point at which to evaluate this functional.
Return type:: float
Returns:: Result of evaluating the functional at x.

class scico.functional.ComposedFunctional(functional, linop)¶

Bases: Functional

A functional constructed by composition.

A functional constructed by composition of a functional with an orthogonal linear operator, i.e.

\[f(\mb{x}) = g(A \mb{x})\]

where \(f\) is the composed functional, \(g\) is the functional from which it is composed, and \(A\) is an orthogonal linear operator. Note that the resulting Functional can only be applied (either via evaluation or prox calls) to inputs of shape and dtype corresponding to the input specification of the linear operator.

Parameters:

functional (Functional) – The functional \(g\) to be composed.
linop (LinearOperator) – The linear operator \(A\) to be composed. Note that it is the user’s responsibility to confirm that the linear operator is orthogonal. If it is not, the result of prox will be incorrect.

__call__(x)[source]¶

Evaluate this functional at point \(\mb{x}\).

Parameters:: x (BlockArray) – Point at which to evaluate this functional.
Return type:: float
Returns:: Result of evaluating the functional at x.

prox(v, lam=1.0, **kwargs)[source]¶

Evaluate proximal operator of a composed functional.

Evaluate proximal operator \(f(\mb{x}) = g(A \mb{x})\), where \(A\) is an orthogonal linear operator, via a special case of Theorem 6.15 of [7]

\[\prox_{\lambda f}(\mb{v}) = A^T \prox_{\lambda g}(A \mb{v}) \;.\]

Examples of orthogonal linear operator in SCICO include linop.Reshape and linop.Transpose.

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.ScaledFunctional(functional, scale)¶

Bases: Functional

A functional multiplied by a scalar.

__call__(x)[source]¶

Evaluate this functional at point \(\mb{x}\).

Parameters:: x (Union[Array, BlockArray]) – Point at which to evaluate this functional.
Return type:: float
Returns:: Result of evaluating the functional at x.

prox(v, lam=1.0, **kwargs)[source]¶

Evaluate the scaled proximal operator of the scaled functional.

Note that, by definition, the scaled proximal operator of a functional is the proximal operator of the scaled functional. The scaled proximal operator of a scaled functional is the scaled proximal operator of the unscaled functional with the proximal operator scaling consisting of the product of the two scaling factors, i.e., for functional \(f\) and scaling factors \(\alpha\) and \(\beta\), the proximal operator with scaling parameter \(\alpha\) of scaled functional \(\beta f\) is the proximal operator with scaling parameter \(\alpha \beta\) of functional \(f\),

\[\prox_{\alpha (\beta f)}(\mb{v}) = \prox_{(\alpha \beta) f}(\mb{v}) \;.\]

Parameters:

v (Union[Array, BlockArray]) – Point at which to evaluate prox function.
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes. These include x0, an initial guess for the minimizer in the definition of \(\prox\).

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.SeparableFunctional(functional_list)¶

Bases: Functional

A functional that is separable in its arguments.

A separable functional \(f : \mathbb{C}^N \to \mathbb{R}\) can be written as the sum of functionals \(f_i : \mathbb{C}^{N_i} \to \mathbb{R}\) with \(\sum_i N_i = N\). In particular,

\[f(\mb{x}) = f(\mb{x}_1, \dots, \mb{x}_N) = f_1(\mb{x}_1) + \dots + f_N(\mb{x}_N) \;.\]

A SeparableFunctional accepts a BlockArray and is separable in the block components.

Parameters:: functional_list (List[Functional]) – List of component functionals f_i. This functional takes as an input a BlockArray with num_blocks == len(functional_list).

__call__(x)[source]¶

Evaluate this functional at point \(\mb{x}\).

Parameters:: x (BlockArray) – Point at which to evaluate this functional.
Return type:: float
Returns:: Result of evaluating the functional at x.

prox(v, lam=1.0, **kwargs)[source]¶

Evaluate proximal operator of the separable functional.

Evaluate proximal operator of the separable functional (see Theorem 6.6 of [7]).

\[\begin{split}\prox_{\lambda f}(\mb{v}) = \begin{bmatrix} \prox_{\lambda f_1}(\mb{v}_1) \\ \vdots \\ \prox_{\lambda f_N}(\mb{v}_N) \\ \end{bmatrix} \;.\end{split}\]

Parameters:

v (BlockArray) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

BlockArray

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.ZeroFunctional¶

Bases: Functional

Zero functional, \(f(\mb{x}) = 0 \in \mbb{R}\) for any input.

__call__(x)[source]¶

Evaluate this functional at point \(\mb{x}\).

Parameters:: x (Union[Array, BlockArray]) – Point at which to evaluate this functional.
Return type:: float
Returns:: Result of evaluating the functional at x.

prox(v, lam=1.0, **kwargs)[source]¶

Scaled proximal operator of functional.

Evaluate scaled proximal operator of this functional, with scaling \(\lambda\) = lam and evaluated at point \(\mb{v}\) = v. The scaled proximal operator is defined as

\[\prox_{\lambda f}(\mb{v}) = \argmin_{\mb{x}} \lambda f(\mb{x}) + \frac{1}{2} \norm{\mb{v} - \mb{x}}_2^2\;,\]

where \(\lambda f(\mb{x})\) represents this functional evaluated at \(\mb{x}\) multiplied by \(\lambda\).

Parameters:

v (Union[Array, BlockArray]) – Point at which to evaluate prox function.
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes. These include x0, an initial guess for the minimizer in the definition of \(\prox\).

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.HuberNorm(delta=1.0, separable=True)¶

Bases: Functional

Huber norm.

Compute a norm based on the Huber function [31] [7] (Sec. 6.7.1). In the non-separable case the norm is

\[\begin{split}H_{\delta}(\mb{x}) = \begin{cases} (1/2) \norm{ \mb{x} }_2^2 & \text{ when } \norm{ \mb{x} }_2 \leq \delta \\ \delta \left( \norm{ \mb{x} }_2 - (\delta / 2) \right) & \text{ when } \norm{ \mb{x} }_2 > \delta \;, \end{cases}\end{split}\]

where \(\delta\) is a parameter controlling the transitions between \(\ell_1\)-norm like and \(\ell_2\)-norm like behavior. In the separable case the norm is

\[H_{\delta}(\mb{x}) = \sum_i h_{\delta}(x_i) \,,\]

where

\[\begin{split}h_{\delta}(x) = \begin{cases} (1/2) \abs{ x }^2 & \text{ when } \abs{ x } \leq \delta \\ \delta \left( \abs{ x } - (\delta / 2) \right) & \text{ when } \abs{ x } > \delta \;. \end{cases}\end{split}\]

Parameters:

delta (float) – Huber function parameter \(\delta\).
separable (bool) – Flag indicating whether to compute separable or non-separable form.

__call__(x)[source]¶

Evaluate this functional at point \(\mb{x}\).

Parameters:: x (Union[Array, BlockArray]) – Point at which to evaluate this functional.
Return type:: float
Returns:: Result of evaluating the functional at x.

prox(v, lam=1.0, **kwargs)[source]¶

Evaluate proximal operator of the Huber function.

Evaluate scaled proximal operator of the Huber function [7] (Sec. 6.7.3). The prox is

\[\prox_{\lambda H_{\delta}} (\mb{v}) = \left( 1 - \frac{\lambda \delta} {\max\left\{\norm{\mb{v}}_2, \delta + \lambda \delta\right\} } \right) \mb{v}\]

in the non-separable case, and

\[\left[ \prox_{\lambda H_{\delta}} (\mb{v}) \right]_i = \left( 1 - \frac{\lambda \delta} {\max\left\{\abs{v_i}, \delta + \lambda \delta\right\} } \right) v_i\]

in the separable case.

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.L0Norm¶

Bases: Functional

The \(\ell_0\) ‘norm’.

The \(\ell_0\) ‘norm’ counts the number of non-zero elements in an array.

static prox(v, lam=1.0, **kwargs)[source]¶

Evaluate scaled proximal operator of \(\ell_0\) norm.

Evaluate scaled proximal operator of \(\ell_0\) norm using

\[\begin{split}\left[ \prox_{\lambda\| \cdot \|_0}(\mb{v}) \right]_i = \begin{cases} v_i & \text{ if } \abs{v_i} \geq \lambda \\ 0 & \text{ otherwise } \;. \end{cases}\end{split}\]

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Thresholding parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.L1Norm¶

Bases: Functional

The \(\ell_1\) norm.

Computes

\[\norm{\mb{x}}_1 = \sum_i \abs{x_i}^2 \;.\]

static prox(v, lam=1.0, **kwargs)[source]¶

Evaluate scaled proximal operator of \(\ell_1\) norm.

Evaluate scaled proximal operator of \(\ell_1\) norm using

\[\left[ \prox_{\lambda \|\cdot\|_1}(\mb{v}) \right]_i = \sign(v_i) (\abs{v_i} - \lambda)_+ \;,\]

where

\[\begin{split}(x)_+ = \begin{cases} x & \text{ if } x \geq 0 \\ 0 & \text{ otherwise} \;. \end{cases}\end{split}\]

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Thresholding parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Array

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.SquaredL2Norm¶

Bases: Functional

The squared \(\ell_2\) norm.

Squared \(\ell_2\) norm

\[\norm{\mb{x}}^2_2 = \sum_i \abs{x_i}^2 \;.\]

static prox(v, lam=1.0, **kwargs)[source]¶

Evaluate proximal operator of squared \(\ell_2\) norm.

Evaluate proximal operator of squared \(\ell_2\) norm using

\[\prox_{\lambda \| \cdot \|_2^2}(\mb{v}) = \frac{\mb{v}}{1 + 2 \lambda} \;.\]

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.L2Norm¶

Bases: Functional

The \(\ell_2\) norm.

\[\norm{\mb{x}}_2 = \sqrt{\sum_i \abs{x_i}^2} \;.\]

static prox(v, lam=1.0, **kwargs)[source]¶

Evaluate proximal operator of \(\ell_2\) norm.

Evaluate proximal operator of \(\ell_2\) norm using

\[\prox_{\lambda \| \cdot \|_2}(\mb{v}) = \mb{v} \, \left(1 - \frac{\lambda}{\norm{\mb{v}}_2} \right)_+ \;,\]

where

\[\begin{split}(x)_+ = \begin{cases} x & \text{ if } x \geq 0 \\ 0 & \text{ otherwise} \;. \end{cases}\end{split}\]

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.L21Norm(l2_axis=0)¶

Bases: Functional

The \(\ell_{2,1}\) norm.

For a \(M \times N\) matrix, \(\mb{A}\), by default,

\[\norm{\mb{A}}_{2,1} = \sum_{n=1}^N \sqrt{\sum_{m=1}^M \abs{A_{m,n}}^2} \;.\]

The norm generalizes to more dimensions by first computing the \(\ell_2\) norm along one or more (user-specified) axes, followed by a sum over all remaining axes. BlockArray inputs require parameter l2_axis to be None, in which case the \(\ell_2\) norm is computed over each block.

A typical use case is computing the isotropic total variation norm.

Parameters:: l2_axis (Union[None, int, Tuple]) – Axis/axes over which to take the l2 norm. Required to be None for BlockArray inputs to be supported.

__call__(x)[source]¶

Evaluate this functional at point \(\mb{x}\).

Parameters:: x (Union[Array, BlockArray]) – Point at which to evaluate this functional.
Return type:: float
Returns:: Result of evaluating the functional at x.

prox(v, lam=1.0, **kwargs)[source]¶

Evaluate proximal operator of the \(\ell_{2,1}\) norm.

In two dimensions,

\[\prox_{\lambda \|\cdot\|_{2,1}}(\mb{v}, \lambda)_{:, n} = \frac{\mb{v}_{:, n}}{\|\mb{v}_{:, n}\|_2} (\|\mb{v}_{:, n}\|_2 - \lambda)_+ \;,\]

where

\[\begin{split}(x)_+ = \begin{cases} x & \text{ if } x \geq 0 \\ 0 & \text{ otherwise} \;. \end{cases}\end{split}\]

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.NuclearNorm¶

Bases: Functional

Nuclear norm.

Compute the nuclear norm

\[\| X \|_* = \sum_i \sigma_i\]

where \(\sigma_i\) are the singular values of matrix \(X\).

static prox(v, lam=1.0, **kwargs)[source]¶

Evaluate proximal operator of the nuclear norm.

Evaluate proximal operator of the nuclear norm [13].

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\). Required to be two-dimensional.
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.L1MinusL2Norm(beta=1.0)¶

Bases: Functional

Difference of \(\ell_1\) and \(\ell_2\) norms.

Difference of \(\ell_1\) and \(\ell_2\) norms

\[\norm{\mb{x}}_1 - \beta * \norm{\mb{x}}_2\]

Parameters:: beta (float) – Parameter \(\beta\) in the norm definition.

__call__(x)[source]¶

Evaluate this functional at point \(\mb{x}\).

Parameters:: x (Union[Array, BlockArray]) – Point at which to evaluate this functional.
Return type:: float
Returns:: Result of evaluating the functional at x.

prox(v, lam=1.0, **kwargs)[source]¶

Proximal operator of difference of \(\ell_1\) and \(\ell_2\) norms.

Evaluate the proximal operator of the difference of \(\ell_1\) and \(\ell_2\) norms, i.e. \(\alpha \left( \| \mb{x} \|_1 - \beta \| \mb{x} \|_2 \right)\) [39]. Note that this is not a proximal operator according to the strict definition since the loss function is non-convex.

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.AnisotropicTVNorm(circular=False, axes=None, input_shape=None, input_dtype=<class 'jax.numpy.float32'>)¶

Bases: TVNorm

The anisotropic total variation (TV) norm.

The anisotropic total variation (TV) norm computed by

ATV = scico.functional.AnisotropicTVNorm()
x_norm = ATV(x)

is equivalent to

C = linop.FiniteDifference(input_shape=x.shape, circular=True)
L1 = functional.L1Norm()
x_norm = L1(C @ x)

The scaled proximal operator is computed using an approximation that holds for small scaling parameters [34]. This does not imply that it can only be applied to problems requiring a small regularization parameter since most proximal algorithms include an additional algorithm parameter that also plays a role in the parameter of the proximal operator. For example, in PGM and AcceleratedPGM, the scaled proximal operator parameter is the regularization parameter divided by the L0 algorithm parameter, and for ADMM, the scaled proximal operator parameters are the regularization parameters divided by the entries in the rho_list algorithm parameter.

Parameters:

circular (bool) – Flag indicating use of circular boundary conditions.
axes (Union[int, Tuple[int, ...], List[int], None]) – Axis or axes over which to apply finite difference operator. If not specified, or None, differences are evaluated along all axes.
input_shape (Optional[Tuple[int, ...]]) – Shape of input arrays of __call__ and prox.
input_dtype (DType) – dtype of input arrays of __call__ and prox.

class scico.functional.IsotropicTVNorm(circular=False, axes=None, input_shape=None, input_dtype=<class 'jax.numpy.float32'>)¶

Bases: TVNorm

The isotropic total variation (TV) norm.

The isotropic total variation (TV) norm computed by

ATV = scico.functional.IsotropicTVNorm()
x_norm = ATV(x)

is equivalent to

C = linop.FiniteDifference(input_shape=x.shape, circular=True)
L21 = functional.L21Norm()
x_norm = L21(C @ x)

The scaled proximal operator is computed using an approximation that holds for small scaling parameters [35]. This does not imply that it can only be applied to problems requiring a small regularization parameter since most proximal algorithms include an additional algorithm parameter that also plays a role in the parameter of the proximal operator. For example, in PGM and AcceleratedPGM, the scaled proximal operator parameter is the regularization parameter divided by the L0 algorithm parameter, and for ADMM, the scaled proximal operator parameters are the regularization parameters divided by the entries in the rho_list algorithm parameter.

Parameters:

circular (bool) – Flag indicating use of circular boundary conditions.
axes (Union[int, Tuple[int, ...], List[int], None]) – Axis or axes over which to apply finite difference operator. If not specified, or None, differences are evaluated along all axes.
input_shape (Optional[Tuple[int, ...]]) – Shape of input arrays of __call__ and prox.
input_dtype (DType) – dtype of input arrays of __call__ and prox.

class scico.functional.TVNorm(norm, circular=True, axes=None, input_shape=None, input_dtype=<class 'jax.numpy.float32'>)¶

Bases: Functional

Generic total variation (TV) norm.

Generic total variation (TV) norm with approximation of the scaled proximal operator [34] [35] [15].

While initializers for Functional objects typically do not take input_shape and input_dtype parameters, they are included here because methods __call__ and prox require instantiation of some LinearOperator objects, which do take these parameters. If these parameters are not provided on intialization of a TVNorm object, then creation of the required LinearOperator objects is deferred until these methods are called, which can result in JAX tracer errors when they are components of a jitted function.

Parameters:

norm (Functional) – Norm functional from which the TV norm is composed.
circular (bool) – Flag indicating use of circular boundary conditions.
axes (Union[int, Tuple[int, ...], List[int], None]) – Axis or axes over which to apply finite difference operator. If not specified, or None, differences are evaluated along all axes.
input_shape (Optional[Tuple[int, ...]]) – Shape of input arrays of __call__ and prox.
input_dtype (DType) – dtype of input arrays of __call__ and prox.

__call__(x)[source]¶

Compute the TV norm of an array.

Parameters:: x (Array) – Array for which the TV norm should be computed.
Return type:: float
Returns:: TV norm of x.

prox(v, lam=1.0, **kwargs)[source]¶

Approximate scaled proximal operator of the TV norm.

Approximation of the scaled proximal operator of the TV norm, computed via the methods described in [34] [35] [15].

Parameters:

v (Array) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lam\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Array

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.ProximalAverage(func_list, alpha_list=None, no_inf_eval=True)¶

Bases: Functional

Weighted average of functionals.

A functional that is composed of a weighted average of functionals. All of the component functionals are required to have proximal operators. The proximal operator of the composite functional is approximated via the proximal average method [62], which holds for small scaling parameters. This does not imply that it can only be applied to problems requiring a small regularization parameter since most proximal algorithms include an additional algorithm parameter that also plays a role in the parameter of the proximal operator. For example, in PGM and AcceleratedPGM, the scaled proximal operator parameter is the regularization parameter divided by the L0 algorithm parameter, and for ADMM, the scaled proximal operator parameters are the regularization parameters divided by the entries in the rho_list algorithm parameter.

Parameters:

func_list (List[Functional]) – List of component Functional objects, all of which must have a proximal operator.
alpha_list (Optional[List[float]]) – List of scalar weights for each Functional. If not specified, defaults to equal weights. If specified, the list of weights must have the same length as the Functional list. If the weights do not sum to unity, they are scaled to ensure that they do.
no_inf_eval – If True, exclude infinite values (typically associated with a functional that is an indicator function) from the evaluation of the sum of component functionals.

__call__(x)[source]¶

Evaluate the weighted average of component functionals.

Return type:: float

prox(v, lam=1.0, **kwargs)[source]¶

Approximate proximal operator of the average of functionals.

Approximation of the proximal operator of a weighted average of functionals computed via the proximal average method [62].

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lam\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.NonNegativeIndicator¶

Bases: Functional

Indicator function for non-negative orthant.

Returns 0 if all elements of input array-like are non-negative, and inf otherwise

\[\begin{split}I(\mb{x}) = \begin{cases} 0 & \text{ if } x_i \geq 0 \; \forall i \\ \infty & \text{ otherwise} \;. \end{cases}\end{split}\]

__call__(x)[source]¶

Evaluate this functional at point \(\mb{x}\).

Parameters:: x (Union[Array, BlockArray]) – Point at which to evaluate this functional.
Return type:: float
Returns:: Result of evaluating the functional at x.

prox(v, lam=1.0, **kwargs)[source]¶

The scaled proximal operator of the non-negative indicator.

Evaluate the scaled proximal operator of the indicator over the non-negative orthant, \(I\),

\[\begin{split}[\mathrm{prox}_{\lambda I}(\mb{v})]_i = \begin{cases} v_i\, & \text{ if } v_i \geq 0 \\ 0\, & \text{ otherwise} \;. \end{cases}\end{split}\]

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lambda\) (has no effect).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.L2BallIndicator(radius=1.0)¶

Bases: Functional

Indicator function for \(\ell_2\) ball of given radius.

Indicator function for \(\ell_2\) ball of given radius, \(r\)

\[\begin{split}I(\mb{x}) = \begin{cases} 0 & \text{ if } \norm{\mb{x}}_2 \leq r \\ \infty & \text{ otherwise} \;. \end{cases}\end{split}\]

Attributes:: radius – Radius of \(\ell_2\) ball.

Initialize a L2BallIndicator object.

Parameters:: radius (float) – Radius of \(\ell_2\) ball. Default: 1.0.

__call__(x)[source]¶

Evaluate this functional at point \(\mb{x}\).

Parameters:: x (Union[Array, BlockArray]) – Point at which to evaluate this functional.
Return type:: float
Returns:: Result of evaluating the functional at x.

prox(v, lam=1.0, **kwargs)[source]¶

The scaled proximal operator of the \(\ell_2\) ball indicator.

Evaluate the scaled proximal operator of the indicator, \(I\), of the \(\ell_2\) ball with radius \(r\)

\[\begin{split}\mathrm{prox}_{\lambda I}(\mb{v}) = \begin{cases} \mb{v} & \text{ if } \norm{\mb{v}}_2 \leq r \\ r \frac{\mb{v}}{\norm{\mb{v}}_2} & \text{ otherwise} \;. \end{cases}\end{split}\]

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lambda\) (has no effect).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.BoxIndicator(lb=0.0, ub=1.0)¶

Bases: Functional

Box indicator function..

Indicator function of the constraint set \(a \leq x \leq b\) for lower and upper bounds \(a\) and \(b\) respectively.

Initialize a BoxIndicator object.

Parameters:

lb (float) – Lower bound.
ub (float) – Upper bound.

__call__(x)[source]¶

Evaluate this functional at point \(\mb{x}\).

Parameters:: x (Union[Array, BlockArray]) – Point at which to evaluate this functional.
Return type:: float
Returns:: Result of evaluating the functional at x.

prox(v, lam=1.0, **kwargs)[source]¶

The scaled proximal operator of the box indicator.

Evaluate the scaled proximal operator of the constraint set \(a \leq x \leq b\) for lower and upper bounds \(a\) and \(b\) respectively.

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lambda\) (has no effect).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Result of evaluating the scaled proximal operator at v.

class scico.functional.BM3D(is_rgb=False, profile='np')¶

Bases: Functional

Pseudo-functional whose prox applies the BM3D denoising algorithm.

A pseudo-functional that has the BM3D algorithm [17] as its proximal operator, which calls denoiser.bm3d. Since this function provides an interface to compiled C code, JAX features such as automatic differentiation and support for GPU devices are not available.

Initialize a BM3D object.

Parameters:

is_rgb (bool) – Flag indicating use of BM3D with a color transform. Default: False.
profile (Union[Any, str]) – Parameter configuration for BM3D.

prox(x, lam=1.0, **kwargs)[source]¶

Apply BM3D denoiser.

Parameters:

x (Array) – Input image.
lam (float) – Noise parameter.
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Array

Returns:

Denoised output.

class scico.functional.BM4D(profile='np')¶

Bases: Functional

Pseudo-functional whose prox applies the BM4D denoising algorithm.

A pseudo-functional that has the BM4D algorithm [41] as its proximal operator, which calls denoiser.bm4d. Since this function provides an interface to compiled C code, JAX features such as automatic differentiation and support for GPU devices are not available.

Initialize a BM4D object.

Parameters:: profile (Union[Any, str]) – Parameter configuration for BM4D.

prox(x, lam=1.0, **kwargs)[source]¶

Apply BM4D denoiser.

Parameters:

x (Array) – Input image.
lam (float) – Noise parameter.
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Array

Returns:

Denoised output.

class scico.functional.DnCNN(variant='6M')¶

Bases: Functional

Pseudo-functional whose prox applies the DnCNN denoising algorithm.

A pseudo-functional that has the DnCNN algorithm [64] as its proximal operator, implemented via denoiser.DnCNN.

Parameters:: variant (str) – Identify the DnCNN model to be used. See denoiser.DnCNN for valid values.

prox(x, lam=1.0, **kwargs)[source]¶

Apply DnCNN denoiser.

Warning: The lam parameter is ignored, and has no effect on the output for DnCNN objects initialized with variant parameter values other than 6N and 17N.

Parameters:

x (Array) – Input array.
lam (float) – Noise parameter (ignored).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Array

Returns:

Denoised output.

class scico.functional.SetDistance(proj, args=())¶

Bases: Functional

Distance to a closed convex set.

This functional computes the \(\ell_2\) distance from a vector to a closed convex set \(C\)

\[d(\mb{x}) = \min_{\mb{y} \in C} \, \| \mb{x} - \mb{y} \|_2 \;.\]

The set is not specified directly, but in terms of a function computing the projection into that set, i.e.

\[d(\mb{x}) = \| \mb{x} - P_C(\mb{x}) \|_2 \;,\]

where \(P_C(\mb{x})\) is the projection of \(\mb{x}\) into set \(C\).

Parameters:

proj (Callable) – Function computing the projection into the convex set.
args – Additional arguments for function proj.

__call__(x)[source]¶

Compute the \(\ell_2\) distance to the set.

Compute the distance \(d(\mb{x})\) between \(\mb{x}\) and the set \(C\).

Parameters:: x (Union[Array, BlockArray]) – Input array \(\mb{x}\).
Return type:: float
Returns:: Euclidean distance from x to the projection of x.

prox(v, lam=1.0, **kwargs)[source]¶

Proximal operator of the \(\ell_2\) distance function.

Compute the proximal operator of the \(\ell_2\) distance function \(d(\mb{x})\) [7] (Lemma 6.43).

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Scaled proximal operator evaluated at v.

class scico.functional.SquaredSetDistance(proj, args=())¶

Bases: Functional

Squared \(\ell_2\) distance to a closed convex set.

This functional computes the \(\ell_2\) distance from a vector to a closed convex set \(C\)

\[d(\mb{x}) = \min_{\mb{y} \in C} \, (1/2) \| \mb{x} - \mb{y} \|_2^2 \;.\]

The set is not specified directly, but in terms of a function computing the projection into that set, i.e.

\[d(\mb{x}) = (1/2) \| \mb{x} - P_C(\mb{x}) \|_2^2 \;,\]

where \(P_C(\mb{x})\) is the projection of \(\mb{x}\) into set \(C\).

Parameters:

proj (Callable) – Function computing the projection into the convex set.
args – Additional arguments for function proj.

__call__(x)[source]¶

Compute the squared \(\ell_2\) distance to the set.

Compute the distance \(d(\mb{x})\) between \(\mb{x}\) and the set \(C\).

Parameters:: x (Union[Array, BlockArray]) – Input array \(\mb{x}\).
Return type:: float
Returns:: Squared \(\ell_2\) distance from x to the projection of x.

prox(v, lam=1.0, **kwargs)[source]¶

Proximal operator of the squared \(\ell_2\) distance function.

Compute the proximal operator of the squared \(\ell_2\) distance function \(d(\mb{x})\) [7] (Example 6.65).

Parameters:

v (Union[Array, BlockArray]) – Input array \(\mb{v}\).
lam (float) – Proximal parameter \(\lambda\).
**kwargs – Additional arguments that may be used by derived classes.

Return type:

Union[Array, BlockArray]

Returns:

Scaled proximal operator evaluated at v.