NAG Toolbox: nag_lapack_dbdsdc (f08md)

Purpose

Syntax

Description

References

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 $\max \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 $\max \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}\times \left(61+8\times \mathrm{int}\left({\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}\times \left(3+3\times \mathrm{int}{\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 $\max \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 $\max \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}=\max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldu}=1$.

The second dimension of the array u will be $\max \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}=\max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldvt}=1$.

The second dimension of the array vt will be $\max \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}{\log }_2\mathbf{n}\right)$ space instead of $2\times {\mathbf{n}}^2$. In particular, q contains all the real data in the first $\mathbf{ldq}=\mathbf{n}\times \left(11+2\times \mathit{smlsiz}+8\times \mathrm{int}\left({\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}{\log }_2\mathbf{n}\right)$ space instead of $2\times {\mathbf{n}}^2$. In particular, iq contains all integer data in the first $\mathbf{ldiq}=\mathbf{n}\times \left(3+3\times \mathrm{int}\left({\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

Further Comments

Example

Open in the MATLAB editor: f08md_example

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