SLARRD2(3)    ScaLAPACK routine of NEC Numeric Library Collection   SLARRD2(3)



NAME
       SLARRD2  - computes the eigenvalues of a symmetric tridiagonal matrix T
       to limited initial accuracy

SYNOPSIS
       SUBROUTINE SLARRD2( RANGE, ORDER, N, VL, VU, IL, IU, GERS,  RELTOL,  D,
                           E,  E2, PIVMIN, NSPLIT, ISPLIT, M, W, WERR, WL, WU,
                           IBLOCK, INDEXW, WORK, IWORK, DOL, DOU, INFO )

           CHARACTER       ORDER, RANGE

           INTEGER         DOL, DOU, IL, INFO, IU, M, N, NSPLIT

           REAL            PIVMIN, RELTOL, VL, VU, WL, WU

           INTEGER         IBLOCK( * ), INDEXW( * ), ISPLIT( * ), IWORK( * )

           REAL            D( * ), E( * ), E2( * ), GERS( * ), W( * ), WERR( *
                           ), WORK( * )

PURPOSE
       SLARRD2 computes the eigenvalues of a symmetric tridiagonal matrix T to
       limited initial accuracy. This is an auxiliary code to be  called  from
       SLARRE2A.

       SLARRD2  has  been  created  using  the LAPACK code SLARRD which itself
       stems from SSTEBZ. The motivation for creating SLARRD2  is  efficiency:
       When computing eigenvalues in parallel and the input tridiagonal matrix
       splits into blocks, SLARRD2 can skip over blocks which contain none  of
       the eigenvalues from DOL to DOU for which the processor responsible. In
       extreme cases (such as large matrices  consisting  of  many  blocks  of
       small size, e.g. 2x2, the gain can be substantial.


ARGUMENTS
       RANGE   (input) CHARACTER
               = 'A': ("All")   all eigenvalues will be found.
               = 'V': ("Value") all eigenvalues in the half-open interval
                                (VL, VU] will be found.
               = 'I': ("Index") the IL-th through IU-th eigenvalues (of the
                                entire matrix) will be found.

       ORDER   (input) CHARACTER
               = 'B': ("By Block") the eigenvalues will be grouped by
                                   split-off block (see IBLOCK, ISPLIT) and
                                   ordered from smallest to largest within
                                   the block.
               = 'E': ("Entire matrix")
                                   the eigenvalues for the entire matrix
                                   will be ordered from smallest to
                                   largest.

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

       VL      (input) REAL

       VU      (input) REAL
               If  RANGE='V', the lower and upper bounds of the interval to be
               searched for eigenvalues.  Eigenvalues less than  or  equal  to
               VL, or greater than VU, will not be returned.  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 referenced if RANGE = 'A' or 'V'.

       GERS    (input) REAL array, dimension (2*N)
               The N Gerschgorin intervals (the i-th Gerschgorin  interval  is
               (GERS(2*i-1), GERS(2*i)).

       RELTOL  (input) REAL
               The minimum relative width of an interval.  When an interval is
               narrower than RELTOL times the larger (in magnitude)  endpoint,
               then  it  is  considered  to  be sufficiently small, i.e., con-
               verged.  Note: this should always  be  at  least  radix*machine
               epsilon.

       D       (input) REAL array, dimension (N)
               The n diagonal elements of the tridiagonal matrix T.

       E       (input) REAL array, dimension (N-1)
               The (n-1) off-diagonal elements of the tridiagonal matrix T.

       E2      (input) REAL array, dimension (N-1)
               The  (n-1)  squared  off-diagonal  elements  of the tridiagonal
               matrix T.

       PIVMIN  (input) REAL
               The minimum pivot allowed in the sturm sequence for T.

       NSPLIT  (input) INTEGER
               The number of diagonal blocks in the matrix T.
               1 <= NSPLIT <= N.

       ISPLIT  (input) INTEGER array, dimension (N)
               The splitting points, at which T breaks up into submatrices.
               The first submatrix consists of rows/columns  1  to  ISPLIT(1),
               the second of rows/columns ISPLIT(1)+1 through ISPLIT(2), etc.,
               and the NSPLIT-th consists of  rows/columns  ISPLIT(NSPLIT-1)+1
               through ISPLIT(NSPLIT)=N.
               (Only  the  first  NSPLIT  elements  will actually be used, but
               since the user cannot know a  priori  what  value  NSPLIT  will
               have, N words must be reserved for ISPLIT.)

       M       (output) INTEGER
               The actual number of eigenvalues found. 0 <= M <= N.
               (See also the description of INFO=2,3.)

       W       (output) REAL array, dimension (N)
               On  exit, the first M elements of W will contain the eigenvalue
               approximations. SLARRD2 computes an interval I_j =  (a_j,  b_j]
               that  includes  eigenvalue  j.  The eigenvalue approximation is
               given as the interval midpoint W(j)= ( a_j + b_j)/2. The corre-
               sponding error is bounded by WERR(j) = abs( a_j - b_j)/2

       WERR    (output) REAL array, dimension (N)
               The  error  bound on the corresponding eigenvalue approximation
               in W.

       WL      (output) REAL

       WU      (output) REAL
               The interval (WL, WU] contains all the wanted eigenvalues.
               If RANGE='V', then WL=VL and WU=VU.
               If RANGE='A', then WL and WU are the global Gerschgorin bounds
                             on the spectrum.
               If RANGE='I', then WL and WU are computed by SLAEBZ from the
                             index range specified.

       IBLOCK  (output) INTEGER array, dimension (N)
               At each row/column j where E(j) is zero or small, the matrix  T
               is  considered to split into a block diagonal matrix.  On exit,
               if INFO = 0, IBLOCK(i) specifies to which block (from 1 to  the
               number  of  blocks)  the eigenvalue W(i) belongs.  (SLARRD2 may
               use the remaining N-M elements as workspace.)

       INDEXW  (output) INTEGER array, dimension (N)
               The indices of the eigenvalues within each  block  (submatrix);
               for  example,  INDEXW(i)= j and IBLOCK(i)=k imply that the i-th
               eigenvalue W(i) is the j-th eigenvalue in block k.

       WORK    (workspace) REAL array, dimension (4*N)

       IWORK   (workspace) INTEGER array, dimension (3*N)

       DOL     (input) INTEGER

       DOU     (input) INTEGER
               If the user wants to work on only a selected part of the repre-
               sentation tree, he can specify an index range DOL:DOU.
               Otherwise, the setting DOL=1, DOU=N should be applied.
               Note that DOL and DOU refer to the order in which the eigenval-
               ues are stored in W.

       INFO    (output) INTEGER
               = 0:  successful exit
               < 0:  if INFO = -i, the i-th argument had an illegal value
               > 0:  some or all of the eigenvalues failed to converge or
                     were not computed:
                     =1 or 3: Bisection failed to converge for some
                             eigenvalues; these eigenvalues are flagged by a
                             negative block number.  The effect is that the
                             eigenvalues may not be as accurate as the
                             absolute and relative tolerances.  This is
                             generally caused by unexpectedly inaccurate
                             arithmetic.
                     =2 or 3: RANGE='I' only: Not all of the eigenvalues
                             IL:IU were found.
                             Effect: M < IU+1-IL
                             Cause:  non-monotonic arithmetic, causing the
                                     Sturm sequence to be non-monotonic.
                             Cure:   recalculate, using RANGE='A', and pick
                                     out eigenvalues IL:IU.  In some cases,
                                     increasing the PARAMETER "FUDGE" may
                                     make things work.
                     = 4:    RANGE='I', and the Gershgorin interval
                             initially used was too small.  No eigenvalues
                             were computed.
                             Probable cause: your machine has sloppy
                                             floating-point arithmetic.
                             Cure: Increase the PARAMETER "FUDGE",
                                   recompile, and try again.

INTERNAL PARAMETERS
       FUDGE   REAL , default = 2 originally, increased to 10.
               A "fudge factor" to widen the Gershgorin intervals.  Ideally,
               a value of 1 should work, but on machines with sloppy
               arithmetic, this needs to be larger.  The default for
               publicly released versions should be large enough to handle
               the worst machine around.  Note that this has no effect
               on accuracy of the solution.



ScaLAPACK routine               31 October 2017                     SLARRD2(3)