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


SYNOPSIS

       SUBROUTINE ZHEEVR( 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

           DOUBLE         PRECISION ABSTOL, VL, VU

           INTEGER        ISUPPZ( * ), IWORK( * )

           DOUBLE         PRECISION RWORK( * ), W( * )

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


PURPOSE

       ZHEEVR  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, ZHEEVR calls ZSTEGR to compute the
       eigenspectrum  using  Relatively  Robust  Representations.
       ZSTEGR  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  :  ZHEEVR  calls ZSTEGR when the full spectrum is
       requested on machines which conform to the ieee-754 float­
       ing  point  standard.   ZHEEVR  calls DSTEBZ and ZSTEIN on
       non-ieee machines and
       when partial spectrum requests are made.

       Normal execution of ZSTEGR 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*16 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) DOUBLE PRECISION
               VU      (input) DOUBLE PRECISION If RANGE='V', the
               lower  and  upper  bounds  of  the  interval to be

               if RANGE = 'A' or 'I'.

       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) DOUBLE PRECISION
               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  DLAMCH( '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) DOUBLE PRECISION array, dimension (N)
               The first M elements contain the  selected  eigen­
               values in ascending order.

       Z       (output) COMPLEX*16 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

               eigenvector associated with W(i).  If JOBZ =  'N',
               then  Z  is  not  referenced.  Note: the user must
               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*16 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
               ZHETRD and for ZUNMTR 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)  DOUBLE  PRECISION  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.

               max(1,10*N).

               If LIWORK = -1, then a workspace query is assumed;
               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