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_dgghrd (f08we)

## Purpose

nag_lapack_dgghrd (f08we) reduces a pair of real matrices $\left(A,B\right)$, where $B$ is upper triangular, to the generalized upper Hessenberg form using orthogonal transformations.

## Syntax

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

## Description

nag_lapack_dgghrd (f08we) is the third step in the solution of the real generalized eigenvalue problem
 $Ax=λBx.$
The (optional) first step balances the two matrices using nag_lapack_dggbal (f08wh). In the second step, matrix $B$ is reduced to upper triangular form using the $QR$ factorization function nag_lapack_dgeqrf (f08ae) and this orthogonal transformation $Q$ is applied to matrix $A$ by calling nag_lapack_dormqr (f08ag).
nag_lapack_dgghrd (f08we) reduces a pair of real matrices $\left(A,B\right)$, where $B$ is upper triangular, to the generalized upper Hessenberg form using orthogonal transformations. This two-sided transformation is of the form
 $QTAZ=H QTBZ=T$
where $H$ is an upper Hessenberg matrix, $T$ is an upper triangular matrix and $Q$ and $Z$ are orthogonal 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
 $Q1AZ1T=Q1QHZ1ZT, Q1BZ1T=Q1QTZ1ZT.$

## 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 orthogonal matrix $Q$.
${\mathbf{compq}}=\text{'N'}$
Do not compute $Q$.
${\mathbf{compq}}=\text{'I'}$
The orthogonal matrix $Q$ is returned.
${\mathbf{compq}}=\text{'V'}$
q must contain an orthogonal 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 orthogonal matrix $Z$.
${\mathbf{compz}}=\text{'N'}$
Do not compute $Z$.
${\mathbf{compz}}=\text{'I'}$
The orthogonal matrix $Z$ is returned.
${\mathbf{compz}}=\text{'V'}$
z must contain an orthogonal matrix ${Z}_{1}$, and the product ${Z}_{1}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_dggbal (f08wh). 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)$ – double 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_dormqr (f08ag).
6:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – double 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_dgeqrf (f08ae).
7:     $\mathrm{q}\left(\mathit{ldq},:\right)$ – double 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 an orthogonal matrix ${Q}_{1}$.
If ${\mathbf{compq}}=\text{'N'}$, q is not referenced.
8:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – double 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 an orthogonal 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 array z.
$n$, the order of the matrices $A$ and $B$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – double 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)$ – double 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)$ – double 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 orthogonal matrix $Q$.
If ${\mathbf{compq}}=\text{'V'}$, q stores ${Q}_{1}Q$.
4:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – double 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 orthogonal 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 orthogonal transformations which are backward stable.

This function is usually followed by nag_lapack_dhgeqz (f08xe) which implements the $QZ$ algorithm for computing generalized eigenvalues of a reduced pair of matrices.
The complex analogue of this function is nag_lapack_zgghrd (f08ws).

## Example

See Example in nag_lapack_dhgeqz (f08xe) and nag_lapack_dtgevc (f08yk).
```function f08we_example

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

a = [ 1.0   1.0    1.0    1.0     1.0;
2.0   4.0    8.0   16.0    32.0;
3.0   9.0   27.0   81.0   243.0;
4.0  16.0   64.0  256.0  1024.0;
5.0  25.0  125.0  625.0  3125.0];
b = a';

%' Balance A and B
job = 'B';
[a, b, ilo, ihi, lscale, rscale, info] = ...
f08wh( ...
job, a, b);

bbal = b(ilo:ihi,ilo:ihi);
abal = a(ilo:ihi,ilo:ihi);

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

% Perform C = Q^T*A
side = 'Left';
trans = 'Transpose';
[c, info] = f08ag( ...
side, trans, QR, tau, abal);

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

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

disp('Generalized eigenvalues of (A,B):');
w = complex(alphar+i*alphai);
disp(w./beta);

```
```f08we example results

Generalized eigenvalues of (A,B):
-2.4367 + 0.0000i
0.6069 + 0.7948i
0.6069 - 0.7948i
1.0000 + 0.0000i
-0.4104 + 0.0000i

```