F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual

# NAG Library Routine DocumentF08WSF (ZGGHRD)

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

## 1  Purpose

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

## 2  Specification

 SUBROUTINE F08WSF ( COMPQ, COMPZ, N, ILO, IHI, A, LDA, B, LDB, Q, LDQ, Z, LDZ, INFO)
 INTEGER N, ILO, IHI, LDA, LDB, LDQ, LDZ, INFO COMPLEX (KIND=nag_wp) A(LDA,*), B(LDB,*), Q(LDQ,*), Z(LDZ,*) CHARACTER(1) COMPQ, COMPZ
The routine may be called by its LAPACK name zgghrd.

## 3  Description

F08WSF (ZGGHRD) 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 F08WVF (ZGGBAL). In the second step, matrix $B$ is reduced to upper triangular form using the $QR$ factorization routine F08ASF (ZGEQRF) and this unitary transformation $Q$ is applied to matrix $A$ by calling F08AUF (ZUNMQR).
F08WSF (ZGGHRD) 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.$

## 4  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

## 5  Parameters

1:     COMPQ – CHARACTER(1)Input
On entry: 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:     COMPZ – CHARACTER(1)Input
On entry: specifies the form of the computed unitary matrix $Z$.
${\mathbf{COMPZ}}=\text{'N'}$
Do not compute $Z$.
${\mathbf{COMPZ}}=\text{'I'}$
The unitary matrix $Z$ is returned.
${\mathbf{COMPZ}}=\text{'V'}$
Z must contain a unitary matrix ${Z}_{1}$, and the product ${Z}_{1}Z$ is returned.
Constraint: ${\mathbf{COMPZ}}=\text{'N'}$, $\text{'I'}$ or $\text{'V'}$.
3:     N – INTEGERInput
On entry: $n$, the order of the matrices $A$ and $B$.
Constraint: ${\mathbf{N}}\ge 0$.
4:     ILO – INTEGERInput
5:     IHI – INTEGERInput
On entry: ${i}_{\mathrm{lo}}$ and ${i}_{\mathrm{hi}}$ as determined by a previous call to F08WVF (ZGGBAL). 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$.
6:     A(LDA,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array A must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
On entry: the matrix $A$ of the matrix pair $\left(A,B\right)$. Usually, this is the matrix $A$ returned by F08AUF (ZUNMQR).
On exit: A is overwritten by the upper Hessenberg matrix $H$.
7:     LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which F08WSF (ZGGHRD) is called.
Constraint: ${\mathbf{LDA}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
8:     B(LDB,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array B must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
On entry: the upper triangular matrix $B$ of the matrix pair $\left(A,B\right)$. Usually, this is the matrix $B$ returned by the $QR$ factorization routine F08ASF (ZGEQRF).
On exit: B is overwritten by the upper triangular matrix $T$.
9:     LDB – INTEGERInput
On entry: the first dimension of the array B as declared in the (sub)program from which F08WSF (ZGGHRD) is called.
Constraint: ${\mathbf{LDB}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
10:   Q(LDQ,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: 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'}$.
On entry: if ${\mathbf{COMPQ}}=\text{'V'}$, Q must contain a unitary matrix ${Q}_{1}$.
If ${\mathbf{COMPQ}}=\text{'N'}$, Q is not referenced.
On exit: if ${\mathbf{COMPQ}}=\text{'I'}$, Q contains the unitary matrix $Q$.
Iif ${\mathbf{COMPQ}}=\text{'V'}$, Q is overwritten by ${Q}_{1}Q$.
11:   LDQ – INTEGERInput
On entry: the first dimension of the array Q as declared in the (sub)program from which F08WSF (ZGGHRD) is called.
Constraints:
• if ${\mathbf{COMPQ}}=\text{'I'}$ or $\text{'V'}$, ${\mathbf{LDQ}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$;
• if ${\mathbf{COMPQ}}=\text{'N'}$, ${\mathbf{LDQ}}\ge 1$.
12:   Z(LDZ,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: 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{'I'}$ or $\text{'V'}$ and at least $1$ if ${\mathbf{COMPZ}}=\text{'N'}$.
On entry: if ${\mathbf{COMPZ}}=\text{'V'}$, Z must contain a unitary matrix ${Z}_{1}$.
If ${\mathbf{COMPZ}}=\text{'N'}$, Z is not referenced.
On exit: if ${\mathbf{COMPZ}}=\text{'I'}$, Z contains the unitary matrix $Z$.
If ${\mathbf{COMPZ}}=\text{'V'}$, Z is overwritten by ${Z}_{1}Z$.
13:   LDZ – INTEGERInput
On entry: the first dimension of the array Z as declared in the (sub)program from which F08WSF (ZGGHRD) is called.
Constraints:
• if ${\mathbf{COMPZ}}=\text{'I'}$ or $\text{'V'}$, ${\mathbf{LDZ}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$;
• if ${\mathbf{COMPZ}}=\text{'N'}$, ${\mathbf{LDZ}}\ge 1$.
14:   INFO – INTEGEROutput
On exit: ${\mathbf{INFO}}=0$ unless the routine detects an error (see Section 6).

## 6  Error Indicators and Warnings

Errors or warnings detected by the routine:
${\mathbf{INFO}}<0$
If ${\mathbf{INFO}}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.

## 7  Accuracy

The reduction to the generalized Hessenberg form is implemented using unitary transformations which are backward stable.

This routine is usually followed by F08XSF (ZHGEQZ) which implements the $QZ$ algorithm for computing generalized eigenvalues of a reduced pair of matrices.