Previous: zgegs Up: ../lapack-z.html Next: zgehd2


zgegv


 NAME
      ZGEGV - a pair of N-by-N complex nonsymmetric matrices A, B

 SYNOPSIS
      SUBROUTINE ZGEGV( JOBVL, JOBVR, N, A, LDA, B, LDB, ALPHA,
                        BETA, VL, LDVL, VR, LDVR, WORK, LWORK,
                        RWORK, INFO )

          CHARACTER     JOBVL, JOBVR

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

          DOUBLE        PRECISION RWORK( * )

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

 PURPOSE
      For a pair of N-by-N complex nonsymmetric matrices A, B:

         compute the generalized eigenvalues (alpha, beta)
         compute the left and/or right generalized eigenvectors
                 (VL and VR)

      The second action is optional -- see the description of
      JOBVL and JOBVR below.

      A generalized eigenvalue for a pair of matrices (A,B) is,
      roughly speaking, 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 interpre-
      tation for beta=0, and even for both being zero.  A good
      beginning reference is the book, "Matrix Computations", by
      G. Golub & C. van Loan (Johns Hopkins U. Press)

      A right generalized eigenvector corresponding to a general-
      ized eigenvalue  w  for a pair of matrices (A,B) is a vector
      r  such that  (A - w B) r = 0 .  A left generalized eigen-
      vector is a vector l  such that  (A - w B)**H l = 0 .

      Note: this routine performs "full balancing" on A and B --
      see "Further Details", below.

 ARGUMENTS
      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 eigenvectors.

      N       (input) INTEGER
              The number of rows and columns in the matrices A, B,
              VL, and VR.  N >= 0.

      A       (input/workspace) COMPLEX*16 array, dimension (LDA, N)
              On entry, the first of the pair of matrices whose
              generalized eigenvalues and (optionally) generalized
              eigenvectors are to be computed.  On exit, the con-
              tents will have been destroyed.  (For a description
              of the contents of A on exit, see "Further Details",
              below.)

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

      B       (input/workspace) COMPLEX*16 array, dimension (LDB, N)
              On entry, the second of the pair of matrices whose
              generalized eigenvalues and (optionally) generalized
              eigenvectors are to be computed.  On exit, the con-
              tents will have been destroyed.  (For a description
              of the contents of B on exit, see "Further Details",
              below.)

      LDB     (input) INTEGER
              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 gen-
              eralized eigenvalues.

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

      VL      (output) COMPLEX*16 array, dimension (LDVL,N)
              If JOBVL = 'V', the left generalized eigenvectors.
              (See "Purpose", above.) Each eigenvector will be
              scaled so the largest component will have abs(real
              part) + abs(imag. part) = 1, *except* that for
              eigenvalues with alpha=beta=0, a zero vector will be
              returned as the corresponding eigenvector.  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 JOBVL = 'V', the right generalized eigenvectors.
              (See "Purpose", above.) Each eigenvector will be
              scaled so the largest component will have abs(real
              part) + abs(imag. part) = 1, *except* that for
              eigenvalues with alpha=beta=0, a zero vector will be
              returned as the corresponding eigenvector.  Not
              referenced if JOBVR = 'N'.

      LDVR    (input) INTEGER
              The leading dimension of the matrix VR. LDVR >= 1,
              and if JOBVR = 'V', LDVR >= 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.  To compute the optimal value of
              LWORK, call ILAENV to get blocksizes (for ZGEQRF,
              ZUNMQR, and CUNGQR.)  Then compute: NB  -- MAX of
              the blocksizes for ZGEQRF, ZUNMQR, and CUNGQR; The
              optimal LWORK is  MAX( 2*N, N*(NB+1) ).

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

      INFO    (output) INTEGER
              = 0:  successful exit
              < 0:  if INFO = -i, the i-th argument had an illegal
              value.
              =1,...,N: The QZ iteration failed.  No eigenvectors
              have been calculated, but ALPHA(j) and BETA(j)
              should be correct for j=INFO+1,...,N.  > N:  errors
              that usually indicate LAPACK problems:
              =N+1: error return from ZGGBAL
              =N+2: error return from ZGEQRF
              =N+3: error return from ZUNMQR
              =N+4: error return from ZUNGQR
              =N+5: error return from ZGGHRD
              =N+6: error return from ZHGEQZ (other than failed
              iteration) =N+7: error return from ZTGEVC
              =N+8: error return from ZGGBAK (computing VL)
              =N+9: error return from ZGGBAK (computing VR)
              =N+10: error return from ZLASCL (various calls)

 FURTHER DETAILS
      Balancing
      ---------

      This driver calls ZGGBAL to both permute and scale rows and
      columns of A and B.  The permutations PL and PR are chosen
      so that PL*A*PR and PL*B*R will be upper triangular except
      for the diagonal blocks A(i:j,i:j) and B(i:j,i:j), with i
      and j as close together as possible.  The diagonal scaling
      matrices DL and DR are chosen so that the pair
      DL*PL*A*PR*DR, DL*PL*B*PR*DR have entries close to one
      (except for the entries that start out zero.)

      After the eigenvalues and eigenvectors of the balanced
      matrices have been computed, ZGGBAK transforms the eigenvec-
      tors back to what they would have been (in perfect arith-
      metic) if they had not been balanced.

      Contents of A and B on Exit
      -------- -- - --- - -- ----

      If any eigenvectors are computed (either JOBVL='V' or
      JOBVR='V' or both), then on exit the arrays A and B will
      contain the complex Schur form[*] of the "balanced" versions
      of A and B.  If no eigenvectors are computed, then only the
      diagonal blocks will be correct.

      [*] In other words, upper triangular form.