NAG Library Routine Document

f08wsf (zgghrd)

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

Fortran Interface
Subroutine f08wsf ( compq, compz, 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
C Header Interface
#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.

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
Arguments

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='V'
z must contain a unitary matrix Z1, and the product Z1Z is returned.
compz='I'
The unitary matrix Z is returned.
Constraint: compz='N', 'V' or 'I'.
3:     n – IntegerInput
On entry: n, the order of the matrices A and B.
Constraint: n0.
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:     alda* – 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: ldamax1,n.
8:     bldb* – 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: ldbmax1,n.
10:   qldq* – 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', ldq1.
12:   zldz* – 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', ldz1.
14:   info – IntegerOutput
On exit: info=0 unless the routine detects an error (see Section 6).

6
Error Indicators and Warnings

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
Parallelism and Performance

f08wsf (zgghrd) is not threaded in any implementation.

9
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).

10
Example

See Section 10 in f08xsf (zhgeqz) and f08yxf (ztgevc).