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


SYNOPSIS

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

       DSTEGR  computes  selected  eigenvalues  and,  optionally,
       eigenvectors of a real  symmetric  tridiagonal  matrix  T.
       Eigenvalues and

          (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
       Inderjit  Dhillon,  Computer  Science  Division  Technical
       Report No. UCB/CSD-97-971, UC Berkeley, May 1997.

       Note 1 : Currently DSTEGR is only set up to find ALL the n
       eigenvalues and eigenvectors of T in O(n^2) time
       Note 2 : Currently the routine DSTEIN is  called  when  an

       DSTEIN invokes modified Gram-Schmidt when eigenvalues  are
       close.
       Note  3  :  DSTEGR  works  only  on  machines which follow
       ieee-754 floating-point  standard  in  their  handling  of
       infinities  and NaNs.  Normal execution of DSTEGR may cre­
       ate NaNs and infinities and  hence  may  abort  due  to  a
       floating point exception in environments which do not con­
       form to the ieee standard.


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 T. On exit, D is overwritten.

       E       (input/output) DOUBLE PRECISION array, dimension
               (N)
               On  entry,  the  (n-1) subdiagonal elements of the
               tridiagonal matrix T in elements 1 to  N-1  of  E;
               E(N)  need not be set.  On exit, E is overwritten.

       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
               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 eigenval­
               ues/eigenvectors. IF JOBZ = 'V',  the  eigenvalues
               and   eigenvectors   output  have  residual  norms
               bounded by ABSTOL, and the  dot  products  between

               ABSTOL is less than N*EPS*|T|, then N*EPS*|T| will
               be  used  in  its  place, where EPS is the machine
               precision and |T| is the 1-norm of the tridiagonal
               matrix.  The  eigenvalues are computed to an accu­
               racy of EPS*|T| irrespective of  ABSTOL.  If  high
               relative  accuracy  is  important,  set  ABSTOL to
               DLAMCH( 'Safe minimum' ).  See Barlow  and  Demmel
               "Computing  Accurate Eigensystems of Scaled Diago­
               nally Dominant Matrices", LAPACK Working  Note  #7
               for  a  discussion  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  T  corresponding  to the selected
               eigenvalues, with the i-th column of Z holding the
               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)  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  >=
               max(1,18*N)

               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
               LIWORK.

       LIWORK  (input) INTEGER
               The dimension  of  the  array  IWORK.   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:  if INFO = 1, internal error  in  DLARRE,  if
               INFO = 2, internal error in DLARRV.


FURTHER DETAILS

       Based on contributions by
          Inderjit Dhillon, IBM Almaden, USA
          Osni Marques, LBNL/NERSC, USA


Man(1) output converted with man2html