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


SYNOPSIS

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

           CHARACTER      JOBZ, RANGE, UPLO

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

           REAL           ABSTOL, VL, VU

           INTEGER        ISUPPZ( * ), IWORK( * )

           REAL           A( LDA, * ), W( * ), WORK( * ), Z( LDZ,
                          * )


PURPOSE

       SSYEVR  computes  selected  eigenvalues  and,  optionally,
       eigenvectors of a real symmetric matrix T. Eigenvalues and
       eigenvectors can be selected by specifying either a  range
       of  values or a range of indices for the desired eigenval­
       ues.

       Whenever possible, SSYEVR calls SSTEGR to compute the
       eigenspectrum  using  Relatively  Robust  Representations.
       SSTEGR  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

       Inderjit  Dhillon,  Computer  Science  Division  Technical
       Report No. UCB//CSD-97-971, UC Berkeley, May 1997.

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

       Normal execution of SSTEGR 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) REAL array, dimension (LDA, N)
               On  entry, the symmetric 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 =
               'A' or 'I'.

               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) REAL 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',
               then  Z  is  not  referenced.  Note: the user must
               ensure that at least max(1,M) columns are supplied

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

       LWORK   (input) INTEGER
               The  dimension  of  the  array  WORK.   LWORK   >=
               max(1,26*N).   For  optimal  efficiency,  LWORK >=
               (NB+6)*N, where NB is the max of the blocksize for
               SSYTRD and SORMTR 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.

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

       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:  Internal error


FURTHER DETAILS

       Based on contributions by
          Inderjit Dhillon, IBM Almaden, USA

          Ken Stanley, Computer Science Division, University of
            California at Berkeley, USA


Man(1) output converted with man2html