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*Σ*VTfor real routines
- A = U*Σ*VHfor 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 {
cl::sycl::event gesvd(cl::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<cl::sycl::event> &events = {})
}
gesvd
(USM version) supports the following precision and
devices.T | Devices Supported |
---|---|
float | Host and CPU |
double | Host and CPU |
std::complex<float> | Host and CPU |
std::complex<double> | Host and CPU |
Input Parameters
- queue
- Device queue where calculations will be performed.
- jobu
- Must bejobsvd::vectors,job::somevec,jobsvd::vectorsina, orjob::novec. Specifies options for computing all or part of the matrixU.Ifjobu = jobsvd::vectors, allmcolumns ofUare returned in the array u;ifjobu = job::somevec, the firstmin(m, n)columns ofU(the left singular vectors) are returned in the array u;ifjobu = jobsvd::vectorsina, the firstmin(m, n)columns ofU(the left singular vectors) are overwritten on the array a;ifjobu = job::novec, no columns ofU(no left singular vectors) are computed.
- jobvt
- Must bejobsvd::vectors, job::somevec,jobsvd::vectorsina, orjob::novec. Specifies options for computing all or part of the matrixVT/VH.Ifjobvt = jobsvd::vectors, all n columns ofVT/VHare returned in the array vt;ifjobvt = job::somevec, the firstmin(m, n)columns ofVT/VH(the left singular vectors) are returned in the array vt;ifjobvt = jobsvd::vectorsina, the firstmin(m, n)columns ofVT/VH(the left singular vectors) are overwritten on the array a;ifjobvt = job::novec, no columns ofVT/VH(no left singular vectors) are computed.jobvt and jobu cannot both bejobsvd::vectorsina.
- m
- The number of rows in the matrixA(0≤m).
- n
- The number of columns in the matrixA(0≤n).
- a
- Pointer to array a, size(lda,*). The second dimension ofamust be at leastmax(1, m).
- 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 typeT. 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,Ifjobu = jobsvd::vectorsina, a is overwritten with the firstmin(m,n)columns ofU(the left singular vectors stored columnwise);Ifjobvt = jobsvd::vectorsina, a is overwritten with the firstmin(m, n)rows ofVT/VH(the right singular vectors stored rowwise);Ifjobu ≠ jobsvd::vectorsinaandjobvt ≠ jobsvd::vectorsina, the contents of a are destroyed.
- s
- Array containing the singular values, size at leastmax(1, min(m,n)). Contains the singular values ofAsorted so thats(i) ≥ s(i+1).
- u
- Array containingU; the second dimension of u must be at leastmax(1, m)ifjobu = jobsvd::vectors, and at leastmax(1, min(m, n))ifjobu = job::somevec.Ifjobu = jobsvd::vectors, u contains the m-by-m orthogonal/unitary matrixU.Ifjobu = job::somevec, u contains the firstmin(m, n)columns ofU(the left singular vectors stored column-wise).Ifjobu = job::novecorjobsvd::vectorsina, u is not referenced.
- vt
- Array containingVT; the second dimension of vt must be at leastmax(1, n).Ifjobvt = jobsvd::vectors, vt contains the n-by-n orthogonal/unitary matrixVT/VH.Ifjobvt = job::somevec, vt contains the firstmin(m, n)rows ofVT/VH(the right singular vectors stored row-wise).Ifjobvt = job::novecorjobsvd::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 V T .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.