Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
Public

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

Document Table of Contents

?gesvd

Computes the singular value decomposition of a general rectangular matrix.

Syntax

lapack_int LAPACKE_sgesvd( int matrix_layout, char jobu, char jobvt, lapack_int m, lapack_int n, float* a, lapack_int lda, float* s, float* u, lapack_int ldu, float* vt, lapack_int ldvt, float* superb );

lapack_int LAPACKE_dgesvd( int matrix_layout, char jobu, char jobvt, lapack_int m, lapack_int n, double* a, lapack_int lda, double* s, double* u, lapack_int ldu, double* vt, lapack_int ldvt, double* superb );

lapack_int LAPACKE_cgesvd( int matrix_layout, char jobu, char jobvt, lapack_int m, lapack_int n, lapack_complex_float* a, lapack_int lda, float* s, lapack_complex_float* u, lapack_int ldu, lapack_complex_float* vt, lapack_int ldvt, float* superb );

lapack_int LAPACKE_zgesvd( int matrix_layout, char jobu, char jobvt, lapack_int m, lapack_int n, lapack_complex_double* a, lapack_int lda, double* s, lapack_complex_double* u, lapack_int ldu, lapack_complex_double* vt, lapack_int ldvt, double* superb );

Include Files

  • mkl.h

Description

The routine computes the singular value decomposition (SVD) of a real/complex m-by-n matrix A, optionally computing the left and/or right singular vectors. The SVD is written as

A = U*Σ*VT for real routines

A = U*Σ*VH for complex routines

where Σ is an m-by-n matrix which is zero except for its min(m,n) diagonal elements, U is an m-by-m orthogonal/unitary matrix, and V is an n-by-n orthogonal/unitary matrix. The diagonal elements of Σ are the singular values of A; they are real and non-negative, and are returned in descending order. The first min(m, n) columns of U and V are the left and right singular vectors of A.

The routine returns VT (for real flavors) or VH (for complex flavors), not V.

Input Parameters

matrix_layout

Specifies whether matrix storage layout is row major (LAPACK_ROW_MAJOR) or column major (LAPACK_COL_MAJOR).

jobu

Must be 'A', 'S', 'O', or 'N'. Specifies options for computing all or part of the matrix U.

If jobu = 'A', all m columns of U are returned in the array u;

if jobu = 'S', the first min(m, n) columns of U (the left singular vectors) are returned in the array u;

if jobu = 'O', the first min(m, n) columns of U (the left singular vectors) are overwritten on the array a;

if jobu = 'N', no columns of U (no left singular vectors) are computed.

jobvt

Must be 'A', 'S', 'O', or 'N'. Specifies options for computing all or part of the matrix VT/VH.

If jobvt = 'A', all n rows of VT/VH are returned in the array vt;

if jobvt = 'S', the first min(m,n) rows of VT/VH (the right singular vectors) are returned in the array vt;

if jobvt = 'O', the first min(m,n) rows of VT/VH) (the right singular vectors) are overwritten on the array a;

if jobvt = 'N', no rows of VT/VH (no right singular vectors) are computed.

jobvt and jobu cannot both be 'O'.

m

The number of rows of the matrix A (m 0).

n

The number of columns in A (n 0).

a

Arrays:

a(size at least max(1, lda*n) for column major layout and max(1, lda*m) for row major layout) is an array containing the m-by-n matrix A.

lda

The leading dimension of the array a.

Must be at least max(1, m) for column major layout and at least max(1, n) for row major layout .

ldu, ldvt

The leading dimensions of the output arrays u and vt, respectively.

Constraints:

ldu 1; ldvt 1.

If jobu = 'A', ldum;

If jobu = 'S', ldum for column major layout and ldu min(m, n) for row major layout;

If jobvt = 'A', ldvtn;

If jobvt = 'S', ldvt min(m, n) for column major layout and ldvtn for row major layout .

Output Parameters

a

On exit,

If jobu = 'O', a is overwritten with the first min(m,n) columns of U (the left singular vectors stored columnwise);

If jobvt = 'O', a is overwritten with the first min(m, n) rows of VT/VH (the right singular vectors stored rowwise);

If jobu'O' and jobvt'O', the contents of a are destroyed.

s

Array, size at least max(1, min(m,n)). Contains the singular values of A sorted so that s[i]  s[i + 1].

u, vt

Arrays:

Array u minimum size:

 

Column major layout

Row major layout

jobu = 'A'

max(1, ldu*m)

max(1, ldu*m)

jobu = 'S'

max(1, ldu*min(m, n))

max(1, ldu*m)

If jobu = 'A', u contains the m-by-m orthogonal/unitary matrix U.

If jobu = 'S', u contains the first min(m, n) columns of U (the left singular vectors stored column-wise).

If jobu = 'N' or 'O', u is not referenced.

Array v minimum size:

 

Column major layout

Row major layout

jobvt = 'A'

max(1, ldvt*n)

max(1, ldvt*n)

jobvt = 'S'

max(1, ldvt*min(m, n))

max(1, ldvt*n)

If jobvt = 'A', vt contains the n-by-n orthogonal/unitary matrix VT/VH.

If jobvt = 'S', vt contains the first min(m, n) rows of VT/VH (the right singular vectors stored row-wise).

If jobvt = 'N'or 'O', vt is not referenced.

superb

If ?bdsqr does not converge (indicated by the return value info > 0), on exit superb(0:min(m,n)-2) contains the unconverged superdiagonal elements of an upper bidiagonal matrix B whose diagonal is in s (not necessarily sorted). B satisfies A = u*B*VT (real flavors) or A = u*B*VH (complex flavors), so it has the same singular values as A, and singular vectors related by u and vt.

Return Values

This function returns a value info.

If info = 0, the execution is successful.

If info = -i, the i-th parameter had an illegal value.

If info = i, then if ?bdsqr did not converge, i specifies how many superdiagonals of the intermediate bidiagonal form B did not converge to zero (see the description of the superb parameter for details).