# p?gesvd

Computes the singular value decomposition of a general matrix, optionally computing the left and/or right singular vectors.

## Syntax

call psgesvd( jobu, jobvt, m, n, a, ia, ja, desca, s, u, iu, ju, descu, vt, ivt, jvt, descvt, work, lwork, info )

call pdgesvd( jobu, jobvt, m, n, a, ia, ja, desca, s, u, iu, ju, descu, vt, ivt, jvt, descvt, work, lwork, info )

call pcgesvd( jobu, jobvt, m, n, a, ia, ja, desca, s, u, iu, ju, descu, vt, ivt, jvt, descvt, work, lwork, rwork, info )

call pzgesvd( jobu, jobvt, m, n, a, ia, ja, desca, s, u, iu, ju, descu, vt, ivt, jvt, descvt, work, lwork, rwork, info )

## Description

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

`A = U*Σ*VT`,

where Σ is an m-by-n matrix that is zero except for its min(m, n) diagonal elements, U is an m-by-m orthogonal matrix, and V is an n-by-n orthogonal matrix. The diagonal elements of Σ are the singular values of A and the columns of U and V are the corresponding right and left singular vectors, respectively. The singular values are returned in array s in decreasing order and only the first min(m,n) columns of U and rows of vt = VT are computed.

## Input Parameters

mp = number of local rows in A and U

nq = number of local columns in A and VT

size = min(m, n)

sizeq = number of local columns in U

sizep = number of local rows in VT

jobu

  (global). CHARACTER*1. Specifies options for computing all or part of the matrix U.

  If `jobu = 'V'`, the first size columns of U (the left singular vectors) are returned in the array u;

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

jobvt

  (global) CHARACTER*1.

  Specifies options for computing all or part of the matrix VT.

  If `jobvt = 'V'`, the first size rows of VT (the right singular vectors) are returned in the array vt;

  If `jobvt = 'N'`, no rows of VT(no right singular vectors) are computed.

m

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

n

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

a

  (local). REAL for psgesvd

  DOUBLE PRECISION for pdgesvd

  COMPLEX for pcgesvd

  COMPLEX*16 for pzgesvd

  Block cyclic array, global dimension (m, n), local dimension (mp, nq).

  `work(lwork)` is a workspace array.

ia, ja

  (global) INTEGER. The row and column indices in the global array a indicating the first row and the first column of the submatrix A, respectively.

desca

  (global and local) INTEGER array, dimension (dlen_). The array descriptor for the distributed matrix A.

iu, ju

  (global) INTEGER. The row and column indices in the global array a indicating the first row and the first column of the submatrix U, respectively.

descu

  (global and local) INTEGER array, dimension (dlen_). The array descriptor for the distributed matrix U.

ivt, jvt

  (global) INTEGER. The row and column indices in the global array vt indicating the first row and the first column of the submatrix VT, respectively.

descvt

  (global and local) INTEGER array, dimension (dlen_). The array descriptor for the distributed matrix VT.

work

  (local). REAL for psgesvd

  DOUBLE PRECISION for pdgesvd

  COMPLEX for pcgesvd

  COMPLEX*16 for pzgesvd

  Workspace array, dimension (lwork)

lwork

  (local) INTEGER. The dimension of the array work;

  `lwork > 2 + 6*sizeb + max(watobd, wbdtosvd)`,

  where `sizeb = max(m, n)`, and watobd and wbdtosvd refer, respectively, to the workspace required to bidiagonalize the matrix A and to go from the bidiagonal matrix to the singular value decomposition U S VT.

  For watobd, the following holds:

  `watobd = max(max(wp?lange,wp?gebrd), max(wp?lared2d, wp?lared1d))`,

  where wp?lange, wp?lared1d, wp?lared2d, wp?gebrd are the workspaces required respectively for the subprograms p?lange, p?lared1d, p?lared2d, p?gebrd. Using the standard notation

  `mp = numroc(m, mb, MYROW, desca(ctxt_), NPROW)`,

  `nq = numroc(n, nb, MYCOL, desca(lld_), NPCOL)`,

  the workspaces required for the above subprograms are

  `wp?lange = mp`,

  `wp?lared1d = nq0`,

  `wp?lared2d = mp0`,

  `wp?gebrd = nb*(mp + nq + 1) + nq`,

  where nq0 and mp0 refer, respectively, to the values obtained at `MYCOL = 0` and `MYROW = 0`. In general, the upper limit for the workspace is given by a workspace required on processor (0,0):

  `watobd ≤ nb*(mp0 + nq0 + 1) + nq0`.

  In case of a homogeneous process grid this upper limit can be used as an estimate of the minimum workspace for every processor.

  For wbdtosvd, the following holds:

  `wbdtosvd = size*(wantu*nru + wantvt*ncvt) + max(w?bdsqr, max(wantu*wp?ormbrqln, wantvt*wp?ormbrprt))`,

  where

  wantu(wantvt) = 1, if left/right singular vectors are wanted, and `wantu(wantvt) =` 0, otherwise. w?bdsqr, wp?ormbrqln, and wp?ormbrprt refer respectively to the workspace required for the subprograms ?bdsqr, p?ormbr(qln), and p?ormbr(prt), where qln and prt are the values of the arguments vect, side, and trans in the call to p?ormbr. nru is equal to the local number of rows of the matrix U when distributed 1-dimensional "column" of processes. Analogously, ncvt is equal to the local number of columns of the matrix VT when distributed across 1-dimensional "row" of processes. Calling the LAPACK procedure ?bdsqr requires

  `w?bdsqr = max(1, 2*size + (2*size - 4)* max(wantu, wantvt))`

  on every processor. Finally,

  `wp?ormbrqln = max((nb*(nb-1))/2, (sizeq+mp)*nb)+nb*nb`,

  `wp?ormbrprt = max((mb*(mb-1))/2, (sizep+nq)*mb)+mb*mb`,

  If `lwork = -1`, then lwork is global input and a workspace query is assumed; the routine only calculates the minimum size for the work array. The required workspace is returned as the first element of work and no error message is issued by pxerbla.

rwork

  REAL for psgesvd

  DOUBLE PRECISION for pdgesvd

  COMPLEX for pcgesvd

  COMPLEX*16 for pzgesvd

  Workspace array, dimension (1 + 4*sizeb)

## Output Parameters

a

  On exit, the contents of a are destroyed.

s

  (global). REAL for psgesvd

  DOUBLE PRECISION for pdgesvd

  COMPLEX for pcgesvd

  COMPLEX*16 for pzgesvd

  Array, DIMENSION (size).

  Contains the singular values of A sorted so that `s(i) ≥ s(i+1)`.

u

  (local). REAL for psgesvd

  DOUBLE PRECISION for pdgesvd

  COMPLEX for pcgesvd

  COMPLEX*16 for pzgesvd

  local dimension (mp, sizeq), global dimension (m, size)

  If `jobu = 'V'`, u contains the first min(m, n) columns of U.

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

vt

  (local). REAL for psgesvd

  DOUBLE PRECISION for pdgesvd

  COMPLEX for pcgesvd

  COMPLEX*16 for pzgesvd

  local dimension (sizep, nq), global dimension (size, n)

  If `jobvt = 'V'`, vt contains the first size rows of VTif `jobu = 'N'`, vt is not referenced.

work

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

rwork

  On exit, if `info = 0`, then `rwork(1)` returns the required size of rwork.

info

  (global) INTEGER.

  If `info = 0`, the execution is successful.

  If `info < 0`, If `info = -i`, the ith parameter had an illegal value.

  If `info > 0 i`, then if ?bdsqr did not converge,

  If `info = min(m,n) + 1`, then p?gesvd has detected heterogeneity by finding that eigenvalues were not identical across the process grid. In this case, the accuracy of the results from p?gesvd cannot be guaranteed.

## See Also

?bdsqr Computes the singular value decomposition of a general matrix that has been reduced to bidiagonal form.
p?ormbr Multiplies a general matrix by one of the orthogonal matrices from a reduction to bidiagonal form determined by p?gebrd.
pxerbla Error handling routine called by ScaLAPACK routines.
Parent topic: Driver Routines