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_zgghrd (f08ws)

## Purpose

nag_lapack_zgghrd (f08ws) reduces a pair of complex matrices $\left(A,B\right)$, where $B$ is upper triangular, to the generalized upper Hessenberg form using unitary transformations.

## Syntax

[a, b, q, z, info] = f08ws(compq, compz, ilo, ihi, a, b, q, z, 'n', n)
[a, b, q, z, info] = nag_lapack_zgghrd(compq, compz, ilo, ihi, a, b, q, z, 'n', n)

## Description

nag_lapack_zgghrd (f08ws) is usually the third step in the solution of the complex generalized eigenvalue problem
 $Ax=λBx.$
The (optional) first step balances the two matrices using nag_lapack_zggbal (f08wv). In the second step, matrix $B$ is reduced to upper triangular form using the $QR$ factorization function nag_lapack_zgeqrf (f08as) and this unitary transformation $Q$ is applied to matrix $A$ by calling nag_lapack_zunmqr (f08au).
nag_lapack_zgghrd (f08ws) reduces a pair of complex matrices $\left(A,B\right)$, where $B$ is triangular, to the generalized upper Hessenberg form using unitary transformations. This two-sided transformation is of the form
 $QHAZ=H QHBZ=T$
where $H$ is an upper Hessenberg matrix, $T$ is an upper triangular matrix and $Q$ and $Z$ are unitary matrices determined as products of Givens rotations. They may either be formed explicitly, or they may be postmultiplied into input matrices ${Q}_{1}$ and ${Z}_{1}$, so that
 $Q1AZ1H=Q1QHZ1ZH, Q1BZ1H=Q1QTZ1ZH.$

## References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Moler C B and Stewart G W (1973) An algorithm for generalized matrix eigenproblems SIAM J. Numer. Anal. 10 241–256

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{compq}$ – string (length ≥ 1)
Specifies the form of the computed unitary matrix $Q$.
${\mathbf{compq}}=\text{'N'}$
Do not compute $Q$.
${\mathbf{compq}}=\text{'I'}$
The unitary matrix $Q$ is returned.
${\mathbf{compq}}=\text{'V'}$
q must contain a unitary matrix ${Q}_{1}$, and the product ${Q}_{1}Q$ is returned.
Constraint: ${\mathbf{compq}}=\text{'N'}$, $\text{'I'}$ or $\text{'V'}$.
2:     $\mathrm{compz}$ – string (length ≥ 1)
Specifies the form of the computed unitary matrix $Z$.
${\mathbf{compz}}=\text{'N'}$
Do not compute $Z$.
${\mathbf{compz}}=\text{'V'}$
z must contain a unitary matrix ${Z}_{1}$, and the product ${Z}_{1}Z$ is returned.
${\mathbf{compz}}=\text{'I'}$
The unitary matrix $Z$ is returned.
Constraint: ${\mathbf{compz}}=\text{'N'}$, $\text{'V'}$ or $\text{'I'}$.
3:     $\mathrm{ilo}$int64int32nag_int scalar
4:     $\mathrm{ihi}$int64int32nag_int scalar
${i}_{\mathrm{lo}}$ and ${i}_{\mathrm{hi}}$ as determined by a previous call to nag_lapack_zggbal (f08wv). Otherwise, they should be set to $1$ and $n$, respectively.
Constraints:
• if ${\mathbf{n}}>0$, $1\le {\mathbf{ilo}}\le {\mathbf{ihi}}\le {\mathbf{n}}$;
• if ${\mathbf{n}}=0$, ${\mathbf{ilo}}=1$ and ${\mathbf{ihi}}=0$.
5:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The matrix $A$ of the matrix pair $\left(A,B\right)$. Usually, this is the matrix $A$ returned by nag_lapack_zunmqr (f08au).
6:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array
The first dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The upper triangular matrix $B$ of the matrix pair $\left(A,B\right)$. Usually, this is the matrix $B$ returned by the $QR$ factorization function nag_lapack_zgeqrf (f08as).
7:     $\mathrm{q}\left(\mathit{ldq},:\right)$ – complex array
The first dimension, $\mathit{ldq}$, of the array q must satisfy
• if ${\mathbf{compq}}=\text{'I'}$ or $\text{'V'}$, $\mathit{ldq}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{compq}}=\text{'N'}$, $\mathit{ldq}\ge 1$.
The second dimension of the array q must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{compq}}=\text{'I'}$ or $\text{'V'}$ and at least $1$ if ${\mathbf{compq}}=\text{'N'}$.
If ${\mathbf{compq}}=\text{'V'}$, q must contain a unitary matrix ${Q}_{1}$.
If ${\mathbf{compq}}=\text{'N'}$, q is not referenced.
8:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – complex array
The first dimension, $\mathit{ldz}$, of the array z must satisfy
• if ${\mathbf{compz}}=\text{'V'}$ or $\text{'I'}$, $\mathit{ldz}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{compz}}=\text{'N'}$, $\mathit{ldz}\ge 1$.
The second dimension of the array z must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{compz}}=\text{'V'}$ or $\text{'I'}$ and at least $1$ if ${\mathbf{compz}}=\text{'N'}$.
If ${\mathbf{compz}}=\text{'V'}$, z must contain a unitary matrix ${Z}_{1}$.
If ${\mathbf{compz}}=\text{'N'}$, z is not referenced.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the arrays a, b and the second dimension of the arrays a, b.
$n$, the order of the matrices $A$ and $B$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
a stores the upper Hessenberg matrix $H$.
2:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array
The first dimension of the array b will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
b stores the upper triangular matrix $T$.
3:     $\mathrm{q}\left(\mathit{ldq},:\right)$ – complex array
The first dimension, $\mathit{ldq}$, of the array q will be
• if ${\mathbf{compq}}=\text{'I'}$ or $\text{'V'}$, $\mathit{ldq}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{compq}}=\text{'N'}$, $\mathit{ldq}=1$.
The second dimension of the array q will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{compq}}=\text{'I'}$ or $\text{'V'}$ and at least $1$ if ${\mathbf{compq}}=\text{'N'}$.
If ${\mathbf{compq}}=\text{'I'}$, q contains the unitary matrix $Q$.
Iif ${\mathbf{compq}}=\text{'V'}$, q stores ${Q}_{1}Q$.
4:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – complex array
The first dimension, $\mathit{ldz}$, of the array z will be
• if ${\mathbf{compz}}=\text{'V'}$ or $\text{'I'}$, $\mathit{ldz}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{compz}}=\text{'N'}$, $\mathit{ldz}=1$.
The second dimension of the array z will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{compz}}=\text{'V'}$ or $\text{'I'}$ and at least $1$ if ${\mathbf{compz}}=\text{'N'}$.
If ${\mathbf{compz}}=\text{'I'}$, z contains the unitary matrix $Z$.
If ${\mathbf{compz}}=\text{'V'}$, z stores ${Z}_{1}Z$.
5:     $\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: compq, 2: compz, 3: n, 4: ilo, 5: ihi, 6: a, 7: lda, 8: b, 9: ldb, 10: q, 11: ldq, 12: z, 13: ldz, 14: 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 reduction to the generalized Hessenberg form is implemented using unitary transformations which are backward stable.

This function is usually followed by nag_lapack_zhgeqz (f08xs) which implements the $QZ$ algorithm for computing generalized eigenvalues of a reduced pair of matrices.
The real analogue of this function is nag_lapack_dgghrd (f08we).

## Example

See Example in nag_lapack_zhgeqz (f08xs) and nag_lapack_ztgevc (f08yx).
```function f08ws_example

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

% Generalized eigenvalues of matrix pair (A,B) , where
a = [ 1.0+3.0i  1.0+4.0i  1.0+5.0i   1.0+6.0i;
2.0+2.0i  4.0+3.0i  8.0+4.0i  16.0+5.0i;
3.0+1.0i  9.0+2.0i 27.0+3.0i  81.0+4.0i;
4.0+0.0i 16.0+1.0i 64.0+2.0i 256.0+3.0i];
b = [ 1.0+0.0i  2.0+1.0i  3.0+2.0i   4.0+3.0i;
1.0+1.0i  4.0+2.0i  9.0+3.0i  16.0+4.0i;
1.0+2.0i  8.0+3.0i 27.0+4.0i  64.0+5.0i;
1.0+3.0i 16.0+4.0i 81.0+5.0i 256.0+6.0i];

% Balance matrix pair
job = 'Balance';
[a, b, ilo, ihi, lscale, rscale, info] = ...
f08wv(job, a, b);
bbal = b(ilo:ihi,ilo:ihi);
abal = a(ilo:ihi,ilo:ihi);

% QR factorize balanced B
[QR, tau, info] = f08as(bbal);

% Perform C = Q^H*A
side = 'Left';
trans = 'Conjugate transpose';
[c, info] = f08au( ...
side, trans, QR, tau, abal);

% Generalized Hessenberg form (C,R) -> (H,T)
compq = 'No Q';
compz = 'No Z';
z = complex(eye(4));
q = complex(eye(4));
jlo = int64(1);
jhi = int64(ihi-ilo+1);
[H, T, ~, ~, info] = ...
f08ws( ...
compq, compz, jlo, jhi, c, QR, q, z);

% Find eigenvalues of generalized Hessenberg form
%    = eigenvalues of (A,B).
job = 'Eigenvalues';
[~, ~, alpha, beta, ~, ~, info] = ...
f08xs( ...
job, compq, compz, jlo, jhi, H, T, q, z);

disp('Generalized eigenvalues of (A,B):');
disp(sort(alpha./beta));

```
```f08ws example results

Generalized eigenvalues of (A,B):
0.6744 - 0.0499i
0.4580 - 0.8426i
0.4934 + 0.9102i
-0.6354 + 1.6529i

```