?gesvd

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

Download PDF

ID 766686

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

View Details

?gesvd

Computes the singular value decomposition of a general rectangular matrix.

Syntax

call sgesvd(jobu, jobvt, m, n, a, lda, s, u, ldu, vt, ldvt, work, lwork, info)

call dgesvd(jobu, jobvt, m, n, a, lda, s, u, ldu, vt, ldvt, work, lwork, info)

call cgesvd(jobu, jobvt, m, n, a, lda, s, u, ldu, vt, ldvt, work, lwork, rwork, info)

call zgesvd(jobu, jobvt, m, n, a, lda, s, u, ldu, vt, ldvt, work, lwork, rwork, info)

call gesvd(a, s [,u] [,vt] [,ww] [,job] [,info])

Include Files

mkl.fi, lapack.f90

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

jobu

CHARACTER*1. 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

CHARACTER*1. 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

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

n

INTEGER. The number of columns in A (n≥ 0).

a, work

REAL for sgesvd

DOUBLE PRECISION for dgesvd

COMPLEX for cgesvd

DOUBLE COMPLEX for zgesvd.

Arrays:

a(lda,*) is an array containing the m-by-n matrix A.

The second dimension of a must be at least max(1, n).

work is a workspace array, its dimension max(1, lwork).

lda

INTEGER. The leading dimension of the array a.

Must be at least max(1, m) .

ldu, ldvt

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

Constraints:

ldu≥ 1; ldvt≥ 1.

If jobu = 'A'or 'S', ldu≥m;

If jobvt = 'A', ldvt≥n;

If jobvt = 'S', ldvt≥ min(m, n) .

lwork

INTEGER.

The dimension of the array work.

Constraints:

lwork≥ 1

lwork≥ max(3*min(m, n)+max(m, n), 5*min(m,n)) (for real flavors);

lwork≥ 2*min(m, n)+max(m, n) (for complex flavors).

For good performance, lwork must generally be larger.

If lwork = -1, then a workspace query is assumed; the routine only calculates the optimal size of the work array, returns this value as the first entry of the work array, and no error message related to lwork is issued by xerbla. See Application Notes for details.

rwork

REAL for cgesvd

DOUBLE PRECISION for zgesvd

Workspace array, size at least max(1, 5*min(m, n)). Used in complex flavors only.

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

REAL for single precision flavors DOUBLE PRECISION for double precision flavors.

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

REAL for sgesvd

DOUBLE PRECISION for dgesvd

COMPLEX for cgesvd

DOUBLE COMPLEX for zgesvd.

Arrays:

u(ldu,*); the second dimension of u must be at least max(1, m) if jobu = 'A', and at least max(1, min(m, n)) if jobu = 'S'.

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.

vt(ldvt,*); the second dimension of vt must be at least max(1, 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.

work

On exit, if info = 0, then work(1) returns the required minimal size of lwork.

For real flavors:

If info > 0, work(2:min(m,n)) 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, so it has the same singular values as A, and singular vectors related by u and vt.

rwork

On exit (for complex flavors), if info > 0, rwork(1:min(m,n)-1) 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, so it has the same singular values as A, and singular vectors related by u and vt.

info

INTEGER.

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 work and rwork parameters for details).

LAPACK 95 Interface Notes

Routines in Fortran 95 interface have fewer arguments in the calling sequence than their FORTRAN 77 counterparts. For general conventions applied to skip redundant or restorable arguments, see LAPACK 95 Interface Conventions.

Specific details for the routine gesvd interface are the following:

a

Holds the matrix A of size (m, n).

s

Holds the vector of length min(m, n).

u

If present and is a square m-by-m matrix, on exit contains the m-by-m orthogonal/unitary matrix U.

Otherwise, if present, on exit contains the first min(m,n) columns of the matrix U (left singular vectors stored column-wise).

vt

If present and is a square n-by-n matrix, on exit contains the n-by-n orthogonal/unitary matrix V'^T/V'^H.

Otherwise, if present, on exit contains the first min(m,n) rows of the matrix V'^T/V'^H (right singular vectors stored row-wise).

ww

Holds the vector of length min(m, n)-1. ww 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, so it has the same singular values as A, and singular vectors related by U and VT.

job

Must be either 'N', or 'U', or 'V'. The default value is 'N'.

If job = 'U', and u is not present, then u is returned in the array a.

If job = 'V', and vt is not present, then vt is returned in the array a.

Application Notes

If you are in doubt how much workspace to supply, use a generous value of lwork for the first run or set lwork = -1.

If you choose the first option and set any of admissible lwork sizes, which is no less than the minimal value described, the routine completes the task, though probably not so fast as with a recommended workspace, and provides the recommended workspace in the first element of the corresponding array work on exit. Use this value (work(1)) for subsequent runs.

If you set lwork = -1, the routine returns immediately and provides the recommended workspace in the first element of the corresponding array (work). This operation is called a workspace query.

Note that if you set lwork to less than the minimal required value and not -1, the routine returns immediately with an error exit and does not provide any information on the recommended workspace.

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 Fortran

?gesvd

Syntax

Include Files

Description

Input Parameters

Output Parameters

LAPACK 95 Interface Notes

Application Notes