Skip to content

Commit bbde965

Browse files
perazzperazz
authored
doc: svd (#75)
2 parents 395057c + dc15471 commit bbde965

File tree

3 files changed

+158
-23
lines changed

3 files changed

+158
-23
lines changed

‎README.md

Lines changed: 88 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -313,23 +313,96 @@ where \f$ \Sigma^+ \f$ is the inverse of the nonzero singular values in \f$ \Sig
313313
- The pseudo-inverse is computed using LAPACK's SVD decomposition routine [GESVD](@ref la_lapack::gesvd).
314314
- This operator is a convenient shorthand for calling the functional interface `pinv(a)`.
315315

316+
## [svd](@ref la_svd::svd) - Singular Value Decomposition (SVD) of a matrix
316317

317-
## `svd(A)`
318-
**Type**: Subroutine
319-
**Description**: Singular value decomposition of $A = U S V^t$.
320-
**Optional arguments**:
321-
- `s`: Singular values.
322-
- `u`: Left singular vectors.
323-
- `vt`: Right singular vectors.
324-
- `full_matrices`: Defaults to `.false.`.
325-
- `err`: State handler.
318+
### Syntax
326319

327-
**Usage**: `call svd(A, s, u, vt, full_matrices=.false., err=state)`.
320+
`call svd(a, s [, u] [, vt] [, overwrite_a] [, full_matrices] [, err])`
328321

329-
## `svdvals(A)`
330-
**Type**: Function
331-
**Description**: Singular values $S$ from $A = U S V^t$.
332-
**Usage**: `s = svdvals(A)` where `s` is a real array with the same precision as `A`.
322+
### Description
323+
324+
This subroutine computes the Singular Value Decomposition (SVD) of a matrix \f$ A \f$:
325+
326+
\f[
327+
A = U \cdot S \cdot V^T
328+
\f]
329+
330+
where:
331+
- \f$ A \f$ is the input matrix of size \f$ [m,n] \f$.
332+
- \f$ U \f$ is an orthogonal matrix of size \f$ [m,m] \f$ (or \f$ [m,k] \f$ for the reduced problem), containing the left singular vectors of \f$ A \f$.
333+
- \f$ S \f$ is a diagonal matrix containing the singular values of size \f$ [k,k] \f$ with \f$ k = \min(m,n) \f$.
334+
- \f$ V^T \f$ is an orthogonal matrix of size \f$ [n,n] \f$ (or \f$ [k,n] \f$ for the reduced problem), containing the right singular vectors of \f$ A^T \f$.
335+
336+
The singular values are returned in the array \f$ S \f$, and optionally, the matrices \f$ U \f$ and \f$ V^T \f$ are computed and returned.
337+
338+
### Arguments
339+
340+
- `a`: A `real` matrix of size \f$ [m,n] \f$ representing the input matrix \f$ A \f$. If `overwrite_a = .true.`, this matrix may be modified during computation. This is an `inout` argument.
341+
- `s`: A `real` array of size \f$ k = \min(m,n) \f$, containing the singular values of \f$ A \f$. This is an output argument.
342+
- `u`: An optional `real` matrix of the same type and kind as `a`, representing the left singular vectors of \f$ A \f$. This has shape \f$ [m,m] \f$ for the full problem or \f$ [m,k] \f$ for the reduced problem. This is an output argument.
343+
- `vt`: An optional `real` matrix of the same type and kind as `a`, representing the right singular vectors of \f$ A^T \f$. This has shape \f$ [n,n] \f$ for the full problem or \f$ [k,n] \f$ for the reduced problem. This is an output argument.
344+
- `overwrite_a`: (Optional, default = `.false.`) A logical flag indicating whether the input matrix `a` may be overwritten during computation. If `.true.`, `a` is overwritten to avoid additional memory allocation.
345+
- `full_matrices`: (Optional, default = `.true.`) A logical flag that determines whether to compute full-sized matrices \f$ U \f$ and \f$ V^T \f$ (shape \f$ [m,m] \f$ and \f$ [n,n] \f$). If `.false.`, computes reduced matrices of shape \f$ [m,k] \f$ and \f$ [k,n] \f$.
346+
- `err`: (Optional) A [type(la_state)](@ref la_state_type::la_state) variable to capture the error state. If not provided, the function will stop execution on error.
347+
348+
### Return value
349+
350+
The SVD of matrix \f$ A \f$ is returned in the corresponding output arguments, with the singular values in `s`, and optionally, the matrices \f$ U \f$ and \f$ V^T \f$.
351+
352+
### Errors
353+
354+
- Raises [LINALG_VALUE_ERROR](@ref la_state_type::linalg_value_error) if the sizes of the matrices are incompatible with the full/reduced problem.
355+
- Raises [LINALG_ERROR](@ref la_state_type::linalg_error) if there is insufficient storage space.
356+
- If `err` is not provided, exceptions will trigger an `error stop`.
357+
358+
### Notes
359+
360+
- This subroutine computes the Singular Value Decomposition using LAPACK's [GESDD](@ref la_lapack::gesdd) algorithm.
361+
- If `overwrite_a` is enabled, the input matrix `a` may be overwritten during computation.
362+
363+
## [svdvals](@ref la_svd::svdvals) - Singular Values Computation (function).
364+
365+
### Syntax
366+
367+
`s = svdvals(a [, err])`
368+
369+
### Description
370+
371+
This function computes the singular values of a `real` or `complex` matrix \f$ A \f$ and returns them in a vector \f$ s \f$, where \f$ s \f$ is an array of size \f$ k = \min(m, n) \f$.
372+
Singular values are non-negative values that provide important insights into the properties of the matrix, such as its rank and conditioning.
373+
374+
This function does not compute the full Singular Value Decomposition ([SVD](@ref la_svd::svd)); instead, it directly calculates and returns only the singular values of matrix \f$ A \f$.
375+
376+
The Singular Value Decomposition of a matrix \f$ A \f$ is expressed as:
377+
378+
\f[
379+
A = U \cdot S \cdot V^T
380+
\f]
381+
382+
where:
383+
- \f$ A \f$ is the input matrix of size \f$ [m,n] \f$,
384+
- \f$ U \f$ and \f$ V \f$ are orthogonal matrices,
385+
- \f$ S \f$ is a diagonal matrix with the singular values of \f$ A \f$.
386+
387+
### Arguments
388+
389+
- `a`: A `real` or `complex` matrix of size \f$ [m,n] \f$, representing the input matrix whose singular values are to be computed.
390+
- `err` (optional): A [type(la_state)](@ref la_state_type::la_state) variable that returns the error state. If not provided, the function will stop execution on error.
391+
392+
### Return value
393+
394+
- `s`: A `real` array containing the singular values of the matrix \f$ A \f$, with the same type and kind as the input matrix. The size of the array is \f$ k = \min(m, n) \f$.
395+
396+
### Errors
397+
398+
- Raises [LINALG_VALUE_ERROR](@ref la_state_type::linalg_value_error) if the input matrix has invalid dimensions or if the SVD computation fails.
399+
- If `err` is not provided, exceptions will trigger an `error stop`.
400+
401+
### Notes
402+
403+
- This function only computes the singular values and does not compute the full SVD (i.e., matrices \f$ U \f$ and \f$ V \f$ are not computed).
404+
- The singular values are returned as a vector, sorted in decreasing order.
405+
- The function uses LAPACK's [GESDD](@ref la_lapack::gesdd) routine for singular value computation.
333406

334407
## [diag](@ref la_eye::diag) - Diagonal matrix.
335408

@@ -548,7 +621,7 @@ The Schur decomposition matrices \f$ T \f$ and optionally \f$ Z \f$ are returned
548621

549622
### Notes
550623

551-
- This subroutine computes the Schur decomposition using LAPACK's Schur decomposition routines ([GEES](@ref la_lapack:gees)).
624+
- This subroutine computes the Schur decomposition using LAPACK's Schur decomposition routines ([GEES](@ref la_lapack::gees)).
552625
- Sorting options for eigenvalues can be requested, utilizing LAPACK's eigenvalue sorting mechanism.
553626
- If `overwrite_a` is enabled, the input matrix `a` will be modified during computation.
554627

‎fypp/src/la_svd.fypp

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
#:include "common.fypp"
2+
!> Singular Value Decomposition
23
module la_svd
34
use la_constants
45
use la_blas
@@ -8,13 +9,43 @@ module la_svd
89
implicit none(type,external)
910
private
1011

11-
!> Singular value decomposition
12+
!> @brief Compute the Singular Value Decomposition (SVD) of a matrix.
13+
!!
14+
!! This subroutine computes the Singular Value Decomposition (SVD) of a matrix \f$ A \f$:
15+
!!
16+
!! \f$ A = U \cdot S \cdot V^T \f$
17+
!!
18+
!! where \f$ A \f$ is a matrix of size \f$ [m,n] \f$, \f$ U \f$ is an orthogonal matrix of size \f$ [m,m] \f$, \f$ S \f$ is a diagonal matrix containing the singular values, and \f$ V^T \f$ is an orthogonal matrix of size \f$ [n,n] \f$.
19+
!! The subroutine computes the singular values and optionally the matrices \f$ U \f$ and \f$ V^T \f$.
20+
!!
21+
!! @param[in,out] a The input matrix \f$ A \f$ of size \f$ [m,n] \f$. If `overwrite_a` is true, the contents of `a` may be modified during computation.
22+
!! @param[out] s The array of singular values of size \f$ k = min(m,n) \f$.
23+
!! @param[out] u (Optional) The left singular vectors of matrix \f$ A \f$, with shape \f$ [m,m] \f$ for the full problem or \f$ [m,k] \f$ for the reduced problem.
24+
!! @param[out] vt (Optional) The right singular vectors of matrix \f$ A^T \f$, with shape \f$ [k,n] \f$ for the reduced problem or \f$ [n,n] \f$ for the full problem.
25+
!! @param[in] overwrite_a (Optional) A logical flag that determines whether matrix `a` may be overwritten. Default is false.
26+
!! @param[in] full_matrices (Optional) If true, computes the full-sized matrices \f$ U \f$ and \f$ V^T \f$. If false, computes the reduced matrices.
27+
!! @param[out] err (Optional) A state return flag. If an error occurs and `err` is not provided, the function will stop execution.
28+
!!
29+
!! @note This subroutine performs the SVD computation using the LAPACK [gesdd](@ref la_lapack::gesdd) backend and can be used for both full and reduced decompositions.
30+
!!
31+
!! @warning If `overwrite_a` is enabled, the original contents of `a` may be lost during computation.
32+
!!
1233
public :: svd
13-
!> Singular values
34+
35+
36+
!> @brief Compute the singular values of a matrix.
37+
!!
38+
!! This function returns the singular values of the input matrix \f$ A \f$.
39+
!! The singular values are stored in a vector \f$ s \f$, which is an array of size \f$ k = min(m,n) \f$.
40+
!!
41+
!! @param[in] a The input matrix \f$ A \f$ of size \f$ [m,n] \f$.
42+
!! @param[out] err (Optional) A state return flag. If an error occurs and `err` is not provided, the function will stop execution.
43+
!! @return The singular values of matrix \f$ A \f$ are returned in the `real` array \f$ s \f$, with the same kind as the input matrix.
44+
!!
45+
!! @note This function returns only the singular values and does not compute the full SVD.
46+
!!
1447
public :: svdvals
1548

16-
! Numpy: svd(a, full_matrices=True, compute_uv=True, hermitian=False)
17-
! Scipy: svd(a, full_matrices=True, compute_uv=True, overwrite_a=False, check_finite=True, lapack_driver='gesdd')
1849

1950
interface svd
2051
#:for rk,rt,ri in ALL_KINDS_TYPES

‎src/la_svd.f90

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
!> Singular Value Decomposition
12
module la_svd
23
use la_constants
34
use la_blas
@@ -7,13 +8,43 @@ module la_svd
78
implicit none(type,external)
89
private
910

10-
!> Singular value decomposition
11+
!> @brief Compute the Singular Value Decomposition (SVD) of a matrix.
12+
!!
13+
!! This subroutine computes the Singular Value Decomposition (SVD) of a matrix \f$ A \f$:
14+
!!
15+
!! \f$ A = U \cdot S \cdot V^T \f$
16+
!!
17+
!! where \f$ A \f$ is a matrix of size \f$ [m,n] \f$, \f$ U \f$ is an orthogonal matrix of size \f$ [m,m] \f$, \f$ S \f$ is a diagonal matrix containing the singular values, and \f$ V^T \f$ is an orthogonal matrix of size \f$ [n,n] \f$.
18+
!! The subroutine computes the singular values and optionally the matrices \f$ U \f$ and \f$ V^T \f$.
19+
!!
20+
!! @param[in,out] a The input matrix \f$ A \f$ of size \f$ [m,n] \f$. If `overwrite_a` is true, the contents of `a` may be modified during computation.
21+
!! @param[out] s The array of singular values of size \f$ k = min(m,n) \f$.
22+
!! @param[out] u (Optional) The left singular vectors of matrix \f$ A \f$, with shape \f$ [m,m] \f$ for the full problem or \f$ [m,k] \f$ for the reduced problem.
23+
!! @param[out] vt (Optional) The right singular vectors of matrix \f$ A^T \f$, with shape \f$ [k,n] \f$ for the reduced problem or \f$ [n,n] \f$ for the full problem.
24+
!! @param[in] overwrite_a (Optional) A logical flag that determines whether matrix `a` may be overwritten. Default is false.
25+
!! @param[in] full_matrices (Optional) If true, computes the full-sized matrices \f$ U \f$ and \f$ V^T \f$. If false, computes the reduced matrices.
26+
!! @param[out] err (Optional) A state return flag. If an error occurs and `err` is not provided, the function will stop execution.
27+
!!
28+
!! @note This subroutine performs the SVD computation using the LAPACK [gesdd](@ref la_lapack::gesdd) backend and can be used for both full and reduced decompositions.
29+
!!
30+
!! @warning If `overwrite_a` is enabled, the original contents of `a` may be lost during computation.
31+
!!
1132
public :: svd
12-
!> Singular values
33+
34+
35+
!> @brief Compute the singular values of a matrix.
36+
!!
37+
!! This function returns the singular values of the input matrix \f$ A \f$.
38+
!! The singular values are stored in a vector \f$ s \f$, which is an array of size \f$ k = min(m,n) \f$.
39+
!!
40+
!! @param[in] a The input matrix \f$ A \f$ of size \f$ [m,n] \f$.
41+
!! @param[out] err (Optional) A state return flag. If an error occurs and `err` is not provided, the function will stop execution.
42+
!! @return The singular values of matrix \f$ A \f$ are returned in the `real` array \f$ s \f$, with the same kind as the input matrix.
43+
!!
44+
!! @note This function returns only the singular values and does not compute the full SVD.
45+
!!
1346
public :: svdvals
1447

15-
! Numpy: svd(a, full_matrices=True, compute_uv=True, hermitian=False)
16-
! Scipy: svd(a, full_matrices=True, compute_uv=True, overwrite_a=False, check_finite=True, lapack_driver='gesdd')
1748

1849
interface svd
1950
module procedure la_svd_s

0 commit comments

Comments
 (0)