NumericAL
A header-only C++20 lexer built on REAL
Loading...
Searching...
No Matches
Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | Static Private Attributes | List of all members
numerical::svd_decomposition< T > Class Template Reference

The singular value decomposition A = U Σ Vᴴ of an m × n matrix. More...

#include <svd.hpp>

Collaboration diagram for numerical::svd_decomposition< T >:
[legend]

Public Member Functions

 svd_decomposition (const matrix< T > &a, svd_method method=svd_method::divide_and_conquer, bool full=false)
 Decomposes a.
 
 svd_decomposition (matrix< T > &&a, svd_method method=svd_method::divide_and_conquer, bool full=false)
 Decomposes a in its own storage, an expiring matrix's elements taken over: its scaled copy is made in place, one matrix less at the peak.
 
const vector< double > & singular_values () const noexcept
 The singular values, descending.
 
const matrix< T > & u () const &noexcept
 The left singular vectors U (columns): m × k, or m × m full.
 
matrix< T > u () &&
 U, moved out of an expiring decomposition (v and the singular values stay).
 
const matrix< T > & v () const &noexcept
 The right singular vectors V (columns): n × k, or n × n full.
 
matrix< T > vh () const
 Vᴴ (k × n, or n × n full), so that A = U Σ Vᴴ reads u() * diag(singular_values()) * vh() (full, Σ padded with zeros to m × n).
 

Private Member Functions

void factor (const matrix< T > &a, svd_method method, bool full)
 Decomposes an m × n a with m ≥ n into u_, singular_values_ and v_, U square when full.
 
void factor (matrix< T > &&a, svd_method method, bool full)
 factor of an expiring matrix, its elements scaled in place.
 
void factor_scaled (const T *source, buffer< T > entries, std::size_t rows, std::size_t cols, svd_method method, bool full)
 The decomposition of the rows × cols matrix at source (row-major), its scaled copy written into entries, which may hold the source itself (each element read before it is written).
 

Static Private Member Functions

static matrix< T > applied_left_vectors (const buffer< T > &left, const std::vector< detail::reflector_block< T > > &blocks, const std::vector< T > &phases, std::size_t rows, std::size_t cols, std::size_t width)
 U = Q [D L; 0] (rows × width): the left vectors left of R (cols × cols), each row times its diagonal's phase phases (D, as detail::householder_qr rotates Q), and where U is square the identity past them, Q's columns past cols; Q the product of the reflectors blocks (detail::apply_q).
 
static matrix< T > left_vectors (buffer< T > q, buffer< T > left, std::size_t rows, std::size_t cols, std::size_t width)
 U from the Householder q (rows × width) and the left vectors left of R (cols × cols): Q times them, and when Q is complete (width = rows) its columns past cols after them.
 
static double largest_cosine (const buffer< T > &x, const buffer< T > &basis, std::size_t n, std::size_t count)
 The largest |⟨b, x⟩| over the first count columns b of the n × n basis.
 
static void orthogonalise (buffer< T > &x, const buffer< T > &basis, std::size_t n, std::size_t count)
 Removes from x its components along the first count columns of the n × n basis.
 

Private Attributes

vector< double > singular_values_
 Singular values, descending.
 
matrix< T > u_
 m×k left singular vectors.
 
matrix< T > v_
 n×k right singular vectors.
 

Static Private Attributes

static constexpr double separate_columns {64.0}
 The cosine past which a left vector, a column of W over its norm, is not taken as orthogonal to those before it, in units of √n ε: one-sided Jacobi leaves its columns within √n ε of each other.
 

Detailed Description

template<field T>
class numerical::svd_decomposition< T >

The singular value decomposition A = U Σ Vᴴ of an m × n matrix.

Template Parameters
TThe scalar element type (double or std::complex<double>).

With k = min(m, n): the k singular values, descending; U (m × k) and V (n × k) with orthonormal columns, also where A is rank-deficient. Computed after a Householder QR of A (of Aᴴ when m < n): by default R is reduced to bidiagonal form and the bidiagonal decomposed by divide and conquer (svd_method::divide_and_conquer), the method of LAPACK's dgesdd, most of its work in matrix products, or by implicit-shift QR (svd_method::bidiagonal_qr, dgesvd's); either way each singular value to an absolute accuracy of the largest times the machine epsilon. One-sided Jacobi on R (svd_method::jacobi) gives every singular value to high relative accuracy — the small ones of a graded matrix too — at several times the cost. vh is Vᴴ, the third factor NumPy's svd returns. Full (full true, NumPy's full_matrices=True), U is m × m and V n × n: the columns past k are an orthonormal basis of the complement, the rest of the complete Householder Q of the larger side.

Definition at line 1600 of file svd.hpp.

Constructor & Destructor Documentation

◆ svd_decomposition() [1/2]

template<field T>
numerical::svd_decomposition< T >::svd_decomposition ( const matrix< T > &  a,
svd_method  method = svd_method::divide_and_conquer,
bool  full = false 
)
inlineexplicit

Decomposes a.

Parameters
[in]aThe matrix.
[in]methodThe algorithm for R.
[in]fullWhether U and V are square (m × m, n × n), as NumPy's full_matrices=True.
Exceptions
non_finite_errorIf an entry is infinite or NaN.
convergence_errorIf the iteration does not converge within its bound (not observed).

Definition at line 1612 of file svd.hpp.

◆ svd_decomposition() [2/2]

template<field T>
numerical::svd_decomposition< T >::svd_decomposition ( matrix< T > &&  a,
svd_method  method = svd_method::divide_and_conquer,
bool  full = false 
)
inlineexplicit

Decomposes a in its own storage, an expiring matrix's elements taken over: its scaled copy is made in place, one matrix less at the peak.

Parameters
[in]aThe matrix.
[in]methodThe algorithm for R.
[in]fullWhether U and V are square (m × m, n × n), as NumPy's full_matrices=True.
Exceptions
non_finite_errorIf an entry is infinite or NaN.
convergence_errorIf the iteration does not converge within its bound (not observed).

Definition at line 1635 of file svd.hpp.

Member Function Documentation

◆ applied_left_vectors()

template<field T>
static matrix< T > numerical::svd_decomposition< T >::applied_left_vectors ( const buffer< T > &  left,
const std::vector< detail::reflector_block< T > > &  blocks,
const std::vector< T > &  phases,
std::size_t  rows,
std::size_t  cols,
std::size_t  width 
)
inlinestaticprivate

U = Q [D L; 0] (rows × width): the left vectors left of R (cols × cols), each row times its diagonal's phase phases (D, as detail::householder_qr rotates Q), and where U is square the identity past them, Q's columns past cols; Q the product of the reflectors blocks (detail::apply_q).

Definition at line 1687 of file svd.hpp.

◆ factor() [1/2]

template<field T>
void numerical::svd_decomposition< T >::factor ( const matrix< T > &  a,
svd_method  method,
bool  full 
)
inlineprivate

Decomposes an m × n a with m ≥ n into u_, singular_values_ and v_, U square when full.

Definition at line 1732 of file svd.hpp.

◆ factor() [2/2]

template<field T>
void numerical::svd_decomposition< T >::factor ( matrix< T > &&  a,
svd_method  method,
bool  full 
)
inlineprivate

factor of an expiring matrix, its elements scaled in place.

Definition at line 1740 of file svd.hpp.

◆ factor_scaled()

template<field T>
void numerical::svd_decomposition< T >::factor_scaled ( const T *  source,
buffer< T >  entries,
std::size_t  rows,
std::size_t  cols,
svd_method  method,
bool  full 
)
inlineprivate

The decomposition of the rows × cols matrix at source (row-major), its scaled copy written into entries, which may hold the source itself (each element read before it is written).

Definition at line 1755 of file svd.hpp.

◆ largest_cosine()

template<field T>
static double numerical::svd_decomposition< T >::largest_cosine ( const buffer< T > &  x,
const buffer< T > &  basis,
std::size_t  n,
std::size_t  count 
)
inlinestaticprivate

The largest |⟨b, x⟩| over the first count columns b of the n × n basis.

Definition at line 1921 of file svd.hpp.

◆ left_vectors()

template<field T>
static matrix< T > numerical::svd_decomposition< T >::left_vectors ( buffer< T >  q,
buffer< T >  left,
std::size_t  rows,
std::size_t  cols,
std::size_t  width 
)
inlinestaticprivate

U from the Householder q (rows × width) and the left vectors left of R (cols × cols): Q times them, and when Q is complete (width = rows) its columns past cols after them.

Definition at line 1711 of file svd.hpp.

◆ orthogonalise()

template<field T>
static void numerical::svd_decomposition< T >::orthogonalise ( buffer< T > &  x,
const buffer< T > &  basis,
std::size_t  n,
std::size_t  count 
)
inlinestaticprivate

Removes from x its components along the first count columns of the n × n basis.

Definition at line 1938 of file svd.hpp.

◆ singular_values()

template<field T>
const vector< double > & numerical::svd_decomposition< T >::singular_values ( ) const
inlinenoexcept

The singular values, descending.

Definition at line 1650 of file svd.hpp.

◆ u() [1/2]

template<field T>
matrix< T > numerical::svd_decomposition< T >::u ( ) &&
inline

U, moved out of an expiring decomposition (v and the singular values stay).

Definition at line 1662 of file svd.hpp.

◆ u() [2/2]

template<field T>
const matrix< T > & numerical::svd_decomposition< T >::u ( ) const &
inlinenoexcept

The left singular vectors U (columns): m × k, or m × m full.

Definition at line 1656 of file svd.hpp.

◆ v()

template<field T>
const matrix< T > & numerical::svd_decomposition< T >::v ( ) const &
inlinenoexcept

The right singular vectors V (columns): n × k, or n × n full.

Definition at line 1668 of file svd.hpp.

◆ vh()

template<field T>
matrix< T > numerical::svd_decomposition< T >::vh ( ) const
inline

Vᴴ (k × n, or n × n full), so that A = U Σ Vᴴ reads u() * diag(singular_values()) * vh() (full, Σ padded with zeros to m × n).

Definition at line 1675 of file svd.hpp.

Member Data Documentation

◆ separate_columns

template<field T>
constexpr double numerical::svd_decomposition< T >::separate_columns {64.0}
staticconstexprprivate

The cosine past which a left vector, a column of W over its norm, is not taken as orthogonal to those before it, in units of √n ε: one-sided Jacobi leaves its columns within √n ε of each other.

Definition at line 1918 of file svd.hpp.

◆ singular_values_

template<field T>
vector<double> numerical::svd_decomposition< T >::singular_values_
private

Singular values, descending.

Definition at line 1954 of file svd.hpp.

◆ u_

template<field T>
matrix<T> numerical::svd_decomposition< T >::u_
private

m×k left singular vectors.

Definition at line 1955 of file svd.hpp.

◆ v_

template<field T>
matrix<T> numerical::svd_decomposition< T >::v_
private

n×k right singular vectors.

Definition at line 1956 of file svd.hpp.


The documentation for this class was generated from the following file: