?gesvd

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 11/07/2023

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-9753DBC0-04D2-40EA-B1BD-4C83D1FD8C43

View Details

?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*Σ*V^T for real routines

A = U*Σ*V^H 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 V^T (for real flavors) or V^H (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 V^T/V^H.

If jobvt = 'A', all n rows of V^T/V^H are returned in the array vt;

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

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

if jobvt = 'N', no rows of V^T/V^H (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', ldu≥m;

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

If jobvt = 'A', ldvt≥n;

If jobvt = 'S', ldvt≥ min(m, n) for column major layout and ldvt≥n 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 V^T/V^H (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 V^T/V^H.

If jobvt = 'S', vt contains the first min(m, n) rows of V^T/V^H (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*V^T (real flavors) or A = u*B*V^H (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).

Parent topic: Singular Value Decomposition: LAPACK Driver Routines

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for C

?gesvd

Syntax

Include Files

Description

Input Parameters

Output Parameters

Return Values