Developer Reference for Intel® oneAPI Math Kernel Library for C
?gesvdx
Computes the SVD and left and right singular vectors for a matrix.
Syntax
lapack_intLAPACKE_sgesvdx ( intmatrix_layout , charjobu , charjobvt , charrange , lapack_intm , lapack_intn , float*a , lapack_intlda , floatvl , floatvu , lapack_intil , lapack_intiu , lapack_int*ns , float*s , float*u , lapack_intldu , float*vt , lapack_intldvt , lapack_int*superb );
lapack_intLAPACKE_dgesvdx ( intmatrix_layout , charjobu , charjobvt , charrange , lapack_intm , lapack_intn , double*a , lapack_intlda , doublevl , doublevu , lapack_intil , lapack_intiu , lapack_int*ns , double*s , double*u , lapack_intldu , double*vt , lapack_intldvt , lapack_int*superb );
lapack_intLAPACKE_cgesvdx ( intmatrix_layout , charjobu , charjobvt , charrange , lapack_intm , lapack_intn , lapack_complex_float*a , lapack_intlda , floatvl , floatvu , lapack_intil , lapack_intiu , lapack_int*ns , float*s , lapack_complex_float*u , lapack_intldu , lapack_complex_float*vt , lapack_intldvt , lapack_int*superb );
lapack_intLAPACKE_zgesvdx ( intmatrix_layout , charjobu , charjobvt , charrange , lapack_intm , lapack_intn , lapack_complex_double*a , lapack_intlda , doublevl , doublevu , lapack_intil , lapack_intiu , lapack_int*ns , double*s , lapack_complex_double*u , lapack_intldu , lapack_complex_double*vt , lapack_intldvt , 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 (Computes the SVD of a bidiagonal matrix.) 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
-
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
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 zgesvdxvl ≥ 0.
- 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
iu
If range =’I’, the indices (in ascending order) of the smallest and largest singular values to be returned. 1 ≤ il ≤ iu ≤ 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’, ldu ≥ m .
ldvt
The leading dimension of the array vt . ldvt ≥ 1; if jobvt = ‘V’, ldvt ≥ ns (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
The size of the array work .
lwork ≥ max(1, min( m , n )*(min( m , n ) + 4)) for the paths (see comments inside the code): 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
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] ≥ s(i + 1)s[i + 1] .
- u
-
REAL for sgesvdx DOUBLE PRECISION for dgesvdx COMPLEX for cgesvdx DOUBLE COMPLEX for zgesvdx
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.
- 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.
iworksuperb
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 .