?gesvda_batch

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 3/22/2024

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-985AE4B9-55A8-406A-AF76-E644BECA466A

View Details

?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.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 for

where 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 (*).

iparm[0]

Specifies a criterion for treating singular values as zeros.

`-1`	Use default `iparm` values (`iparm(0-2)=0`, `iparm[3]=1`) . All other `iparm` settings are ignored.
`= 0`*	Computes the truncated SVD with the help of the input array `irank`.
`= 1`	Computes the truncated SVD using the parameter `tolerance`.
`= 2`	Computes the 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 multiplied by the largest singular value.

iparm[1]

Specifies the option for computing singular vectors.

`0`*	Both singular values and singular vectors are computed.
`1`	Only singular values are computed.

iparm[2]

Specifies the type of the returned SVD decomposition.

0*

Computes the truncated SVD as a product of three matrices:

A_i=U_i×S_i×V_i^T

1

Computes the truncated SVD as a low-rank product:

A_i=P_i×Q_i

iparm[3]

Specifies the option for computing the residual vector.

`0`	The residual vector is not computed.
`1`*	Computes the residual vector.

NOTE:

iparm[4]–iparm[15] are reserved for future use.

irank

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_i^T, 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).

a

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_i^T matrices: ldvt ≥ max(1, n).

stride_vt

The stride between two consecutive V_i^T matrices: stride_vt ≥ max(1, ldvt * n).

tolerance

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

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[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 A_i:=A_i- U_i×S_i×V_i^T if `iparm[2]=0`, and A_i:=A_i-P_i×Q_i 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_i^T 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.

Parent topic: Singular Value Decomposition: LAPACK Driver Routines

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in