F08WSF (ZGGHRD) (PDF version)
F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

F08WSF (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.

+− Contents

    1  Purpose
    2  Specification
    3  Description
    4  References
    5  Parameters
    6  Error Indicators and Warnings
    7  Accuracy
    8  Further Comments
    9  Example

1  Purpose

F08WSF (ZGGHRD) reduces a pair of complex matrices A,B, 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 A,B, 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 Q1 and Z1, 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.
COMPQ='N'
Do not compute Q.
COMPQ='I'
The unitary matrix Q is returned.
COMPQ='V'
Q must contain a unitary matrix Q1, and the product Q1Q is returned.
Constraint: COMPQ='N', 'I' or 'V'.
2:     COMPZ – CHARACTER(1)Input
On entry: specifies the form of the computed unitary matrix Z.
COMPZ='N'
Do not compute Z.
COMPZ='I'
The unitary matrix Z is returned.
COMPZ='V'
Z must contain a unitary matrix Z1, and the product Z1Z is returned.
Constraint: COMPZ='N', 'I' or 'V'.
3:     N – INTEGERInput
On entry: n, the order of the matrices A and B.
Constraint: N≥0.
4:     ILO – INTEGERInput
5:     IHI – INTEGERInput
On entry: ilo and ihi as determined by a previous call to F08WVF (ZGGBAL). Otherwise, they should be set to 1 and n, respectively.
Constraints:
  • if N>0, 1≤ILO≤IHI≤N;
  • if N=0, ILO=1 and IHI=0.
6:     A(LDA,*) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array A must be at least max1,N.
On entry: the matrix A of the matrix pair A,B. 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: LDA≥max1,N.
8:     B(LDB,*) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array B must be at least max1,N.
On entry: the upper triangular matrix B of the matrix pair A,B. 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: LDB≥max1,N.
10:   Q(LDQ,*) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array Q must be at least max1,N if COMPQ='I' or 'V' and at least 1 if COMPQ='N'.
On entry: if COMPQ='V', Q must contain a unitary matrix Q1.
If COMPQ='N', Q is not referenced.
On exit: if COMPQ='I', Q contains the unitary matrix Q.
Iif COMPQ='V', Q is overwritten by Q1Q.
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 COMPQ='I' or 'V', LDQ≥max1,N;
  • if COMPQ='N', LDQ≥1.
12:   Z(LDZ,*) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array Z must be at least max1,N if COMPZ='V' or 'I' and at least 1 if COMPZ='N'.
On entry: if COMPZ='V', Z must contain a unitary matrix Z1.
If COMPZ='N', Z is not referenced.
On exit: if COMPZ='I', Z contains the unitary matrix Z.
If COMPZ='V', Z is overwritten by Z1Z.
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 COMPZ='V' or 'I', LDZ≥max1,N;
  • if COMPZ='N', LDZ≥1.
14:   INFO – INTEGEROutput
On exit: INFO=0 unless the routine detects an error (see Section 6).

6  Error Indicators and Warnings

Errors or warnings detected by the routine:
INFO<0
If 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.

8  Further Comments

This routine is usually followed by F08XSF (ZHGEQZ) which implements the QZ algorithm for computing generalized eigenvalues of a reduced pair of matrices.
The real analogue of this routine is F08WEF (DGGHRD).

9  Example

See Section 9 in F08XSF (ZHGEQZ) and F08YXF (ZTGEVC).
F08WSF (ZGGHRD) (PDF version)
F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2011