f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_zgbbrd (f08lsc)

## 1  Purpose

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

## 2  Specification

 #include #include
 void nag_zgbbrd (Nag_OrderType order, Nag_VectType vect, Integer m, Integer n, Integer ncc, Integer kl, Integer ku, Complex ab[], Integer pdab, double d[], double e[], Complex q[], Integer pdq, Complex pt[], Integer pdpt, Complex c[], Integer pdc, NagError *fail)

## 3  Description

nag_zgbbrd (f08lsc) 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.

## 5  Arguments

1:     orderNag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or Nag_ColMajor.
2:     vectNag_VectTypeInput
On entry: indicates whether the matrices $Q$ and/or ${P}^{\mathrm{H}}$ are generated.
${\mathbf{vect}}=\mathrm{Nag_DoNotForm}$
Neither $Q$ nor ${P}^{\mathrm{H}}$ is generated.
${\mathbf{vect}}=\mathrm{Nag_FormQ}$
$Q$ is generated.
${\mathbf{vect}}=\mathrm{Nag_FormP}$
${P}^{\mathrm{H}}$ is generated.
${\mathbf{vect}}=\mathrm{Nag_FormBoth}$
Both $Q$ and ${P}^{\mathrm{H}}$ are generated.
Constraint: ${\mathbf{vect}}=\mathrm{Nag_DoNotForm}$, $\mathrm{Nag_FormQ}$, $\mathrm{Nag_FormP}$ or $\mathrm{Nag_FormBoth}$.
3:     mIntegerInput
On entry: $m$, the number of rows of the matrix $A$.
Constraint: ${\mathbf{m}}\ge 0$.
4:     nIntegerInput
On entry: $n$, the number of columns of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
5:     nccIntegerInput
On entry: ${n}_{C}$, the number of columns of the matrix $C$.
Constraint: ${\mathbf{ncc}}\ge 0$.
6:     klIntegerInput
On entry: the number of subdiagonals, ${k}_{l}$, within the band of $A$.
Constraint: ${\mathbf{kl}}\ge 0$.
7:     kuIntegerInput
On entry: the number of superdiagonals, ${k}_{u}$, within the band of $A$.
Constraint: ${\mathbf{ku}}\ge 0$.
8:     ab[$\mathit{dim}$]ComplexInput/Output
Note: the dimension, dim, of the array ab must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdab}}×{\mathbf{n}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}×{\mathbf{pdab}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the original $m$ by $n$ band matrix $A$.
This is stored as a notional two-dimensional array with row elements or column elements stored contiguously. The storage of elements ${A}_{ij}$, for row $i=1,\dots ,m$ and column $j=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,i-{k}_{l}\right),\dots ,\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(n,i+{k}_{u}\right)$, depends on the order argument as follows:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${A}_{ij}$ is stored as ${\mathbf{ab}}\left[\left(j-1\right)×{\mathbf{pdab}}+{\mathbf{ku}}+i-j\right]$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${A}_{ij}$ is stored as ${\mathbf{ab}}\left[\left(i-1\right)×{\mathbf{pdab}}+{\mathbf{kl}}+j-i\right]$.
On exit: ab is overwritten by values generated during the reduction.
9:     pdabIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) of the matrix $A$ in the array ab.
Constraint: ${\mathbf{pdab}}\ge {\mathbf{kl}}+{\mathbf{ku}}+1$.
10:   d[$\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)$]doubleOutput
On exit: the diagonal elements of the bidiagonal matrix $B$.
11:   e[$\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)-1$]doubleOutput
On exit: the superdiagonal elements of the bidiagonal matrix $B$.
12:   q[$\mathit{dim}$]ComplexOutput
Note: the dimension, dim, of the array q must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdq}}×{\mathbf{m}}\right)$ when ${\mathbf{vect}}=\mathrm{Nag_FormQ}$ or $\mathrm{Nag_FormBoth}$;
• $1$ otherwise.
The $\left(i,j\right)$th element of the matrix $Q$ is stored in
• ${\mathbf{q}}\left[\left(j-1\right)×{\mathbf{pdq}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{q}}\left[\left(i-1\right)×{\mathbf{pdq}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On exit: if ${\mathbf{vect}}=\mathrm{Nag_FormQ}$ or $\mathrm{Nag_FormBoth}$, contains the $m$ by $m$ unitary matrix $Q$.
If ${\mathbf{vect}}=\mathrm{Nag_DoNotForm}$ or $\mathrm{Nag_FormP}$, q is not referenced.
13:   pdqIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array q.
Constraints:
• if ${\mathbf{vect}}=\mathrm{Nag_FormQ}$ or $\mathrm{Nag_FormBoth}$, ${\mathbf{pdq}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• otherwise ${\mathbf{pdq}}\ge 1$.
14:   pt[$\mathit{dim}$]ComplexOutput
Note: the dimension, dim, of the array pt must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdpt}}×{\mathbf{n}}\right)$ when ${\mathbf{vect}}=\mathrm{Nag_FormP}$ or $\mathrm{Nag_FormBoth}$;
• $1$ otherwise.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{pt}}\left[\left(j-1\right)×{\mathbf{pdpt}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{pt}}\left[\left(i-1\right)×{\mathbf{pdpt}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On exit: the $n$ by $n$ unitary matrix ${P}^{\mathrm{H}}$, if ${\mathbf{vect}}=\mathrm{Nag_FormP}$ or $\mathrm{Nag_FormBoth}$. If ${\mathbf{vect}}=\mathrm{Nag_DoNotForm}$ or $\mathrm{Nag_FormQ}$, pt is not referenced.
15:   pdptIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array pt.
Constraints:
• if ${\mathbf{vect}}=\mathrm{Nag_FormP}$ or $\mathrm{Nag_FormBoth}$, ${\mathbf{pdpt}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise ${\mathbf{pdpt}}\ge 1$.
16:   c[$\mathit{dim}$]ComplexInput/Output
Note: the dimension, dim, of the array c must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdc}}×{\mathbf{ncc}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}×{\mathbf{pdc}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
The $\left(i,j\right)$th element of the matrix $C$ is stored in
• ${\mathbf{c}}\left[\left(j-1\right)×{\mathbf{pdc}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{c}}\left[\left(i-1\right)×{\mathbf{pdc}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: an $m$ by ${n}_{C}$ matrix $C$.
On exit: c is overwritten by ${Q}^{\mathrm{H}}C$. If ${\mathbf{ncc}}=0$, c is not referenced.
17:   pdcIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array c.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$,
• if ${\mathbf{ncc}}>0$, ${\mathbf{pdc}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• if ${\mathbf{ncc}}=0$, ${\mathbf{pdc}}\ge 1$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdc}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{ncc}}\right)$.
18:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_ENUM_INT_2
On entry, ${\mathbf{vect}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdpt}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{vect}}=\mathrm{Nag_FormP}$ or $\mathrm{Nag_FormBoth}$, ${\mathbf{pdpt}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
otherwise ${\mathbf{pdpt}}\ge 1$.
On entry, ${\mathbf{vect}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdq}}=〈\mathit{\text{value}}〉$ and ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{vect}}=\mathrm{Nag_FormQ}$ or $\mathrm{Nag_FormBoth}$, ${\mathbf{pdq}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
otherwise ${\mathbf{pdq}}\ge 1$.
NE_INT
On entry, ${\mathbf{kl}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{kl}}\ge 0$.
On entry, ${\mathbf{ku}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ku}}\ge 0$.
On entry, ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{m}}\ge 0$.
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 0$.
On entry, ${\mathbf{ncc}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ncc}}\ge 0$.
On entry, ${\mathbf{pdab}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdab}}>0$.
On entry, ${\mathbf{pdc}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdc}}>0$.
On entry, ${\mathbf{pdpt}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdpt}}>0$.
On entry, ${\mathbf{pdq}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdq}}>0$.
NE_INT_2
On entry, ${\mathbf{pdc}}=〈\mathit{\text{value}}〉$ and ${\mathbf{ncc}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdc}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{ncc}}\right)$.
NE_INT_3
On entry, ${\mathbf{ncc}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdc}}=〈\mathit{\text{value}}〉$ and ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{ncc}}>0$, ${\mathbf{pdc}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
if ${\mathbf{ncc}}=0$, ${\mathbf{pdc}}\ge 1$.
On entry, ${\mathbf{pdab}}=〈\mathit{\text{value}}〉$, ${\mathbf{kl}}=〈\mathit{\text{value}}〉$ and ${\mathbf{ku}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdab}}\ge {\mathbf{kl}}+{\mathbf{ku}}+1$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

## 7  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}}=\mathrm{Nag_DoNotForm}$ 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_dgbbrd (f08lec).

## 9  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 .$

### 9.1  Program Text

Program Text (f08lsce.c)

### 9.2  Program Data

Program Data (f08lsce.d)

### 9.3  Program Results

Program Results (f08lsce.r)