ZGGEVX - compute for a pair of N-by-N complex nonsymmetric
       matrices (A,B) the generalized  eigenvalues,  and  option­
       ally, the left and/or right generalized eigenvectors


SYNOPSIS

       SUBROUTINE ZGGEVX( BALANC, JOBVL, JOBVR, SENSE, N, A, LDA,
                          B, LDB,  ALPHA,  BETA,  VL,  LDVL,  VR,
                          LDVR,  ILO, IHI, LSCALE, RSCALE, ABNRM,
                          BBNRM,  RCONDE,  RCONDV,  WORK,  LWORK,
                          RWORK, IWORK, BWORK, INFO )

           CHARACTER      BALANC, JOBVL, JOBVR, SENSE

           INTEGER        IHI,  ILO,  INFO, LDA, LDB, LDVL, LDVR,
                          LWORK, N

           DOUBLE         PRECISION ABNRM, BBNRM

           LOGICAL        BWORK( * )

           INTEGER        IWORK( * )

           DOUBLE         PRECISION LSCALE( *  ),  RCONDE(  *  ),
                          RCONDV( * ), RSCALE( * ), RWORK( * )

           COMPLEX*16     A(  LDA,  * ), ALPHA( * ), B( LDB, * ),
                          BETA( * ), VL( LDVL, * ), VR(  LDVR,  *
                          ), WORK( * )


PURPOSE

       ZGGEVX  computes for a pair of N-by-N complex nonsymmetric
       matrices (A,B) the generalized  eigenvalues,  and  option­
       ally,  the  left  and/or  right  generalized eigenvectors.
       Optionally, it also computes a balancing transformation to
       improve  the conditioning of the eigenvalues and eigenvec­
       tors (ILO, IHI, LSCALE, RSCALE, ABNRM, and BBNRM),  recip­
       rocal  condition numbers for the eigenvalues (RCONDE), and
       reciprocal condition numbers for  the  right  eigenvectors
       (RCONDV).

       A generalized eigenvalue for a pair of matrices (A,B) is a
       scalar lambda or a ratio alpha/beta = lambda, such that  A
       -  lambda*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.

       The right eigenvector v(j) corresponding to the eigenvalue
       lambda(j) of (A,B) satisfies
                        A * v(j) = lambda(j) * B * v(j) .
       The left eigenvector u(j) corresponding to the  eigenvalue
       lambda(j) of (A,B) satisfies
                        u(j)**H * A  = lambda(j) * u(j)**H * B.
       where u(j)**H is the conjugate-transpose of u(j).

       BALANC  (input) CHARACTER*1
               Specifies the balance option to be performed:
               = 'N':  do not diagonally scale or permute;
               = 'P':  permute only;
               = 'S':  scale only;
               = 'B':  both permute and scale.  Computed recipro­
               cal condition numbers will  be  for  the  matrices
               after  permuting  and/or balancing. Permuting does
               not change  condition  numbers  (in  exact  arith­
               metic), but balancing does.

       JOBVL   (input) CHARACTER*1
               = 'N':  do not compute the left generalized eigen­
               vectors;
               = 'V':  compute the left generalized eigenvectors.

       JOBVR   (input) CHARACTER*1
               =  'N':   do  not  compute  the  right generalized
               eigenvectors;
               = 'V':  compute the  right  generalized  eigenvec­
               tors.

       SENSE   (input) CHARACTER*1
               Determines  which reciprocal condition numbers are
               computed.  = 'N': none are computed;
               = 'E': computed for eigenvalues only;
               = 'V': computed for eigenvectors only;
               = 'B': computed for eigenvalues and  eigenvectors.

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

       A       (input/output) COMPLEX*16 array, dimension (LDA,
               N)
               On  entry,  the  matrix  A  in the pair (A,B).  On
               exit, A has  been  overwritten.  If  JOBVL='V'  or
               JOBVR='V'  or both, then A contains the first part
               of the complex Schur form of the  "balanced"  ver­
               sions of the input A and B.

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

       B       (input/output) COMPLEX*16 array, dimension (LDB,
               N)
               On entry, the matrix B  in  the  pair  (A,B).   On
               exit,  B  has  been  overwritten.  If JOBVL='V' or
               JOBVR='V' or both, then B contains the second part
               of  the  complex Schur form of the "balanced" ver­
               sions of the input A and B.

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

       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.

               Note: the quotient 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).

       VL      (output) COMPLEX*16 array, dimension (LDVL,N)
               If JOBVL = 'V', the left generalized  eigenvectors
               u(j)  are  stored one after another in the columns
               of VL, in the same  order  as  their  eigenvalues.
               Each  eigenvector  will  be  scaled so the largest
               component will have  abs(real  part)  +  abs(imag.
               part) = 1.  Not referenced if JOBVL = 'N'.

       LDVL    (input) INTEGER
               The leading dimension of the matrix VL. LDVL >= 1,
               and if JOBVL = 'V', LDVL >= N.

       VR      (output) COMPLEX*16 array, dimension (LDVR,N)
               If JOBVR = 'V', the right generalized eigenvectors
               v(j)  are  stored one after another in the columns
               of VR, in the same  order  as  their  eigenvalues.
               Each  eigenvector  will  be  scaled so the largest
               component will have  abs(real  part)  +  abs(imag.
               part) = 1.  Not referenced if JOBVR = 'N'.

       LDVR    (input) INTEGER
               The leading dimension of the matrix VR. LDVR >= 1,
               and if JOBVR = 'V', LDVR >= N.

               ILO,IHI (output) INTEGER ILO and IHI  are  integer
               values such that on exit A(i,j) = 0 and B(i,j) = 0
               if i > j and j = 1,...,ILO-1 or i  =  IHI+1,...,N.
               If BALANC = 'N' or 'S', ILO = 1 and IHI = N.

       LSCALE  (output) DOUBLE PRECISION array, dimension (N)
               Details  of  the  permutations and scaling factors
               applied to the left side of A and B.  If PL(j)  is
               the  index of the row interchanged with row j, and
               DL(j) is the scaling factor applied to row j, then
               LSCALE(j)  =  PL(j)   for  j = 1,...,ILO-1 = DL(j)
               for j = ILO,...,IHI = PL(j)  for j =  IHI+1,...,N.
               The  order in which the interchanges are made is N
               to IHI+1, then 1 to ILO-1.

               Details of the permutations  and  scaling  factors
               applied to the right side of A and B.  If PR(j) is
               the index of the column interchanged  with  column
               j, and DR(j) is the scaling factor applied to col­
               umn j, then RSCALE(j) = PR(j)  for j = 1,...,ILO-1
               =  DR(j)   for  j  =  ILO,...,IHI = PR(j)  for j =
               IHI+1,...,N The order in  which  the  interchanges
               are made is N to IHI+1, then 1 to ILO-1.

       ABNRM   (output) DOUBLE PRECISION
               The one-norm of the balanced matrix A.

       BBNRM   (output) DOUBLE PRECISION
               The one-norm of the balanced matrix B.

       RCONDE  (output) DOUBLE PRECISION array, dimension (N)
               If  SENSE  =  'E' or 'B', the reciprocal condition
               numbers of the  selected  eigenvalues,  stored  in
               consecutive  elements  of  the  array.  If SENSE =
               'V', RCONDE is not referenced.

       RCONDV  (output) DOUBLE PRECISION array, dimension (N)
               If JOB = 'V' or 'B', the estimated reciprocal con­
               dition   numbers  of  the  selected  eigenvectors,
               stored in consecutive elements of  the  array.  If
               the  eigenvalues  cannot  be  reordered to compute
               RCONDV(j), RCONDV(j) is set to 0;  this  can  only
               occur when the true value would be very small any­
               way.  If SENSE = 'E', RCONDV  is  not  referenced.
               Not referenced if JOB = 'E'.

       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).  If SENSE = 'N' or 'E', LWORK >=  2*N.
               If SENSE = 'V' or 'B', LWORK >= 2*N*N+2*N.

               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
               related to LWORK is issued by XERBLA.

       RWORK   (workspace) DOUBLE PRECISION array, dimension
               (6*N)
               Real workspace.

       IWORK   (workspace) INTEGER array, dimension (N+2)
               If SENSE = 'E', IWORK is not referenced.

               If SENSE = 'N', BWORK is not referenced.

       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.  No eigenvec­
               tors  have  been  calculated,  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: error return from ZTGEVC.


FURTHER DETAILS

       Balancing  a  matrix pair (A,B) includes, first, permuting
       rows and columns to isolate eigenvalues, second,  applying
       diagonal similarity transformation to the rows and columns
       to make the rows and columns as close in norm as possible.
       The  computed  reciprocal  condition numbers correspond to
       the balanced matrix. Permuting rows and columns  will  not
       change  the  condition  numbers  (in exact arithmetic) but
       diagonal scaling will.  For further explanation of balanc­
       ing, see section 4.11.1.2 of LAPACK Users' Guide.

       An approximate error bound on the chordal distance between
       the i-th computed generalized eigenvalue w and the  corre­
       sponding exact eigenvalue lambda is

            chord(w,  lambda)  <=  EPS  *  norm(ABNRM,  BBNRM)  /
       RCONDE(I)

       An approximate error bound for the angle between the  i-th
       computed eigenvector VL(i) or VR(i) is given by

            EPS * norm(ABNRM, BBNRM) / DIF(i).

       For  further  explanation of the reciprocal condition num­
       bers RCONDE and RCONDV, see section 4.11 of LAPACK  User's
       Guide.


Man(1) output converted with man2html