`corrct.regularizers`

Regularizers module.

@author: Nicola VIGANÒ, Computational Imaging group, CWI, The Netherlands, and ESRF - The European Synchrotron, Grenoble, France

Module Contents

Classes

`BaseRegularizer`	Initialize a base regularizer class, that defines the Regularizer object interface.
`Regularizer_Grad`	Gradient regularizer.
`Regularizer_TV1D`	Total Variation (TV) regularizer in 1D. It can be used to promote piece-wise constant reconstructions.
`Regularizer_TV2D`	Total Variation (TV) regularizer in 2D. It can be used to promote piece-wise constant reconstructions.
`Regularizer_TV3D`	Total Variation (TV) regularizer in 3D. It can be used to promote piece-wise constant reconstructions.
`Regularizer_HubTV2D`	Total Variation (TV) regularizer in 2D. It can be used to promote piece-wise constant reconstructions.
`Regularizer_HubTV3D`	Total Variation (TV) regularizer in 3D. It can be used to promote piece-wise constant reconstructions.
`Regularizer_smooth1D`	It can be used to promote smooth reconstructions.
`Regularizer_smooth2D`	It can be used to promote smooth reconstructions.
`Regularizer_smooth3D`	It can be used to promote smooth reconstructions.
`Regularizer_lap`	Laplacian regularizer. It can be used to promote smooth reconstructions.
`Regularizer_lap1D`	Laplacian regularizer in 1D. It can be used to promote smooth reconstructions.
`Regularizer_lap2D`	Laplacian regularizer in 2D. It can be used to promote smooth reconstructions.
`Regularizer_lap3D`	Laplacian regularizer in 3D. It can be used to promote smooth reconstructions.
`Regularizer_l1`	l1-norm regularizer. It can be used to promote sparse reconstructions.
`Regularizer_swl`	Base stationary wavelet regularizer. It can be used to promote sparse reconstructions in the wavelet domain.
`Regularizer_l1swl`	l1-norm Wavelet regularizer. It can be used to promote sparse reconstructions in the wavelet domain.
`Regularizer_l21swl`	l1-norm Wavelet regularizer. It can be used to promote sparse reconstructions in the wavelet domain.
`Regularizer_Hub_swl`	l1-norm Wavelet regularizer. It can be used to promote sparse reconstructions in the wavelet domain.
`Regularizer_dwl`	Base decimated wavelet regularizer. It can be used to promote sparse reconstructions in the wavelet domain.
`Regularizer_l1dwl`	l1-norm decimated wavelet regularizer. It can be used to promote sparse reconstructions.
`Regularizer_l21dwl`	l1-norm decimated wavelet regularizer. It can be used to promote sparse reconstructions.
`Regularizer_Hub_dwl`	l1-norm decimated wavelet regularizer. It can be used to promote sparse reconstructions.
`BaseRegularizer_med`	Median filter regularizer base class. It can be used to promote filtered reconstructions.
`Regularizer_l1med`	l1-norm median filter regularizer. It can be used to promote filtered reconstructions.
`Regularizer_l2med`	l2-norm median filter regularizer. It can be used to promote filtered reconstructions.
`Regularizer_fft`	Fourier regularizer. It can be used to promote sparse reconstructions in the Fourier domain.
`Regularizer_TNV`	Total Nuclear Variation (TNV) regularizer.
`Regularizer_VTV`	Vectorial Total Variation (VTV) regularizer.
`Regularizer_lnswl`	Nuclear-norm Wavelet regularizer.
`Regularizer_vl1wl`	l1-norm vectorial Wavelet regularizer. It can be used to promote compressed reconstructions.
`Regularizer_vSVD`	Regularizer based on the Singular Value Decomposition.
`Constraint_LowerLimit`	Lower limit constraint. It can be used to promote reconstructions in certain regions of solution space.
`Constraint_UpperLimit`	Upper limit constraint. It can be used to promote reconstructions in certain regions of solution space.

Data

NDArrayInt

API

corrct.regularizers.NDArrayInt: None

class corrct.regularizers.BaseRegularizer(weight: float | numpy.typing.NDArray, norm: corrct.data_terms.DataFidelityBase, upd_mask: numpy.typing.NDArray | None = None, dtype: numpy.typing.DTypeLike = np.float32)[source]

Bases: abc.ABC

Initialize a base regularizer class, that defines the Regularizer object interface.

Parameters

weight : float | NDArray The weight of the regularizer. norm : DataFidelityBase The norm of the regularizer minimization.

Initialization

__reg_name__ = <Multiline-String>

weight: numpy.typing.NDArray: None

dtype: numpy.typing.DTypeLike: None

op: corrct.operators.BaseTransform | None: None

sigma: float | numpy.typing.NDArray: None

upd_mask: numpy.typing.NDArray | None: None

info() → str[source]

Return the regularizer info.

Returns

str Regularizer info string.

upper() → str[source]

Return the upper case name of the regularizer.

Returns

str Upper case string name of the regularizer.

lower() → str[source]

Return the lower case name of the regularizer.

Returns

str Lower case string name of the regularizer.

abstract initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

Initialize the internal state, operator, and sigma. It then returns the tau.

Parameters

primal : NDArray The primal vector.

Returns

float | NDArray The tau to be used in the SIRT or PDHG algorithm.

initialize_dual() → numpy.typing.NDArray[source]

Return the initialized dual.

Returns

NDArray Initialized (zero) dual.

update_dual(dual: numpy.typing.NDArray, primal: numpy.typing.NDArray) → None[source]

Update the dual in-place.

Parameters

dual : NDArray Current stat of the dual. primal : NDArray Primal or over-relaxation of the primal.

apply_proximal_dual(dual: numpy.typing.NDArray) → None[source]

Apply the proximal operator to the dual in-place.

Parameters

dual : NDArray The dual to be applied the proximal on.

abstract apply_proximal_primal(primal: numpy.typing.NDArray, tau: float | numpy.typing.NDArray) → None[source]

Apply the proximal of the regularizer in the primal domain, in-place.

Computes prox_{tau * weight * g}(primal) where g is the regularization functional, and stores the result back into primal.

This method is only implemented for regularizers whose operator is unitary (or the identity), so that the proximal separates in the primal domain. For regularizers based on non-unitary transforms (gradient, Laplacian, etc.), this raises NotImplementedError — use PDHG instead.

Parameters

primal : NDArray The primal variable to update in-place. tau : float | NDArray The proximal step size.

compute_update_primal(dual: numpy.typing.NDArray) → numpy.typing.NDArray[source]

Compute the partial update of a primal term, from this regularizer.

Parameters

dual : NDArray The dual associated to this regularizer.

Returns

upd : NDArray The update to the primal.

_check_primal(primal: numpy.typing.NDArray) → None[source]

class corrct.regularizers.Regularizer_Grad(weight: float | numpy.typing.NDArray, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l21())[source]

Bases: corrct.regularizers.BaseRegularizer

Gradient regularizer.

When used with l1-norms, it promotes piece-wise constant reconstructions. When used with l2-norm, it promotes smooth reconstructions.

Parameters

weight : float | NDArray The weight of the regularizer. ndims : int, optional The number of dimensions. The default is 2. axes : Sequence, optional The axes over which it computes the gradient. If None, it uses the last 2. The default is None. pad_mode: str, optional The padding mode to use. The default is “edge”. norm : DataFidelityBase, optional The norm of the regularizer minimization. The default is DataFidelity_l21().

Initialization

__reg_name__: ‘grad’

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

abstract apply_proximal_primal(primal: numpy.typing.NDArray, tau: float | numpy.typing.NDArray) → None[source]

Not implemented: gradient-based regularizers (TV, smooth) require solving a non-trivial optimization subproblem in the primal domain, because the gradient operator is not unitary. There is no simple closed-form proximal.

Raises

NotImplementedError Always raised; use PDHG for gradient-based regularizers.

class corrct.regularizers.Regularizer_TV1D(weight: float | numpy.typing.NDArray, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l21())[source]

Bases: corrct.regularizers.Regularizer_Grad

Total Variation (TV) regularizer in 1D. It can be used to promote piece-wise constant reconstructions.

Initialization

__reg_name__: ‘TV1D’

class corrct.regularizers.Regularizer_TV2D(weight: float | numpy.typing.NDArray, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l21())[source]

Bases: corrct.regularizers.Regularizer_Grad

Total Variation (TV) regularizer in 2D. It can be used to promote piece-wise constant reconstructions.

Initialization

__reg_name__: ‘TV2D’

class corrct.regularizers.Regularizer_TV3D(weight: float | numpy.typing.NDArray, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l21())[source]

Bases: corrct.regularizers.Regularizer_Grad

Total Variation (TV) regularizer in 3D. It can be used to promote piece-wise constant reconstructions.

Initialization

__reg_name__: ‘TV3D’

class corrct.regularizers.Regularizer_HubTV2D(weight: float | numpy.typing.NDArray, huber_size: float, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None)[source]

Bases: corrct.regularizers.Regularizer_Grad

Total Variation (TV) regularizer in 2D. It can be used to promote piece-wise constant reconstructions.

Initialization

__reg_name__: ‘HubTV2D’

class corrct.regularizers.Regularizer_HubTV3D(weight: float | numpy.typing.NDArray, huber_size: float, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None)[source]

Bases: corrct.regularizers.Regularizer_Grad

Total Variation (TV) regularizer in 3D. It can be used to promote piece-wise constant reconstructions.

Initialization

__reg_name__: ‘HubTV3D’

class corrct.regularizers.Regularizer_smooth1D(weight: float | numpy.typing.NDArray, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l2())[source]

Bases: corrct.regularizers.Regularizer_Grad

It can be used to promote smooth reconstructions.

Initialization

__reg_name__: ‘smooth1D’

class corrct.regularizers.Regularizer_smooth2D(weight: float | numpy.typing.NDArray, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l2())[source]

Bases: corrct.regularizers.Regularizer_Grad

It can be used to promote smooth reconstructions.

Initialization

__reg_name__: ‘smooth2D’

class corrct.regularizers.Regularizer_smooth3D(weight: float | numpy.typing.NDArray, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l2())[source]

Bases: corrct.regularizers.Regularizer_Grad

It can be used to promote smooth reconstructions.

Initialization

__reg_name__: ‘smooth3D’

class corrct.regularizers.Regularizer_lap(weight: float | numpy.typing.NDArray, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None)[source]

Bases: corrct.regularizers.BaseRegularizer

Laplacian regularizer. It can be used to promote smooth reconstructions.

Initialization

__reg_name__: ‘lap’

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

abstract apply_proximal_primal(primal: numpy.typing.NDArray, tau: float | numpy.typing.NDArray) → None[source]

Not implemented: the Laplacian operator is not unitary, so its proximal in the primal domain has no closed-form solution and requires an iterative solve.

Raises

NotImplementedError Always raised; use PDHG for Laplacian regularizers.

class corrct.regularizers.Regularizer_lap1D(weight, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None)[source]

Bases: corrct.regularizers.Regularizer_lap

Laplacian regularizer in 1D. It can be used to promote smooth reconstructions.

Initialization

__reg_name__: ‘lap1D’

class corrct.regularizers.Regularizer_lap2D(weight, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None)[source]

Bases: corrct.regularizers.Regularizer_lap

Laplacian regularizer in 2D. It can be used to promote smooth reconstructions.

Initialization

__reg_name__: ‘lap2D’

class corrct.regularizers.Regularizer_lap3D(weight, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None)[source]

Bases: corrct.regularizers.Regularizer_lap

Laplacian regularizer in 3D. It can be used to promote smooth reconstructions.

Initialization

__reg_name__: ‘lap3D’

class corrct.regularizers.Regularizer_l1(weight: float | numpy.typing.NDArray, upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l1())[source]

Bases: corrct.regularizers.BaseRegularizer

l1-norm regularizer. It can be used to promote sparse reconstructions.

Initialization

__reg_name__: ‘l1’

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

update_dual(dual: numpy.typing.NDArray, primal: numpy.typing.NDArray) → None[source]

apply_proximal_primal(primal: numpy.typing.NDArray, tau: float | numpy.typing.NDArray) → None[source]

Apply prox_{tau * weight * ||.||_1} in-place via element-wise soft-thresholding.

For g(x) = weight * ||x||_1, the proximal is: prox(x)_i = sign(x_i) * max(|x_i| - tau * weight, 0)

The operator is the identity (TransformIdentity), so the proximal separates element-wise. When upd_mask is set, only the elements inside the mask are thresholded; the rest are left unchanged.

Parameters

primal : NDArray The primal variable to update in-place. tau : float | NDArray The proximal step size.

class corrct.regularizers.Regularizer_swl(weight: float | numpy.typing.NDArray, wavelet: str, level: int, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_on_demand: str = 'constant', upd_mask: numpy.typing.NDArray | None = None, normalized: bool = False, min_approx: bool = True, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l1())[source]

Bases: corrct.regularizers.BaseRegularizer

Base stationary wavelet regularizer. It can be used to promote sparse reconstructions in the wavelet domain.

Initialization

__reg_name__: ‘swl’

info() → str[source]

Return the regularizer info.

Returns

str Regularizer info string.

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

update_dual(dual: numpy.typing.NDArray, primal: numpy.typing.NDArray) → None[source]

apply_proximal_dual(dual: numpy.typing.NDArray) → None[source]

apply_proximal_primal(primal: numpy.typing.NDArray, tau: float | numpy.typing.NDArray) → None[source]

Apply prox_{tau * weight * g} in the primal domain via the wavelet transform.

The stationary wavelet transform (with normalized=True) is a tight frame (Parseval / isometric), so the proximal of weight * ||W .||_1 in the primal domain is:

prox(x) = W^T * prox_{tau * weight * ||.||_1}(W * x)

i.e. transform -> soft-threshold coefficients -> inverse transform.

When normalized=False the frame is not tight and this method raises NotImplementedError, because the correct step sizes per sub-band cannot be collapsed into a single tau without further information.

Parameters

primal : NDArray The primal variable to update in-place. tau : float | NDArray The proximal step size.

Raises

NotImplementedError When the wavelet transform is not normalized (not a tight frame). ValueError When the regularizer has not been initialized.

class corrct.regularizers.Regularizer_l1swl(weight: float | numpy.typing.NDArray, wavelet: str, level: int, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_on_demand: str = 'constant', upd_mask: numpy.typing.NDArray | None = None, normalized: bool = False, min_approx: bool = True)[source]

Bases: corrct.regularizers.Regularizer_swl

l1-norm Wavelet regularizer. It can be used to promote sparse reconstructions in the wavelet domain.

Initialization

__reg_name__: ‘l1swl’

class corrct.regularizers.Regularizer_l21swl(weight: float | numpy.typing.NDArray, wavelet: str, level: int, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_on_demand: str = 'constant', upd_mask: numpy.typing.NDArray | None = None, normalized: bool = False, min_approx: bool = True)[source]

Bases: corrct.regularizers.Regularizer_swl

l1-norm Wavelet regularizer. It can be used to promote sparse reconstructions in the wavelet domain.

Initialization

__reg_name__: ‘l21swl’

class corrct.regularizers.Regularizer_Hub_swl(weight: float | numpy.typing.NDArray, wavelet: str, level: int, huber_size: float, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_on_demand: str = 'constant', upd_mask: numpy.typing.NDArray | None = None, normalized: bool = False, min_approx: bool = True)[source]

Bases: corrct.regularizers.Regularizer_swl

l1-norm Wavelet regularizer. It can be used to promote sparse reconstructions in the wavelet domain.

Initialization

__reg_name__: ‘Hubswl’

class corrct.regularizers.Regularizer_dwl(weight: float | numpy.typing.NDArray, wavelet: str, level: int, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_on_demand: str = 'constant', upd_mask: numpy.typing.NDArray | None = None, min_approx: bool = True, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l1())[source]

Bases: corrct.regularizers.BaseRegularizer

Base decimated wavelet regularizer. It can be used to promote sparse reconstructions in the wavelet domain.

Initialization

__reg_name__: ‘dwl’

info() → str[source]

Return the regularizer info.

Returns

str Regularizer info string.

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

update_dual(dual: numpy.typing.NDArray, primal: numpy.typing.NDArray) → None[source]

apply_proximal_dual(dual: numpy.typing.NDArray) → None[source]

apply_proximal_primal(primal: numpy.typing.NDArray, tau: float | numpy.typing.NDArray) → None[source]

Apply prox_{tau * weight * g} in the primal domain for decimated wavelets.

The decimated wavelet transform is orthogonal (W^T W = I), so it is a tight frame with frame bound 1. The proximal of weight * ||W .||_1 is therefore:

prox(x) = W^T * prox_{tau * weight * ||.||_1}(W * x)

i.e. transform -> soft-threshold each sub-band -> inverse transform.

Parameters

primal : NDArray The primal variable to update in-place. tau : float | NDArray The proximal step size.

Raises

ValueError When the regularizer has not been initialized.

class corrct.regularizers.Regularizer_l1dwl(weight: float | numpy.typing.NDArray, wavelet: str, level: int, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_on_demand: str = 'constant', upd_mask: numpy.typing.NDArray | None = None, min_approx: bool = True)[source]

Bases: corrct.regularizers.Regularizer_dwl

l1-norm decimated wavelet regularizer. It can be used to promote sparse reconstructions.

Initialization

__reg_name__: ‘l1dwl’

class corrct.regularizers.Regularizer_l21dwl(weight: float | numpy.typing.NDArray, wavelet: str, level: int, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_on_demand: str = 'constant', upd_mask: numpy.typing.NDArray | None = None, min_approx: bool = True)[source]

Bases: corrct.regularizers.Regularizer_dwl

l1-norm decimated wavelet regularizer. It can be used to promote sparse reconstructions.

Initialization

__reg_name__: ‘l21dwl’

class corrct.regularizers.Regularizer_Hub_dwl(weight: float | numpy.typing.NDArray, wavelet: str, level: int, huber_size: float, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_on_demand: str = 'constant', upd_mask: numpy.typing.NDArray | None = None)[source]

Bases: corrct.regularizers.Regularizer_dwl

l1-norm decimated wavelet regularizer. It can be used to promote sparse reconstructions.

Initialization

__reg_name__: ‘Hubdwl’

class corrct.regularizers.BaseRegularizer_med(weight: float | numpy.typing.NDArray, filt_size: int = 3, upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l1())[source]

Bases: corrct.regularizers.BaseRegularizer

Median filter regularizer base class. It can be used to promote filtered reconstructions.

Initialization

__reg_name__: ‘med’

info() → str[source]

Return the regularizer info.

Returns

str Regularizer info string.

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

update_dual(dual: numpy.typing.NDArray, primal: numpy.typing.NDArray) → None[source]

abstract apply_proximal_primal(primal: numpy.typing.NDArray, tau: float | numpy.typing.NDArray) → None[source]

Not implemented: the median-filter regularizer has a non-linear, non-unitary ‘operator’ (x - median_filter(x)), so no closed-form primal proximal exists.

Raises

NotImplementedError Always raised; use PDHG for median-filter regularizers.

class corrct.regularizers.Regularizer_l1med(weight: float | numpy.typing.NDArray, filt_size: int = 3)[source]

Bases: corrct.regularizers.BaseRegularizer_med

l1-norm median filter regularizer. It can be used to promote filtered reconstructions.

Initialization

__reg_name__: ‘l1med’

class corrct.regularizers.Regularizer_l2med(weight: float | numpy.typing.NDArray, filt_size: int = 3)[source]

Bases: corrct.regularizers.BaseRegularizer_med

l2-norm median filter regularizer. It can be used to promote filtered reconstructions.

Initialization

__reg_name__: ‘l2med’

class corrct.regularizers.Regularizer_fft(weight: float | numpy.typing.NDArray, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, fft_filter: str = 'exp', upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l21())[source]

Bases: corrct.regularizers.BaseRegularizer

Fourier regularizer. It can be used to promote sparse reconstructions in the Fourier domain.

Initialization

__reg_name__: ‘fft’

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

apply_proximal_primal(primal: numpy.typing.NDArray, tau: float | numpy.typing.NDArray) → None[source]

Apply prox_{tau * weight * g} in the primal domain for the Fourier regularizer.

The DFT (with ortho normalization) is unitary, so the proximal of weight * ||W .||_{norm} separates in the frequency domain:

prox(x) = W^{-1} * prox_{tau * weight * ||.||_norm}(W * x)

where W is TransformFourier (ortho-normalized FFT). The frequency mask self.sigma is applied before thresholding (as in the dual), and masked-out frequencies (sigma == 0, i.e. the DC or low-frequency components, depending on fft_filter) are left unpenalized.

Parameters

primal : NDArray The primal variable to update in-place. tau : float | NDArray The proximal step size.

Raises

ValueError When the regularizer has not been initialized.

class corrct.regularizers.Regularizer_TNV(weight: float | numpy.typing.NDArray, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_mode: str = 'edge', upd_mask: numpy.typing.NDArray | None = None, spectral_norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l1(), x_ref: numpy.typing.NDArray | None = None)[source]

Bases: corrct.regularizers.Regularizer_Grad

Total Nuclear Variation (TNV) regularizer.

It can be used to promote piece-wise constant reconstructions, for multi-channel volumes.

Initialization

__reg_name__: ‘TNV’

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

class corrct.regularizers.Regularizer_VTV(weight: float | numpy.typing.NDArray, ndims: int = 2, pwise_der_norm: int | float = 2, pwise_chan_norm: int | float = np.inf, x_ref: numpy.typing.NDArray | None = None, upd_mask: numpy.typing.NDArray | None = None)[source]

Bases: corrct.regularizers.Regularizer_Grad

Vectorial Total Variation (VTV) regularizer.

It can be used to promote piece-wise constant reconstructions, for multi-channel volumes.

Initialization

__reg_name__: ‘VTV’

_raise_pwise_norm_error()[source]

apply_proximal_dual(dual: numpy.typing.NDArray) → None[source]

class corrct.regularizers.Regularizer_lnswl(weight: float | numpy.typing.NDArray, wavelet: str, level: int, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_on_demand: str = 'constant', upd_mask: numpy.typing.NDArray | None = None, normalized: bool = False, min_approx: bool = True, spectral_norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l1(), x_ref: numpy.typing.NDArray | None = None)[source]

Bases: corrct.regularizers.Regularizer_l1swl

Nuclear-norm Wavelet regularizer.

It can be used to promote compressed multi-channel reconstructions.

Initialization

__reg_name__: ‘lnswl’

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

class corrct.regularizers.Regularizer_vl1wl(weight: float | numpy.typing.NDArray, wavelet: str, level: int, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, pad_on_demand: str = 'constant', upd_mask: numpy.typing.NDArray | None = None, normalized: bool = False, min_approx: bool = True, pwise_lvl_norm: int | float = 1, pwise_chan_norm: int | float = np.inf, x_ref: numpy.typing.NDArray | None = None)[source]

Bases: corrct.regularizers.Regularizer_l1swl

l1-norm vectorial Wavelet regularizer. It can be used to promote compressed reconstructions.

Initialization

__reg_name__: ‘vl1wl’

_raise_pwise_norm_error()[source]

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

apply_proximal_dual(dual: numpy.typing.NDArray) → None[source]

class corrct.regularizers.Regularizer_vSVD(weight: float | numpy.typing.NDArray, ndims: int = 2, axes: collections.abc.Sequence[int] | numpy.typing.NDArray | None = None, axis_channels: collections.abc.Sequence[int] = (0,), upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l1())[source]

Bases: corrct.regularizers.BaseRegularizer

Regularizer based on the Singular Value Decomposition.

It can be used to promote similar reconstructions across different channels.

Initialization

__reg_name__: ‘vsvd’

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

abstract apply_proximal_primal(primal: numpy.typing.NDArray, tau: float | numpy.typing.NDArray) → None[source]

Not implemented: the SVD-based regularizer uses a non-unitary, data-dependent transform (TransformSVD stores U and Vt from the last forward pass), so the proximal cannot be applied in the primal domain without re-computing the SVD.

Raises

NotImplementedError Always raised; use PDHG for SVD-based regularizers.

class corrct.regularizers.Constraint_LowerLimit(limit: float | numpy.typing.NDArray, upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l2())[source]

Bases: corrct.regularizers.BaseRegularizer

Lower limit constraint. It can be used to promote reconstructions in certain regions of solution space.

Initialization

__reg_name__: ‘lowlim’

info() → str[source]

Return the regularizer info.

Returns

str Regularizer info string.

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

update_dual(dual: numpy.typing.NDArray, primal: numpy.typing.NDArray) → None[source]

apply_proximal_dual(dual: numpy.typing.NDArray) → None[source]

apply_proximal_primal(primal: numpy.typing.NDArray, tau: float | numpy.typing.NDArray) → None[source]

Apply the lower-limit constraint proximal in-place.

The proximal of the indicator function of {x >= limit} is the projection onto the feasible half-space: prox(x)_i = max(x_i, limit)

The step size tau has no effect on an indicator function proximal (the projection is independent of tau).

Parameters

primal : NDArray The primal variable to update in-place. tau : float | NDArray The proximal step size (unused for indicator functions, kept for API consistency).

class corrct.regularizers.Constraint_UpperLimit(limit: float | numpy.typing.NDArray, upd_mask: numpy.typing.NDArray | None = None, norm: corrct.data_terms.DataFidelityBase = dt.DataFidelity_l2())[source]

Bases: corrct.regularizers.BaseRegularizer

Upper limit constraint. It can be used to promote reconstructions in certain regions of solution space.

Initialization

__reg_name__: ‘uplim’

info() → str[source]

Return the regularizer info.

Returns

str Regularizer info string.

initialize_sigma_tau(primal: numpy.typing.NDArray) → float | numpy.typing.NDArray[source]

update_dual(dual: numpy.typing.NDArray, primal: numpy.typing.NDArray) → None[source]

apply_proximal_dual(dual: numpy.typing.NDArray) → None[source]

apply_proximal_primal(primal: numpy.typing.NDArray, tau: float | numpy.typing.NDArray) → None[source]

Apply the upper-limit constraint proximal in-place.

The proximal of the indicator function of {x <= limit} is the projection onto the feasible half-space: prox(x)_i = min(x_i, limit)

The step size tau has no effect on an indicator function proximal (the projection is independent of tau).

Parameters

primal : NDArray The primal variable to update in-place. tau : float | NDArray The proximal step size (unused for indicator functions, kept for API consistency).

corrct.regularizers

Module Contents

Classes

Data

API

`corrct.regularizers`