# NAG Library Routine Document

## 1Purpose

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.

## 2Specification

Fortran Interface
 Subroutine f08wsf ( n, ilo, ihi, a, lda, b, ldb, q, ldq, z, ldz, info)
 Integer, Intent (In) :: n, ilo, ihi, lda, ldb, ldq, ldz Integer, Intent (Out) :: info Complex (Kind=nag_wp), Intent (Inout) :: a(lda,*), b(ldb,*), q(ldq,*), z(ldz,*) Character (1), Intent (In) :: compq, compz
#include nagmk26.h
 void f08wsf_ ( const char *compq, const char *compz, const Integer *n, const Integer *ilo, const Integer *ihi, Complex a[], const Integer *lda, Complex b[], const Integer *ldb, Complex q[], const Integer *ldq, Complex z[], const Integer *ldz, Integer *info, const Charlen length_compq, const Charlen length_compz)
The routine may be called by its LAPACK name zgghrd.

## 3Description

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

## 4References

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

## 5Arguments

1:     $\mathbf{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:     $\mathbf{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{'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:     $\mathbf{n}$ – IntegerInput
On entry: $n$, the order of the matrices $A$ and $B$.
Constraint: ${\mathbf{n}}\ge 0$.
4:     $\mathbf{ilo}$ – IntegerInput
5:     $\mathbf{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:     $\mathbf{a}\left({\mathbf{lda}},*\right)$ – 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:     $\mathbf{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:     $\mathbf{b}\left({\mathbf{ldb}},*\right)$ – 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:     $\mathbf{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:   $\mathbf{q}\left({\mathbf{ldq}},*\right)$ – 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:   $\mathbf{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:   $\mathbf{z}\left({\mathbf{ldz}},*\right)$ – 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{'V'}$ or $\text{'I'}$ 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:   $\mathbf{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{'V'}$ or $\text{'I'}$, ${\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:   $\mathbf{info}$ – IntegerOutput
On exit: ${\mathbf{info}}=0$ unless the routine detects an error (see Section 6).

## 6Error Indicators and Warnings

${\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.

## 7Accuracy

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

## 8Parallelism and Performance

f08wsf (zgghrd) is not threaded in any implementation.

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