naginterfaces.library.lapackeig.dbdsqr

naginterfaces.library.lapackeig.dbdsqr(uplo, d, e, vt, u, c)

dbdsqr computes the singular value decomposition of a real upper or lower bidiagonal matrix, or of a real general matrix which has been reduced to bidiagonal form.

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

https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f08/f08mef.html

Parameters

uplostr, length 1

Indicates whether $B$ is an upper or lower bidiagonal matrix.

$uplo=\text{'U'}$

$B$ is an upper bidiagonal matrix.

$uplo=\text{'L'}$

$B$ is a lower bidiagonal matrix.

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

The diagonal elements of the bidiagonal matrix $B$.

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

The off-diagonal elements of the bidiagonal matrix $B$.

vtfloat, array-like, shape $(:,\text{ncvt})$

Note: the required extent for this argument in dimension 1 is determined as follows: if $\text{ncvt}>0$: $n$; otherwise: $1$.

If $\text{ncvt}>0$, $vt$ must contain an $n\times \text{ncvt}$ matrix. If the right singular vectors of $B$ are required, $\text{ncvt}=n$ and $vt$ must contain the unit matrix; if the right singular vectors of $A$ are required, $vt$ must contain the orthogonal matrix $P^T$ returned by dorgbr() with $\text{vect}=\text{'P'}$.

ufloat, array-like, shape $(\text{nru},n)$

If $\text{nru}>0$, $u$ must contain an $\text{nru}\times n$ matrix. If the left singular vectors of $B$ are required, $\text{nru}=n$ and $u$ must contain the unit matrix; if the left singular vectors of $A$ are required, $u$ must contain the orthogonal matrix $Q$ returned by dorgbr() with $\text{vect}=\text{'Q'}$.

cfloat, array-like, shape $(:,\text{ncc})$

Note: the required extent for this argument in dimension 1 is determined as follows: if $\text{ncc}>0$: $n$; otherwise: $1$.

The $n\times \text{ncc}$ matrix $C$ if $\text{ncc}>0$.

Returns

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

The singular values in decreasing order of magnitude, unless $errno$ > 0 (in which case see Exceptions).

efloat, ndarray, shape $(max(1,n-1))$

$e$ is overwritten, but if $errno$ > 0 see Exceptions.

vtfloat, ndarray, shape $(:,\text{ncvt})$

The $n\times \text{ncvt}$ matrix $V^T$ or $V^T{P}^T$ of right singular vectors, stored by rows.

If $\text{ncvt}=0$, $vt$ is not referenced.

ufloat, ndarray, shape $(\text{nru},n)$

The $\text{nru}\times n$ matrix $U$ or $QU$ of left singular vectors, stored as columns of the matrix.

If $\text{nru}=0$, $u$ is not referenced.

cfloat, ndarray, shape $(:,\text{ncc})$

$c$ is overwritten by the matrix $U^{T}C$. If $\text{ncc}=0$, $c$ 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 $\text{n}$.

Constraint: $n\ge 0$.

(errno $-3$)

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

Constraint: $\text{ncvt}\ge 0$.

(errno $-4$)

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

Constraint: $\text{nru}\ge 0$.

(errno $-5$)

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

Constraint: $\text{ncc}\ge 0$.

Warns

NagAlgorithmicWarning

(errno $i>0$)

$⟨value⟩$ off-diagonals did not converge. The arrays $d$ and $e$ contain the diagonal and off-diagonal elements, respectively, of a bidiagonal matrix orthogonally equivalent to $B$.

Notes

dbdsqr computes the singular values and, optionally, the left or right singular vectors of a real upper or lower bidiagonal matrix $B$. In other words, it can compute the singular value decomposition (SVD) of $B$ as

$$B=U\Sigma V^T\text{.}$$

Here $\Sigma$ is a diagonal matrix with real diagonal elements ${\sigma }_i$ (the singular values of $B$), such that

$${\sigma }_1\ge {\sigma }_2\ge \cdots \ge {\sigma }_n\ge 0\text{;}$$

$U$ is an orthogonal matrix whose columns are the left singular vectors $u_i$; $V$ is an orthogonal matrix whose rows are the right singular vectors $v_i$. Thus

$$B{u}_i={\sigma }_i{v}_i\text{and}{B}^T{v}_i={\sigma }_i{u}_i\text{,}i=1,2,\dots ,n\text{.}$$

To compute $U$ and/or $V^T$, the arrays $u$ and/or $vt$ must be initialized to the unit matrix before dbdsqr is called.

The function may also be used to compute the SVD of a real general matrix $A$ which has been reduced to bidiagonal form by an orthogonal transformation: $A=QB{P}^T$. If $A$ is $m\times n$ with $m\ge n$, then $Q$ is $m\times n$ and $P^T$ is $n\times n$; if $A$ is $n\times p$ with $n<p$, then $Q$ is $n\times n$ and $P^T$ is $n\times p$. In this case, the matrices $Q$ and/or $P^T$ must be formed explicitly by dorgbr() and passed to dbdsqr in the arrays $u$ and/or $vt$ respectively.

dbdsqr also has the capability of forming $U^{T}C$, where $C$ is an arbitrary real matrix; this is needed when using the SVD to solve linear least squares problems.

dbdsqr uses two different algorithms. If any singular vectors are required (i.e., if $\text{ncvt}>0$ or $\text{nru}>0$ or $\text{ncc}>0$), the bidiagonal $QR$ algorithm is used, switching between zero-shift and implicitly shifted forms to preserve the accuracy of small singular values, and switching between $QR$ and $QL$ variants in order to handle graded matrices effectively (see Demmel and Kahan (1990)). If only singular values are required (i.e., if $\text{ncvt}=\text{nru}=\text{ncc}=0$), they are computed by the differential qd algorithm (see Fernando and Parlett (1994)), which is faster and can achieve even greater accuracy.

The singular vectors are normalized so that $\parallel u_i\parallel =\parallel v_i\parallel =1$, but are determined only to within a factor $\pm 1$.

References

Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873–912

Fernando, K V and Parlett, B N, 1994, Accurate singular values and differential qd algorithms, Numer. Math. (67), 191–229

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore