DTREVC  -  compute  some  or  all of the right and/or left
       eigenvectors of a real upper quasi-triangular matrix T


SYNOPSIS

       SUBROUTINE DTREVC( SIDE, HOWMNY, SELECT, N,  T,  LDT,  VL,
                          LDVL, VR, LDVR, MM, M, WORK, INFO )

           CHARACTER      HOWMNY, SIDE

           INTEGER        INFO, LDT, LDVL, LDVR, M, MM, N

           LOGICAL        SELECT( * )

           DOUBLE         PRECISION  T(  LDT, * ), VL( LDVL, * ),
                          VR( LDVR, * ), WORK( * )


PURPOSE

       DTREVC computes some or  all  of  the  right  and/or  left
       eigenvectors  of  a  real upper quasi-triangular matrix T.
       The right eigenvector x and the left eigenvector  y  of  T
       corresponding to an eigenvalue w are defined by:

                    T*x = w*x,     y'*T = w*y'

       where  y' denotes the conjugate transpose of the vector y.

       If all eigenvectors are requested, the routine may  either
       return  the matrices X and/or Y of right or left eigenvec­
       tors of T, or the products Q*X and/or Q*Y, where Q  is  an
       input orthogonal
       matrix.  If  T was obtained from the real-Schur factoriza­
       tion of an original matrix A = Q*T*Q', then  Q*X  and  Q*Y
       are the matrices of right or left eigenvectors of A.

       T must be in Schur canonical form (as returned by DHSEQR),
       that is, block upper triangular  with  1-by-1  and  2-by-2
       diagonal blocks; each 2-by-2 diagonal block has its diago­
       nal elements equal and its off-diagonal elements of  oppo­
       site sign.  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 corresponding to the eigenvalue with  positive  imagi­
       nary part.


ARGUMENTS

       SIDE    (input) CHARACTER*1
               = '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

               =  'B':   compute  all right and/or left eigenvec­
               tors,  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/output) 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 a 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.;  then  on  exit
               SELECT(j) is .TRUE. and SELECT(j+1) is .FALSE..

       N       (input) INTEGER
               The order of the matrix T. N >= 0.

       T       (input) DOUBLE PRECISION array, dimension (LDT,N)
               The  upper  quasi-triangular  matrix  T  in  Schur
               canonical form.

       LDT     (input) INTEGER
               The leading dimension  of  the  array  T.  LDT  >=
               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 Schur vectors returned by
               DHSEQR).  On exit, if SIDE = 'L' or 'B',  VL  con­
               tains:  if  HOWMNY  =  'A',  the  matrix Y of left
               eigenvectors of T; VL  has  the  same  quasi-lower
               triangular  form as T'. If T(i,i) is a real eigen­
               value, then the i-th column VL(i) of  VL   is  its
               corresponding  eigenvector. If T(i:i+1,i:i+1) is a
               2-by-2 block whose eigenvalues are  complex-conju­
               gate eigenvalues of T, then VL(i)+sqrt(-1)*VL(i+1)
               is the complex eigenvector  corresponding  to  the
               eigenvalue  with  positive real part.  if HOWMNY =
               'B', the matrix Q*Y; if HOWMNY  =  'S',  the  left
               eigenvectors of T specified by SELECT, stored con­
               secutively in the columns of VL, in the same order
               as  their eigenvalues.  A complex eigenvector cor­
               responding to a complex eigenvalue  is  stored  in
               two  consecutive  columns,  the  first holding the
               real part, and the second the imaginary part.   If
               SIDE = 'R', VL is not referenced.

               The  leading  dimension  of the 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  Q of Schur vectors returned by
               DHSEQR).  On exit, if SIDE = 'R' or 'B',  VR  con­
               tains:  if  HOWMNY  =  'A',  the matrix X of right
               eigenvectors of T; VR  has  the  same  quasi-upper
               triangular  form  as T. If T(i,i) is a real eigen­
               value, then the i-th column VR(i) of  VR   is  its
               corresponding  eigenvector. If T(i:i+1,i:i+1) is a
               2-by-2 block whose eigenvalues are  complex-conju­
               gate eigenvalues of T, then VR(i)+sqrt(-1)*VR(i+1)
               is the complex eigenvector  corresponding  to  the
               eigenvalue  with  positive real part.  if HOWMNY =
               'B', the matrix Q*X; if HOWMNY =  'S',  the  right
               eigenvectors of T specified by SELECT, stored con­
               secutively in the columns of VR, in the same order
               as  their eigenvalues.  A complex eigenvector cor­
               responding to a complex eigenvalue  is  stored  in
               two  consecutive  columns,  the  first holding the
               real part and the second the imaginary  part.   If
               SIDE = 'L', VR is not referenced.

       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
               (3*N)

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

       The  algorithm  used in this program is basically backward
       (forward) substitution, with scaling to make the the  code
       robust against possible overflow.

       Each  eigenvector  is  normalized  so  that the element of
       largest magnitude has magnitude 1; here the magnitude of a
       complex number (x,y) is taken to be |x| + |y|.


Man(1) output converted with man2html