cherab.inversion.regularization._SVDBase

class cherab.inversion.regularization._SVDBase(s: ArrayLike, U: ArrayLike, basis: ArrayLike, /, B: NDArray[float64] | _spbase[float64, tuple[int, int]] | None = None, *, data: ArrayLike | None = None)Source
class cherab.inversion.regularization._SVDBase(T: NDArray[float64] | _spbase[float64, tuple[int, int]], /, *, H: NDArray[float64] | _spbase[float64, tuple[int, int]] | None = None, Q: NDArray[float64] | _spbase[float64, tuple[int, int]] | None = None, data: ArrayLike | None = None, use_gpu: bool = False, dtype: DTypeLike | None = None, sp: Progress | None = None, task_id: TaskID | None = None)

Bases: object

Base class for inversion calculations based on the Singular Value Decomposition (SVD) method.

This class provides the common mathematical operations for SVD-based inversion solvers. The Tikhonov filter is used by default; subclasses may override filter() to provide alternative filter strategies (e.g. TSVD).

To obtain the optimal regularization parameter, pass a Criterion object to solve().

Can be constructed in two ways:

SVD-component mode

Construct directly from precomputed SVD components.

Matrix mode

Construct from a forward matrix. SVD components are computed internally.

Parameters:
s: ArrayLike

Singular values, \(\mathbf{s} = (\sigma_1, \sigma_2, ...) \in \mathbb{R}^r\).

U: ArrayLike

Left singular vectors, \(\mathbf{U}\in\mathbb{R}^{M\times r}\).

basis: ArrayLike

Inverted solution basis, \(\tilde{\mathbf{V}} \in \mathbb{R}^{N\times r}\).

B: NDArray[float64] | _spbase[float64, tuple[int, int]] | None = None

Matrix \(\mathbf{B}\) from \(\mathbf{Q} = \mathbf{B}^\mathsf{T}\mathbf{B}\). Default is None, i.e. \(\mathbf{B} = \mathbf{I}\).

data: ArrayLike | None = None

Given data vector, \(\mathbf{b}\in\mathbb{R}^M\), by default None.

T: NDArray[float64] | _spbase[float64, tuple[int, int]]

Forward matrix \(\mathbf{T}\in\mathbb{R}^{M\times N}\) (2-D dense or sparse). When the first positional argument is 2-D, SVD components are computed internally via compute_svd.

H: NDArray[float64] | _spbase[float64, tuple[int, int]] | None = None

Regularization matrix \(\mathbf{H}\in\mathbb{R}^{N\times N}\), by default numpy.eye(N) (i.e. standard L2 regularization).

Q: NDArray[float64] | _spbase[float64, tuple[int, int]] | None = None

Weighted matrix \(\mathbf{Q}\in\mathbb{R}^{M\times M}\), by default None.

data: ArrayLike | None = None

Given data vector, \(\mathbf{b}\in\mathbb{R}^M\), by default None.

use_gpu: bool = False

Whether to use GPU acceleration via cupy, by default False.

dtype: DTypeLike | None = None

Data type passed to compute_svd, by default None (inherits from T).

sp: Progress | None = None

rich.progress.Progress instance for displaying computation status, by default None.

task_id: TaskID | None = None

Task ID within sp to update with sub-step descriptions, by default None.

Methods

eta(beta)

Squared regularization norm \(\eta\).

eta_diff(beta)

Differential of \(\eta\).

filter(beta)

Tikhonov filter factors \(f_{\lambda,i}\).

regularization_norm(beta)

Regularization norm: \(\sqrt{\eta} = \|\mathbf{x}_\lambda\|_\mathbf{H}\).

residual_norm(beta)

Residual norm: \(\sqrt{\rho} = \|\mathbf{T}\mathbf{x}_\lambda - \mathbf{b}\|_{\mathbf{Q}}\).

rho(beta)

Squared residual norm \(\rho\).

solution(beta)

Solution vector \(\mathbf{x}_\lambda\).

solve(criterion[, bounds, stepsize])

Solve the ill-posed inversion problem using criterion to select \(\lambda\).

Attributes

B

Matrix \(\mathbf{B}\) from \(\mathbf{Q} = \mathbf{B}^\mathsf{T}\mathbf{B}\).

U

Left singular vectors \(\mathbf{U}\).

basis

Inverted solution basis \(\tilde{\mathbf{V}}\).

bounds

\((\log_{10}\sigma_r^2, \log_{10}\sigma_1^2)\).

data

Given data for inversion calculation \(\mathbf{b}\).

lambda_opt

Optimal regularization parameter, set after solve() is executed.

s

Singular values \(\mathbf{s}\).
property s : ndarray[tuple[Any, ...], dtype[float64]]Source

Singular values \(\mathbf{s}\).

Singular values form a vector array like \(\mathbf{s} = \begin{bmatrix}\sigma_1 & \cdots & \sigma_r\end{bmatrix}^\mathsf{T} \in \mathbb{R}^r\).

property U : ndarray[tuple[Any, ...], dtype[float64]]Source

Left singular vectors \(\mathbf{U}\).

Left singular vectors form a matrix containing column vectors like \(\mathbf{U}=\begin{bmatrix}\mathbf{u}_1 & \cdots &\mathbf{u}_r\end{bmatrix}\in\mathbb{R}^{M\times r}\).

property basis : ndarray[tuple[Any, ...], dtype[float64]]Source

Inverted solution basis \(\tilde{\mathbf{V}}\).

The inverted solution basis is a matrix containing column vectors like \(\tilde{\mathbf{V}}=\begin{bmatrix}\tilde{\mathbf{v}}_1&\cdots&\tilde{\mathbf{v}}_r\end{bmatrix}\in\mathbb{R}^{N\times r}\).

property B : NDArray[float64] | _spbase[float64, tuple[int, int]] | NoneSource

Matrix \(\mathbf{B}\) from \(\mathbf{Q} = \mathbf{B}^\mathsf{T}\mathbf{B}\).

If users do not specify the matrix \(\mathbf{B}\), this property is None.

property data : ndarray[tuple[Any, ...], dtype[float64]] | NoneSource

Given data for inversion calculation \(\mathbf{b}\).

The given data is a vector array like \(\mathbf{b} \in \mathbb{R}^M\).

property bounds : tuple[float, float]Source

\((\log_{10}\sigma_r^2, \log_{10}\sigma_1^2)\).

Type:

Default bounds of \(\log_{10}\lambda\)

property lambda_opt : float | NoneSource

Optimal regularization parameter, set after solve() is executed.

filter(beta: float) → ndarray[tuple[Any, ...], dtype[float64]]Source

Tikhonov filter factors \(f_{\lambda,i}\).

The filter factors are diagonal elements of the filter matrix \(\mathbf{F}_\lambda\), and can be expressed with SVD components as follows:

\[f_{\lambda, i} = \left( 1 + \frac{\lambda}{\sigma_i^2} \right)^{-1}.\]
Parameters:
beta: float

Regularization parameter \(\lambda\).

Returns:

(r,) ndarray – 1-D array containing filter factors, the length of which is the same as the number of singular values.

rho(beta: float) → floatSource

Squared residual norm \(\rho\).

\(\rho\) can be expressed with SVD components as follows:

\[\begin{split}\rho &= \| \mathbf{T}\mathbf{x}_\lambda - \mathbf{b} \|_\mathbf{Q}^2\\ &= \| (\mathbf{F}_\lambda - \mathbf{I}_r) \mathbf{U}^\mathsf{T}\mathbf{B}\mathbf{b} \|^2.\end{split}\]
Parameters:
beta: float

Regularization parameter.

Returns:

float – Squared residual norm \(\rho\).

eta(beta: float) → floatSource

Squared regularization norm \(\eta\).

\(\eta\) can be expressed with SVD components as follows:

\[\begin{split}\eta &= \|\mathbf{x}_\lambda\|_\mathbf{H}^2\\ &= \| \mathbf{F}_\lambda\mathbf{S}^{-1} \mathbf{U}^\mathsf{T}\mathbf{B}\mathbf{b} \|^2\end{split}\]
Parameters:
beta: float

Regularization parameter.

Returns:

float – Squared regularization norm \(\eta\).

eta_diff(beta: float) → floatSource

Differential of \(\eta\).

\(\eta'\equiv\frac{\partial\eta}{\partial\lambda}\) can be calculated with SVD components as follows:

\[\eta' = \frac{2}{\lambda} (\mathbf{U}^\mathsf{T}\mathbf{B}\mathbf{b})^\mathsf{T} (\mathbf{F}_\lambda - \mathbf{I}_r) \mathbf{F}_\lambda^2\mathbf{S}^{-2}\ \mathbf{U}^\mathsf{T}\mathbf{B}\mathbf{b}.\]
Parameters:
beta: float

Regularization parameter \(\lambda\).

Returns:

float – Differential of \(\eta\) with respect to \(\lambda\).

residual_norm(beta: float) → floatSource

Residual norm: \(\sqrt{\rho} = \|\mathbf{T}\mathbf{x}_\lambda - \mathbf{b}\|_{\mathbf{Q}}\).

Parameters:
beta: float

Regularization parameter.

Returns:

float – Residual norm \(\sqrt{\rho}\).

regularization_norm(beta: float) → floatSource

Regularization norm: \(\sqrt{\eta} = \|\mathbf{x}_\lambda\|_\mathbf{H}\).

Parameters:
beta: float

Regularization parameter.

Returns:

float – Regularization norm \(\sqrt{\eta}\).

solution(beta: float) → ndarraySource

Solution vector \(\mathbf{x}_\lambda\).

The solution vector \(\mathbf{x}_\lambda\) can be expressed with SVD components as

\[\mathbf{x}_\lambda = \tilde{\mathbf{V}} \mathbf{F}_\lambda \mathbf{S}^{-1} \mathbf{U}^\mathsf{T}\mathbf{B}\mathbf{b}.\]
Parameters:
beta: float

Regularization parameter.

Returns:

(N, ) array – Solution vector \(\mathbf{x}_\lambda\).

solve(criterion: Criterion, bounds: Collection[float | None] | None = None, stepsize: float = 10, **kwargs: Any) → tuple[ndarray, Any]Source

Solve the ill-posed inversion problem using criterion to select \(\lambda\).

Parameters:
criterion: Criterion

A Criterion instance (e.g. GCV, Lcurve, etc.).

bounds: Collection[float | None] | None = None

Boundary pair (log10_lower, log10_upper) for the optimization, by default bounds. Either element may be None to use the default limit.

stepsize: float = 10

Step-size for basinhopping, by default 10.

**kwargs: Any

Additional keyword arguments forwarded to the criterion’s optimize method.

Returns: