naginterfaces.library.lapackeig.dgesdd

naginterfaces.library.lapackeig.dgesdd(jobz, a)

dgesdd computes the singular value decomposition (SVD) of a real $m\times n$ matrix $A$, optionally computing the left and/or right singular vectors, by using a divide-and-conquer method.

For full information please refer to the NAG Library document for f08kd

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08kdf.html

Parameters

jobzstr, length 1

Specifies options for computing all or part of the matrix $U$.

$jobz=\text{'A'}$

All $m$ columns of $U$ and all $n$ rows of $V^T$ are returned in the arrays $u$ and $vt$.

$jobz=\text{'S'}$

The first $min(m,n)$ columns of $U$ and the first $min(m,n)$ rows of $V^T$ are returned in the arrays $u$ and $vt$.

$jobz=\text{'O'}$

If $m\ge n$, the first $n$ columns of $U$ are overwritten on the array $a$ and all rows of $V^T$ are returned in the array $vt$. Otherwise, all columns of $U$ are returned in the array $u$ and the first $m$ rows of $V^T$ are overwritten in the array $vt$.

$jobz=\text{'N'}$

No columns of $U$ or rows of $V^T$ are computed.

afloat, array-like, shape $(m,n)$

The $m\times n$ matrix $A$.

Returns

afloat, ndarray, shape $(m,n)$

If $jobz=\text{'O'}$, $a$ is overwritten with the first $n$ columns of $U$ (the left singular vectors, stored column-wise) if $m\ge n$; $a$ is overwritten with the first $m$ rows of $V^T$ (the right singular vectors, stored row-wise) otherwise.

If $jobz\ne \text{'O'}$, the contents of $a$ are destroyed.

sfloat, ndarray, shape $(min(m,n))$

The singular values of $A$, sorted so that $s[i-1]\ge s\left[i\right]$.

ufloat, ndarray, shape $(:,:)$

If $jobz=\text{'A'}$ or $jobz=\text{'O'}$ and $m<n$, $u$ contains the $m\times m$ orthogonal matrix $U$.

If $jobz=\text{'S'}$, $u$ contains the first $min(m,n)$ columns of $U$ (the left singular vectors, stored column-wise).

If $jobz=\text{'O'}$ and $m\ge n$, or $jobz=\text{'N'}$, $u$ is not referenced.

vtfloat, ndarray, shape $(:,:)$

If $jobz=\text{'A'}$ or $jobz=\text{'O'}$ and $m\ge n$, $vt$ contains the $n\times n$ orthogonal matrix $V^T$.

If $jobz=\text{'S'}$, $vt$ contains the first $min(m,n)$ rows of $V^T$ (the right singular vectors, stored row-wise).

If $jobz=\text{'O'}$ and $m<n$, or $jobz=\text{'N'}$, $vt$ is not referenced.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $jobz$.

Constraint: $jobz=\text{'A'}$, $\text{'S'}$, $\text{'O'}$ or $\text{'N'}$.

(errno $-2$)

On entry, error in parameter $\text{m}$.

Constraint: $m\ge 0$.

(errno $-3$)

On entry, error in parameter $\text{n}$.

Constraint: $n\ge 0$.

(errno $i>0$)

dgesdd did not converge, the updating process failed.

Notes

The SVD is written as

$$A=U\Sigma V^T\text{,}$$

where $\Sigma$ is an $m\times n$ matrix which is zero except for its $min(m,n)$ diagonal elements, $U$ is an $m\times m$ orthogonal matrix, and $V$ is an $n\times n$ orthogonal 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$.

Note that the function returns $V^T$, not $V$.

References

Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, LAPACK Users’ Guide, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore