naginterfaces.library.lapackeig.zgesvd

naginterfaces.library.lapackeig.zgesvd(jobu, jobvt, a)

zgesvd computes the singular value decomposition (SVD) of a complex $m\times n$ matrix $A$, optionally computing the left and/or right singular vectors.

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

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

Parameters

jobustr, length 1

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

$jobu=\text{'A'}$

All $m$ columns of $U$ are returned in array $u$.

$jobu=\text{'S'}$

The first $min(m,n)$ columns of $U$ (the left singular vectors) are returned in the array $u$.

$jobu=\text{'O'}$

The first $min(m,n)$ columns of $U$ (the left singular vectors) are overwritten on the array $a$.

$jobu=\text{'N'}$

No columns of $U$ (no left singular vectors) are computed.

jobvtstr, length 1

Specifies options for computing all or part of the matrix $V^H$.

$jobvt=\text{'A'}$

All $n$ rows of $V^H$ are returned in the array $vt$.

$jobvt=\text{'S'}$

The first $min(m,n)$ rows of $V^H$ (the right singular vectors) are returned in the array $vt$.

$jobvt=\text{'O'}$

The first $min(m,n)$ rows of $V^H$ (the right singular vectors) are overwritten on the array $a$.

$jobvt=\text{'N'}$

No rows of $V^H$ (no right singular vectors) are computed.

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

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

Returns

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

If $jobu=\text{'O'}$, $a$ is overwritten with the first $min(m,n)$ columns of $U$ (the left singular vectors, stored column-wise).

If $jobvt=\text{'O'}$, $a$ is overwritten with the first $min(m,n)$ rows of $V^H$ (the right singular vectors, stored row-wise).

If $jobu\ne \text{'O'}$ and $jobvt\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 $jobu=\text{'A'}$, $u$ contains the $m\times m$ unitary matrix $U$.

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

If $jobu=\text{'N'}$ or $\text{'O'}$, $u$ is not referenced.

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

If $jobvt=\text{'A'}$, $vt$ contains the $n\times n$ unitary matrix $V^H$.

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

If $jobvt=\text{'N'}$ or $\text{'O'}$, $vt$ is not referenced.

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

If $errno$ > 0, $rworkb[0:min(m,n)-1]$ contains the unconverged superdiagonal elements of an upper bidiagonal matrix $B$ whose diagonal is in $S$ (not necessarily sorted). $B$ satisfies $A=UB{V}^T$, so it has the same singular values as $A$, and singular vectors related by $U$ and $V^T$.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $jobu$.

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

(errno $-2$)

On entry, error in parameter $jobvt$.

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

(errno $-2$)

On entry, error in parameter $jobvt$.

Constraint: $jobvt\ne \text{'O'}$ or $jobu\ne \text{'O'}$.

(errno $-3$)

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

Constraint: $m\ge 0$.

(errno $-4$)

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

Constraint: $n\ge 0$.

(errno $i>0$)

If zgesvd did not converge, $\text{errno}$ specifies how many superdiagonals of an intermediate bidiagonal form did not converge to zero.

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