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

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$n$ by n$n$ (upper or lower) bidiagonal matrix B$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$B$ as
 B = USVT , $B = USVT ,$
where S$S$ is a diagonal matrix with non-negative diagonal elements sii = si${s}_{ii}={s}_{i}$, such that
 s1 ≥ s2 ≥ ⋯ ≥ sn ≥ 0 , $s1 ≥ s2 ≥ ⋯ ≥ sn ≥ 0 ,$
and U$U$ and V$V$ are orthogonal matrices. The diagonal elements of S$S$ are the singular values of B$B$ and the columns of U$U$ and V$V$ are respectively the corresponding left and right singular vectors of B$B$.
When only singular values are required the function uses the QR$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$U$ or V$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:     uplo – string (length ≥ 1)
Indicates whether B$B$ is upper or lower bidiagonal.
uplo = 'U'${\mathbf{uplo}}=\text{'U'}$
B$B$ is upper bidiagonal.
uplo = 'L'${\mathbf{uplo}}=\text{'L'}$
B$B$ is lower bidiagonal.
Constraint: uplo = 'U'${\mathbf{uplo}}=\text{'U'}$ or 'L'$\text{'L'}$.
2:     compq – string (length ≥ 1)
Specifies whether singular vectors are to be computed.
compq = 'N'${\mathbf{compq}}=\text{'N'}$
Compute singular values only.
compq = 'P'${\mathbf{compq}}=\text{'P'}$
Compute singular values and compute singular vectors in compact form.
compq = 'I'${\mathbf{compq}}=\text{'I'}$
Compute singular values and singular vectors.
Constraint: compq = 'N'${\mathbf{compq}}=\text{'N'}$, 'P'$\text{'P'}$ or 'I'$\text{'I'}$.
3:     d( : $:$) – double array
Note: the dimension of the array d must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The n$n$ diagonal elements of the bidiagonal matrix B$B$.
4:     e( : $:$) – double array
Note: the dimension of the array e must be at least max (1,n1)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}-1\right)$.
The (n1)$\left(n-1\right)$ off-diagonal elements of the bidiagonal matrix B$B$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the array d.
n$n$, the order of the matrix B$B$.
Constraint: n0${\mathbf{n}}\ge 0$.
2:     ldq – int64int32nag_int scalar
The dimension of the array q as declared in the (sub)program from which nag_lapack_dbdsdc (f08md) is called. See the description of q.
Default:
• if compq = 'P'${\mathbf{compq}}=\text{'P'}$, n × (61 + 8 × int(log2n / 26 )) ${\mathbf{n}}×\left(61+8×\mathrm{int}\left({\mathrm{log}}_{2}{\mathbf{n}}/26\right)\right)$;
• otherwise 1$1$.
3:     ldiq – int64int32nag_int scalar
The dimension of the array iq as declared in the (sub)program from which nag_lapack_dbdsdc (f08md) is called. See the description of iq.
Default:
• if compq = 'P'${\mathbf{compq}}=\text{'P'}$, n × (3 + 3 × intlog2 n / (26) ) ${\mathbf{n}}×\left(3+3×\mathrm{int}{\mathrm{log}}_{2}{\mathbf{n}}/\left(26\right)\right)$;
• otherwise 1$1$.

### Input Parameters Omitted from the MATLAB Interface

ldu ldvt work iwork

### Output Parameters

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

## Error Indicators and Warnings

info = i${\mathbf{info}}=-i$
If info = i${\mathbf{info}}=-i$, parameter i$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.
INFO > 0${\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$B$ is accurate to nearly full relative precision, no matter how tiny the singular value. The i$i$th computed singular value, i${\stackrel{^}{s}}_{i}$, satisfies the bound
 |ŝi − si| ≤ p(n)εsi $|s^i-si| ≤ p(n)εsi$
where ε$\epsilon$ is the machine precision and p(n)$p\left(n\right)$ is a modest function of n$n$.
For bounds on the computed singular values, see Section 4.9.1 of Anderson et al. (1999). See also nag_lapack_ddisna (f08fl).

If only singular values are required, the total number of floating point operations is approximately proportional to n2${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

```function nag_lapack_dbdsdc_example
uplo = 'Upper';
compq = 'I';
d = [3.62;
-2.41;
1.92;
-1.43];
e = [1.26;
-1.53;
1.19];
[dOut, eOut, u, vt, q, iq, info] = nag_lapack_dbdsdc(uplo, compq, d, e)
```
```

dOut =

4.0001
3.0006
1.9960
0.9998

eOut =

0
0
0

u =

0.9129    0.3740    0.1556    0.0512
-0.3935    0.7005    0.5489    0.2307
0.1081   -0.5904    0.6173    0.5086
-0.0132    0.1444   -0.5417    0.8280

vt =

0.8261    0.5246    0.2024    0.0369
0.4512   -0.4056   -0.7350   -0.3030
0.2823   -0.5644    0.1731    0.7561
0.1852   -0.4916    0.6236   -0.5789

q =

0

iq =

0

info =

0

```
```function f08md_example
uplo = 'Upper';
compq = 'I';
d = [3.62;
-2.41;
1.92;
-1.43];
e = [1.26;
-1.53;
1.19];
[dOut, eOut, u, vt, q, iq, info] = f08md(uplo, compq, d, e)
```
```

dOut =

4.0001
3.0006
1.9960
0.9998

eOut =

0
0
0

u =

0.9129    0.3740    0.1556    0.0512
-0.3935    0.7005    0.5489    0.2307
0.1081   -0.5904    0.6173    0.5086
-0.0132    0.1444   -0.5417    0.8280

vt =

0.8261    0.5246    0.2024    0.0369
0.4512   -0.4056   -0.7350   -0.3030
0.2823   -0.5644    0.1731    0.7561
0.1852   -0.4916    0.6236   -0.5789

q =

0

iq =

0

info =

0

```