# p?stebz

Computes the eigenvalues of a symmetric tridiagonal matrix by bisection.

## Syntax

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

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

## Description

This routine computes the eigenvalues of a symmetric tridiagonal matrix in parallel. These may be all eigenvalues, all eigenvalues in the interval `[v1 vu]`, or the eigenvalues indexed il through iu. A static partitioning of work is done at the beginning of p?stebz which results in all processes finding an (almost) equal number of eigenvalues.

## Input Parameters

ictxt

  (global) INTEGER. The BLACS context handle.

range

  (global) CHARACTER. Must be 'A' or 'V' or 'I'.

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

  If `range = 'V'`, the routine computes eigenvalues in the interval `[v1, vu]`.

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

order

  (global) CHARACTER. 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

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

vl, vu

  (global)

  REAL for psstebz

  DOUBLE PRECISION for pdstebz.

  If `range = 'V'`, the routine computes the lower and the upper bounds for the eigenvalues on the interval `[1, vu]`.

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

il, iu

  (global)

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

  If `range = 'I'`, the index of the smallest eigenvalue is returned for il and of the largest eigenvalue for iu (assuming that the eigenvalues are in ascending order) must be returned. il must be at least 1. iu must be at least il and no greater than n.

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

abstol

  (global)

  REAL for psstebz

  DOUBLE PRECISION for pdstebz.

  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`, then the tolerance is taken as `ulp||T||`, where ulp is the machine precision, and `||T||` means the 1-norm of T

  Eigenvalues will be computed most accurately when abstol is set to the underflow threshold slamch('U'), not 0. Note that if eigenvectors are desired later by inverse iteration (p?stein), abstol should be set to `2*p?lamch('S')`.

d

  (global)

  REAL for psstebz

  DOUBLE PRECISION for pdstebz.

  Array, DIMENSION (n).

  Contains n diagonal elements of the tridiagonal matrix T. To avoid overflow, the matrix must be scaled so that its largest entry is no greater than the `overflow(1/2) * underflow(1/4)` in absolute value, and for greatest accuracy, it should not be much smaller than that.

e

  (global)

  REAL for psstebz

  DOUBLE PRECISION for pdstebz.

  Array, DIMENSION `(n - 1)`.

  Contains `(n-1)` off-diagonal elements of the tridiagonal matrix T. To avoid overflow, the matrix must be scaled so that its largest entry is no greater than `overflow(1/2) * underflow(1/4)` in absolute value, and for greatest accuracy, it should not be much smaller than that.

work

  (local)

  REAL for psstebz

  DOUBLE PRECISION for pdstebz.

  Array, DIMENSION `max(5n, 7)`. This is a workspace array.

lwork

  (local) INTEGER. The size of the work array must be `≥ max(5n, 7)`.

  If `lwork = -1`, then lwork is global input and a workspace query is assumed; the routine only calculates the minimum and optimal size for all work arrays. Each of these values is returned in the first entry of the corresponding work array, and no error message is issued by pxerbla.

iwork

  (local) INTEGER. Array, DIMENSION `max(4n, 14)`. This is a workspace array.

liwork

  (local) INTEGER. the size of the iwork array must ≥`max(4n, 14, NPROCS)`.

  If `liwork = -1`, then liwork is global input and a workspace query is assumed; the routine only calculates the minimum and optimal size for all work arrays. Each of these values is returned in the first entry of the corresponding work array, and no error message is issued by pxerbla.

## Output Parameters

m

  (global) INTEGER. The actual number of eigenvalues found. `0≤m≤n`

nsplit

  (global) INTEGER. The number of diagonal blocks detected in T. `1≤nsplit≤n`

w

  (global)

  REAL for psstebz

  DOUBLE PRECISION for pdstebz.

  Array, DIMENSION (n). On exit, the first m elements of w contain the eigenvalues on all processes.

iblock

  (global) 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 iblock(i) specifies which block (from 1 to the number of blocks) the eigenvalue w(i) belongs to.

  ### Note

  In the (theoretically impossible) event that bisection does not converge for some or all eigenvalues, info is set to 1 and the ones for which it did not are identified by a negative block number.

isplit

  (global) INTEGER.

  Array, DIMENSION (n).

  Contains 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 are used, but since the nsplit values are not known, n words must be reserved for isplit.)

info

  (global) INTEGER.

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

  If `info < 0`, if `info = -i`, the i-th argument has an illegal value.

  If `info > 0`, some or all of the eigenvalues fail to converge or not computed.

  If `info = 1`, bisection fails 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.

  If `info = 2`, mismatch between the number of eigenvalues output and the number desired.

  If `info = 3`: `range='i'`, and the Gershgorin interval initially used is incorrect. No eigenvalues are computed. Probable cause: the machine has a sloppy floating point arithmetic. Increase the fudge parameter, recompile, and try again.

Parent topic: Symmetric Eigenproblems