F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual

NAG Library Routine DocumentF08WEF (DGGHRD)

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

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

2  Specification

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

3  Description

F08WEF (DGGHRD) is the third step in the solution of the real generalized eigenvalue problem
 $Ax=λBx.$
The (optional) first step balances the two matrices using F08WHF (DGGBAL). In the second step, matrix $B$ is reduced to upper triangular form using the $QR$ factorization routine F08AEF (DGEQRF) and this orthogonal transformation $Q$ is applied to matrix $A$ by calling F08AGF (DORMQR).
F08WEF (DGGHRD) 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.$

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 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:     COMPZ – CHARACTER(1)Input
On entry: 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{'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 F08WHF (DGGBAL). 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,$*$) – REAL (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 F08AGF (DORMQR).
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 F08WEF (DGGHRD) is called.
Constraint: ${\mathbf{LDA}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
8:     B(LDB,$*$) – REAL (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 F08AEF (DGEQRF).
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 F08WEF (DGGHRD) is called.
Constraint: ${\mathbf{LDB}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
10:   Q(LDQ,$*$) – REAL (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 an orthogonal matrix ${Q}_{1}$.
If ${\mathbf{COMPQ}}=\text{'N'}$, Q is not referenced.
On exit: if ${\mathbf{COMPQ}}=\text{'I'}$, Q contains the orthogonal matrix $Q$.
If ${\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 F08WEF (DGGHRD) 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,$*$) – REAL (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 an orthogonal matrix ${Z}_{1}$.
If ${\mathbf{COMPZ}}=\text{'N'}$, Z is not referenced.
On exit: if ${\mathbf{COMPZ}}=\text{'I'}$, Z contains the orthogonal 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 F08WEF (DGGHRD) 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 orthogonal transformations which are backward stable.

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