naginterfaces.library.lapackeig.dgesvdx

naginterfaces.library.lapackeig.dgesvdx(jobu, jobvt, erange, a, vl, vu, il, iu)

dgesvdx computes the singular value decomposition (SVD) of a real $m\times n$ matrix $A$, optionally computing the left and/or right singular vectors. All singular values or a selected set of singular values may be computed.

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

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

Parameters

jobustr, length 1

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

$jobu=\text{'V'}$

The $ns$ columns of $U$, as specified by $erange$, are returned in array $u$.

$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^T$.

$jobvt=\text{'V'}$

The $ns$ rows of $V^T$, as specified by $erange$, are returned in the array $vt$.

$jobvt=\text{'N'}$

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

erangestr, length 1

Indicates which singular values should be returned.

$erange=\text{'A'}$

All singular values will be found.

$erange=\text{'V'}$

All singular values in the half-open interval $(vl,vu]$ will be found.

$erange=\text{'I'}$

The $il$th through $iu$th singular values will be found.

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

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

vlfloat

If $erange=\text{'V'}$, the lower bound of the interval to be searched for singular values.

If $erange=\text{'A'}$ or $\text{'I'}$, $vl$ is not referenced.

vufloat

If $erange=\text{'V'}$, the upper bound of the interval to be searched for singular values.

If $erange=\text{'A'}$ or $\text{'I'}$, $vu$ is not referenced.

ilint

If $erange=\text{'I'}$, $il$ and $iu$ specify the indices (in ascending order) of the smallest and largest singular values to be returned, respectively.

If $erange=\text{'A'}$ or $\text{'V'}$, $il$ and $iu$ are not referenced.

iuint

If $erange=\text{'I'}$, $il$ and $iu$ specify the indices (in ascending order) of the smallest and largest singular values to be returned, respectively.

If $erange=\text{'A'}$ or $\text{'V'}$, $il$ and $iu$ are not referenced.

Returns

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

If $jobu\ne \text{'N'}$ and $jobvt\ne \text{'N'}$, the contents of $a$ are destroyed.

nsint

The total number of singular values found. $0\le ns\le min(m,n)$.

If $erange=\text{'A'}$, $ns=min(m,n)$.

If $erange=\text{'I'}$, $ns=iu-il+1$.

If $erange=\text{'V'}$ then the value of $ns$ is not known in advance and so an upper limit should be used when specifying the dimensions of array $u$, e.g., $min(m,n)$.

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

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

uNone or float, ndarray, shape $(:,:)$

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

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

vtNone or float, ndarray, shape $(:,:)$

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

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

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

If $errno$ > 0, $workb[1:min(m,n)]$ 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$.

jfailint, ndarray, shape $(2\times min(m,n))$

If $errno$ > 0, $jfail$ contains, in its first $k$ nonzero elements, the indices of the $k$ eigenvectors (associated with a left or right singular vector, see dbdsvdx()) that failed to converge.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $jobu$.

Constraint: $jobu=\text{'V'}$ or $\text{'N'}$.

(errno $-2$)

On entry, error in parameter $jobvt$.

Constraint: $jobvt=\text{'V'}$ or $\text{'N'}$.

(errno $-3$)

On entry, error in parameter $erange$.

Constraint: $erange=\text{'A'}$, $\text{'V'}$ or $\text{'I'}$.

(errno $-4$)

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

Constraint: $m\ge 0$.

(errno $-5$)

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

Constraint: $n\ge 0$.

(errno $-8$)

On entry, error in parameter $vl$.

Constraint: $0.0\le vl$.

(errno $-9$)

On entry, error in parameter $vu$.

Constraint: $vl<vu$.

(errno $-10$)

On entry, error in parameter $il$.

(errno $-11$)

On entry, error in parameter $iu$.

(errno $i>0$)

If dgesvdx 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^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$, respectively.

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

Alternative to computing all singular values of $A$, a selected set can be computed. The set is either those singular values lying in a given interval, $\sigma \in (v_l,v_u]$, or those whose index (counting from largest to smallest in magnitude) lies in a given range $1\le i_l,\dots ,i_u\le n$. In these cases, the corresponding left and right singular vectors can optionally be computed.

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