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 routinesA = 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 {
sycl::event gesvd(sycl::queue &queue,
mkl::jobsvd jobu,
mkl::jobsvd jobvt,
int64_t m,
int64_t n,
T *a,
int64_t lda,
RealT *s,
T *u,
int64_t ldu,
T *vt,
int64_t ldvt,
T *scratchpad,
int64_t scratchpad_size,
const std::vector<sycl::event> &events = {})
}
gesvd (USM version) supports the following precision and
devices.
T |
Devices Supported |
|---|---|
|
CPU |
|
CPU |
|
CPU |
|
CPU |
Input Parameters#
- queue
Device queue where calculations will be performed.
- jobu
Must be
jobsvd::vectors,job::somevec,jobsvd::vectorsina, orjob::novec. Specifies options for computing all or part of the matrixU.If
jobu = jobsvd::vectors, allmcolumns ofUare returned in the array u;if
jobu = job::somevec, the firstmin(m, n)columns ofU(the left singular vectors) are returned in the array u;if
jobu = jobsvd::vectorsina, the firstmin(m, n)columns ofU(the left singular vectors) are overwritten on the array a;if
jobu = job::novec, no columns ofU(no left singular vectors) are computed.- jobvt
Must be
jobsvd::vectors, job::somevec,jobsvd::vectorsina, orjob::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 firstmin(m, n)columns of VT/VH (the left singular vectors) are returned in the array vt;if
jobvt = jobsvd::vectorsina, the firstmin(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 the memory holding the input matrix
A. The memory must have size at leastlda*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 firstmin(m,n)columns ofU(the left singular vectors stored columnwise);If
jobvt = jobsvd::vectorsina, a is overwritten with the firstmin(m, n)rows ofVT/VH (the right singular vectors stored rowwise);If
jobu ≠ jobsvd::vectorsinaandjobvt ≠ 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 ofAsorted so thats(i) ≥ s(i+1).- u
Array containing
U; the size of the array must be at leastldu*mifjobu = jobsvd::vectors, and at leastldu*min(m, n)ifjobu = job::somevec.If
jobu = jobsvd::vectors, u contains the m-by-m orthogonal/unitary matrixU.If
jobu = job::somevec, u contains the firstmin(m, n)columns ofU(the left singular vectors stored column-wise).If
jobu = job::novecorjobsvd::vectorsina, u is not referenced.- vt
Array containing
VT; the size ofvtmust be at leastldvt*n.If
jobvt = jobsvd::vectors, vt contains the n-by-n orthogonal/unitary matrixVT/VH.If
jobvt = job::somevec, vt contains the firstmin(m, n)rows ofVT/VH (the right singular vectors stored row-wise).If
jobvt = job::novecorjobsvd::vectorsina, vt is not referenced.
Exceptions#
Exception |
Description |
|---|---|
|
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 If If |
Return Values#
Output event to wait on to ensure computation is complete.