naginterfaces.library.lapackeig.dbdsvdx

naginterfaces.library.lapackeig.dbdsvdx(uplo, jobz, erange, d, e, vl, vu, il, iu)

dbdsvdx computes all or selected singular values and, optionally, the corresponding left and right singular vectors of a real $n\times n$ (upper or lower) bidiagonal matrix $B$.

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

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

Parameters

uplostr, length 1

Indicates whether $B$ is upper or lower bidiagonal.

$uplo=\text{'U'}$

$B$ is upper bidiagonal.

$uplo=\text{'L'}$

$B$ is lower bidiagonal.

jobzstr, length 1

Indicates whether singular vectors are computed.

$jobz=\text{'N'}$

Only singular values are computed.

$jobz=\text{'V'}$

Singular values and 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.

dfloat, array-like, shape $\left(n\right)$

The diagonal elements $d$ of the bidiagonal matrix $B$.

efloat, array-like, shape $(n-1)$

The $(n-1)$ off-diagonal elements $e$ of the bidiagonal matrix $B$.

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

nsint

The total number of singular values found. $0\le ns\le n$.

If $erange=\text{'A'}$, $ns=n$.

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

sfloat, ndarray, shape $\left(n\right)$

The first $ns$ elements contain the selected singular values in ascending order.

zfloat, ndarray, shape $(:,:)$

If $jobz=\text{'V'}$, then if $\text{errno}=0$ the first $ns$ columns of $z$ contain the singular vectors of the matrix $B$ corresponding to the selected singular values, with $U$ in rows $1$ to $n$ and $V$ in rows $n+1$ to $n\times 2$.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $uplo$.

Constraint: $uplo=\text{'U'}$ or $\text{'L'}$.

(errno $-2$)

On entry, error in parameter $jobz$.

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

(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{n}$.

Constraint: $n\ge 0$.

(errno $-7$)

On entry, error in parameter $vl$.

Constraint: $0.0\le vl$.

(errno $-8$)

On entry, error in parameter $vu$.

Constraint: $vl<vu$.

(errno $-9$)

On entry, error in parameter $il$.

(errno $-10$)

On entry, error in parameter $iu$.

(errno $i>0$)

The algorithm failed to converge; $⟨value⟩$ eigenvectors of the associated eigenproblem did not converge. Their indices are stored in array $\text{iwork}$.

Notes

dbdsvdx computes the singular value decomposition (SVD) of a real $n\times n$ (upper or lower) bidiagonal matrix $B$ as

$$B=US{V}^T\text{,}$$

where $S$ is a diagonal matrix with non-negative diagonal elements (the singular values of $B$), and $U$ and $V^T$ are orthogonal matrices. The columns of $U$ and $V$ are the left and right singular vectors of $B$, respectively.

Given an upper bidiagonal matrix $B$ with diagonal $d=\left(\begin{array}{cccc}{d}_1& d_2& \dots & d_n\end{array}\right)$ and superdiagonal $e=\left(\begin{array}{cccc}{e}_1& e_2& \dots & e_{N-1}\end{array}\right)$, dbdsvdx computes the singular value decomposition of $B$ through the eigenvalues and eigenvectors of the $(n\times 2)\times (n\times 2)$ tridiagonal matrix

$$\begin{array}{c}\text{TGK}=\left(\begin{array}{cccccc}0& d_1& & & & \\ d_1& 0& e_1& & & \\ & e_1& 0& d_2& & \\ & & d_2& .& .& \\ & & & .& .& \end{array}\right)\text{.}\end{array}$$

If $(s,u,v)$ is a singular triplet of $B$ with $\parallel u\parallel =\parallel v\parallel =1$, then $(s,q_1)$ and $(-s,q_2)$, $\parallel q_1\parallel =\parallel q_2\parallel =1$, are eigenpairs of $\text{TGK}$, with $q_1=(v_1,u_1,v_2,u_2,\dots ,v_n,u_n)/\sqrt{2}$, and $q_2=({-v}_1,u_1,{-v}_2,u_2,\dots ,{-v}_n,u_n)/\sqrt{2}$.

Given a $\text{TGK}$ matrix, you can either

1. compute $-s,-v$ and change signs so that the singular values (and corresponding vectors) are already in descending order (as in dgesvd()) or

2. compute $s,v$ and reorder the values (and corresponding vectors).

dbdsvdx implements (i) by calling dstevx() (bisection plus inverse iteration, to be replaced with a version of the Multiple Relative Robust Representation algorithm. (See Williams and Lang (2013).)

Alternative to computing all singular values of $B$, 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

Williams, P and Lang, B, 2013, A framework for the $M{R}^3$ Algorithm: theory and implementation, SIAM J. Sci. Comput. (35), 740–766