CHEEVR  -  compute  selected  eigenvalues and, optionally,
       eigenvectors of a complex Hermitian matrix T


SYNOPSIS

       SUBROUTINE CHEEVR( JOBZ, RANGE, UPLO, N, A, LDA,  VL,  VU,
                          IL,  IU,  ABSTOL, M, W, Z, LDZ, ISUPPZ,
                          WORK,  LWORK,  RWORK,  LRWORK,   IWORK,
                          LIWORK, INFO )

           CHARACTER      JOBZ, RANGE, UPLO

           INTEGER        IL, INFO, IU, LDA, LDZ, LIWORK, LRWORK,
                          LWORK, M, N

           REAL           ABSTOL, VL, VU

           INTEGER        ISUPPZ( * ), IWORK( * )

           REAL           RWORK( * ), W( * )

           COMPLEX        A( LDA, * ), WORK( * ), Z( LDZ, * )


PURPOSE

       CHEEVR  computes  selected  eigenvalues  and,  optionally,
       eigenvectors  of a complex Hermitian matrix T. Eigenvalues
       and eigenvectors can be selected by  specifying  either  a
       range  of  values  or  a  range of indices for the desired
       eigenvalues.

       Whenever possible, CHEEVR calls CSTEGR to compute the
       eigenspectrum  using  Relatively  Robust  Representations.
       CSTEGR  computes  eigenvalues by the dqds algorithm, while
       orthogonal eigenvectors are computed from various "good" L
       D  L^T  representations  (also  known as Relatively Robust
       Representations).   Gram-Schmidt   orthogonalization    is
       avoided as far as possible. More specifically, the various
       steps of the algorithm are as follows. For the i-th  unre­
       duced block of T,
          (a)  Compute T - sigma_i = L_i D_i L_i^T, such that L_i
       D_i L_i^T
               is a relatively robust representation,
          (b) Compute the eigenvalues, lambda_j, of L_i D_i L_i^T
       to high
              relative accuracy by the dqds algorithm,
          (c)  If  there  is  a  cluster  of  close  eigenvalues,
       "choose" sigma_i
              close to the cluster, and go to step (a),
          (d) Given the approximate eigenvalue  lambda_j  of  L_i
       D_i L_i^T,
              compute the corresponding eigenvector by forming a
              rank-revealing twisted factorization.
       The desired accuracy of the output can be specified by the
       input parameter ABSTOL.

       metric  tridiagonal  eigenvalue/eigenvector  problem",  by
       Inderjit  Dhillon,  Computer  Science  Division  Technical
       Report No. UCB//CSD-97-971, UC Berkeley, May 1997.

       Note  1  :  CHEEVR  calls CSTEGR when the full spectrum is
       requested on machines which conform to the ieee-754 float­
       ing  point  standard.   CHEEVR  calls SSTEBZ and CSTEIN on
       non-ieee machines and
       when partial spectrum requests are made.

       Normal execution of CSTEGR may create NaNs and  infinities
       and  hence  may abort due to a floating point exception in
       environments which do not handle NaNs  and  infinities  in
       the ieee standard default manner.


ARGUMENTS

       JOBZ    (input) CHARACTER*1
               = 'N':  Compute eigenvalues only;
               = 'V':  Compute eigenvalues and eigenvectors.

       RANGE   (input) CHARACTER*1
               = 'A': all eigenvalues will be found.
               =  'V':  all eigenvalues in the half-open interval
               (VL,VU] will be found.  = 'I': the  IL-th  through
               IU-th eigenvalues will be found.

       UPLO    (input) CHARACTER*1
               = 'U':  Upper triangle of A is stored;
               = 'L':  Lower triangle of A is stored.

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

       A       (input/output) COMPLEX array, dimension (LDA, N)
               On  entry, the Hermitian matrix A.  If UPLO = 'U',
               the leading N-by-N upper triangular part of A con­
               tains  the  upper triangular part of the matrix A.
               If UPLO = 'L', the leading N-by-N lower triangular
               part  of  A  contains the lower triangular part of
               the matrix A.  On exit,  the  lower  triangle  (if
               UPLO='L')  or  the upper triangle (if UPLO='U') of
               A, including the diagonal, is destroyed.

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

       VL      (input) REAL
               VU       (input)  REAL If RANGE='V', the lower and
               upper bounds of the interval to  be  searched  for
               eigenvalues.  VL  < VU.  Not referenced if RANGE =


       IL      (input) INTEGER
               IU      (input) INTEGER If RANGE='I', the  indices
               (in  ascending  order) of the smallest and largest
               eigenvalues to be returned.  1 <= IL <= IU  <=  N,
               if  N > 0; IL = 1 and IU = 0 if N = 0.  Not refer­
               enced if RANGE = 'A' or 'V'.

       ABSTOL  (input) REAL
               The absolute error tolerance for the  eigenvalues.
               An approximate eigenvalue is accepted as converged
               when it is determined to lie in an interval  [a,b]
               of width less than or equal to

               ABSTOL + EPS *   max( |a|,|b| ) ,

               where  EPS is the machine precision.  If ABSTOL is
               less than or equal to zero, then  EPS*|T|  will be
               used  in its place, where |T| is the 1-norm of the
               tridiagonal  matrix  obtained  by  reducing  A  to
               tridiagonal form.

               See "Computing Small Singular Values of Bidiagonal
               Matrices with Guaranteed High Relative  Accuracy,"
               by Demmel and Kahan, LAPACK Working Note #3.

               If high relative accuracy is important, set ABSTOL
               to SLAMCH( 'Safe minimum' ).  Doing so will  guar­
               antee  that eigenvalues are computed to high rela­
               tive accuracy when possible  in  future  releases.
               The  current  code  does  not  make any guarantees
               about high relative accuracy, but furutre releases
               will.  See  J.  Barlow  and  J. Demmel, "Computing
               Accurate Eigensystems of Scaled  Diagonally  Domi­
               nant Matrices", LAPACK Working Note #7, for a dis­
               cussion of which matrices define their eigenvalues
               to high relative accuracy.

       M       (output) INTEGER
               The  total number of eigenvalues found.  0 <= M <=
               N.  If RANGE = 'A', M = N, and if RANGE = 'I', M =
               IU-IL+1.

       W       (output) REAL array, dimension (N)
               The  first  M elements contain the selected eigen­
               values in ascending order.

       Z       (output) COMPLEX array, dimension (LDZ, max(1,M))
               If JOBZ = 'V', then if  INFO  =  0,  the  first  M
               columns  of Z contain the orthonormal eigenvectors
               of the matrix  A  corresponding  to  the  selected
               eigenvalues, with the i-th column of Z holding the
               eigenvector associated with W(i).  If JOBZ =  'N',

               ensure that at least max(1,M) columns are supplied
               in the array Z; if RANGE = 'V', the exact value of
               M is not known in advance and an upper bound  must
               be used.

       LDZ     (input) INTEGER
               The  leading  dimension of the array Z.  LDZ >= 1,
               and if JOBZ = 'V', LDZ >= max(1,N).

       ISUPPZ  (output) INTEGER ARRAY, dimension ( 2*max(1,M) )
               The support of the eigenvectors in  Z,  i.e.,  the
               indices  indicating the nonzero elements in Z. The
               i-th  eigenvector  is  nonzero  only  in  elements
               ISUPPZ( 2*i-1 ) through ISUPPZ( 2*i ).

       WORK    (workspace/output) COMPLEX array, dimension
               (LWORK)
               On exit, if INFO = 0, WORK(1) returns the  optimal
               LWORK.

       LWORK   (input) INTEGER
               The   length   of   the   array  WORK.   LWORK  >=
               max(1,2*N).   For  optimal  efficiency,  LWORK  >=
               (NB+1)*N, where NB is the max of the blocksize for
               CHETRD and for CUNMTR as returned by ILAENV.

               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/output) REAL array, dimension (LRWORK)
               On exit, if INFO = 0, RWORK(1) returns the optimal
               (and minimal) LRWORK.

               The   length   of  the  array  RWORK.   LRWORK  >=
               max(1,24*N).

               If LRWORK = -1, then a workspace query is assumed;
               the  routine  only  calculates the optimal size of
               the RWORK array, returns this value as  the  first
               entry  of  the  RWORK  array, and no error message
               related to LRWORK is issued by XERBLA.

       IWORK   (workspace/output) INTEGER array, dimension
               (LIWORK)
               On exit, if INFO = 0, IWORK(1) returns the optimal
               (and minimal) LIWORK.

               The dimension  of  the  array  IWORK.   LIWORK  >=
               max(1,10*N).

               the routine only calculates the  optimal  size  of
               the  IWORK  array, returns this value as the first
               entry of the IWORK array,  and  no  error  message
               related to LIWORK is issued by XERBLA.

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


FURTHER DETAILS

       Based on contributions by
          Inderjit Dhillon, IBM Almaden, USA
          Osni Marques, LBNL/NERSC, USA
          Ken Stanley, Computer Science Division, University of
            California at Berkeley, USA


Man(1) output converted with man2html