naginterfaces.library.lapackeig.zgesdd

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

zgesdd computes the singular value decomposition (SVD) of a complex $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 f08kr

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08krf.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^H$ 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^H$ 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^H$ are returned in the array $vt$. Otherwise, all columns of $U$ are returned in the array $u$ and the first $m$ rows of $V^H$ are overwritten in the array $vt$.

$jobz=\text{'N'}$

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

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

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

Returns

acomplex, 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^H$ (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]$.

ucomplex, ndarray, shape $(:,:)$

If $jobz=\text{'A'}$ or $jobz=\text{'O'}$ and $m<n$, $u$ contains the $m\times m$ unitary 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.

vtcomplex, ndarray, shape $(:,:)$

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

If $jobz=\text{'S'}$, $vt$ contains the first $min(m,n)$ rows of $V^H$ (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$)

zgesdd did not converge, the updating process failed.

Notes

The SVD is written as

$$A=U\Sigma V^H\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$ unitary matrix, and $V$ is an $n\times n$ 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$.

Note that the function returns $V^H$, 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