A newer version of this document is available. Customers should click here to go to the newest version.
gesvd (USM Version)
Computes the singular value decomposition of a general rectangular matrix. This routine belongs to the oneapi::mkl::lapack namespace.
Description
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*Σ*VT for real routines
A = U*Σ*VH for complex routines
where Σ is an m-by-n diagonal matrix, 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.
API
Syntax
namespace oneapi::mkl::lapack {
sycl::event gesvd(sycl::queue &queue,
mkl::jobsvd jobu,
mkl::jobsvd jobvt,
std::int64_t m,
std::int64_t n,
T *a,
std::int64_t lda,
RealT *s,
T *u,
std::int64_t ldu,
T *vt,
std::int64_t ldvt,
T *scratchpad,
std::int64_t scratchpad_size,
const std::vector<sycl::event> &events = {})
}
gesvd (USM version) supports the following precision and devices.
T |
Devices Supported |
|---|---|
float |
CPU |
double |
CPU |
std::complex<float> |
CPU |
std::complex<double> |
CPU |
Input Parameters
- queue
-
Device queue where calculations will be performed.
- jobu
-
Must be jobsvd::vectors, job::somevec, jobsvd::vectorsina, or job::novec. Specifies options for computing all or part of the matrix U.
If jobu = jobsvd::vectors, all m columns of U are returned in the array u;
if jobu = job::somevec, the first min(m, n) columns of U (the left singular vectors) are returned in the array u;
if jobu = jobsvd::vectorsina, the first min(m, n) columns of U (the left singular vectors) are overwritten on the array a;
if jobu = job::novec, no columns of U (no left singular vectors) are computed.
- jobvt
-
Must be jobsvd::vectors, job::somevec, jobsvd::vectorsina, or job::novec. Specifies options for computing all or part of the matrix VT/VH.
If jobvt = jobsvd::vectors, all n columns of VT/VH are returned in the array vt;
if jobvt = job::somevec, the first min(m, n) columns of VT/VH (the left singular vectors) are returned in the array vt;
if jobvt = jobsvd::vectorsina, the first min(m, n) columns of VT/VH (the left singular vectors) are overwritten on the array a;
if jobvt = job::novec, no columns of VT/VH (no left singular vectors) are computed.
jobvt and jobu cannot both be jobsvd::vectorsina.
- m
-
The number of rows in the matrix A (0 ≤ m).
- n
-
The number of columns in the matrix A (0 ≤ n).
- a
-
Pointer to array a, size (lda,*). The second dimension of a must be at least max(1, n).
- lda
-
The leading dimension of a.
- ldu
-
The leading dimension of u.
- ldvt
-
The leading dimension of vt.
- scratchpad
-
Pointer to scratchpad memory to be used by the routine for storing intermediate results.
- scratchpad_size
-
Size of scratchpad memory as a number of floating point elements of type T. Size should not be less than the value returned by the gesvd_scratchpad_size function.
- events
-
List of events to wait for before starting computation. Defaults to empty list.
Output Parameters
- a
-
On exit,
If jobu = jobsvd::vectorsina, a is overwritten with the first min(m,n) columns of U (the left singular vectors stored columnwise);
If jobvt = jobsvd::vectorsina, a is overwritten with the first min(m, n) rows of VT/VH (the right singular vectors stored rowwise);
If jobu ≠ jobsvd::vectorsina and jobvt ≠ jobsvd::vectorsina, the contents of a are destroyed.
- s
-
Array containing the singular values, size at least max(1, min(m,n)). Contains the singular values of A sorted so that s(i) ≥ s(i+1).
- u
-
Array containing U; the second dimension of u must be at least max(1, m) if jobu = jobsvd::vectors, and at least max(1, min(m, n)) if jobu = job::somevec.
If jobu = jobsvd::vectors, u contains the m-by-m orthogonal/unitary matrix U.
If jobu = job::somevec, u contains the first min(m, n) columns of U (the left singular vectors stored column-wise).
If jobu = job::novec or jobsvd::vectorsina, u is not referenced.
- vt
-
Array containing VT; the second dimension of vt must be at least max(1, n).
If jobvt = jobsvd::vectors, vt contains the n-by-n orthogonal/unitary matrix VT/VH.
If jobvt = job::somevec, vt contains the first min(m, n) rows of VT/VH (the right singular vectors stored row-wise).
If jobvt = job::novec or jobsvd::vectorsina, vt is not referenced.
Exceptions
Exception |
Description |
|---|---|
mkl::lapack::exception |
This exception is thrown when problems occur during calculations. You can obtain the info code of the problem using the get_info() method of the exception object: 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, and scratchpad(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. If info is equal to the value passed as scratchpad size, and get_detail() returns non zero, then the passed scratchpad has an insufficient size, and the required size should not be less than the value returned by the get_detail() method of the exception object. |
Return Values
Output event to wait on to ensure computation is complete.