NAG Library Function Document

nag_dstebz (f08jjc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     range – Nag_RangeTypeInput

On entry: indicates which eigenvalues are required.

$\mathbf{range}=\mathrm{Nag\_AllValues}$

All the eigenvalues are required.

$\mathbf{range}=\mathrm{Nag\_Interval}$

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

$\mathbf{range}=\mathrm{Nag\_Indices}$

Eigenvalues with indices il to iu are required.

Constraint: $\mathbf{range}=\mathrm{Nag\_AllValues}$, $\mathrm{Nag\_Interval}$ or $\mathrm{Nag\_Indices}$.

2:     rank – Nag_EigValRankTypeInput

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

$\mathbf{rank}=\mathrm{Nag\_ByBlock}$

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

$\mathbf{rank}=\mathrm{Nag\_Entire}$

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

Constraint: $\mathbf{rank}=\mathrm{Nag\_ByBlock}$ or $\mathrm{Nag\_Entire}$.

3:     n – IntegerInput

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

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

4:     vl – doubleInput

5:     vu – doubleInput

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

If $\mathbf{range}=\mathrm{Nag\_AllValues}$ or $\mathrm{Nag\_Indices}$, vl is not referenced.

Constraint: if $\mathbf{range}=\mathrm{Nag\_Interval}$, $\mathbf{vl}<\mathbf{vu}$.

6:     il – IntegerInput

7:     iu – IntegerInput

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

If $\mathbf{range}=\mathrm{Nag\_AllValues}$ or $\mathrm{Nag\_Interval}$, il is not referenced.

Constraint: if $\mathbf{range}=\mathrm{Nag\_Indices}$, $1\le \mathbf{il}\le \mathbf{iu}\le \mathbf{n}$.

8:     abstol – doubleInput

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$, then the tolerance is taken as $\mathit{machine precision}\times {‖T‖}_1$.

9:     d[$\mathit{dim}$] – const doubleInput

Note: the dimension, dim, 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:   e[$\mathit{dim}$] – const doubleInput

Note: the dimension, dim, 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:   m – Integer *Output

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

12:   nsplit – Integer *Output

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

13:   w[n] – doubleOutput

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

14:   iblock[n] – IntegerOutput

On exit: at each row/column $j$ where $\mathbf{e}\left[j-1\right]$ is zero or negligible, $T$ is considered to split into a block diagonal matrix and $\mathbf{iblock}\left[\mathit{i}-1\right]$ contains the block number of the eigenvalue stored in $\mathbf{w}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,m$. Note that $\mathbf{iblock}\left[\mathit{i}-1\right]<0$ for some $i$ whenever $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_CONVERGENCE (see Section 6) and $\mathbf{range}=\mathrm{Nag\_AllValues}$ or $\mathrm{Nag\_Interval}$.

15:   isplit[n] – IntegerOutput

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[0\right]$, the second sub-matrix consists of rows/columns $\mathbf{isplit}\left[0\right]+1$ to $\mathbf{isplit}\left[1\right]$, $\dots$, and the nsplit(th) sub-matrix consists of rows/columns $\mathbf{isplit}\left[\mathbf{nsplit}-2\right]+1$ to $\mathbf{isplit}\left[\mathbf{nsplit}-1\right]$ ($=n$).

16:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_CONVERGENCE

If $\mathbf{range}=\mathrm{Nag\_AllValues}$ or $\mathrm{Nag\_Interval}$, the algorithm failed to compute some (or all) of the required eigenvalues to the required accuracy. More precisely, $\mathbf{iblock}\left[⟨\mathit{\text{value}}⟩\right]<0$ indicates that eigenvalue $⟨\mathit{\text{value}}⟩$ (stored in $\mathbf{w}\left[⟨\mathit{\text{value}}⟩\right]$) failed to converge.

If $\mathbf{range}=\mathrm{Nag\_Indices}$, the algorithm failed to compute some (or all) of the required eigenvalues. Try calling the function again with $\mathbf{range}=\mathrm{Nag\_AllValues}$.

If $\mathbf{range}=\mathrm{Nag\_Indices}$, the algorithm failed to compute some (or all) of the required eigenvalues. Try calling the function again with $\mathbf{range}=\mathrm{Nag\_AllValues}$. If $\mathbf{range}=\mathrm{Nag\_AllValues}$ or $\mathrm{Nag\_Interval}$, the algorithm failed to compute some (or all) of the required eigenvalues to the required accuracy. More precisely, $\mathbf{iblock}\left[⟨\mathit{\text{value}}⟩\right]<0$ indicates that eigenvalue $⟨\mathit{\text{value}}⟩$ (stored in $\mathbf{w}\left[⟨\mathit{\text{value}}⟩\right]$) failed to converge.

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

NE_ENUM_INT_3

On entry, $\mathbf{range}=⟨\mathit{\text{value}}⟩$, $\mathbf{n}=⟨\mathit{\text{value}}⟩$, $\mathbf{il}=⟨\mathit{\text{value}}⟩$ and $\mathbf{iu}=⟨\mathit{\text{value}}⟩$.
Constraint: if $\mathbf{range}=\mathrm{Nag\_Indices}$, $1\le \mathbf{il}\le \mathbf{iu}\le \mathbf{n}$.

NE_ENUM_REAL_2

On entry, $\mathbf{range}=⟨\mathit{\text{value}}⟩$, $\mathbf{vl}=⟨\mathit{\text{value}}⟩$ and $\mathbf{vu}=⟨\mathit{\text{value}}⟩$.
Constraint: if $\mathbf{range}=\mathrm{Nag\_Interval}$, $\mathbf{vl}<\mathbf{vu}$.

NE_INT

On entry, $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{n}\ge 0$.

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example