Developer Reference for Intel® oneAPI Math Kernel Library for C
?gesvda_batch_strided
Computes the truncated SVD of a group of general m-by-n matrices that are stored at a constant stride from each other in a contiguous block of memory.
Syntax
void sgesvda_batch_strided(
const MKL_INT* iparm, MKL_INT* irank,
const MKL_INT* m, const MKL_INT* n,
float* a, const MKL_INT* lda, const MKL_INT* stride_a,
float* s, const MKL_INT* stride_s,
float* u, const MKL_INT* ldu, const MKL_INT* stride_u,
float* vt, const MKL_INT* ldvt, const MKL_INT* stride_vt,
const float* tolerance, float *residual,
float* work, const MKL_INT* lwork,
const MKL_INT* batch_size, MKL_INT* info
)void dgesvda_batch_strided(
const MKL_INT* iparm, MKL_INT* irank,
const MKL_INT* m, const MKL_INT* n,
double* a, const MKL_INT* lda, const MKL_INT* stride_a,
double* s, const MKL_INT* stride_s,
double* u, const MKL_INT* ldu, const MKL_INT* stride_u,
double* vt, const MKL_INT* ldvt, const MKL_INT* stride_vt,
const double* tolerance, double *residual,
double* work, const MKL_INT* lwork,
const MKL_INT* batch_size, MKL_INT* info
)void cgesvda_batch_strided(
const MKL_INT* iparm, MKL_INT* irank,
const MKL_INT* m, const MKL_INT* n,
MKL_Complex8* a, const MKL_INT* lda, const MKL_INT* stride_a,
float* s, const MKL_INT* stride_s,
MKL_Complex8* u, const MKL_INT* ldu, const MKL_INT* stride_u,
MKL_Complex8* vt, const MKL_INT* ldvt, const MKL_INT* stride_vt,
const float* tolerance, float *residual,
MKL_Complex8* work, const MKL_INT* lwork,
const MKL_INT* batch_size, MKL_INT* info
)void zgesvda_batch_strided(
const MKL_INT* iparm, MKL_INT* irank,
const MKL_INT* m, const MKL_INT* n,
MKL_Complex16* a, const MKL_INT* lda, const MKL_INT* stride_a,
double* s, const MKL_INT* stride_s,
MKL_Complex16* u, const MKL_INT* ldu, const MKL_INT* stride_u,
MKL_Complex16* vt, const MKL_INT* ldvt, const MKL_INT* stride_vt,
const double* tolerance, double *residual,
MKL_Complex16* work, const MKL_INT* lwork,
const MKL_INT* batch_size, MKL_INT* info
)Include Files
mkl.fi
Include Files
mkl.h
Description
The ?gesvda_batch_strided routines compute the truncated SVD for a group of general m -by- n matrices.
All matrices have the same parameters (matrix size, leading dimension) and are stored at constant stride_a from each other in a contiguous block of memory. The operation is defined as
for i = 0 … batch_size-1
A_{i} is a matrix at offset i * stride_a from A
A_{i} := U_{i} * S_{i}*V_{i}^{T}
A_{i} := U_{i} * S_{i} *
end forwhere Ui and Vi are orthogonal matrices, and Si is a diagonal matrix with singular values on the diagonal. Singular values are nonnegative and listed in decreasing order. A truncated SVD of a given mxn matrix produces matrices with the specified number of columns, where the number of columns is defined by the user or determined at runtime with the help of the user-defined tolerance threshold.
An approximation of each matrix can be also obtained as a product of two low-rank matrices (low-rank product):
A_{i}=P_{i}×Q_{i}where P_{i}=U_{i}×S_{i} , Q_{i}=V_{i}^{T} if m≥n , and P_{i}=U_{i} , Q_{i}=S_{i} × V_{i}^{T} otherwise.
The routines provide three possible ways to compute truncated SVD:
Compute truncated SVD with the help of the input array rank where rank(i) specifies the number of singular values and vectors to be computed in parameters U i ,V i and S i for each matrix A i .
Compute truncated SVD using a tolerance threshold. While computing SVD, singular values that are less than the user-defined tolerance are treated as zero, and they are not computed but set to zero.
Compute truncated SVD using the effective rank. The effective rank of A is determined by treating as zero those singular values that are less than the user-defined tolerance threshold times the largest singular value.
The routines can be also used for computing singular values only.
Input Parameters
iparm
Array of dimension 16 specifying options to compute truncated SVD. Also specifies the type of returned SVD decomposition form. The individual components of the iparm parameter appear below. Default values are denoted with an asterisk (*).
- irank
-
INTEGER. Array of size at least batch_size . If iparm(1)=0 or iparm(1)=-1 , element irank(i) specifies the number of singular values and/or singular vectors to be computed in U i , V iT , and S i for each matrix A i . Array with size at least batch_size . If iparm[0]=0 or iparm[0]=-1 , element irank[i] specifies the number of singular values and/or singular vectors to be computed in U i , V iT , and S i for each matrix A i .
m
The number of rows in the matrices A i ( m ≥ 0 ).
n
The number of columns in the matrices A i ( n ≥ 0 ).
- Aa
-
REAL for sgesvda_batch_strided . DOUBLE PRECISION for dgesvda_batch_strided . COMPLEX for cgesvda_batch_strided . DOUBLE COMPLEX for zgesvda_batch_strided . Array of size at least stride_a * batch_size holding input matrices A i .
lda
Specifies the leading dimension of the A i matrices: lda ≥ max(1, m) .
strde_a
Stride between two consecutive A i matrices: stride_a ≥max(1, lda * n) .
stride_s
The stride between two consecutive S i matrices: stride_s ≥ max(1, min(m,n)) .
ldu
Specifies the leading dimension of the U i matrices: ldu ≥ max(1, m) .
stride_u
The stride between two consecutive U i matrices: stride_u ≥ max(1, ldu * m) .
ldvt
Specifies the leading dimension of the V iT matrices: ldvt ≥ max(1, n) .
stride_vt
The stride between two consecutive V iT matrices: stride_vt ≥ max(1, ldvt * n) .
- tolerance
-
REAL for single precision flavors. DOUBLE PRECISION for double precision flavors. Specifies the tolerance threshold for computing truncated SVD in the cases of iparm(1)=1 and iparm(1)=2 . Not used otherwise. Specifies the tolerance threshold for computing truncated SVD in the cases of iparm[0]=1 and iparm[0]=2 . Not used otherwise.
batch_size
The number of problems in a batch. Must be at least 0.
- work
-
REAL for sgesvda_batch_strided . DOUBLE PRECISION for dgesvda_batch_strided . COMPLEX for cgesvda_batch_strided . DOUBLE COMPLEX for zgesvda_batch_strided . Workspace array with dimension max(1, lwork) .
lwork
The dimension of the array work .
If lwork = -1 , a workspace query is assumed: the routine only calculates the optimal size of the work array and returns this value as the first entry of the work array, and no error message related to lwork is issued by xerbla . If lwork is less than the required minimum size but is positive, the routine internally allocates the needed memory.
Output Parameters
- irank
-
On exit, if iparm(1)=1 or iparm(1)=2 , element irank(i) is the number of computed singular values and/or singular vectors for matrix A i .
- A
-
Unchanged on exit if the residual vector is not required. Otherwise, contains the residual matrix if iparm(3)=0 , and otherwise.
- S
-
REAL for single precision flavors. DOUBLE PRECISION for double precision flavors. Array of size at least min(m,n)*batch_size to store a batch of singular values S i .
- U
-
REAL for sgesvda_batch_strided . DOUBLE PRECISION for dgesvda_batch_strided . COMPLEX for cgesvda_batch_strided . DOUBLE COMPLEX for zgesvda_batch_strided . Array of size at least stride_u*batch_size to store a batch of U i if iparm(3)=0 , or to store a batch of P i if iparm(3)=1 .
- Vt
-
REAL for sgesvda_batch_strided . DOUBLE PRECISION for dgesvda_batch_strided . COMPLEX for cgesvda_batch_strided . DOUBLE COMPLEX for zgesvda_batch_strided . Array of size at least stride_vt*batch_size to store a batch of V iT if iparm(3)=0 , or to store a batch of Q i if iparm(3)=1 .
- residual
-
REAL for single precision flavors. DOUBLE PRECISION for double precision flavors. Array of dimension batch_size . If iparm(4)=1 , residual(i) is the Frobenius norm of the matrix ||A_{i} - U_{i}×S_{i}×V_{i}^{T}|| if iparm(3)=0 , and ||A_{i} - P_{i}×Q_{i}|| if iparm(3)=1 .
info
INTEGER. Array of size at least batch_size , which reports the status for each matrix.
If info(i) = 0 , the execution is successful for A i .
If info(1) = -j , the j-th parameter had an illegal value.
If info(1) = 1, an internal memory allocation failed.
If info(i) = 2 , an input parameter contains an invalid value.
If info(i) = 3 , an error in algorithm while computing singular values of A i occurred.
If info(1) = 4 , the routine encountered an empty structure or matrix array.
Output Parameters
- irank
-
On exit, if iparm[0]=1 or iparm[0]=2 , element irank[0] is the number of computed singular values and/or singular vectors for matrix A i .
- a
-
Unchanged on exit if the residual vector is not required. Otherwise, contains the residual matrix if iparm[2]=0 , and otherwise.
- s
-
Array of size at least min(m,n)*batch_size to store a batch of singular values S i .
- u
-
Array of size at least stride_u*batch_size to store a batch of U i if iparm[2]=0 , or to store a batch of P i if iparm[2]=1 .
- vt
-
Array of size at least stride_vt*batch_size to store a batch of V iT if iparm[2]=0 , or to store a batch of Q i if iparm[2]=1 .
- residual
-
Array of dimension batch_size . If iparm[3]=1 , residual[i] is the Frobenius norm of the matrix ||A_{i} - U_{i}×S_{i}×V_{i}^{T}|| if iparm[2]=0 , and ||A_{i} - P_{i}×Q_{i}|| if iparm[2]=1 .
- info
-
Array of size at least batch_size , which reports the status for each matrix. If info[i] = 0 , the execution is successful for A i . If info[0] = -j , the j-th parameter had an illegal value. If info[0]= 1, an internal memory allocation failed. If info[i] = 2 , an input parameter contains an invalid value. If info[i] = 3 , an error in algorithm while computing singular values of A i occurred. If info[0] = 4 , the routine encountered an empty structure or matrix array.