Detailed Description

Various matrix decompositions like SVD, QR, etc.

Functions
template<typename LP = F_layout, MemoryMatrix A> requires (mem::have_host_compatible_addr_space<A> and blas_lapack::has_F_layout<A>)
auto	nda::linalg::get_lu_matrices (A const &a)
	Get the \( \mathbf{L} \) and \( \mathbf{U} \) matrices from the output of nda::lapack::getrf.
template<blas_lapack::BlasArray< 2 > A, blas_lapack::BlasArrayFor< A, 1 > TAU> requires (mem::have_host_compatible_addr_space<A, TAU>)
auto	nda::linalg::get_qr_matrices (A const &a, TAU const &tau, bool complete=false)
	Get the \( \mathbf{Q} \) and \( \mathbf{R} \) matrices from the output of nda::lapack::geqp3 or nda::lapack::geqrf.
template<Matrix A> requires (mem::have_host_compatible_addr_space<A> and is_blas_lapack_v<get_value_t<A>>)
auto	nda::linalg::lu (A const &a, bool allow_singular=false)
	Compute the LU factorization of a matrix.
template<typename LP = F_layout, blas_lapack::BlasArray< 2 > A> requires (mem::have_host_compatible_addr_space<A> and blas_lapack::has_F_layout<A>)
auto	nda::linalg::lu_in_place (A &&a, bool allow_singular=false)
	Compute the LU factorization of a matrix in place.
template<Matrix A> requires (mem::have_host_compatible_addr_space<A> and is_blas_lapack_v<get_value_t<A>>)
auto	nda::linalg::qr (A const &a, bool complete=false)
	Compute the QR factorization of a matrix.
template<blas_lapack::BlasArray< 2 > A> requires (mem::have_host_compatible_addr_space<A> and blas_lapack::has_F_layout<A>)
auto	nda::linalg::qr_in_place (A &&a, bool complete=false)
	Compute the QR factorization of a matrix in place.
template<Matrix A> requires (is_blas_lapack_v<get_value_t<A>>)
auto	nda::linalg::svd (A const &a)
	Compute the singular value decomposition (SVD) of a matrix.
template<blas_lapack::BlasArray< 2 > A>
auto	nda::linalg::svd_in_place (A &&a)
	Compute the singular value decomposition (SVD) of a matrix in place.

Function Documentation

◆ get_lu_matrices()

template<typename LP = F_layout, MemoryMatrix A>
requires (mem::have_host_compatible_addr_space<A> and blas_lapack::has_F_layout<A>)

auto nda::linalg::get_lu_matrices ( A const & a )

#include <nda/linalg/lu.hpp>

Get the \( \mathbf{L} \) and \( \mathbf{U} \) matrices from the output of nda::lapack::getrf.

Let the original matrix \( \mathbf{A} \) be of size \( m \times n \). Then the returned \( \mathbf{L} \) matrix is of size \( m \times k \) and \( \mathbf{U} \) is of size \( k \times n \), where \( k = \min(m, n) \).

Note: \( \mathbf{A} \) is required to satisfy nda::mem::have_host_compatible_addr_space and to have nda::F_layout.

Template Parameters

LP	Policy determining the memory layout of the \( \mathbf{L} \) and \( \mathbf{U} \) matrices.
A	nda::MemoryMatrix type.

Parameters

a	Input matrix \( \mathbf{A} \) containing the output of nda::lapack::getrf.

Returns: A tuple containing the \( \mathbf{L} \) and \( \mathbf{U} \) matrices.

Definition at line 55 of file lu.hpp.

◆ get_qr_matrices()

template<blas_lapack::BlasArray< 2 > A, blas_lapack::BlasArrayFor< A, 1 > TAU>
requires (mem::have_host_compatible_addr_space<A, TAU>)

auto nda::linalg::get_qr_matrices	(	A const &	a,
		TAU const &	tau,
		bool	complete = false )

#include <nda/linalg/qr.hpp>

Get the \( \mathbf{Q} \) and \( \mathbf{R} \) matrices from the output of nda::lapack::geqp3 or nda::lapack::geqrf.

\( \mathbf{R} \) is simply the upper triangular (trapezoidal) part of the \( m \times n \) matrix \(\mathbf{A} \) returned by nda::lapack::geqp3 or nda::lapack::geqrf.

\( \mathbf{Q} \) is computed from the elementary reflectors stored in the lower part of \( \mathbf{A} \) and the vector of scalar factors \( \mathbf{\tau} \) using nda::lapack::orgqr or nda::lapack::ungqr.

\( \mathbf{Q} \) has dimensions \( m \times k \) and \( \mathbf{R} \) has dimensions \( k \times n \), where \( k \) depends on the mode of the factorization:

reduced mode (default): \( k = \min(m, n) \).
complete mode: \( k = m \).

The resulting matrices \( \mathbf{Q} \) and \( \mathbf{R} \) are always returned in nda::F_layout.

An exception is thrown, if the LAPACK call fails.

Note: \( \mathbf{A} \) and \( \mathbf{\tau} \) are required to satisfy nda::mem::have_host_compatible_addr_space.

Template Parameters

A	nda::blas_lapack::BlasArray<2> type.
TAU	nda::blas_lapack::BlasArrayFor<A, 1> type.

Parameters

a	Input matrix \( \mathbf{A} \) containing the output of nda::lapack::geqp3 or nda::lapack::geqrf.
tau	Input vector \( \mathbf{\tau} \) containing the scalar factors of the elementary reflectors as returned by nda::lapack::geqp3 or nda::lapack::geqrf.
complete	If true, retrieves the matrices for the complete QR factorization.

Returns: A tuple containing the \( \mathbf{Q} \) and \( \mathbf{R} \) matrices.

Definition at line 72 of file qr.hpp.

◆ lu()

template<Matrix A>
requires (mem::have_host_compatible_addr_space<A> and is_blas_lapack_v<get_value_t<A>>)

auto nda::linalg::lu	(	A const &	a,
		bool	allow_singular = false )

#include <nda/linalg/lu.hpp>

Compute the LU factorization of a matrix.

It makes a copy of the input matrix \( \mathbf{A} \) and calls nda::linalg::lu_in_place.

The resulting \( \mathbf{L} \) and \( \mathbf{U} \) matrices have the same layout as the input matrix \(\mathbf{A} \).

Note: \( \mathbf{A} \) is required to satisfy nda::mem::have_host_compatible_addr_space and to have a value type that satisfies nda::is_blas_lapack_v.

Template Parameters

A	nda::Matrix type.

Parameters

a	Input matrix. The \( m \times n \) matrix \( \mathbf{A} \) to be factorized.
allow_singular	If true, allows factorization of singular matrices. If false (default), throws an error when the matrix is detected to be singular.

Returns: A tuple containing \( \mathbf{\sigma} \), \( \mathbf{L} \) and \( \mathbf{U} \).

Definition at line 145 of file lu.hpp.

◆ lu_in_place()

template<typename LP = F_layout, blas_lapack::BlasArray< 2 > A>
requires (mem::have_host_compatible_addr_space<A> and blas_lapack::has_F_layout<A>)

auto nda::linalg::lu_in_place	(	A &&	a,
		bool	allow_singular = false )

#include <nda/linalg/lu.hpp>

Compute the LU factorization of a matrix in place.

The function computes the LU factorization of a general \( m \times n \) matrix \( \mathbf{A} \) using nda::lapack::getrf. The factorization has the form

\[ \mathbf{P A} = \mathbf{L U} \]

where \( \mathbf{P} \) is an \( m \times m \) permutation matrix, \( \mathbf{L} \) is an \( m \times k \) lower triangular (trapezoidal if \( m > n \)) matrix with unit diagonal elements, and \( \mathbf{U} \) is a \(k \times n \) upper triangular (trapezoidal if \( m < n \)) matrix. Here, \( k = \min(m, n) \).

\( \mathbf{P} \) is returned as a permutation vector \( \mathbf{\sigma} \) of size \( m \). See nda::linalg::get_permutation_vector for more information.

An exception is thrown, if the LAPACK call returns

a non-zero value (allow_singular == false) or
a value \( > 0 \) (allow_singular == true).

Note: \( \mathbf{A} \) is required to satisfy nda::mem::have_host_compatible_addr_space and to have nda::F_layout. See nda::linalg::lu for a version that handles nda::C_layout.

Template Parameters

LP	Policy determining the memory layout of the \( \mathbf{L} \) and \( \mathbf{U} \) matrices.
A	nda::blas_lapack::BlasArray<2> type.

Parameters

a	Input/Output matrix. On entry, the \( m \times n \) matrix \( \mathbf{A} \). On exit, the result of the nda::lapack::getrf call.
allow_singular	If true, allows factorization of singular matrices. If false (default), throws an error when the matrix is detected to be singular.

Returns: A tuple containing \( \mathbf{\sigma} \), \( \mathbf{L} \) and \( \mathbf{U} \).

Definition at line 107 of file lu.hpp.

◆ qr()

template<Matrix A>
requires (mem::have_host_compatible_addr_space<A> and is_blas_lapack_v<get_value_t<A>>)

auto nda::linalg::qr	(	A const &	a,
		bool	complete = false )

#include <nda/linalg/qr.hpp>

Compute the QR factorization of a matrix.

It makes a copy of the input matrix \( \mathbf{A} \) and calls nda::linalg::qr_in_place.

The resulting matrices \( \mathbf{Q} \) and \( \mathbf{R} \) have the same layout as the input matrix \(\mathbf{A} \).

Note: \( \mathbf{A} \) is required to satisfy nda::mem::have_host_compatible_addr_space and to have a value type that satisfies nda::is_blas_lapack_v.

Template Parameters

A	nda::Matrix type.

Parameters

a	Input matrix. The \( m \times n \) matrix \( \mathbf{A} \) to be factorized.
complete	If true, computes the complete QR factorization. See nda::linalg::qr_in_place for details.

Returns: A tuple containing \( \mathbf{\sigma} \), \( \mathbf{Q} \) and \( \mathbf{R} \).

Definition at line 168 of file qr.hpp.

◆ qr_in_place()

template<blas_lapack::BlasArray< 2 > A>
requires (mem::have_host_compatible_addr_space<A> and blas_lapack::has_F_layout<A>)

auto nda::linalg::qr_in_place	(	A &&	a,
		bool	complete = false )

#include <nda/linalg/qr.hpp>

Compute the QR factorization of a matrix in place.

The function computes the QR factorization of a general \( m \times n \) matrix \( \mathbf{A} \) using nda::lapack::geqp3 and nda::lapack::orgqr or nda::lapack::ungqr. The factorization has the form

\[ \mathbf{A P} = \mathbf{Q R} \]

where \( \mathbf{P} \) is a \( k \times k \) permutation matrix, \( \mathbf{Q} \) is an \( m \times k \) (orthogonal/unitary if \( k = m \)) matrix, and \( \mathbf{R} \) is a \( k \times n \) upper triangular (trapezoidal if \( k < n \)) matrix.

The dimension \( k \) depends on the mode of the factorization:

reduced mode (default): \( k = \min(m, n) \).
complete mode: \( k = m \).

The matrix \( \mathbf{P} \) is returned as a permutation vector \( \mathbf{\sigma} \) of size \( n \). See nda::linalg::get_permutation_vector for more information.

The resulting matrices \( \mathbf{Q} \) and \( \mathbf{R} \) are always returned in nda::F_layout.

An exception is thrown, if one of the LAPACK calls fails.

Note: \( \mathbf{A} \) is required to satisfy nda::mem::have_host_compatible_addr_space and to have nda::F_layout. See nda::linalg::qr for a version that handles nda::C_layout.

Template Parameters

A	nda::blas_lapack::BlasArray<2> type.

Parameters

a	Input/Output matrix. On entry, the \( m \times n \) matrix \( \mathbf{A} \). On exit, the result of the nda::lapack::geqp3 call.
complete	If true, computes the complete QR factorization.

Returns: A tuple containing \( \mathbf{\sigma} \), \( \mathbf{Q} \) and \( \mathbf{R} \).

Definition at line 130 of file qr.hpp.

◆ svd()

template<Matrix A>
requires (is_blas_lapack_v<get_value_t<A>>)

auto nda::linalg::svd ( A const & a )

#include <nda/linalg/svd.hpp>

Compute the singular value decomposition (SVD) of a matrix.

It calls nda::linalg::svd_in_place with a copy of the input matrix \( \mathbf{A} \).

This function makes copies of the input arrays/views. When working on the device memory space, this may lead to runtime errors if the copying fails.

Note: \( \mathbf{A} \) is required to have a value type that satisfies nda::is_blas_lapack_v.

Template Parameters

A	nda::Matrix type.

Parameters

a	Input matrix \( \mathbf{A} \).

Returns: std::tuple containing \( \mathbf{U} \), \( \mathbf{s} \) and \( \mathbf{V}^H \).

Definition at line 95 of file svd.hpp.

◆ svd_in_place()

template<blas_lapack::BlasArray< 2 > A>

auto nda::linalg::svd_in_place ( A && a )

#include <nda/linalg/svd.hpp>

Compute the singular value decomposition (SVD) of a matrix in place.

The function computes the SVD of a given \( m \times n \) matrix \( \mathbf{A} \):

\[ \mathbf{A} = \mathbf{U} \mathbf{S} \mathbf{V}^H \; , \]

where \( \mathbf{U} \) is a unitary \( m \times m \) matrix, \( \mathbf{V} \) is a unitary \( n \times n \) matrix and \( \mathbf{S} \) is an \( m \times n \) matrix with non-negative real numbers on the diagonal.

It first constructs the output vector \( \mathbf{s} \), which contains the singular values, and the output matrices \( \mathbf{U} \) and \( \mathbf{V}^H \). It then calls nda::lapack::gesvd to compute the SVD.

The resulting matrices \( \mathbf{U} \) and \( \mathbf{V}^H \) have the same memory layout, address space and value type as \( \mathbf{A} \). The vector \( \mathbf{s} \) has the same address space as \( \mathbf{A} \) and its value type is given by nda::get_fp_t<A>.

An exception is thrown, if the LAPACK call returns a non-zero value.

Template Parameters

A	nda::blas_lapack::BlasArray<2> type.

Parameters

a	Input/output matrix. On entry, the \( m \times n \) matrix \( \mathbf{A} \). On exit, the contents of \( \mathbf{A} \) are destroyed.

Returns: std::tuple containing \( \mathbf{U} \), \( \mathbf{s} \) and \( \mathbf{V}^H \).

Definition at line 62 of file svd.hpp.

Detailed Description

Functions

Function Documentation

◆ get_lu_matrices()

◆ get_qr_matrices()

◆ lu()

◆ lu_in_place()

◆ qr()

◆ qr_in_place()

◆ svd()

◆ svd_in_place()