# 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.

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.

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.

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.