naginterfaces.library.lapackeig.dbdsdc

naginterfaces.library.lapackeig.dbdsdc(uplo, compq, d, e)

dbdsdc computes the singular values and, optionally, the 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 f08md

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/f08/f08mdf.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.

compqstr, length 1

Specifies whether singular vectors are to be computed.

$compq=\text{'N'}$

Compute singular values only.

$compq=\text{'P'}$

Compute singular values and compute singular vectors in compact form.

$compq=\text{'I'}$

Compute singular values and singular vectors.

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

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

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

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

Returns

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

If no exception or warning is raised, the singular values of $B$.

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

If $compq=\text{'I'}$, then if no exception or warning is raised, $u$ contains the left singular vectors of the bidiagonal matrix $B$.

If $compq\ne \text{'I'}$, $u$ is not referenced.

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

If $compq=\text{'I'}$, then if no exception or warning is raised, the rows of $vt$ contain the right singular vectors of the bidiagonal matrix $B$.

If $compq\ne \text{'I'}$, $vt$ is not referenced.

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

If $compq=\text{'P'}$, then if no exception or warning is raised, $q$ and $iq$ contain the left and right singular vectors in a compact form, requiring $O\left(nlog2\left(n\right)\right)$ space instead of $2\times n^2$. In particular, $q$ contains all the real data in the first $\text{ldq}=n\times (11+2\times \text{smlsiz}+8\times int\left(log2\left(n/(\text{smlsiz}+1)\right)\right))$ elements of $q$, where $\text{smlsiz}$ is equal to the maximum size of the subproblems at the bottom of the computation tree (usually about $25$).

If $compq\ne \text{'P'}$, $q$ is not referenced.

iqNone or int, ndarray, shape $(:)$

If $compq=\text{'P'}$, then if no exception or warning is raised, $q$ and $iq$ contain the left and right singular vectors in a compact form, requiring $O\left(nlog2\left(n\right)\right)$ space instead of $2\times n^2$. In particular, $iq$ contains all integer data in the first $\text{ldiq}=n\times (3+3\times int\left(log2\left(n/(\text{smlsiz}+1)\right)\right))$ elements of $iq$, where $\text{smlsiz}$ is equal to the maximum size of the subproblems at the bottom of the computation tree (usually about $25$).

If $compq\ne \text{'P'}$, $iq$ is not referenced.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $uplo$.

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

(errno $-2$)

On entry, error in parameter $compq$.

Constraint: $compq=\text{'N'}$, $\text{'P'}$ or $\text{'I'}$.

(errno $-3$)

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

Constraint: $n\ge 0$.

(errno $i>0$)

The algorithm failed to compute a singular value. The update process of divide-and-conquer failed.

Notes

dbdsdc computes the singular value decomposition (SVD) of the (upper or lower) bidiagonal matrix $B$ as

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

where $S$ is a diagonal matrix with non-negative diagonal elements $s_{ii}=s_i$, such that

$$s_1\ge s_2\ge \cdots \ge s_n\ge 0\text{,}$$

and $U$ and $V$ are orthogonal matrices. The diagonal elements of $S$ are the singular values of $B$ and the columns of $U$ and $V$ are respectively the corresponding left and right singular vectors of $B$.

When only singular values are required the function uses the $QR$ algorithm, but when singular vectors are required a divide and conquer method is used. The singular values can optionally be returned in compact form, although currently no function is available to apply $U$ or $V$ when stored in compact form.

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