Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

ID 766686
Date 7/13/2023
Public

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

Document Table of Contents

?gesvdx

Computes the SVD and left and right singular vectors for a matrix.

Syntax

call sgesvdx(jobu, jobvt, range, m, n, a, lda, vl, vu, il, iu, ns, s, u, ldu, vt, ldvt, work, lwork, iwork, info)

call dgesvdx(jobu, jobvt, range, m, n, a, lda, vl, vu, il, iu, ns, s, u, ldu, vt, ldvt, work, lwork, iwork, info)

call cgesvdx(jobu, jobvt, range, m, n, a, lda, vl, vu, il, iu, ns, s, u, ldu, vt, ldvt, work, lwork, rwork, iwork, info)

call zgesvdx(jobu, jobvt, range, m, n, a, lda, vl, vu, il, iu, ns, s, u, ldu, vt, ldvt, work, lwork, rwork, iwork, info)

Include Files

  • mkl.fi

Description

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

A = U * Σ * transpose(V)

where Σ is an m-by-n matrix which is zero except for its min(m,n) diagonal elements, U is an m-by-m matrix, and V is an n-by-n matrix. The matrices U and V are orthogonal for real A, and unitary for complex A. 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.

?gesvdx uses an eigenvalue problem for obtaining the SVD, which allows for the computation of a subset of singular values and vectors. See ?bdsvdx for details.

Note that the routine returns VT, not V.

Input Parameters

jobu

CHARACTER*1. Specifies options for computing all or part of the matrix U:

= 'V': the first min(m,n) columns of U (the left singular vectors) or as specified by range are returned in the array u;

= 'N': no columns of U (no left singular vectors) are computed.

jobvt

CHARACTER*1. Specifies options for computing all or part of the matrix VT:

= 'V': the first min(m,n) rows of VT (the right singular vectors) or as specified by range are returned in the array vt;

= 'N': no rows of VT (no right singular vectors) are computed.

range

CHARACTER*1. = 'A': find all singular values.

= 'V': all singular values in the half-open interval (vl,vu] are found.

= 'I': the il-th through iu-th singular values are found.

m

INTEGER. The number of rows of the input matrix A. m 0.

n

INTEGER. The number of columns of the input matrix A. n 0.

a

REAL for sgesvdx

DOUBLE PRECISION for dgesvdx

COMPLEX for cgesvdx

DOUBLE COMPLEX for zgesvdx

Array, size (lda,n)

On entry, the m-by-n matrix A.

lda

INTEGER. The leading dimension of the array a.

lda max(1,m).

vl

REAL for sgesvdx

DOUBLE PRECISION for dgesvdx

REAL for cgesvdx

DOUBLE PRECISION for zgesvdx

vl0.

vu

REAL for sgesvdx

DOUBLE PRECISION for dgesvdx

REAL for cgesvdx

DOUBLE PRECISION for zgesvdx

If range='V', the lower and upper bounds of the interval to be searched for singular values. vu > vl. Not referenced if range = 'A' or 'I'.

il

INTEGER.

iu

INTEGER. If range='I', the indices (in ascending order) of the smallest and largest singular values to be returned. 1 iliu min(m,n), if min(m,n) > 0. Not referenced if range = 'A' or 'V'.

ldu

INTEGER. The leading dimension of the array u. ldu 1; if jobu = 'V', ldum.

ldvt

INTEGER. The leading dimension of the array vt. ldvt 1; if jobvt = 'V', ldvtns (see above).

work

REAL for sgesvdx

DOUBLE PRECISION for dgesvdx

COMPLEX for cgesvdx

DOUBLE COMPLEX for zgesvdx

Array, size (max(1,lwork)).

On exit, if info = 0, work(1) returns the optimal lwork;

lwork

INTEGER. The size of the array work.

lwork max(1, min(m, n)*(min(m, n) + 4)) for the paths (see comments inside the code):

  • PATH 1 (m much larger than n)

  • PATH 1t (n much larger than m)

lwork max(1, min(m, n)*2 + max(m, n)) for the other paths. For good performance, lwork should 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.

rwork

REAL for cgesvdx

DOUBLE PRECISION for zgesvdx

Array, size (max(1, lrwork)).

lrwork min(m, n)*(min(m, n)*2 + 15*min(m, n)).

Output Parameters

a

On exit, the contents of a are destroyed.

ns

INTEGER. The total number of singular values found,

0 ns min(m, n).

If range = 'A', ns = min(m, n); if range = 'I', ns = iu - il + 1.

s

REAL for sgesvdx

DOUBLE PRECISION for dgesvdx

REAL for cgesvdx

DOUBLE PRECISION for zgesvdx

Array, size (min(m,n))

The singular values of A, sorted so that s(i)s(i + 1).

u

REAL for sgesvdx

DOUBLE PRECISION for dgesvdx

COMPLEX for cgesvdx

DOUBLE COMPLEX for zgesvdx

If jobu = 'V', u contains columns of U (the left singular vectors, stored columnwise) as specified by range; if jobu = 'N', u is not referenced.

NOTE:

Make sure that ucolns; if range = 'V', the exact value of ns is not known in advance and an upper bound must be used.

vt

REAL for sgesvdx

DOUBLE PRECISION for dgesvdx

COMPLEX for cgesvdx

DOUBLE COMPLEX for zgesvdx

Array, size (ldvt,n)

If jobvt = 'V', vt contains the rows of VT (the right singular vectors, stored rowwise) as specified by range; if jobvt = 'N', vt is not referenced.

NOTE:

Make sure that ldvtns; if range = 'V', the exact value of ns is not known in advance and an upper bound must be used.

iwork

INTEGER. Array, size (12*min(m, n)).

If info = 0, the first ns elements of superb are zero. If info > 0, then superb contains the indices of the eigenvectors that failed to converge in ?bdsvdx/?stevx.

info

INTEGER.

= 0: successful exit.

< 0: if info = -i, the i-th argument had an illegal value.

> 0: if info = i, then i eigenvectors failed to converge in ?bdsvdx/?stevx. if info = n*2 + 1, an internal error occurred in ?bdsvdx.