NAG Library Routine Document

f08jjf  (dstebz)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:     $\mathbf{range}$ – Character(1)Input

On entry: indicates which eigenvalues are required.

$\mathbf{range}=\text{'A'}$

All the eigenvalues are required.

$\mathbf{range}=\text{'V'}$

All the eigenvalues in the half-open interval (vl,vu] are required.

$\mathbf{range}=\text{'I'}$

Eigenvalues with indices il to iu are required.

Constraint: $\mathbf{range}=\text{'A'}$, $\text{'V'}$ or $\text{'I'}$.

2:     $\mathbf{order}$ – Character(1)Input

On entry: indicates the order in which the eigenvalues and their block numbers are to be stored.

$\mathbf{order}=\text{'B'}$

The eigenvalues are to be grouped by split-off block and ordered from smallest to largest within each block.

$\mathbf{order}=\text{'E'}$

The eigenvalues for the entire matrix are to be ordered from smallest to largest.

Constraint: $\mathbf{order}=\text{'B'}$ or $\text{'E'}$.

3:     $\mathbf{n}$ – IntegerInput

On entry: $n$, the order of the matrix $T$.

Constraint: $\mathbf{n}\ge 0$.

4:     $\mathbf{vl}$ – Real (Kind=nag_wp)Input

5:     $\mathbf{vu}$ – Real (Kind=nag_wp)Input

On entry: if $\mathbf{range}=\text{'V'}$, the lower and upper bounds, respectively, of the half-open interval
(vl,vu] within which the required eigenvalues lie.

If $\mathbf{range}=\text{'A'}$ or $\text{'I'}$, vl is not referenced.

Constraint: if $\mathbf{range}=\text{'V'}$, $\mathbf{vl}<\mathbf{vu}$.

6:     $\mathbf{il}$ – IntegerInput

7:     $\mathbf{iu}$ – IntegerInput

On entry: if $\mathbf{range}=\text{'I'}$, the indices of the first and last eigenvalues, respectively, to be computed (assuming that the eigenvalues are in ascending order).

If $\mathbf{range}=\text{'A'}$ or $\text{'V'}$, il is not referenced.

Constraint: if $\mathbf{range}=\text{'I'}$, $1\le \mathbf{il}\le \mathbf{iu}\le \mathbf{n}$.

8:     $\mathbf{abstol}$ – Real (Kind=nag_wp)Input

On entry: 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 $\le \mathbf{abstol}$. If $\mathbf{abstol}\le 0.0$, the tolerance is taken as $\mathit{machine precision}\times {‖T‖}_1$.

9:     $\mathbf{d}\left(*\right)$ – Real (Kind=nag_wp) arrayInput

Note: the dimension of the array d must be at least $\max \left(1,\mathbf{n}\right)$.

On entry: the diagonal elements of the tridiagonal matrix $T$.

10:   $\mathbf{e}\left(*\right)$ – Real (Kind=nag_wp) arrayInput

Note: the dimension of the array e must be at least $\max \left(1,\mathbf{n}-1\right)$.

On entry: the off-diagonal elements of the tridiagonal matrix $T$.

11:   $\mathbf{m}$ – IntegerOutput

On exit: $m$, the actual number of eigenvalues found.

12:   $\mathbf{nsplit}$ – IntegerOutput

On exit: the number of diagonal blocks which constitute the tridiagonal matrix $T$.

13:   $\mathbf{w}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: the required eigenvalues of the tridiagonal matrix $T$ stored in $\mathbf{w}\left(1\right)$ to $\mathbf{w}\left(m\right)$.

14:   $\mathbf{iblock}\left(\mathbf{n}\right)$ – Integer arrayOutput

On exit: at each row/column $j$ where $\mathbf{e}\left(j\right)$ is zero or negligible, $T$ is considered to split into a block diagonal matrix and $\mathbf{iblock}\left(\mathit{i}\right)$ contains the block number of the eigenvalue stored in $\mathbf{w}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,m$. Note that $\mathbf{iblock}\left(\mathit{i}\right)<0$ for some $i$ whenever $\mathbf{info}=\mathbf{1}$ or $\mathbf{3}$ (see Section 6) and $\mathbf{range}=\text{'A'}$ or $\text{'V'}$.

15:   $\mathbf{isplit}\left(\mathbf{n}\right)$ – Integer arrayOutput

On exit: the leading nsplit elements contain the points at which $T$ splits up into sub-matrices as follows. The first sub-matrix consists of rows/columns $1$ to $\mathbf{isplit}\left(1\right)$, the second sub-matrix consists of rows/columns $\mathbf{isplit}\left(1\right)+1$ to $\mathbf{isplit}\left(2\right)$, $\dots$, and the nsplit(th) sub-matrix consists of rows/columns $\mathbf{isplit}\left(\mathbf{nsplit}-1\right)+1$ to $\mathbf{isplit}\left(\mathbf{nsplit}\right)$ ($=n$).

16:   $\mathbf{work}\left(4\times \mathbf{n}\right)$ – Real (Kind=nag_wp) arrayWorkspace

17:   $\mathbf{iwork}\left(3\times \mathbf{n}\right)$ – Integer arrayWorkspace

18:   $\mathbf{info}$ – IntegerOutput

On exit: $\mathbf{info}=0$ unless the routine detects an error (see Section 6).

6

Error Indicators and Warnings

$\mathbf{info}<0$

If $\mathbf{info}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.

$\mathbf{info}=1$

If $\mathbf{range}=\text{'A'}$ or $\text{'V'}$, the algorithm failed to compute some (or all) of the required eigenvalues to the required accuracy. More precisely, $\mathbf{iblock}\left(i\right)<0$ indicates that eigenvalue $i$ (stored in $\mathbf{w}\left(i\right)$) failed to converge.

$\mathbf{info}=2$

If $\mathbf{range}=\text{'I'}$, the algorithm failed to compute some (or all) of the required eigenvalues. Try calling the routine again with $\mathbf{range}=\text{'A'}$.

$\mathbf{info}=3$

If $\mathbf{range}=\text{'I'}$, see the description above for $\mathbf{info}=2$.

If $\mathbf{range}=\text{'A'}$ or $\text{'V'}$, see the description above for $\mathbf{info}=1$.

$\mathbf{info}=4$

No eigenvalues have been computed. The floating-point arithmetic on the computer is not behaving as expected.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example