# ?stebz

Computes selected eigenvalues of a real symmetric tridiagonal matrix by bisection.

## Syntax

FORTRAN 77:

call sstebz (range, order, n, vl, vu, il, iu, abstol, d, e, m, nsplit, w, iblock, isplit, work, iwork, info)

call dstebz (range, order, n, vl, vu, il, iu, abstol, d, e, m, nsplit, w, iblock, isplit, work, iwork, info)

Fortran 95:

call stebz(d, e, m, nsplit, w, iblock, isplit [, order] [,vl] [,vu] [,il] [,iu] [,abstol] [,info])

## Description

This routine computes some (or all) of the eigenvalues of a real symmetric tridiagonal matrix T by bisection. The routine searches for zero or negligible off-diagonal elements to see if T splits into block-diagonal form `T = diag(T1, T2, ...)`. Then it performs bisection on each of the blocks Ti and returns the block index of each computed eigenvalue, so that a subsequent call to ?stein can also take advantage of the block structure.

See also ?laebz.

## Input Parameters

range

  CHARACTER*1. Must be 'A' or 'V' or 'I'.

  If `range = 'A'`, the routine computes all eigenvalues.

  If `range = 'V'`, the routine computes eigenvalues lambda(i) in the half-open interval: `vl < lambda(i) ≤ vu`.

  If `range = 'I'`, the routine computes eigenvalues with indices il to iu.

order

  CHARACTER*1. Must be 'B' or 'E'.

  If `order = 'B'`, the eigenvalues are to be ordered from smallest to largest within each split-off block.

  If `order = 'E'`, the eigenvalues for the entire matrix are to be ordered from smallest to largest.

n

  INTEGER. The order of the matrix T (`n ≥ 0`).

vl, vu

  REAL for sstebz

  DOUBLE PRECISION for dstebz.

  If `range = 'V'`, the routine computes eigenvalues lambda(i) in the half-open interval:

  `vl < lambda(i) ≤ vu`.

  If `range = 'A'` or 'I', vl and vu are not referenced.

il, iu

  INTEGER. Constraint: `1 ≤ il ≤ iu ≤ n`.

  If `range = 'I'`, the routine computes eigenvalues lambda(i) such that `il≤ i ≤ iu` (assuming that the eigenvalues lambda(i) are in ascending order).

  If `range = 'A'` or 'V', il and iu are not referenced.

abstol

  REAL for sstebz

  DOUBLE PRECISION for dstebz.

  The absolute tolerance to which each eigenvalue is required. An eigenvalue (or cluster) is considered to have converged if it lies in an interval of width abstol.

  If `abstol ≤ 0.0`, then the tolerance is taken as `eps*|T|`, where `eps` is the machine precision, and `|T|` is the 1-norm of the matrix T.

d, e, work

  REAL for sstebz

  DOUBLE PRECISION for dstebz.

  Arrays:

  d(*) contains the diagonal elements of T.

  The dimension of d must be at least max(1, n).

  e(*) contains the off-diagonal elements of T.

  The dimension of e must be at least max(1, n-1).

  work(*) is a workspace array.

  The dimension of work must be at least max(1, 4n).

iwork

  INTEGER. Workspace.

  Array, DIMENSION at least max(1, 3n).

## Output Parameters

m

  INTEGER. The actual number of eigenvalues found.

nsplit

  INTEGER. The number of diagonal blocks detected in T.

w

  REAL for sstebz

  DOUBLE PRECISION for dstebz.

  Array, DIMENSION at least max(1, n). The computed eigenvalues, stored in `w(1)` to w(m).

iblock, isplit

  INTEGER.

  Arrays, DIMENSION at least max(1, n).

  A positive value iblock(i) is the block number of the eigenvalue stored in w(i) (see also info).

  The leading nsplit elements of isplit contain points at which T splits into blocks Ti as follows: the block T1 contains rows/columns 1 to `isplit(1)`; the block T2 contains rows/columns `isplit(1)+1` to `isplit(2)`, and so on.

info

  INTEGER.

  If `info = 0`, the execution is successful.

  If `info = 1`, for `range = 'A'` or 'V', the algorithm failed to compute some of the required eigenvalues to the desired accuracy; iblock(i)<0 indicates that the eigenvalue stored in w(i) failed to converge.

  If `info = 2`, for `range = 'I'`, the algorithm failed to compute some of the required eigenvalues. Try calling the routine again with `range = 'A'`.

  If `info = 3`:

  for `range = 'A'` or 'V', same as `info = 1`;

  for `range = 'I'`, same as `info = 2`.

  If `info = 4`, no eigenvalues have been computed. The floating-point arithmetic on the computer is not behaving as expected.

  If `info = -i`, the i-th parameter had an illegal value.

## Fortran 95 Interface Notes

Routines in Fortran 95 interface have fewer arguments in the calling sequence than their FORTRAN 77 counterparts. For general conventions applied to skip redundant or restorable arguments, see Fortran 95 Interface Conventions.

Specific details for the routine stebz interface are the following:

d

  Holds the vector of length (n).

e

  Holds the vector of length (n-1).

w

  Holds the vector of length (n).

iblock

  Holds the vector of length (n).

isplit

  Holds the vector of length (n).

order

  Must be 'B' or 'E'. The default value is 'B'.

vl

  Default value for this argument is vl = - HUGE (vl) where HUGE(a) means the largest machine number of the same precision as argument a.

vu

  Default value for this argument is `vu = HUGE (vl)`.

il

  Default value for this argument is `il = 1`.

iu

  Default value for this argument is `iu = n`.

abstol

  Default value for this argument is `abstol = 0.0_WP`.

range

  Restored based on the presence of arguments vl, vu, il, iu as follows:

  `range = 'V'`, if one of or both vl and vu are present,

  `range = 'I'`, if one of or both il and iu are present,

  `range = 'A'`, if none of vl, vu, il,

  iu is present, Note that there will be an error condition if one of or both vl and vu are present and at the same time one of or both il and iu are present.

## Application Notes

The eigenvalues of T are computed to high relative accuracy which means that if they vary widely in magnitude, then any small eigenvalues will be computed more accurately than, for example, with the standard QR method. However, the reduction to tridiagonal form (prior to calling the routine) may exclude the possibility of obtaining high relative accuracy in the small eigenvalues of the original matrix if its eigenvalues vary widely in magnitude.

Parent topic: Symmetric Eigenvalue Problems