Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
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

lapack_int LAPACKE_sgesvdx (int matrix_layout, char jobu, char jobvt, char range, lapack_int m, lapack_int n, float * a, lapack_int lda, float vl, float vu, lapack_int il, lapack_int iu, lapack_int * ns, float * s, float * u, lapack_int ldu, float * vt, lapack_int ldvt, lapack_int * superb);

lapack_int LAPACKE_dgesvdx (int matrix_layout, char jobu, char jobvt, char range, lapack_int m, lapack_int n, double * a, lapack_int lda, double vl, double vu, lapack_int il, lapack_int iu, lapack_int *ns, double * s, double * u, lapack_int ldu, double * vt, lapack_int ldvt, lapack_int * superb);

lapack_int LAPACKE_cgesvdx (int matrix_layout, char jobu, char jobvt, char range, lapack_int m, lapack_int n, lapack_complex_float * a, lapack_int lda, float vl, float vu, lapack_int il, lapack_int iu, lapack_int * ns, float * s, lapack_complex_float * u, lapack_int ldu, lapack_complex_float * vt, lapack_int ldvt, lapack_int * superb);

lapack_int LAPACKE_zgesvdx (int matrix_layout, char jobu, char jobvt, char range, lapack_int m, lapack_int n, lapack_complex_double * a, lapack_int lda, double vl, double vu, lapack_int il, lapack_int iu, lapack_int * ns, double * s, lapack_complex_double * u, lapack_int ldu, lapack_complex_double * vt, lapack_int ldvt, lapack_int * superb);

Include Files

  • mkl.h

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

matrix_layout

Specifies whether matrix storage layout is row major (LAPACK_ROW_MAJOR) or column major (LAPACK_COL_MAJOR).

jobu

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

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

= '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

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

n

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

a

Array, size lda*n

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

lda

The leading dimension of the array a.

lda max(1,m).

vl

vl0.

vu

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

iu

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

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

ldvt

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

Output Parameters

a

On exit, the contents of a are destroyed.

ns

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

Array, size (min(m,n))

The singular values of A, sorted so that s[i]s[i + 1].

u

Array, size ldu*ucol

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

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.

superb

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.

Return Values

This function returns a value info.

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