rocsolver_sgesvdx_batched Interface Reference

rocsolver_sgesvdx_batched Interface Reference#

HIPFORT API Reference: hipfort_rocsolver::rocsolver_sgesvdx_batched Interface Reference

The GESVDX_BATCHED functions compute a set of singular values and optionally the corresponding singular vectors of a batch of general m -by-n matrices \(A_l\) (partial Singular Value Decomposition). More...

Public Member Functions
integer(kind(rocblas_status_success)) function	rocsolver_sgesvdx_batched_ (handle, left_svect, right_svect, srange, m, n, a, lda, vl, vu, il, iu, nsv, s, strides, u, ldu, strideu, v, ldv, stridev, ifail, stridef, myinfo, batch_count)

Detailed Description

The GESVDX_BATCHED functions compute a set of singular values and optionally the corresponding singular vectors of a batch of general m -by-n matrices \(A_l\) (partial Singular Value Decomposition).

This function computes all the singular values of \(A_l\), all the singular values in the half-open interval \([vl, vu)\), or the il -th through iu -th singular values, depending on the value of srange.

The full SVD of matrix \(A_l\) is given by:

\[ A_l = U_l S_l V_l^H \]

where the m-by-n matrix \(S_l\) is zero except, possibly, for its min(m,n) diagonal elements, which are the singular values of \(A_l\). \(U_l\) and \(V_l\) are orthogonal (unitary) matrices. The first min(m,n) columns of \(U_l\) and \(V_l\) are the left and right singular vectors of \(A_l\), 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_l^H\).

left_svect and right_svect are rocblas_svect enums that, for this function, can take the following values:

rocblas_svect_singular: the singular vectors (first min(m,n) columns of \(U_l\) or rows of \(V_l^H\) ) corresponding to the computed singular values are computed,
rocblas_svect_none: no columns (or rows) of \(U_l\) (or \(V_l^H\) ) are computed, that is, no singular vectors.

Parameters

[in]	handle	- rocblas_handle.
[in]	left_svect	- `rocblas_svect`. Specifies if the left singular vectors are computed.
[in]	right_svect	- `rocblas_svect`. Specifies if the right singular vectors are computed.
[in]	srange	- `rocblas_srange`. Specifies the type of range or interval of the singular values to be computed.
[in]	m	- rocblas_int. m >= 0. The number of rows of matrix A_l.
[in]	n	- rocblas_int. n >= 0. The number of columns of matrix A_l.
[in,out]	A	- Array of pointers to type. Each pointer points to an array on the GPU of dimension lda*n. On entry, the matrices A_l. On exit, the contents of A_l are destroyed.
[in]	lda	- rocblas_int. lda >= m. The leading dimension of A_l.
[in]	vl	- real type. 0 <= vl < vu. The lower bound of the search interval [vl, vu). Ignored if srange indicates to look for all the singular values of A_l or the singular values within a set of indices.
[in]	vu	- real type. 0 <= vl < vu. The upper bound of the search interval [vl, vu). Ignored if srange indicates to look for all the singular values of A_l or the singular values within a set of indices.
[in]	il	- rocblas_int. il = 1 if n = 0, and 1 <= il <= iu otherwise. The index of the largest singular value to be computed. Ignored if srange indicates to look for all the singular values of A_l or the singular values in a half-open interval.
[in]	iu	- rocblas_int. iu = 0 if n = 0, and 1 <= il <= iu otherwise. The index of the smallest singular value to be computed. Ignored if srange indicates to look for all the singular values of A_l or the singular values in a half-open interval.
[out]	nsv	- pointer to rocblas_int. Array of batch_count integers on the GPU. The total number of singular values found. If srange is rocblas_srange_all, nsv[l] = min(m,n). If srange is rocblas_srange_index, nsv[l] = iu - il + 1. Otherwise, 0 <= nsv[l] <= min(m,n).
[out]	S	- pointer to real type. Array on the GPU (the size depends on the value of strideS). The first nsv_l elements contain the computed singular values in descending order. (The remaining elements can be used as workspace for internal computations.)
[in]	strideS	- rocblas_stride. Stride from the start of one vector S_l to the next one S_(l+1). There is no restriction for the value of strideS. The normal use case is strideS >= nsv_l. Note: If srange is rocblas_srange_value, then the value of nsv_l is not known in advance. In this case, the user should ensure that S_l is large enough to hold min(m,n) values.
[out]	U	- pointer to type. Array on the GPU (the size depends on the value of strideU). The matrix U_l of left singular vectors stored as columns. Not referenced if left_svect is set to none.
[in]	ldu	- rocblas_int. ldu >= m if left_svect singular, and ldu >= 1 otherwise. The leading dimension of U_l.
[in]	strideU	- rocblas_stride. Stride from the start of one matrix U_l to the next one U_(l+1). There is no restriction for the value of strideU. The normal use case is strideU >= ldu*nsv_l. Note: If srange is rocblas_srange_value, then the value of nsv_l is not known in advance. In this case, the user should ensure that U_l is large enough to hold min(m,n) columns.
[out]	V	- pointer to type. Array on the GPU (the size depends on the value of strideV). The matrix V_l of right singular vectors stored as rows (transposed / conjugate-transposed). Not referenced if right_svect is set to none.
[in]	ldv	- rocblas_int. ldv >= nsv_l if right_svect is set to singular, or ldv >= 1 otherwise. The leading dimension of V_l. Note: If srange is rocblas_srange_value, then the value of nsv_l is not known in advance. In this case, the user should ensure that V_l is large enough to hold min(m,n) rows.
[in]	strideV	- rocblas_stride. Stride from the start of one matrix V_l to the next one V_(l+1). There is no restriction for the value of strideV. The normal use case is strideV >= ldv*n.
[out]	ifail	- pointer to rocblas_int. Array on the GPU (the size depends on the value of strideF). If info[l] = 0, the first nsv[l] elements of ifail_l are zero. Otherwise, contains the indices of those eigenvectors that failed to converge, as returned by BDSVDX.
[in]	strideF	- rocblas_stride. Stride from the start of one vector ifail_l to the next one ifail_(l+1). There is no restriction for the value of strideF. The normal use case is strideF >= min(m,n).
[out]	myInfo	- pointer to a rocblas_int on the GPU. If info[l] = 0, successful exit. If info[l] = i > 0, i eigenvectors did not converge in BDSVDX. Their indices are stored in ifail_l.
[in]	batch_count	- rocblas_int. batch_count >= 0. Number of matrices in the batch.

Member Function/Subroutine Documentation