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_dgbbrd (f08le)

## Purpose

nag_lapack_dgbbrd (f08le) reduces a real $m$ by $n$ band matrix to upper bidiagonal form.

## Syntax

[ab, d, e, q, pt, c, info] = f08le(vect, m, kl, ku, ab, c, 'n', n, 'ncc', ncc)
[ab, d, e, q, pt, c, info] = nag_lapack_dgbbrd(vect, m, kl, ku, ab, c, 'n', n, 'ncc', ncc)

## Description

nag_lapack_dgbbrd (f08le) reduces a real $m$ by $n$ band matrix to upper bidiagonal form $B$ by an orthogonal transformation: $A=QB{P}^{\mathrm{T}}$. The orthogonal matrices $Q$ and ${P}^{\mathrm{T}}$, of order $m$ and $n$ respectively, are determined as a product of Givens rotation matrices, and may be formed explicitly by the function if required. A matrix $C$ may also be updated to give $\stackrel{~}{C}={Q}^{\mathrm{T}}C$.
The function uses a vectorizable form of the reduction.

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{vect}$ – string (length ≥ 1)
Indicates whether the matrices $Q$ and/or ${P}^{\mathrm{T}}$ are generated.
${\mathbf{vect}}=\text{'N'}$
Neither $Q$ nor ${P}^{\mathrm{T}}$ is generated.
${\mathbf{vect}}=\text{'Q'}$
$Q$ is generated.
${\mathbf{vect}}=\text{'P'}$
${P}^{\mathrm{T}}$ is generated.
${\mathbf{vect}}=\text{'B'}$
Both $Q$ and ${P}^{\mathrm{T}}$ are generated.
Constraint: ${\mathbf{vect}}=\text{'N'}$, $\text{'Q'}$, $\text{'P'}$ or $\text{'B'}$.
2:     $\mathrm{m}$int64int32nag_int scalar
$m$, the number of rows of the matrix $A$.
Constraint: ${\mathbf{m}}\ge 0$.
3:     $\mathrm{kl}$int64int32nag_int scalar
The number of subdiagonals, ${k}_{l}$, within the band of $A$.
Constraint: ${\mathbf{kl}}\ge 0$.
4:     $\mathrm{ku}$int64int32nag_int scalar
The number of superdiagonals, ${k}_{u}$, within the band of $A$.
Constraint: ${\mathbf{ku}}\ge 0$.
5:     $\mathrm{ab}\left(\mathit{ldab},:\right)$ – double array
The first dimension of the array ab must be at least ${\mathbf{kl}}+{\mathbf{ku}}+1$.
The second dimension of the array ab must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The original $m$ by $n$ band matrix $A$.
The matrix is stored in rows $1$ to ${k}_{l}+{k}_{u}+1$, more precisely, the element ${A}_{ij}$ must be stored in
 $abku+1+i-jj for ​max1,j-ku≤i≤minm,j+kl.$
6:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – double array
The first dimension, $\mathit{ldc}$, of the array c must satisfy
• if ${\mathbf{ncc}}>0$, $\mathit{ldc}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• if ${\mathbf{ncc}}=0$, $\mathit{ldc}\ge 1$.
The second dimension of the array c must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{ncc}}\right)$.
An $m$ by ${n}_{C}$ matrix $C$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the second dimension of the array ab.
$n$, the number of columns of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
2:     $\mathrm{ncc}$int64int32nag_int scalar
Default: the second dimension of the array c.
${n}_{C}$, the number of columns of the matrix $C$.
Constraint: ${\mathbf{ncc}}\ge 0$.

### Output Parameters

1:     $\mathrm{ab}\left(\mathit{ldab},:\right)$ – double array
The first dimension of the array ab will be ${\mathbf{kl}}+{\mathbf{ku}}+1$.
The second dimension of the array ab will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
ab stores values generated during the reduction.
2:     $\mathrm{d}\left(\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)\right)$ – double array
The diagonal elements of the bidiagonal matrix $B$.
3:     $\mathrm{e}\left(\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)-1\right)$ – double array
The superdiagonal elements of the bidiagonal matrix $B$.
4:     $\mathrm{q}\left(\mathit{ldq},:\right)$ – double array
The first dimension, $\mathit{ldq}$, of the array q will be
• if ${\mathbf{vect}}=\text{'Q'}$ or $\text{'B'}$, $\mathit{ldq}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• otherwise $\mathit{ldq}=1$.
The second dimension of the array q will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$ if ${\mathbf{vect}}=\text{'Q'}$ or $\text{'B'}$ and $1$ otherwise.
If ${\mathbf{vect}}=\text{'Q'}$ or $\text{'B'}$, contains the $m$ by $m$ orthogonal matrix $Q$.
If ${\mathbf{vect}}=\text{'N'}$ or $\text{'P'}$, q is not referenced.
5:     $\mathrm{pt}\left(\mathit{ldpt},:\right)$ – double array
The first dimension, $\mathit{ldpt}$, of the array pt will be
• if ${\mathbf{vect}}=\text{'P'}$ or $\text{'B'}$, $\mathit{ldpt}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldpt}=1$.
The second dimension of the array pt will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{vect}}=\text{'P'}$ or $\text{'B'}$ and $1$ otherwise.
The $n$ by $n$ orthogonal matrix ${P}^{\mathrm{T}}$, if ${\mathbf{vect}}=\text{'P'}$ or $\text{'B'}$. If ${\mathbf{vect}}=\text{'N'}$ or $\text{'Q'}$, pt is not referenced.
6:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – double array
The first dimension, $\mathit{ldc}$, of the array c will be
• if ${\mathbf{ncc}}>0$, $\mathit{ldc}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• if ${\mathbf{ncc}}=0$, $\mathit{ldc}=1$.
The second dimension of the array c will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{ncc}}\right)$.
c stores ${Q}^{\mathrm{T}}C$. If ${\mathbf{ncc}}=0$, c 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: vect, 2: m, 3: n, 4: ncc, 5: kl, 6: ku, 7: ab, 8: ldab, 9: d, 10: e, 11: q, 12: ldq, 13: pt, 14: ldpt, 15: c, 16: ldc, 17: work, 18: 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.

## Accuracy

The computed bidiagonal form $B$ satisfies $QB{P}^{\mathrm{T}}=A+E$, where
 $E2 ≤ c n ε A2 ,$
$c\left(n\right)$ is a modestly increasing function of $n$, and $\epsilon$ is the machine precision.
The elements of $B$ themselves may be sensitive to small perturbations in $A$ or to rounding errors in the computation, but this does not affect the stability of the singular values and vectors.
The computed matrix $Q$ differs from an exactly orthogonal matrix by a matrix $F$ such that
 $F2 = Oε .$
A similar statement holds for the computed matrix ${P}^{\mathrm{T}}$.

## Further Comments

The total number of real floating-point operations is approximately the sum of:
• $6{n}^{2}k$, if ${\mathbf{vect}}=\text{'N'}$ and ${\mathbf{ncc}}=0$, and
• $3{n}^{2}{n}_{C}\left(k-1\right)/k$, if $C$ is updated, and
• $3{n}^{3}\left(k-1\right)/k$, if either $Q$ or ${P}^{\mathrm{T}}$ is generated (double this if both),
where $k={k}_{l}+{k}_{u}$, assuming $n\gg k$. For this section we assume that $m=n$
The complex analogue of this function is nag_lapack_zgbbrd (f08ls).

## Example

This example reduces the matrix $A$ to upper bidiagonal form, where
 $A = -0.57 -1.28 0.00 0.00 -1.93 1.08 -0.31 0.00 2.30 0.24 0.40 -0.35 0.00 0.64 -0.66 0.08 0.00 0.00 0.15 -2.13 -0.00 0.00 0.00 0.50 .$
```function f08le_example

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

% Banded matrix A stored in banded format
m  = int64(6);
n  = int64(4);
kl = int64(2);
ku = int64(1);
ab = [ 0.00, -1.28, -0.31, -0.35;
-0.57,  1.08,  0.40,  0.08;
-1.93,  0.24, -0.66, -2.13;
2.30,  0.64,  0.15,  0.50];

% Reduce A to bidiagonal form
c  = [];
vect = 'No Q or PT';
[abf, d, e, q, pt, c, info] = f08le( ...
vect, m, kl, ku, ab, c);

fprintf('Diagonal:\n');
fprintf(' %8.4f',d);
fprintf('\nOff-diagonal (absolute values):\n');
fprintf(' %8.4f',abs(e));
fprintf('\n');

```
```f08le example results

Diagonal:
3.0561   1.5259   0.9690   1.5685
Off-diagonal (absolute values):
0.6206   1.2353   1.1240
```

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