Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_lapack_dbdsdc (f08md)

## Purpose

nag_lapack_dbdsdc (f08md) computes the singular values and, optionally, the left and right singular vectors of a real $n$ by $n$ (upper or lower) bidiagonal matrix $B$.

## Syntax

[d, e, u, vt, q, iq, info] = f08md(uplo, compq, d, e, 'n', n, 'ldq', ldq, 'ldiq', ldiq)
[d, e, u, vt, q, iq, info] = nag_lapack_dbdsdc(uplo, compq, d, e, 'n', n, 'ldq', ldq, 'ldiq', ldiq)

## Description

nag_lapack_dbdsdc (f08md) computes the singular value decomposition (SVD) of the (upper or lower) bidiagonal matrix $B$ as
 $B = USVT ,$
where $S$ is a diagonal matrix with non-negative diagonal elements ${s}_{ii}={s}_{i}$, such that
 $s1 ≥ s2 ≥ ⋯ ≥ sn ≥ 0 ,$
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 http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{uplo}$ – string (length ≥ 1)
Indicates whether $B$ is upper or lower bidiagonal.
${\mathbf{uplo}}=\text{'U'}$
$B$ is upper bidiagonal.
${\mathbf{uplo}}=\text{'L'}$
$B$ is lower bidiagonal.
Constraint: ${\mathbf{uplo}}=\text{'U'}$ or $\text{'L'}$.
2:     $\mathrm{compq}$ – string (length ≥ 1)
Specifies whether singular vectors are to be computed.
${\mathbf{compq}}=\text{'N'}$
Compute singular values only.
${\mathbf{compq}}=\text{'P'}$
Compute singular values and compute singular vectors in compact form.
${\mathbf{compq}}=\text{'I'}$
Compute singular values and singular vectors.
Constraint: ${\mathbf{compq}}=\text{'N'}$, $\text{'P'}$ or $\text{'I'}$.
3:     $\mathrm{d}\left(:\right)$ – double array
The dimension of the array d must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The $n$ diagonal elements of the bidiagonal matrix $B$.
4:     $\mathrm{e}\left(:\right)$ – double array
The dimension of the array e must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}-1\right)$
The $\left(n-1\right)$ off-diagonal elements of the bidiagonal matrix $B$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the dimension of the array d.
$n$, the order of the matrix $B$.
Constraint: ${\mathbf{n}}\ge 0$.
2:     $\mathrm{ldq}$int64int32nag_int scalar
Default:
• if ${\mathbf{compq}}=\text{'P'}$, ${\mathbf{n}}×\left(61+8×\mathrm{int}\left({\mathrm{log}}_{2}{\mathbf{n}}/26\right)\right)$;
• otherwise $1$.
The dimension of the array q. see the description of q.
3:     $\mathrm{ldiq}$int64int32nag_int scalar
Default:
• if ${\mathbf{compq}}=\text{'P'}$, ${\mathbf{n}}×\left(3+3×\mathrm{int}{\mathrm{log}}_{2}{\mathbf{n}}/\left(26\right)\right)$;
• otherwise $1$.
The dimension of the array iq. see the description of iq.

### Output Parameters

1:     $\mathrm{d}\left(:\right)$ – double array
The dimension of the array d will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
If ${\mathbf{info}}={\mathbf{0}}$, the singular values of $B$.
2:     $\mathrm{e}\left(:\right)$ – double array
The dimension of the array e will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}-1\right)$
The contents of e are destroyed.
3:     $\mathrm{u}\left(\mathit{ldu},:\right)$ – double array
The first dimension, $\mathit{ldu}$, of the array u will be
• if ${\mathbf{compq}}=\text{'I'}$, $\mathit{ldu}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldu}=1$.
The second dimension of the array u will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{compq}}=\text{'I'}$ and $1$ otherwise.
If ${\mathbf{compq}}=\text{'I'}$, then if ${\mathbf{info}}={\mathbf{0}}$, u contains the left singular vectors of the bidiagonal matrix $B$.
If ${\mathbf{compq}}\ne \text{'I'}$, u is not referenced.
4:     $\mathrm{vt}\left(\mathit{ldvt},:\right)$ – double array
The first dimension, $\mathit{ldvt}$, of the array vt will be
• if ${\mathbf{compq}}=\text{'I'}$, $\mathit{ldvt}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldvt}=1$.
The second dimension of the array vt will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{compq}}=\text{'I'}$ and $1$ otherwise.
If ${\mathbf{compq}}=\text{'I'}$, then if ${\mathbf{info}}={\mathbf{0}}$, the rows of vt contain the right singular vectors of the bidiagonal matrix $B$.
If ${\mathbf{compq}}\ne \text{'I'}$, vt is not referenced.
5:     $\mathrm{q}\left(:\right)$ – double array
The dimension of the array q will be ${\mathbf{ldq}}$
If ${\mathbf{compq}}=\text{'P'}$, then if ${\mathbf{info}}={\mathbf{0}}$, q and iq contain the left and right singular vectors in a compact form, requiring $\mathit{O}\left({\mathbf{n}}{\mathrm{log}}_{2}{\mathbf{n}}\right)$ space instead of $2×{{\mathbf{n}}}^{2}$. In particular, q contains all the real data in the first ${\mathbf{ldq}}={\mathbf{n}}×\left(11+2×\mathit{smlsiz}+8×\mathrm{int}\left({\mathrm{log}}_{2}\left({\mathbf{n}}/\left(\mathit{smlsiz}+1\right)\right)\right)\right)$ elements of q, where $\mathit{smlsiz}$ is equal to the maximum size of the subproblems at the bottom of the computation tree (usually about $25$).
If ${\mathbf{compq}}\ne \text{'P'}$, q is not referenced.
6:     $\mathrm{iq}\left(:\right)$int64int32nag_int array
The dimension of the array iq will be ${\mathbf{ldiq}}$
If ${\mathbf{compq}}=\text{'P'}$, then if ${\mathbf{info}}={\mathbf{0}}$, q and iq contain the left and right singular vectors in a compact form, requiring $\mathit{O}\left({\mathbf{n}}{\mathrm{log}}_{2}{\mathbf{n}}\right)$ space instead of $2×{{\mathbf{n}}}^{2}$. In particular, iq contains all integer data in the first ${\mathbf{ldiq}}={\mathbf{n}}×\left(3+3×\mathrm{int}\left({\mathrm{log}}_{2}\left({\mathbf{n}}/\left(\mathit{smlsiz}+1\right)\right)\right)\right)$ elements of iq, where $\mathit{smlsiz}$ is equal to the maximum size of the subproblems at the bottom of the computation tree (usually about $25$).
If ${\mathbf{compq}}\ne \text{'P'}$, iq is not referenced.
7:     $\mathrm{info}$int64int32nag_int scalar
${\mathbf{info}}=0$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

${\mathbf{info}}=-i$
If ${\mathbf{info}}=-i$, parameter $i$ had an illegal value on entry. The parameters are numbered as follows:
1: uplo, 2: compq, 3: n, 4: d, 5: e, 6: u, 7: ldu, 8: vt, 9: ldvt, 10: q, 11: ldq, 12: iq, 13: ldiq, 14: work, 15: iwork, 16: info.
It is possible that info refers to a parameter that is omitted from the MATLAB interface. This usually indicates that an error in one of the other input parameters has caused an incorrect value to be inferred.
${\mathbf{info}}>0$
The algorithm failed to compute a singular value. The update process of divide-and-conquer failed.

## Accuracy

Each computed singular value of $B$ is accurate to nearly full relative precision, no matter how tiny the singular value. The $i$th computed singular value, ${\stackrel{^}{s}}_{i}$, satisfies the bound
 $s^i-si ≤ pnεsi$
where $\epsilon$ is the machine precision and $p\left(n\right)$ is a modest function of $n$.
For bounds on the computed singular values, see Section 4.9.1 of Anderson et al. (1999). See also nag_lapack_ddisna (f08fl).

## Further Comments

If only singular values are required, the total number of floating-point operations is approximately proportional to ${n}^{2}$. When singular vectors are required the number of operations is bounded above by approximately the same number of operations as nag_lapack_dbdsqr (f08me), but for large matrices nag_lapack_dbdsdc (f08md) is usually much faster.
There is no complex analogue of nag_lapack_dbdsdc (f08md).

## Example

This example computes the singular value decomposition of the upper bidiagonal matrix
 $B = 3.62 1.26 0.00 0.00 0.00 -2.41 -1.53 0.00 0.00 0.00 1.92 1.19 0.00 0.00 0.00 -1.43 .$
```function f08md_example

fprintf('f08md example results\n\n');

% Bidiagonal matrix B stored as diagonal and off-diagonal
uplo = 'Upper';
d = [3.62;     -2.41;     1.92;     -1.43];
e = [1.26;     -1.53;     1.19];

% Compute singular values
compq = 'I';
[s, ~, ~, ~, ~, ~, info] = f08md( ...
uplo, compq, d, e);

disp('Singular values');
disp(s');

```
```f08md example results

Singular values
4.0001    3.0006    1.9960    0.9998

```

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015