The cuSolver handler class. More...

Public Member Functions
	CuSolverHandler ()
	Constructor.
	~CuSolverHandler ()
	Destructor.
cusolverDnHandle_t	handle ()
	Get the cuSolver handle.
cusolverDnParams_t	params () const
	Get the cuSolver parameters object.
void	clear ()
	Clears all internal workspace buffers.
template<typename T_Matrix>
void	reserveLU (const T_Matrix &A)
	Reserves workspace memory for LU factorization.
template<typename T_Matrix>
void	decomposeLU (const T_Matrix &A)
	Performs LU factorization with partial pivoting.
template<typename T_Matrix>
void	solveLU (T_Matrix &B)
	Solves a linear system using the computed LU factorization.
template<typename T_Matrix>
void	reserveGeev (const T_Matrix &A, bool calcLeft, bool calcRight)
	Reserves workspace memory for eigenvalue decomposition.
template<typename T_Matrix>
void	executeGeev (const T_Matrix &A, bool calcLeft, bool calcRight)
	Computes eigenvalues and eigenvectors of a general matrix.
template<typename T_Vector>
void	geevGetEigenvalues (T_Vector &eigs)
	Retrieves computed eigenvalues from the eigenvalue decomposition.
template<typename T_Matrix>
void	geevGetEigenvectors (bool calcLeft, bool calcRight, T_Matrix &leftEigenvectors, T_Matrix &rightEigenvectors)
	Retrieves computed eigenvectors from the eigenvalue decomposition.
template<typename T_Matrix>
void	reserveSyevd (const T_Matrix &A, bool calcVectors)
	Reserves workspace memory for symmetric/Hermitian eigenvalue decomposition.
template<typename T_Matrix>
void	executeSyevd (const T_Matrix &A, bool calcVectors)
	Computes eigenvalues and optionally eigenvectors of a symmetric/Hermitian matrix.
template<typename T_Matrix>
void	reserveSyevdx (const T_Matrix &A, bool calcVectors, eigRange_t range, cuSolverInt il, cuSolverInt iu, typename TypeTraits< typename T_Matrix::value_type >::real_type vl, typename TypeTraits< typename T_Matrix::value_type >::real_type vu)
	Reserves workspace memory for selective symmetric/Hermitian eigenvalue decomposition.
template<typename T_Matrix>
int_t	executeSyevdx (const T_Matrix &A, bool calcVectors, eigRange_t range, cuSolverInt il, cuSolverInt iu, typename TypeTraits< typename T_Matrix::value_type >::real_type vl, typename TypeTraits< typename T_Matrix::value_type >::real_type vu)
	Computes selected eigenvalues and optionally eigenvectors of a symmetric/Hermitian matrix.
template<typename T_Matrix>
void	reserveGesvd (const T_Matrix &A, svdPolicy_t policyU, svdPolicy_t policyVT)
	Reserves workspace memory for Singular Value Decomposition (SVD).
template<typename T_Matrix>
void	executeGesvd (const T_Matrix &A, svdPolicy_t policyU, svdPolicy_t policyVT)
	Computes the Singular Value Decomposition (SVD) of a matrix.
template<typename T_Vector>
void	gesvdGetSingularValues (T_Vector &sigma)
	Retrieves computed singular values from the Singular Value Decomposition.
template<typename T_Matrix>
void	gesvdGetSingularVectors (svdPolicy_t policyU, svdPolicy_t policyVT, T_Matrix &U, T_Matrix &V, bool transposeVT=true)
	Retrieves computed singular vectors from the Singular Value Decomposition.

Detailed Description

The cuSolver handler class.

This class provides a wrapper around the cuSOLVER library for performing linear algebra operations on GPU devices. It manages the cuSOLVER handle and internal workspace buffers required for factorization and solve operations.

The handler uses both device memory buffers and pinned host memory buffers to optimize performance and meet cuSOLVER requirements.

Constructor & Destructor Documentation

◆ CuSolverHandler()

culite::CuSolverHandler::CuSolverHandler ( )

Constructor.

Initializes the cuSOLVER handle and internal state.

◆ ~CuSolverHandler()

culite::CuSolverHandler::~CuSolverHandler ( )

Destructor.

Destroys the cuSOLVER handle and releases all allocated resources.

Member Function Documentation

◆ handle()

cusolverDnHandle_t culite::CuSolverHandler::handle ( )

Get the cuSolver handle.

Returns: The cuSolver handle.

◆ params()

cusolverDnParams_t culite::CuSolverHandler::params ( ) const

Get the cuSolver parameters object.

Returns: The cuSolver DN parameters handle.

◆ clear()

void culite::CuSolverHandler::clear ( )

Clears all internal workspace buffers.

Releases memory allocated for pivot indices, info arrays, and workspace buffers, resetting the handler to its initial state.

◆ reserveLU()

template<typename T_Matrix>

void culite::CuSolverHandler::reserveLU ( const T_Matrix & A )

Reserves workspace memory for LU factorization.

Computes the required workspace size and allocates buffers for performing LU decomposition on matrix A. This includes memory for pivot indices, info arrays, factorization storage, and device/host workspaces.

Template Parameters

T_Matrix The matrix type. Supported: dns::RdMatrix, dns::RfMatrix, dns::CdMatrix, dns::CfMatrix.

Parameters

[in] A The matrix for which to reserve workspace.

◆ decomposeLU()

template<typename T_Matrix>

void culite::CuSolverHandler::decomposeLU ( const T_Matrix & A )

Performs LU factorization with partial pivoting.

Computes the LU decomposition \( P A = L U \) of matrix A, where P is a permutation matrix, L is lower triangular, and U is upper triangular. The factorization is stored internally for subsequent solve operations.

Template Parameters

T_Matrix The matrix type. Supported: dns::RdMatrix, dns::RfMatrix, dns::CdMatrix, dns::CfMatrix.

Parameters

[in] A The matrix to factorize.

◆ solveLU()

template<typename T_Matrix>

void culite::CuSolverHandler::solveLU ( T_Matrix & B )

Solves a linear system using the computed LU factorization.

Solves the system \( A X = B \) using the previously computed LU factorization. The solution is stored in-place in matrix B.

Template Parameters

T_Matrix The matrix type. Supported: dns::RdMatrix, dns::RfMatrix, dns::CdMatrix, dns::CfMatrix.

Parameters

[in,out] B On input, the right-hand side matrix; on output, the solution matrix.

◆ reserveGeev()

template<typename T_Matrix>

void culite::CuSolverHandler::reserveGeev	(	const T_Matrix &	A,
		bool	calcLeft,
		bool	calcRight )

Reserves workspace memory for eigenvalue decomposition.

Computes the required workspace size and allocates buffers for performing eigenvalue decomposition on matrix A. This includes memory for eigenvalues, eigenvectors (if requested), and device/host workspaces.

Template Parameters

T_Matrix The matrix type. Supported: dns::RdMatrix, dns::RfMatrix, dns::CdMatrix, dns::CfMatrix.

Parameters

[in]	A	The matrix for which to reserve workspace.
[in]	calcLeft	If true, reserves memory for left eigenvectors.
[in]	calcRight	If true, reserves memory for right eigenvectors.

Note: This must be called before executeGeev with the same calcLeft/calcRight parameters.

◆ executeGeev()

template<typename T_Matrix>

void culite::CuSolverHandler::executeGeev	(	const T_Matrix &	A,
		bool	calcLeft,
		bool	calcRight )

Computes eigenvalues and eigenvectors of a general matrix.

Performs eigenvalue decomposition on matrix A, computing eigenvalues and optionally left and/or right eigenvectors. For a matrix \( A \), computes eigenvalues \( \lambda \) and eigenvectors such that \( A v = \lambda v \) (right) or \( w^H A = \lambda w^H \) (left).

This method uses cusolverDnXgeev() internally. The input matrix is copied to internal workspace before decomposition (original matrix is not modified). Results are stored internally and can be retrieved using geevGetEigenvalues and geevGetEigenvectors.

Template Parameters

T_Matrix The matrix type. Supported: dns::RdMatrix, dns::RfMatrix, dns::CdMatrix, dns::CfMatrix.

Parameters

[in]	A	The matrix for which to compute eigenvalues/eigenvectors.
[in]	calcLeft	If true, computes left eigenvectors.
[in]	calcRight	If true, computes right eigenvectors.

Note: reserveGeev must be called first with matching parameters.; The input matrix A is not modified; an internal copy is made.

◆ geevGetEigenvalues()

template<typename T_Vector>

void culite::CuSolverHandler::geevGetEigenvalues ( T_Vector & eigs )

Retrieves computed eigenvalues from the eigenvalue decomposition.

Extracts the eigenvalues computed by a previous executeGeev call and stores them in the provided vector. Eigenvalues are always returned as complex values, even for real input matrices.

Template Parameters

T_Vector The vector type. Supported: dns::CdVector, dns::CfVector.

Parameters

[out] eigs Complex vector to store the computed eigenvalues.

Exceptions

CudaException if T_Vector contains real scalars instead of complex.

Note: The output vector must have complex value type (e.g., dns::CdVector for double precision).

◆ geevGetEigenvectors()

template<typename T_Matrix>

void culite::CuSolverHandler::geevGetEigenvectors	(	bool	calcLeft,
		bool	calcRight,
		T_Matrix &	leftEigenvectors,
		T_Matrix &	rightEigenvectors )

Retrieves computed eigenvectors from the eigenvalue decomposition.

Extracts the left and/or right eigenvectors computed by a previous executeGeev call. Eigenvectors are always returned as complex matrices.

For real input matrices with complex eigenvalues, this method automatically converts the compact real representation (where conjugate pairs share storage) to full complex eigenvectors. For complex input matrices, eigenvectors are returned directly without conversion.

Template Parameters

T_Matrix The matrix type. Supported: dns::CdMatrix, dns::CfMatrix.

Parameters

[in]	calcLeft	If true, retrieves left eigenvectors (must match executeGeev parameters).
[in]	calcRight	If true, retrieves right eigenvectors (must match executeGeev parameters).
[out]	leftEigenvectors	Complex matrix to store the left eigenvectors (if calcLeft is true).
[out]	rightEigenvectors	Complex matrix to store the right eigenvectors (if calcRight is true).

Note: The output matrices must have complex value type (e.g., dns::CdMatrix for double precision).; The calcLeft and calcRight parameters must match those used in the executeGeev call.

◆ reserveSyevd()

template<typename T_Matrix>

void culite::CuSolverHandler::reserveSyevd	(	const T_Matrix &	A,
		bool	calcVectors )

Reserves workspace memory for symmetric/Hermitian eigenvalue decomposition.

Computes the required workspace size and allocates buffers for performing eigenvalue decomposition on a symmetric or Hermitian matrix A. This includes memory for eigenvalues (real), eigenvectors (if requested), and device/host workspaces.

Template Parameters

T_Matrix The matrix type (must have symmetric or Hermitian property). Supported: dns::RdMatrix, dns::RfMatrix, dns::CdMatrix, dns::CfMatrix.

Parameters

[in]	A	The symmetric/Hermitian matrix for which to reserve workspace.
[in]	calcVectors	If true, reserves memory for eigenvectors; if false, only eigenvalues.

Note: This must be called before executeSyevd with the same calcVectors parameter.; The matrix uplo property (upper/lower triangular storage) is preserved in workspace allocation.

◆ executeSyevd()

template<typename T_Matrix>

void culite::CuSolverHandler::executeSyevd	(	const T_Matrix &	A,
		bool	calcVectors )

Computes eigenvalues and optionally eigenvectors of a symmetric/Hermitian matrix.

Performs eigenvalue decomposition on a symmetric or Hermitian matrix A, computing real eigenvalues \( \lambda \) and optionally eigenvectors \( v \) such that \( A v = \lambda v \).

This method uses cusolverDnXsyevd() internally, which employs a divide-and-conquer algorithm for efficient computation. The input matrix is copied to internal workspace before decomposition (original matrix is not modified). Results are stored internally and can be retrieved using appropriate getter methods.

For symmetric/Hermitian matrices, all eigenvalues are guaranteed to be real, and eigenvectors form an orthonormal basis.

Template Parameters

T_Matrix The matrix type (must have symmetric or Hermitian property). Supported: dns::RdMatrix, dns::RfMatrix, dns::CdMatrix, dns::CfMatrix.

Parameters

[in]	A	The symmetric/Hermitian matrix for which to compute eigenvalues/eigenvectors.
[in]	calcVectors	If true, computes eigenvectors; if false, only eigenvalues.

Note: reserveSyevd must be called first with matching calcVectors parameter.; The input matrix A is not modified; an internal copy is made.; Only the upper or lower triangular part of A is accessed, as specified by A.prop().uplo().

◆ reserveSyevdx()

template<typename T_Matrix>

void culite::CuSolverHandler::reserveSyevdx	(	const T_Matrix &	A,
		bool	calcVectors,
		eigRange_t	range,
		cuSolverInt	il,
		cuSolverInt	iu,
		typename TypeTraits< typename T_Matrix::value_type >::real_type	vl,
		typename TypeTraits< typename T_Matrix::value_type >::real_type	vu )

Reserves workspace memory for selective symmetric/Hermitian eigenvalue decomposition.

Computes the required workspace size and allocates buffers for performing selective eigenvalue decomposition on a symmetric or Hermitian matrix A. This is an expert routine that allows computing only a subset of eigenvalues and eigenvectors based on value range or index range criteria.

Eigenvalue Range Options:

Value	Description	Parameters Used
All	Computes all eigenvalues (equivalent to syevd)	-
Value	Computes eigenvalues in the half-open interval (vl, vu]	vl, vu
Index	Computes eigenvalues with indices il through iu (1-based indexing)	il, iu

Template Parameters

T_Matrix The matrix type (must have symmetric or Hermitian property). Supported: dns::RdMatrix, dns::RfMatrix, dns::CdMatrix, dns::CfMatrix.

Parameters

[in]	A	The symmetric/Hermitian matrix for which to reserve workspace.
[in]	calcVectors	If true, reserves memory for eigenvectors; if false, only eigenvalues.
[in]	range	Specifies the range of eigenvalues to compute (see table above).
[in]	il	Lower index of the eigenvalue range (1-based, used when range = Index).
[in]	iu	Upper index of the eigenvalue range (1-based, used when range = Index).
[in]	vl	Lower bound of the eigenvalue interval (used when range = Value).
[in]	vu	Upper bound of the eigenvalue interval (used when range = Value).

Note: This must be called before executeSyevdx with matching parameters.

◆ executeSyevdx()

template<typename T_Matrix>

int_t culite::CuSolverHandler::executeSyevdx	(	const T_Matrix &	A,
		bool	calcVectors,
		eigRange_t	range,
		cuSolverInt	il,
		cuSolverInt	iu,
		typename TypeTraits< typename T_Matrix::value_type >::real_type	vl,
		typename TypeTraits< typename T_Matrix::value_type >::real_type	vu )

Computes selected eigenvalues and optionally eigenvectors of a symmetric/Hermitian matrix.

Performs selective eigenvalue decomposition on a symmetric or Hermitian matrix A, computing a subset of real eigenvalues \( \lambda \) and optionally eigenvectors \( v \) such that \( A v = \lambda v \). The subset is determined by the range parameter.

This method uses cusolverDnXsyevdx() internally, which employs a divide-and-conquer algorithm optimized for selective computation. The input matrix is copied to internal workspace before decomposition (original matrix is not modified). Results are stored internally and can be retrieved using appropriate getter methods.

For symmetric/Hermitian matrices, all eigenvalues are guaranteed to be real, and eigenvectors form an orthonormal basis. This expert routine is more efficient than computing all eigenvalues when only a subset is needed.

Eigenvalue Range Options:

Value	Description	Parameters Used
All	Behaves identically to executeSyevd and returns n eigenvalues	-
Value	Computes eigenvalues in the half-open interval (vl, vu]	vl, vu
Index	Eigenvalues are sorted in ascending order (1-based indexing)	il, iu

Template Parameters

T_Matrix The matrix type (must have symmetric or Hermitian property). Supported: dns::RdMatrix, dns::RfMatrix, dns::CdMatrix, dns::CfMatrix.

Parameters

[in]	A	The symmetric/Hermitian matrix for which to compute eigenvalues/eigenvectors.
[in]	calcVectors	If true, computes eigenvectors; if false, only eigenvalues.
[in]	range	Specifies the range of eigenvalues to compute (see table above).
[in]	il	Lower index of the eigenvalue range (1-based, used when range = Index).
[in]	iu	Upper index of the eigenvalue range (1-based, used when range = Index).
[in]	vl	Lower bound of the eigenvalue interval (used when range = Value).
[in]	vu	Upper bound of the eigenvalue interval (used when range = Value).

Returns: The number of eigenvalues found that satisfy the range criteria.

Note: reserveSyevdx must be called first with matching parameters.; The input matrix A is not modified; an internal copy is made.; Only the upper or lower triangular part of A is accessed, as specified by A.prop().uplo().

◆ reserveGesvd()

template<typename T_Matrix>

void culite::CuSolverHandler::reserveGesvd	(	const T_Matrix &	A,
		svdPolicy_t	policyU,
		svdPolicy_t	policyVT )

Reserves workspace memory for Singular Value Decomposition (SVD).

Computes the required workspace size and allocates buffers for performing SVD on matrix A. This includes memory for singular values, singular vectors (U and V^T matrices), working copy of the input matrix, and device/host workspaces.

Left Singular Vectors (U) Policy:

Policy	Description	Matrix Size
Full	Compute all m columns of U	m×m
Economy	Compute first min(m,n) columns of U (economy-size)	m×min(m,n)
NoCalculation	Do not compute U	-

Right Singular Vectors (V^T) Policy:

Policy	Description	Matrix Size
Full	Compute all n rows of V^T	n×n
Economy	Compute first min(m,n) rows of V^T (economy-size)	min(m,n)×n
NoCalculation	Do not compute V^T	-

Template Parameters

T_Matrix The matrix type. Supported: dns::RdMatrix, dns::RfMatrix, dns::CdMatrix, dns::CfMatrix.

Parameters

[in]	A	The matrix for which to reserve workspace (m×n).
[in]	policyU	Policy for computing left singular vectors U (see table above).
[in]	policyVT	Policy for computing right singular vectors V^T (see table above).

Note: This must be called before executeGesvd with matching policyU and policyVT parameters.; For economy-size SVD (Economy policy), memory usage is significantly reduced compared to Full.

◆ executeGesvd()

template<typename T_Matrix>

void culite::CuSolverHandler::executeGesvd	(	const T_Matrix &	A,
		svdPolicy_t	policyU,
		svdPolicy_t	policyVT )

Computes the Singular Value Decomposition (SVD) of a matrix.

Performs SVD on matrix A, computing the factorization \( A = U \Sigma V^T \) where \( U \) and \( V \) are orthogonal/unitary matrices, and \( \Sigma \) is a diagonal matrix containing the singular values in descending order.

This method uses cusolverDnXgesvd() internally. The input matrix is copied to internal workspace before decomposition (original matrix is not modified). Results are stored internally and can be retrieved using appropriate getter methods.

The singular values are always real and non-negative, even for complex input matrices. The computation policies control whether full or economy-size decompositions are performed.

Left Singular Vectors (U) Policy:

Policy	Description	Matrix Size
Full	Compute all m columns of U	m×m
Economy	Compute first min(m,n) columns of U (economy-size)	m×min(m,n)
NoCalculation	Do not compute U	-

Right Singular Vectors (V^T) Policy:

Policy	Description	Matrix Size
Full	Compute all n rows of V^T	n×n
Economy	Compute first min(m,n) rows of V^T (economy-size)	min(m,n)×n
NoCalculation	Do not compute V^T	-

Template Parameters

T_Matrix The matrix type. Supported: dns::RdMatrix, dns::RfMatrix, dns::CdMatrix, dns::CfMatrix.

Parameters

[in]	A	The matrix to decompose (m×n).
[in]	policyU	Policy for computing left singular vectors U (see table above).
[in]	policyVT	Policy for computing right singular vectors V^T (see table above).

Note: reserveGesvd must be called first with matching policyU and policyVT parameters.; The input matrix A is not modified; an internal copy is made.; Singular values are returned in descending order: σ₁ ≥ σ₂ ≥ ... ≥ σₘᵢₙ₍ₘ,ₙ₎ ≥ 0.; For economy-size decomposition (Economy policy), computational cost is reduced.

◆ gesvdGetSingularValues()

template<typename T_Vector>

void culite::CuSolverHandler::gesvdGetSingularValues ( T_Vector & sigma )

Retrieves computed singular values from the Singular Value Decomposition.

Extracts the singular values computed by a previous executeGesvd call and stores them in the provided vector. Singular values are always real and non-negative, returned in descending order: σ₁ ≥ σ₂ ≥ ... ≥ σₘᵢₙ₍ₘ,ₙ₎ ≥ 0.

For an m×n matrix, the number of singular values is min(m,n).

Template Parameters

T_Vector The vector type. Supported: dns::RdVector, dns::RfVector.

Parameters

[out] sigma Real vector to store the computed singular values.

Exceptions

CudaException if T_Vector contains complex scalars instead of real.

Note: The output vector must have real value type (e.g., dns::RdVector for double precision).; The vector will be automatically sized to min(m,n) if not already allocated.

◆ gesvdGetSingularVectors()

template<typename T_Matrix>

void culite::CuSolverHandler::gesvdGetSingularVectors	(	svdPolicy_t	policyU,
		svdPolicy_t	policyVT,
		T_Matrix &	U,
		T_Matrix &	V,
		bool	transposeVT = true )

Retrieves computed singular vectors from the Singular Value Decomposition.

Extracts the left singular vectors (U) and/or right singular vectors computed by a previous executeGesvd call. The matrices returned depend on the policies specified, which must match those used in the executeGesvd call.

For an m×n matrix decomposition \( A = U \Sigma V^T \), the singular vectors form orthogonal/unitary matrices satisfying specific size constraints based on the computation policy.

The transposeVT parameter controls whether the right singular vectors are returned as \( V^T \) (transpose format, as computed by cuSOLVER) or as \( V \) (standard format, transposed for convenience).

Left Singular Vectors (U) Policy:

Policy	Description	Matrix Size
Full	Returns all m columns of U	m×m
Economy	Returns first min(m,n) columns of U (economy-size)	m×min(m,n)
NoCalculation	Does not retrieve U (U is not modified)	-

Right Singular Vectors (V/V^T) Policy:

When transposeVT = true (default), returns V:

Policy	Description	Matrix Size
Full	Returns all n columns of V	n×n
Economy	Returns first min(m,n) columns of V (economy-size)	n×min(m,n)
NoCalculation	Does not retrieve V (V is not modified)	-

When transposeVT = false, returns V^T:

Policy	Description	Matrix Size
Full	Returns all n rows of V^T	n×n
Economy	Returns first min(m,n) rows of V^T (economy-size)	min(m,n)×n
NoCalculation	Does not retrieve V^T (V is not modified)	-

Template Parameters

T_Matrix The matrix type. Supported: dns::RdMatrix, dns::RfMatrix, dns::CdMatrix, dns::CfMatrix.

Parameters

[in]	policyU	Policy for retrieving left singular vectors (must match executeGesvd).
[in]	policyVT	Policy for retrieving right singular vectors (must match executeGesvd).
[out]	U	Matrix to store the left singular vectors (if policyU ≠ NoCalculation).
[out]	V	Matrix to store the right singular vectors, either as V or V^T depending on transposeVT.
[in]	transposeVT	If true (default), returns V by transposing V^T; if false, returns V^T directly.

Note: The policyU and policyVT parameters must match those used in the executeGesvd call.; Output matrices will be automatically sized if not already allocated.; If a policy is NoCalculation, the corresponding matrix parameter is ignored.; Setting transposeVT = true requires additional transpose operation but provides V in standard format.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CuSolverHandler()

◆ ~CuSolverHandler()

Member Function Documentation

◆ handle()

◆ params()

◆ clear()

◆ reserveLU()

◆ decomposeLU()

◆ solveLU()

◆ reserveGeev()

◆ executeGeev()

◆ geevGetEigenvalues()

◆ geevGetEigenvectors()

◆ reserveSyevd()

◆ executeSyevd()

◆ reserveSyevdx()

◆ executeSyevdx()

◆ reserveGesvd()

◆ executeGesvd()

◆ gesvdGetSingularValues()

◆ gesvdGetSingularVectors()