Robject¶

template <typename T1> class Robject

Abstract base class for regularization penalty functions.

Provides finite-difference operators Cd (forward) and Ctd (adjoint) along with high-level helpers Penalty, Gradient, and Denom. Subclasses override the potential functions wpot, dpot, and pot to implement specific penalties (e.g. quadratic, total variation).

The penalty is defined through a potential function family:

$\psi(d)$: potential function (penalty applied to each difference)
$\dot\psi(d) = \psi'(d)$: first derivative of the potential
$\omega(d) = \psi'(d)/d$: weighting function for surrogate optimization

The total penalty is: $$R(\mathbf{x}) = \sum_j \beta_j \, \psi([C\mathbf{x}]_j)$$

where $C$ is the finite-difference operator computed by Cd() and $C^T$ (adjoint) is computed by Ctd().

To define a custom penalty, subclass Robject and override: - wpot(d): returns $\omega(d) = \psi'(d)/d$ (weighting function) - dpot(d): returns $\dot\psi(d) = \psi'(d)$ (derivative) - pot(d): returns $\psi(d)$ (potential value)

The default implementations are quadratic: $\psi(d) = \frac{1}{2}d^2$, $\omega(d) = 1$, $\dot\psi(d) = d$.

QuadPenalty<float> R(Nx, Ny, Nz, beta);
auto xhat = solve_pwls_pcg<float>(x0, G, W, yi, R, niter);

See : QuadPenalty, TVPenalty

T1 : Floating-point precision type (float or double).

Variables¶

Name	Description
Nx	Image x-dimension (number of pixels in x).
Ny	Image y-dimension (number of pixels in y).
Nz	Image z-dimension (number of pixels in z; 1 for 2-D).
DeltaX	Voxel spacing in x (unused by default, available for subclasses).
DeltaY	Voxel spacing in y.
DeltaZ	Voxel spacing in z.
Beta	Regularization strength parameter $\beta$.
Dims2Penalize	Number of spatial dimensions to penalize (1, 2, or 3).

Functions¶

Name	Description
Robject	Default constructor.
Robject	Construct a regularization object.
wpot	Penalty weight function $\omega(d) = \psi'(d)/d$.
dpot	Penalty derivative function $\dot\psi(d) = \psi'(d)$.
pot	Penalty potential function $\psi(d)$.
Cd	Forward finite-difference operator along dimension `dim.` `d` : Input image vector of length Nx·Ny·Nz. `dim` : Spatial dimension (0=x, 1=y, 2=z). Return : Finite-difference output, same length as `d.`
Ctd	Adjoint finite-difference operator along dimension `dim.` `d` : Input vector of length Nx·Ny·Nz. `dim` : Spatial dimension (0=x, 1=y, 2=z). Return : Adjoint output, same length as `d.`
Penalty	Evaluate the total penalty value $R(\mathbf{x}) = \beta \sum_{\mathrm{dim}} \sum_k \psi([C\mathbf{x}]_k)$.
Gradient	Compute the gradient of the penalty $\nabla R(\mathbf{x})$.
Denom	Compute the quadratic surrogate denominator for step-size selection.
Cd	Forward finite-difference operator along `dim` (forgeCol overload).
Ctd	Adjoint finite-difference operator along `dim` (forgeCol overload).
Penalty	Evaluate the total penalty $R(\mathbf{x})$ (forgeCol overload).
Gradient	Compute the gradient $\nabla R(\mathbf{x})$ (forgeCol overload).
Denom	Compute the quadratic surrogate denominator (forgeCol overload).
wpot	Penalty weight function $\omega(d) = \psi'(d)/d$ (forgeCol overload).
dpot	Penalty derivative function $\dot\psi(d) = \psi'(d)$ (forgeCol overload).
pot	Penalty potential function $\psi(d)$ (forgeCol overload).

Variable Details¶

Beta ¶

T1 Beta

Regularization strength parameter $\beta$.

DeltaX ¶

T1 DeltaX

Voxel spacing in x (unused by default, available for subclasses).

DeltaY ¶

T1 DeltaY

Voxel spacing in y.

DeltaZ ¶

T1 DeltaZ

Voxel spacing in z.

Dims2Penalize ¶

uword Dims2Penalize

Number of spatial dimensions to penalize (1, 2, or 3).

Nx ¶

uword Nx

Image x-dimension (number of pixels in x).

Ny ¶

uword Ny

Image y-dimension (number of pixels in y).

Nz ¶

uword Nz

Image z-dimension (number of pixels in z; 1 for 2-D).

Function Details¶

Cd ¶

Col<CxT1> Cd(const Col<CxT1>& d, uword dim) const

Forward finite-difference operator along dimension `dim.`

d : Input image vector of length Nx·Ny·Nz.

dim : Spatial dimension (0=x, 1=y, 2=z).

Return : Finite-difference output, same length as d.

forgeCol<forgeComplex<T1>> Cd(const forgeCol<forgeComplex<T1>>& d, arma::uword dim) const

Forward finite-difference operator along `dim` (forgeCol overload).

d : Input image vector of length Nx·Ny·Nz.

dim : Spatial dimension (0=x, 1=y, 2=z).

Return : Finite-difference output, same length as d.

Ctd ¶

Col<CxT1> Ctd(const Col<CxT1>& d, uword dim) const

Adjoint finite-difference operator along dimension `dim.`

d : Input vector of length Nx·Ny·Nz.

dim : Spatial dimension (0=x, 1=y, 2=z).

Return : Adjoint output, same length as d.

forgeCol<forgeComplex<T1>> Ctd(const forgeCol<forgeComplex<T1>>& d, arma::uword dim) const

Adjoint finite-difference operator along `dim` (forgeCol overload).

d : Input vector of length Nx·Ny·Nz.

dim : Spatial dimension (0=x, 1=y, 2=z).

Return : Adjoint output, same length as d.

Denom ¶

CxT1 Denom(const Col<CxT1>& ddir, const Col<CxT1>& x) const

Compute the quadratic surrogate denominator for step-size selection.

ddir : Search direction vector, length Nx·Ny·Nz.

x : Current image estimate, same length.

Return : Scalar denominator value.

forgeComplex<T1> Denom(const forgeCol<forgeComplex<T1>>& ddir, const forgeCol<forgeComplex<T1>>& x) const

Compute the quadratic surrogate denominator (forgeCol overload).

ddir : Search direction vector, length Nx·Ny·Nz.

x : Current image estimate, same length.

Return : Scalar denominator value.

Gradient ¶

Col<CxT1> Gradient(const Col<CxT1>& x) const

Compute the gradient of the penalty $\nabla R(\mathbf{x})$.

x : Image vector of length Nx·Ny·Nz.

Return : Gradient vector, same length as x.

forgeCol<forgeComplex<T1>> Gradient(const forgeCol<forgeComplex<T1>>& x) const

Compute the gradient $\nabla R(\mathbf{x})$ (forgeCol overload).

x : Image vector of length Nx·Ny·Nz.

Return : Gradient vector, same length as x.

Penalty ¶

T1 Penalty(const Col<CxT1>& x) const

Evaluate the total penalty value $R(\mathbf{x}) = \beta \sum_{\mathrm{dim}} \sum_k \psi([C\mathbf{x}]_k)$.

x : Image vector of length Nx·Ny·Nz.

Return : Scalar penalty value.

T1 Penalty(const forgeCol<forgeComplex<T1>>& x) const

Evaluate the total penalty $R(\mathbf{x})$ (forgeCol overload).

x : Image vector of length Nx·Ny·Nz.

Return : Scalar penalty value.

Robject ¶

Robject()

Default constructor.

Robject(uword nx, uword ny, uword nz, T1 beta, uword dims2penalize = 3)

Construct a regularization object.

nx : Image x-dimension.

ny : Image y-dimension.

nz : Image z-dimension (use 1 for 2-D).

beta : Regularization strength $\beta$.

dims2penalize : Number of spatial dimensions to penalize (default 3).