Developer Reference for Intel® oneAPI Math Kernel Library for C
?gesvd
Computes the singular value decomposition of a general rectangular matrix.
Syntax
lapack_int LAPACKE_sgesvd ( intmatrix_layout , charjobu , charjobvt , lapack_intm , lapack_intn , float*a , lapack_intlda , float*s , float*u , lapack_intldu , float*vt , lapack_intldvt , float*superb );
lapack_int LAPACKE_dgesvd ( intmatrix_layout , charjobu , charjobvt , lapack_intm , lapack_intn , double*a , lapack_intlda , double*s , double*u , lapack_intldu , double*vt , lapack_intldvt , double*superb );
lapack_int LAPACKE_cgesvd ( intmatrix_layout , charjobu , charjobvt , lapack_intm , lapack_intn , lapack_complex_float*a , lapack_intlda , float*s , lapack_complex_float*u , lapack_intldu , lapack_complex_float*vt , lapack_intldvt , float*superb );
lapack_int LAPACKE_zgesvd ( intmatrix_layout , charjobu , charjobvt , lapack_intm , lapack_intn , lapack_complex_double*a , lapack_intlda , double*s , lapack_complex_double*u , lapack_intldu , lapack_complex_double*vt , lapack_intldvt , double*superb );
Include Files
mkl.h
Description
sgesvd dgesvd cgesvd zgesvd gesvd
The 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 as
A = U*Σ*V^{T} for real routines
A = U*Σ*V^{H} for complex routines
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 .
The routine returns V:code:`T` (for real flavors) or V:code:`H` (for complex flavors), not V .
Input Parameters
- matrix_layout
-
Specifies whether matrix storage layout is row major ( LAPACK_ROW_MAJOR ) or column major ( LAPACK_COL_MAJOR ).
jobu
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
Must be ‘A’ , ‘S’ , ‘O’ , or ‘N’ . Specifies options for computing all or part of the matrix V:code:`T` / V:code:`H` .
If jobvt = 'A' , all n rows of V:code:`T` / V:code:`H` are returned in the array vt ; if jobvt = 'S' , the first min( m , n ) rows of V:code:`T` / V:code:`H` (the right singular vectors) are returned in the array vt ; if jobvt = 'O' , the first min( m , n ) rows of V:code:`T` / V:code:`H` ) (the right singular vectors) are overwritten on the array a ; if jobvt = 'N' , no rows of V:code:`T` / V:code:`H` (no right singular vectors) are computed. jobvt and jobu cannot both be ‘O’ .
m
The number of rows of the matrix A ( m≥ 0 ).
n
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 (size at least max(1, lda * n ) for column major layout and max(1, lda * m ) for row major layout) 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
The leading dimension of the array a .
Must be at least max(1, m ) for column major layout and at least max(1, n ) for row major layout .
ldu , ldvt
The leading dimensions of the output arrays u and vt , respectively.
Constraints: ldu≥ 1; ldvt≥ 1 .
If jobu = 'A' , ldu≥m ;
If jobu = 'S' , ldu≥m for column major layout and ldu ≥ min( m , n ) for row major layout; If jobvt = 'A' , ldvt≥n ;
If jobvt = 'S' , ldvt≥ min ( m , n ) for column major layout and ldvt ≥ n for row major layout .
lwork
The dimension of the array work . Constraints: lwork≥ 1lwork≥ 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, size 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 V:code:`T` / V:code:`H` (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, size at least max(1, min( m , n )). Contains the singular values of A sorted so that s(i) ≥ s(i+1)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' . Array u minimum size: Column major layout Row major layout jobu = 'A' max(1, ldu * m ) max(1, ldu * m ) jobu = 'S' max(1, ldu *min( m , n )) max(1, ldu * m ) 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 column-wise). If jobu = 'N' or ‘O’ , u is not referenced. vt ( ldvt ,*); the second dimension of vt must be at least max(1, n ). Array v minimum size: Column major layout Row major layout jobvt = 'A' max(1, ldvt * n ) max(1, ldvt * n ) jobvt = 'S' max(1, ldvt *min( m , n )) max(1, ldvt * n ) If jobvt = 'A' , vt contains the n -by- n orthogonal/unitary matrix V:code:`T` / V:code:`H` . If jobvt = 'S' , vt contains the first min( m , n ) rows of V:code:`T` / V:code:`H` (the right singular vectors stored row-wise). 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 .
- superb
-
If ?bdsqr does not converge (indicated by the return value info > 0 ), on exit superb(0:min(m,n)-2) contains the unconverged superdiagonal elements of an upper bidiagonal matrix B whose diagonal is in s (not necessarily sorted). B satisfies A = u*B*V^{T} (real flavors) or A = u*B*V^{H} (complex flavors), so it has the same singular values as A , and singular vectors related by u and vt .
Return Values
This function returns a value info .
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 (see the description of the superb parameter for details).
LAPACK 95 Interface Notes
There exist FORTRAN 77 and FORTRAN 95 interfaces for this routine. See the Intel® oneMKL Fortran Developer Reference for details.
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.