cherab.inversion.regularization.compute_svd

cherab.inversion.regularization.compute_svd(T: NDArray[float64] | _spbase[float64, tuple[int, int]], H: NDArray[float64] | _spbase[float64, tuple[int, int]], Q: None = None, use_gpu: bool = False, dtype: DTypeLike | None = None, progress: Progress | None = None, task_id: TaskID | None = None) → tuple[NDArray[float64], NDArray[float64], NDArray[float64]]Source
cherab.inversion.regularization.compute_svd(T: NDArray[float64] | _spbase[float64, tuple[int, int]], H: NDArray[float64] | _spbase[float64, tuple[int, int]], Q: NDArray[float64] | _spbase[float64, tuple[int, int]], use_gpu: bool = False, dtype: DTypeLike | None = None, progress: Progress | None = None, task_id: TaskID | None = None) → tuple[NDArray[float64], NDArray[float64], NDArray[float64], sp_csr_array[float64, tuple[int, int]]]

Compute singular value decomposition (SVD) components of the generalized Tikhonov regularization problem.

This function returns the \(\mathbf{s}\), \(\mathbf{U}\), \(\tilde{\mathbf{V}}\) and \(\mathbf{B}\) from the given matrix \(\mathbf{T}\), \(\mathbf{Q}\), and \(\mathbf{H}\).

Note

The mathematical notation and calculation procedure is based on the inversion theory.

Parameters:
T : (M, N) array_like

Matrix for a linear equation \(\mathbf{T}\in\mathbb{R}^{M\times N}\).

H : (N, N) array_like

Regularization matrix \(\mathbf{H} \in \mathbb{R}^{N\times N}\) which must be a symmetric positive semi-definite matrix.

Q : (M, M) array_like, optional

Weighted matrix for the residual norm \(\mathbf{Q}\in\mathbb{R}^{M\times M}\), by default None (meaning \(\mathbf{Q} = \mathbf{I}\)). This matrix must be a symmetric positive semi-definite matrix.

use_gpu: bool = False

Whether to use GPU or not, by default False. If True, the cupy functionalities is used instead of numpy and scipy ones when calculating the inverse of a sparse matrix, singular value decomposition, inverted solution basis \(\tilde{\mathbf{V}}\), etc. Please ensure cupy is installed before using this option, otherwise an ModuleNotFoundError will be raised.

dtype: DTypeLike | None = None

Data type of the matrix elements, by default same as the input matrix T. In case of using GPU, the data type numpy.float32 is a little bit faster and saves memory.

progress: Progress | None = None

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

task_id: TaskID | None = None

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

Returns:

  • s ({ (r, ), (r-1, ) } ndarray) – Vector of singular values like \(\begin{bmatrix}\sigma_1&\cdots&\sigma_r\end{bmatrix}^\mathsf{T}\in\mathbb{R}^r\). If one set \(\mathbf{T}\) as a sparse matrix, \(r\) is reduced by 1 (i.e. \(r \to r-1\)) because of the use of scipy.sparse.linalg.eigsh function to calculate the singular values.

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

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

  • B ((M, M) scipy.sparse.csr_array) – Matrix \(\mathbf{B}\) coming from \(\mathbf{Q} = \mathbf{B}^\mathsf{T}\mathbf{B}\). Only returned when \(\mathbf{Q}\) is given.

Raises:

  • AttributeError – If T or H (or Q if given) do not have the attributes ndim or shape.

  • ValueError – If the dimensions or shapes of T, H, or Q (if given) are not appropriate.

Examples

>>> s, U, basis = compute_svd(T, H)

>>> s, U, basis, B = compute_svd(T, H, Q, dtype=np.float32, use_gpu=True)