DSTEVR  -  compute  selected  eigenvalues and, optionally,
       eigenvectors of a real symmetric tridiagonal matrix T


SYNOPSIS

       SUBROUTINE DSTEVR( JOBZ, RANGE, N, D, E, VL, VU,  IL,  IU,
                          ABSTOL,  M,  W,  Z,  LDZ, ISUPPZ, WORK,
                          LWORK, IWORK, LIWORK, INFO )

           CHARACTER      JOBZ, RANGE

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

           DOUBLE         PRECISION ABSTOL, VL, VU

           INTEGER        ISUPPZ( * ), IWORK( * )

           DOUBLE         PRECISION D( * ), E( * ), W( * ), WORK(
                          * ), Z( LDZ, * )


PURPOSE

       DSTEVR  computes  selected  eigenvalues  and,  optionally,
       eigenvectors of a real  symmetric  tridiagonal  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, DSTEVR calls SSTEGR to compute the
       eigenspectrum  using  Relatively  Robust  Representations.
       DSTEGR 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.

       For more details, see "A new O(n^2) algorithm for the sym­
       metric  tridiagonal  eigenvalue/eigenvector  problem",  by

       Report No. UCB//CSD-97-971, UC Berkeley, May 1997.

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

       Normal  execution of DSTEGR 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.

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

       D       (input/output) DOUBLE PRECISION array, dimension
               (N)
               On entry, the n diagonal elements of the tridiago­
               nal matrix A.  On exit, D may be multiplied  by  a
               constant  factor chosen to avoid over/underflow in
               computing the eigenvalues.

       E       (input/output) DOUBLE PRECISION array, dimension
               (N)
               On  entry,  the  (n-1) subdiagonal elements of the
               tridiagonal matrix A in elements 1 to  N-1  of  E;
               E(N)  need  not  be set.  On exit, E may be multi­
               plied  by  a  constant  factor  chosen  to   avoid
               over/underflow in computing the eigenvalues.

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

       IL      (input) INTEGER
               IU      (input) INTEGER If RANGE='I', the  indices
               (in  ascending  order) of the smallest and largest

               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 future  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) DOUBLE PRECISION 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).  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.

               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)  DOUBLE  PRECISION  array,
               dimension (LWORK)
               On exit, if INFO = 0, WORK(1) returns the  optimal
               (and minimal) LWORK.

       LWORK   (input) INTEGER
               The dimension of the array WORK.  LWORK >= 20*N.

               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.

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

       LIWORK  (input) INTEGER
               The dimension of the array IWORK.  LIWORK >= 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