gesvd

Computes the singular value decomposition of a general rectangular matrix.

Description

gesvd supports the following precisions.

T
float
double
std::complex<float>
std::complex<double>

gesvd (Buffer Version)

Description

The routine computes the singular value decomposition (SVD) of a real/complex \(m \times n\) matrix \(A\), optionally computing the left and/or right singular vectors. The SVD is written as

\(A = U\Sigma V^T\) for real routines

\(A = U\Sigma V^H\) for complex routines

where \(\Sigma\) is an \(m \times n\) diagonal matrix, \(U\) is an \(m \times m\) orthogonal/unitary matrix, and \(V\) is an \(n \times n\) orthogonal/unitary matrix. The diagonal elements of \(\Sigma\) 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\).

Syntax

namespace oneapi::mkl::lapack {
  void gesvd(sycl::queue &queue, oneapi::mkl::job jobu, oneapi::mkl::job jobvt, std::int64_t m, std::int64_t n, sycl::buffer<T,1> &a, std::int64_t lda, sycl::buffer<realT,1> &s, sycl::buffer<T,1> &u, std::int64_t ldu, sycl::buffer<T,1> &vt, std::int64_t ldvt, sycl::buffer<T,1> &scratchpad, std::int64_t scratchpad_size)
}

Input Parameters

queue

The queue where the routine should be executed.

jobu

Must be job::allvec, job::somevec, job::overwritevec, or job::novec. Specifies options for computing all or part of the matrix \(U\).

If jobu = job::allvec, all \(m\) columns of \(U\) are returned in the buffer u;

if jobu = job::somevec, the first \(\min(m, n)\) columns of \(U\) (the left singular vectors) are returned in the buffer u;

if jobu = job::overwritevec, the first \(\min(m, n)\) columns of \(U\) (the left singular vectors) are overwritten on the buffer a;

if jobu = job::novec, no columns of \(U\) (no left singular vectors) are computed.

jobvt

Must be job::allvec, job::somevec, job::overwritevec, or job::novec. Specifies options for computing all or part of the matrix \(V^T/V^H\).

If jobvt = job::allvec, all \(n\) columns of \(V^T/V^H\) are returned in the buffer vt;

if jobvt = job::somevec, the first \(\min(m, n)\) columns of \(V^T/V^H\) (the left singular vectors) are returned in the buffer vt;

if jobvt = job::overwritevec, the first \(\min(m, n)\) columns of \(V^T/V^H\) (the left singular vectors) are overwritten on the buffer a;

if jobvt = job::novec, no columns of \(V^T/V^H\) (no left singular vectors) are computed.

jobvt and jobu cannot both be job::overwritevec.

m

The number of rows in the matrix \(A\) (\(0 \le m\)).

a

The buffer a, size (lda,*). The buffer a contains the matrix \(A\). The second dimension of a must be at least \(\max(1, m)\).

lda

The leading dimension of a.

ldu

The leading dimension of u.

ldvt

The leading dimension of vt.

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 gesvd_scratchpad_size function.

Output Parameters

a

On exit,

If jobu = job::overwritevec, a is overwritten with the first \(\min(m,n)\) columns of \(U\) (the left singular vectors stored columnwise);

If jobvt = job::overwritevec, a is overwritten with the first \(\min(m, n)\) rows of \(V^{T}\)/\(V^{H}\) (the right singular vectors stored rowwise);

If jobu \(\ne\) job::overwritevec and jobvt \(\ne\) job::overwritevec, the contents of a are destroyed.

s

Buffer containing the singular values, size at least \(\max(1, \min(m,n))\). Contains the singular values of \(A\) sorted so that \(s(i) \ge s(i+1)\).

u

Buffer containing \(U\); the second dimension of u must be at least \(\max(1, m)\) if jobu = job::allvec, and at least \(\max(1, \min(m, n))\) if jobu = job::somevec.

If jobu = job::allvec, u contains the \(m \times 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 job::overwritevec, u is not referenced.

vt

Buffer containing \(V^{T}\); the second dimension of vt must be at least \(\max(1, n)\).

If jobvt = job::allvec, vt contains the \(n \times n\) orthogonal/unitary matrix \(V^{T}\)/\(V^{H}\).

If jobvt = job::somevec, vt contains the first \(\min(m, n)\) rows of \(V^{T}\)/\(V^{H}\) (the right singular vectors stored row-wise).

If jobvt = job::novec or job::overwritevec, vt is not referenced.

scratchpad

Buffer holding scratchpad memory to be used by routine for storing intermediate results.

gesvd (USM Version)

Description

The routine computes the singular value decomposition (SVD) of a real/complex \(m \times n\) matrix \(A\), optionally computing the left and/or right singular vectors. The SVD is written as

\(A = U\Sigma V^T\) for real routines

\(A = U\Sigma V^H\) for complex routines

where \(\Sigma\) is an \(m \times n\) diagonal matrix, \(U\) is an \(m \times m\) orthogonal/unitary matrix, and \(V\) is an \(n \times n\) orthogonal/unitary matrix. The diagonal elements of \(\Sigma\) 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\).

Syntax

namespace oneapi::mkl::lapack {
  sycl::event gesvd(sycl::queue &queue, oneapi::mkl::job jobu, oneapi::mkl::job 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 = {})
}

Input Parameters

queue

The queue where the routine should be executed.

jobu

Must be job::allvec, job::somevec, job::overwritevec, or job::novec. Specifies options for computing all or part of the matrix \(U\).

If jobu = job::allvec, 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 = job::overwritevec, 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 job::allvec, job::somevec, job::overwritevec, or job::novec. Specifies options for computing all or part of the matrix \(V^T/V^H\).

If jobvt = job::allvec, all \(n\) columns of \(V^T/V^H\) are returned in the array vt;

if jobvt = job::somevec, the first \(\min(m, n)\) columns of \(V^T/V^H\) (the left singular vectors) are returned in the array vt;

if jobvt = job::overwritevec, the first \(\min(m, n)\) columns of \(V^T/V^H\) (the left singular vectors) are overwritten on the array a;

if jobvt = job::novec, no columns of \(V^T/V^H\) (no left singular vectors) are computed.

jobvt and jobu cannot both be job::overwritevec.

m

The number of rows in the matrix \(A\) (\(0 \le m\)).

a

Pointer to array a, size (lda,*), containing the matrix \(A\). The second dimension of a must be at least \(\max(1, m)\).

lda

The leading dimension of a.

ldu

The leading dimension of u.

ldvt

The leading dimension of vt.

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 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 = job::overwritevec, a is overwritten with the first \(\min(m,n)\) columns of \(U\) (the left singular vectors stored columnwise);

If jobvt = job::overwritevec, a is overwritten with the first \(\min(m, n)\) rows of \(V^{T}\)/\(V^{H}\) (the right singular vectors stored rowwise);

If jobu \(\ne\) job::overwritevec and jobvt \(\ne\) job::overwritevec, 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) \ge s(i+1)\).

u

Array containing \(U\); the second dimension of u must be at least \(\max(1, m)\) if jobu = job::allvec, and at least \(\max(1, \min(m, n))\) if jobu = job::somevec.

If jobu = job::allvec, u contains the \(m \times 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 job::overwritevec, u is not referenced.

vt

Array containing \(V^{T}\); the second dimension of vt must be at least \(\max(1, n)\).

If jobvt = job::allvec, vt contains the \(n \times n\) orthogonal/unitary matrix \(V^{T}\)/\(V^{H}\).

If jobvt = job::somevec, vt contains the first \(\min(m, n)\) rows of \(V^{T}\)/\(V^{H}\) (the right singular vectors stored row-wise).

If jobvt = job::novec or job::overwritevec, vt is not referenced.

scratchpad

Pointer to scratchpad memory to be used by routine for storing intermediate results.

Return Values

Output event to wait on to ensure computation is complete.

Parent topic: LAPACK Singular Value and Eigenvalue Problem Routines