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_zgbbrd (f08ls)

## Purpose

nag_lapack_zgbbrd (f08ls) reduces a complex $m$ by $n$ band matrix to real upper bidiagonal form.

## Syntax

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

## Description

nag_lapack_zgbbrd (f08ls) reduces a complex $m$ by $n$ band matrix to real upper bidiagonal form $B$ by a unitary transformation: $A=QB{P}^{\mathrm{H}}$. The unitary matrices $Q$ and ${P}^{\mathrm{H}}$, 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{H}}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{H}}$ are generated.
${\mathbf{vect}}=\text{'N'}$
Neither $Q$ nor ${P}^{\mathrm{H}}$ is generated.
${\mathbf{vect}}=\text{'Q'}$
$Q$ is generated.
${\mathbf{vect}}=\text{'P'}$
${P}^{\mathrm{H}}$ is generated.
${\mathbf{vect}}=\text{'B'}$
Both $Q$ and ${P}^{\mathrm{H}}$ 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)$ – complex 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)$ – complex 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)$ – complex 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)$ – complex 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$ unitary matrix $Q$.
If ${\mathbf{vect}}=\text{'N'}$ or $\text{'P'}$, q is not referenced.
5:     $\mathrm{pt}\left(\mathit{ldpt},:\right)$ – complex 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$ unitary matrix ${P}^{\mathrm{H}}$, 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)$ – complex 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{H}}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: rwork, 19: 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{H}}=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 unitary matrix by a matrix $F$ such that
 $F2 = Oε .$
A similar statement holds for the computed matrix ${P}^{\mathrm{H}}$.

The total number of real floating-point operations is approximately the sum of:
• $20{n}^{2}k$, if ${\mathbf{vect}}=\text{'N'}$ and ${\mathbf{ncc}}=0$, and
• $10{n}^{2}{n}_{C}\left(k-1\right)/k$, if $C$ is updated, and
• $10{n}^{3}\left(k-1\right)/k$, if either $Q$ or ${P}^{\mathrm{H}}$ 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 real analogue of this function is nag_lapack_dgbbrd (f08le).

## Example

This example reduces the matrix $A$ to upper bidiagonal form, where
 $A = 0.96-0.81i -0.03+0.96i 0.00+0.00i 0.00+0.00i -0.98+1.98i -1.20+0.19i -0.66+0.42i 0.00+0.00i 0.62-0.46i 1.01+0.02i 0.63-0.17i -1.11+0.60i 0.00+0.00i 0.19-0.54i -0.98-0.36i 0.22-0.20i 0.00+0.00i 0.00+0.00i -0.17-0.46i 1.47+1.59i 0.00+0.00i 0.00+0.00i 0.00+0.00i 0.26+0.26i .$
```function f08ls_example

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

% Banded complex matrix A stored in banded format
m  = int64(6);
n  = int64(4);
kl = int64(2);
ku = int64(1);
ab = [ 0.00 + 0.00i, -0.03 + 0.96i, -0.66 + 0.42i, -1.11 + 0.60i;
0.96 - 0.81i, -1.20 + 0.19i,  0.63 - 0.17i,  0.22 - 0.20i;
-0.98 + 1.98i,  1.01 + 0.02i, -0.98 - 0.36i,  1.47 + 1.59i;
0.62 - 0.46i,  0.19 - 0.54i, -0.17 - 0.46i,  0.26 + 0.26i];

% Reduce A to bidiagonal form
c = [];
vect = 'No Q or PT';
[~, d, e, ~, ~, ~, info] = f08ls( ...
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');

```
```f08ls example results

Diagonal:
2.6560   1.7501   2.0607   0.8658
Off-diagonal (absolute values):
1.7033   1.2800   0.1467
```