SHSEIN  -  use  inverse  iteration to find specified right
       and/or left eigenvectors of a real upper Hessenberg matrix
       H


SYNOPSIS

       SUBROUTINE SHSEIN( SIDE, EIGSRC, INITV, SELECT, N, H, LDH,
                          WR, WI, VL,  LDVL,  VR,  LDVR,  MM,  M,
                          WORK, IFAILL, IFAILR, INFO )

           CHARACTER      EIGSRC, INITV, SIDE

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

           LOGICAL        SELECT( * )

           INTEGER        IFAILL( * ), IFAILR( * )

           REAL           H( LDH, * ), VL( LDVL, * ), VR( LDVR, *
                          ), WI( * ), WORK( * ), WR( * )


PURPOSE

       SHSEIN uses inverse  iteration  to  find  specified  right
       and/or left eigenvectors of a real upper Hessenberg matrix
       H.  The right eigenvector x and the left eigenvector y  of
       the  matrix H corresponding to an eigenvalue w are defined
       by:

                    H * x = w * x,     y**h * H = w * y**h

       where y**h denotes the conjugate transpose of  the  vector
       y.


ARGUMENTS

       SIDE    (input) CHARACTER*1
               = 'R': compute right eigenvectors only;
               = 'L': compute left eigenvectors only;
               = 'B': compute both right and left eigenvectors.

       EIGSRC  (input) CHARACTER*1
               Specifies  the  source  of eigenvalues supplied in
               (WR,WI):
               = 'Q': the eigenvalues were  found  using  SHSEQR;
               thus,  if  H has zero subdiagonal elements, and so
               is block-triangular, then the j-th eigenvalue  can
               be  assumed  to be an eigenvalue of the block con­
               taining the j-th row/column.  This property allows
               SHSEIN  to  perform  inverse iteration on just one
               diagonal block.  = 'N': no assumptions are made on
               the  correspondence between eigenvalues and diago­
               nal blocks.  In this case, SHSEIN must always per­
               form inverse iteration using the whole matrix H.

               = 'N': no initial vectors are supplied;
               = 'U': user-supplied initial vectors are stored in
               the arrays VL and/or VR.

       SELECT  (input/output) LOGICAL array, dimension (N)
               Specifies the  eigenvectors  to  be  computed.  To
               select  the  real  eigenvector  corresponding to a
               real eigenvalue WR(j), SELECT(j) must  be  set  to
               .TRUE..  To  select the complex eigenvector corre­
               sponding to a  complex  eigenvalue  (WR(j),WI(j)),
               with  complex  conjugate (WR(j+1),WI(j+1)), either
               SELECT(j) or SELECT(j+1) or both must be set to

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

       H       (input) REAL array, dimension (LDH,N)
               The upper Hessenberg matrix H.

       LDH     (input) INTEGER
               The leading dimension of  the  array  H.   LDH  >=
               max(1,N).

       WR      (input/output) REAL array, dimension (N)
               WI       (input)  REAL  array,  dimension  (N)  On
               entry, the real and imaginary parts of the  eigen­
               values of H; a complex conjugate pair of eigenval­
               ues must be stored in consecutive elements  of  WR
               and  WI.   On exit, WR may have been altered since
               close  eigenvalues  are  perturbed   slightly   in
               searching for independent eigenvectors.

       VL      (input/output) REAL array, dimension (LDVL,MM)
               On entry, if INITV = 'U' and SIDE = 'L' or 'B', VL
               must contain  starting  vectors  for  the  inverse
               iteration  for the left eigenvectors; the starting
               vector for each eigenvector must be  in  the  same
               column(s) in which the eigenvector will be stored.
               On exit, if SIDE = 'L' or 'B', the left  eigenvec­
               tors  specified  by SELECT will be stored consecu­
               tively in the columns of VL, in the same order  as
               their  eigenvalues.  A  complex eigenvector corre­
               sponding 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.

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

               On entry, if INITV = 'U' and SIDE = 'R' or 'B', VR
               must contain  starting  vectors  for  the  inverse
               iteration for the right eigenvectors; the starting
               vector for each eigenvector must be  in  the  same
               column(s) in which the eigenvector will be stored.
               On exit, if SIDE = 'R' or 'B', the right eigenvec­
               tors  specified  by SELECT will be stored consecu­
               tively in the columns of VR, in the same order  as
               their  eigenvalues.  A  complex eigenvector corre­
               sponding 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
               required  to store the eigenvectors; each selected
               real eigenvector  occupies  one  column  and  each
               selected complex eigenvector occupies two columns.

       WORK    (workspace) REAL array, dimension ((N+2)*N)

       IFAILL  (output) INTEGER array, dimension (MM)
               If SIDE = 'L' or 'B', IFAILL(i) = j  >  0  if  the
               left  eigenvector in the i-th column of VL (corre­
               sponding to the eigenvalue w(j))  failed  to  con­
               verge;  IFAILL(i) = 0 if the eigenvector converged
               satisfactorily. If the i-th and (i+1)th columns of
               VL  hold a complex eigenvector, then IFAILL(i) and
               IFAILL(i+1) are set to the same value.  If SIDE  =
               'R', IFAILL is not referenced.

       IFAILR  (output) INTEGER array, dimension (MM)
               If  SIDE  =  'R'  or 'B', IFAILR(i) = j > 0 if the
               right eigenvector in the i-th column of VR (corre­
               sponding  to  the  eigenvalue w(j)) failed to con­
               verge; IFAILR(i) = 0 if the eigenvector  converged
               satisfactorily. If the i-th and (i+1)th columns of
               VR hold a complex eigenvector, then IFAILR(i)  and
               IFAILR(i+1)  are set to the same value.  If SIDE =
               'L', IFAILR is not referenced.

       INFO    (output) INTEGER
               = 0:  successful exit

               gal value
               > 0:  if INFO = i, i is the number of eigenvectors
               which failed to converge; see  IFAILL  and  IFAILR
               for further details.


FURTHER DETAILS

       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