# ?gesvd

Computes the singular value decomposition of a general rectangular matrix.

## Syntax

FORTRAN 77:

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)

Fortran 95:

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

## Description

This 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

`A = U*Σ*VH`

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.

Note that the routine returns VH, 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 VH.

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

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

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

  if `jobvt = 'N'`, no rows of VH (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 first 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 = 'S'` or 'A', `ldu ≥ m`;

  If `jobvt = 'A'`, `ldvt≥ n`;

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

lwork

  INTEGER.

  The dimension of the array work; `lwork ≥ 1`.

  Constraints:

  `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, DIMENSION 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 VH (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, DIMENSION 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 columnwise).

  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 VH.

  If `jobvt = 'S'`, vt contains the first min(m, n) rows of VH (the right singular vectors, stored rowwise).

  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.

## Fortran 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 Fortran 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

  Holds the matrix U of size (m,min(m, n)).

vt

  Holds the matrix VT of size (min(m, n),n).

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.

jobu

  Restored based on the presence of the argument u, value of job and sizes of arrays u and a as follows:

  `jobu = 'A'`, if u is present and the number of columns in u is equal to the number of rows in a,

  `jobu = 'S'`, if u is present and the number of columns in u is not equal to the number of rows in a,

  `jobu = 'O'`, if u is not present and job is equal to 'U',

  `jobu = 'N'`, if u is not present and job is not equal to 'U'.

jobvt

  Restored based on the presence of the argument vt, value of job and sizes of arrays vt and a as follows:

  `jobvt = 'A'`, if vt is present and the number of columns in vt is equal to the number of rows in a,

  `jobvt = 'S'`, if vt is present and the number of columns in vt is not equal to the number of rows in a,

  `jobvt = 'O'`, if vt is not present and job is equal to 'V',

  `jobvt = 'N'`, if vt is not present and job is not equal to 'V',

## 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