ZGGES  - compute for a pair of N-by-N complex nonsymmetric
       matrices (A,B), the generalized eigenvalues, the  general­
       ized complex Schur form (S, T), and optionally left and/or
       right Schur vectors (VSL and VSR)


SYNOPSIS

       SUBROUTINE ZGGES( JOBVSL, JOBVSR, SORT, DELCTG, N, A, LDA,
                         B,  LDB,  SDIM, ALPHA, BETA, VSL, LDVSL,
                         VSR, LDVSR, WORK, LWORK,  RWORK,  BWORK,
                         INFO )

           CHARACTER     JOBVSL, JOBVSR, SORT

           INTEGER       INFO,  LDA, LDB, LDVSL, LDVSR, LWORK, N,
                         SDIM

           LOGICAL       BWORK( * )

           DOUBLE        PRECISION RWORK( * )

           COMPLEX*16    A( LDA, * ), ALPHA( * ), B(  LDB,  *  ),
                         BETA(  * ), VSL( LDVSL, * ), VSR( LDVSR,
                         * ), WORK( * )

           LOGICAL       DELCTG

           EXTERNAL      DELCTG


PURPOSE

       ZGGES computes for a pair of N-by-N  complex  nonsymmetric
       matrices  (A,B), the generalized eigenvalues, the general­
       ized complex Schur form (S, T), and optionally left and/or
       right Schur vectors (VSL and VSR). This gives the general­
       ized Schur factorization
               (A,B) = ( (VSL)*S*(VSR)**H, (VSL)*T*(VSR)**H )

       where (VSR)**H is the conjugate-transpose of VSR.

       Optionally, it also  orders  the  eigenvalues  so  that  a
       selected  cluster  of  eigenvalues  appears in the leading
       diagonal blocks of the upper triangular matrix S  and  the
       upper  triangular matrix T. The leading columns of VSL and
       VSR then form an unitary basis for the corresponding  left
       and right eigenspaces (deflating subspaces).

       (If  only  the generalized eigenvalues are needed, use the
       driver ZGGEV instead, which is faster.)

       A generalized eigenvalue for a pair of matrices (A,B) is a
       scalar  w or a ratio alpha/beta = w, such that  A - w*B is
       singular.   It  is  usually  represented   as   the   pair
       (alpha,beta),  as there is a reasonable interpretation for
       beta=0, and even for both being zero.

       form if S and T are upper triangular and, in addition, the
       diagonal elements of T are non-negative real numbers.


ARGUMENTS

       JOBVSL  (input) CHARACTER*1
               = 'N':  do not compute the left Schur vectors;
               = 'V':  compute the left Schur vectors.

       JOBVSR  (input) CHARACTER*1
               = 'N':  do not compute the right Schur vectors;
               = 'V':  compute the right Schur vectors.

       SORT    (input) CHARACTER*1
               Specifies whether or not to order the  eigenvalues
               on  the diagonal of the generalized Schur form.  =
               'N':  Eigenvalues are not ordered;
               = 'S':  Eigenvalues are ordered (see DELZTG).

       DELZTG  (input) LOGICAL FUNCTION of two COMPLEX*16 argu­
               ments
               DELZTG  must  be  declared EXTERNAL in the calling
               subroutine.  If SORT = 'N', DELZTG is  not  refer­
               enced.   If  SORT  = 'S', DELZTG is used to select
               eigenvalues to sort to the top left of  the  Schur
               form.   An eigenvalue ALPHA(j)/BETA(j) is selected
               if DELZTG(ALPHA(j),BETA(j)) is true.

               Note that a selected  complex  eigenvalue  may  no
               longer  satisfy  DELZTG(ALPHA(j),BETA(j)) = .TRUE.
               after ordering,  since  ordering  may  change  the
               value  of  complex  eigenvalues (especially if the
               eigenvalue is ill-conditioned), in this case  INFO
               is set to N+2 (See INFO below).

       N       (input) INTEGER
               The  order  of the matrices A, B, VSL, and VSR.  N
               >= 0.

       A       (input/output) COMPLEX*16 array, dimension (LDA,
               N)
               On  entry,  the first of the pair of matrices.  On
               exit, A has been overwritten  by  its  generalized
               Schur form S.

       LDA     (input) INTEGER
               The leading dimension of A.  LDA >= max(1,N).

       B       (input/output) COMPLEX*16 array, dimension (LDB,
               N)
               On entry, the second of the pair of matrices.   On
               exit,  B  has  been overwritten by its generalized
               Schur form T.

               The leading dimension of B.  LDB >= max(1,N).

       SDIM    (output) INTEGER
               If SORT = 'N', SDIM = 0.  If SORT =  'S',  SDIM  =
               number  of  eigenvalues  (after sorting) for which
               DELZTG is true.

       ALPHA   (output) COMPLEX*16 array, dimension (N)
               BETA    (output) COMPLEX*16 array,  dimension  (N)
               On exit,  ALPHA(j)/BETA(j), j=1,...,N, will be the
               generalized eigenvalues.  ALPHA(j), j=1,...,N  and
               BETA(j),  j=1,...,N  are the diagonals of the com­
               plex  Schur  form  (A,B)  output  by  ZGGES.   The
               BETA(j) will be non-negative real.

               Note:  the  quotients  ALPHA(j)/BETA(j) may easily
               over- or underflow, and BETA(j) may even be  zero.
               Thus,  the user should avoid naively computing the
               ratio alpha/beta.  However, ALPHA will  be  always
               less  than  and usually comparable with norm(A) in
               magnitude, and BETA always less than  and  usually
               comparable with norm(B).

       VSL     (output) COMPLEX*16 array, dimension (LDVSL,N)
               If  JOBVSL  = 'V', VSL will contain the left Schur
               vectors.  Not referenced if JOBVSL = 'N'.

       LDVSL   (input) INTEGER
               The leading dimension of the matrix VSL. LDVSL  >=
               1, and if JOBVSL = 'V', LDVSL >= N.

       VSR     (output) COMPLEX*16 array, dimension (LDVSR,N)
               If  JOBVSR = 'V', VSR will contain the right Schur
               vectors.  Not referenced if JOBVSR = 'N'.

       LDVSR   (input) INTEGER
               The leading dimension of the matrix VSR. LDVSR  >=
               1, and if JOBVSR = 'V', LDVSR >= N.

       WORK    (workspace/output) COMPLEX*16 array, dimension
               (LWORK)
               On exit, if INFO = 0, WORK(1) returns the  optimal
               LWORK.

       LWORK   (input) INTEGER
               The   dimension  of  the  array  WORK.   LWORK  >=
               max(1,2*N).  For good performance, LWORK must gen­
               erally be larger.

               If  LWORK = -1, then a workspace query is assumed;
               the routine only calculates the  optimal  size  of
               the  WORK  array,  returns this value as the first
               entry of the WORK  array,  and  no  error  message


       RWORK   (workspace) DOUBLE PRECISION array, dimension
               (8*N)

       BWORK   (workspace) LOGICAL array, dimension (N)
               Not referenced if SORT = 'N'.

       INFO    (output) INTEGER
               = 0:  successful exit
               < 0:  if INFO = -i, the i-th argument had an ille­
               gal value.
               =1,...,N:  The QZ iteration failed.  (A,B) are not
               in Schur form, but ALPHA(j) and BETA(j) should  be
               correct  for  j=INFO+1,...,N.   >  N:  =N+1: other
               than QZ iteration failed in ZHGEQZ
               =N+2: after reordering, roundoff changed values of
               some complex eigenvalues so that leading eigenval­
               ues in the Generalized Schur form no  longer  sat­
               isfy  DELZTG=.TRUE.  This could also be caused due
               to scaling.  =N+3: reordering falied in ZTGSEN.


Man(1) output converted with man2html