DTGEVC - compute some or all of the right and/or left gen­
       eralized eigenvectors of a pair of real  upper  triangular
       matrices (A,B)


SYNOPSIS

       SUBROUTINE DTGEVC( SIDE,  HOWMNY,  SELECT,  N,  A, LDA, B,
                          LDB, VL, LDVL, VR, LDVR, MM,  M,  WORK,
                          INFO )

           CHARACTER      HOWMNY, SIDE

           INTEGER        INFO, LDA, LDB, LDVL, LDVR, M, MM, N

           LOGICAL        SELECT( * )

           DOUBLE         PRECISION A( LDA, * ), B( LDB, * ), VL(
                          LDVL, * ), VR( LDVR, * ), WORK( * )


PURPOSE

       DTGEVC computes some or all of the right and/or left  gen­
       eralized  eigenvectors  of a pair of real upper triangular
       matrices (A,B).  The right generalized eigenvector  x  and
       the  left generalized eigenvector y of (A,B) corresponding
       to a generalized eigenvalue w are defined by:

               (A - wB) * x = 0  and  y**H * (A - wB) = 0

       where y**H denotes the conjugate tranpose of y.

       If an eigenvalue w is determined by zero diagonal elements
       of  both  A and B, a unit vector is returned as the corre­
       sponding eigenvector.

       If all eigenvectors are requested, the routine may  either
       return  the matrices X and/or Y of right or left eigenvec­
       tors of (A,B), or the products Z*X and/or Q*Y, where Z and
       Q  are  input  orthogonal matrices.  If (A,B) was obtained
       from the generalized real-Schur factorization of an origi­
       nal pair of matrices
          (A0,B0) = (Q*A*Z**H,Q*B*Z**H),
       then  Z*X and Q*Y are the matrices of right or left eigen­
       vectors of A.

       A must be block upper triangular, with 1-by-1  and  2-by-2
       diagonal  blocks.   Corresponding  to each 2-by-2 diagonal
       block is a  complex  conjugate  pair  of  eigenvalues  and
       eigenvectors; only one
       eigenvector of the pair is computed, namely the one corre­
       sponding to the eigenvalue with positive imaginary part.


ARGUMENTS


               = 'R': compute right eigenvectors only;
               = 'L': compute left eigenvectors only;
               = 'B': compute both right and left eigenvectors.

       HOWMNY  (input) CHARACTER*1
               = 'A': compute all right and/or left eigenvectors;
               = 'B': compute all right and/or left eigenvectors,
               and backtransform them using  the  input  matrices
               supplied  in VR and/or VL; = 'S': compute selected
               right and/or left eigenvectors, specified  by  the
               logical array SELECT.

       SELECT  (input) LOGICAL array, dimension (N)
               If  HOWMNY='S',  SELECT specifies the eigenvectors
               to be computed.  If HOWMNY='A' or 'B',  SELECT  is
               not  referenced.   To  select the real eigenvector
               corresponding  to  the   real   eigenvalue   w(j),
               SELECT(j)  must  be  set  to .TRUE.  To select the
               complex eigenvector  corresponding  to  a  complex
               conjugate  pair  w(j) and w(j+1), either SELECT(j)
               or SELECT(j+1) must be set to .TRUE..

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

       A       (input) DOUBLE PRECISION array, dimension (LDA,N)
               The upper quasi-triangular matrix A.

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

       B       (input) DOUBLE PRECISION array, dimension (LDB,N)
               The  upper triangular matrix B.  If A has a 2-by-2
               diagonal  block,  then  the  corresponding  2-by-2
               block  of  B  must  be diagonal with positive ele­
               ments.

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

       VL        (input/output)   DOUBLE   PRECISION   array,
               dimension (LDVL,MM)
               On  entry,  if SIDE = 'L' or 'B' and HOWMNY = 'B',
               VL must contain an N-by-N matrix  Q  (usually  the
               orthogonal matrix Q of left Schur vectors returned
               by DHGEQZ).  On exit, if SIDE =  'L'  or  'B',  VL
               contains:  if  HOWMNY  = 'A', the matrix Y of left
               eigenvectors of (A,B); if HOWMNY = 'B', the matrix
               Q*Y;  if  HOWMNY  =  'S', the left eigenvectors of
               (A,B) specified by SELECT, stored consecutively in
               the  columns  of  VL,  in  the same order as their


               A  complex  eigenvector corresponding to a complex
               eigenvalue is stored in two  consecutive  columns,
               the  first  holding  the real part, and the second
               the imaginary part.

       LDVL    (input) INTEGER
               The  leading  dimension  of  array  VL.   LDVL  >=
               max(1,N)  if  SIDE  = 'L' or 'B'; LDVL >= 1 other­
               wise.

       VR       (input/output)   DOUBLE   PRECISION   array,
               dimension (LDVR,MM)
               On entry, if SIDE = 'R' or 'B' and HOWMNY  =  'B',
               VR  must  contain  an N-by-N matrix Q (usually the
               orthogonal  matrix  Z  of  right   Schur   vectors
               returned  by  DHGEQZ).   On exit, if SIDE = 'R' or
               'B', VR contains: if HOWMNY = 'A', the matrix X of
               right  eigenvectors of (A,B); if HOWMNY = 'B', the
               matrix Z*X; if HOWMNY = 'S', the  right  eigenvec­
               tors of (A,B) specified by SELECT, stored consecu­
               tively in the columns of VR, in the same order  as
               their  eigenvalues.  If SIDE = 'L', VR is not ref­
               erenced.

               A complex eigenvector corresponding to  a  complex
               eigenvalue  is  stored in two consecutive columns,
               the first holding the real part and the second the
               imaginary part.

       LDVR    (input) INTEGER
               The  leading  dimension  of the array VR.  LDVR >=
               max(1,N) if SIDE = 'R' or 'B'; LDVR  >=  1  other­
               wise.

       MM      (input) INTEGER
               The  number of columns in the arrays VL and/or VR.
               MM >= M.

       M       (output) INTEGER
               The number of columns in the arrays VL  and/or  VR
               actually  used  to  store  the  eigenvectors.   If
               HOWMNY = 'A' or 'B', M is set to N.  Each selected
               real  eigenvector  occupies  one  column  and each
               selected complex eigenvector occupies two columns.

       WORK    (workspace) DOUBLE PRECISION array, dimension
               (6*N)

       INFO    (output) INTEGER
               = 0:  successful exit.
               < 0:  if INFO = -i, the i-th argument had an ille­
               gal value.

               a complex eigenvalue.


FURTHER DETAILS

       Allocation of workspace:
       ---------- -- ---------

          WORK( j ) = 1-norm of j-th column of A, above the diag­
       onal
          WORK(  N+j  )  =  1-norm of j-th column of B, above the
       diagonal
          WORK( 2*N+1:3*N ) = real part of eigenvector
          WORK( 3*N+1:4*N ) = imaginary part of eigenvector
          WORK( 4*N+1:5*N  )  =  real  part  of  back-transformed
       eigenvector
          WORK(  5*N+1:6*N ) = imaginary part of back-transformed
       eigenvector

       Rowwise vs. columnwise solution methods:
       ------- --  ---------- -------- -------

       Finding a generalized eigenvector  consists  basically  of
       solving the singular triangular system

        (A  - w B) x = 0     (for right) or:   (A - w B)**H y = 0
       (for left)

       Consider finding the i-th right  eigenvector  (assume  all
       eigenvalues are real). The equation to be solved is:
            n                   i
       0 = sum  C(j,k) v(k)  = sum  C(j,k) v(k)     for j = i,. .
       .,1
           k=j                 k=j

       where  C = (A - w B)  (The components v(i+1:n) are 0.)

       The "rowwise" method is:

       (1)  v(i) := 1
       for j = i-1,. . .,1:
                               i
           (2) compute  s = - sum C(j,k) v(k)   and
                             k=j+1

           (3) v(j) := s / C(j,j)

       Step 2 is sometimes called the "dot product"  step,  since
       it  is  an inner product between the j-th row and the por­
       tion of the eigenvector that has been computed so far.

       The "columnwise" method consists basically  in  doing  the
       sums  for  all the rows in parallel.  As each v(j) is com­
       puted, the contribution of v(j) times the j-th column of C
       is  added  to  the partial sums.  Since FORTRAN arrays are

       step,  the elements of C that are accessed are adjacent to
       one another, whereas with the rowwise method, the elements
       accessed at a step are spaced LDA (and LDB) words apart.

       When  finding left eigenvectors, the matrix in question is
       the transpose of the one in storage, so the rowwise method
       then  actually  accesses  columns of A and B at each step,
       and so is the preferred method.


Man(1) output converted with man2html