rocsolver_sgesvd Interface Reference

rocsolver_sgesvd Interface Reference#

hipFORT API Reference: hipfort_rocsolver::rocsolver_sgesvd Interface Reference

The GESVD functions compute the singular values and optionally the singular vectors of a general m-by-n matrix A (Singular Value Decomposition). More...

Public Member Functions
integer(kind(rocblas_status_success)) function	rocsolver_sgesvd_ (handle, left_svect, right_svect, m, n, a, lda, s, u, ldu, v, ldv, e, fast_alg, myinfo)

integer(kind(rocblas_status_success)) function	rocsolver_sgesvd_rank_0 (handle, left_svect, right_svect, m, n, a, lda, s, u, ldu, v, ldv, e, fast_alg, myinfo)

integer(kind(rocblas_status_success)) function	rocsolver_sgesvd_rank_1 (handle, left_svect, right_svect, m, n, a, lda, s, u, ldu, v, ldv, e, fast_alg, myinfo)

integer(kind(rocblas_status_success)) function	rocsolver_sgesvd_full_rank (handle, left_svect, right_svect, m, n, a, lda, s, u, ldu, v, ldv, e, fast_alg, myinfo)

Detailed Description

The GESVD functions compute the singular values and optionally the singular vectors of a general m-by-n matrix A (Singular Value Decomposition).

The SVD of matrix A is given by:

\[ A = U S V^H \]

where the m-by-n matrix S is zero except, possibly, for its min(m,n) diagonal elements, which are the singular values of A. U and V are orthogonal (unitary) matrices. The first min(m,n) columns of U and V are the left and right singular vectors of A, respectively.

The computation of the singular vectors is optional and is controlled by the function arguments left_svect and right_svect, as described below. When computed, this function returns the transpose (or transpose conjugate) of the right singular vectors, that is, the rows of \(V^H\).

left_svect and right_svect are rocblas_svect enums that can take the following values:

rocblas_svect_all: the entire matrix U (or \(V^H\)) is computed,
rocblas_svect_singular: only the singular vectors (first min(m,n) columns of U or rows of \(V^H\)) are computed,
rocblas_svect_overwrite: the first columns (or rows) of A are overwritten with the singular vectors, or
rocblas_svect_none: no columns (or rows) of U (or \(V^H\)) are computed, i.e. no singular vectors.

left_svect and right_svect cannot both be set to overwrite. When neither is set to overwrite, the contents of A are destroyed by the time the function returns.

Note: When m >> n (or n >> m) the algorithm could be sped up by compressing the matrix A via a QR (or LQ) factorization, and working with the triangular factor afterwards (thin-SVD). If the singular vectors are also requested, its computation could be sped up as well via executing some intermediate operations out-of-place and relying more on matrix multiplications (GEMMs), but this will require a larger memory workspace. The parameter fast_alg controls whether the fast algorithm is executed or not. For more details, see the "rocSOLVER performance tuning" and "Memory model" sections of the documentation.; In order to carry out calculations, this method could potentially synchronize the stream contained within the rocblas_handle.; A hybrid (CPU+GPU) approach is available for GESVD, primarily intended for homogeneous architectures. Use rocsolver_set_alg_mode to enable it.

Parameters

[in]	handle	- rocblas_handle.
[in]	left_svect	- `rocblas_svect`. Specifies how the left singular vectors are computed.
[in]	right_svect	- `rocblas_svect`. Specifies how the right singular vectors are computed.
[in]	m	- rocblas_int. m >= 0. The number of rows of matrix A.
[in]	n	- rocblas_int. n >= 0. The number of columns of matrix A.
[in,out]	A	- pointer to type. Array on the GPU of dimension lda*n. On entry, the matrix A. On exit, if left_svect (or right_svect) is equal to overwrite, the first columns (or rows) contain the left (or right) singular vectors. Otherwise, the contents of A are destroyed.
[in]	lda	- rocblas_int. lda >= m. The leading dimension of A.
[out]	S	- pointer to real type. Array on the GPU of dimension min(m,n). The singular values of A in decreasing order.
[out]	U	- pointer to type. Array on the GPU of dimension ldumin(m,n) if left_svect is set to singular, or ldum when left_svect is equal to all. The matrix of left singular vectors stored as columns. Not referenced if left_svect is set to overwrite or none.
[in]	ldu	- rocblas_int. ldu >= m if left_svect is all or singular, and ldu >= 1 otherwise. The leading dimension of U.
[out]	V	- pointer to type. Array on the GPU of dimension ldv*n. The matrix of right singular vectors stored as rows (transposed / conjugate-transposed). Not referenced if right_svect is set to overwrite or none.
[in]	ldv	- rocblas_int. ldv >= n if right_svect is all, and ldv >= min(m,n) if right_svect is set to singular, or ldv >= 1 otherwise. The leading dimension of V.
[out]	E	- pointer to real type. Array on the GPU of dimension min(m,n)-1. This array is used to work internally with the bidiagonal matrix B associated with A (using BDSQR). On exit, if info > 0, it contains the unconverged off-diagonal elements of B (or properly speaking, a bidiagonal matrix orthogonally equivalent to B). The diagonal elements of this matrix are in S. Those that converged correspond to a subset of the singular values of A (not necessarily ordered).
[in]	fast_alg	- `rocblas_workmode`. If set to rocblas_outofplace, the function will execute the fast thin-SVD version of the algorithm when possible.
[out]	myInfo	- pointer to a rocblas_int on the GPU. If info = 0, successful exit. If info = i > 0, BDSQR did not converge. i elements of E did not converge to zero.

Member Function/Subroutine Documentation