NAG Library Function Document

nag_dstebz (f08jjc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:    $\mathbf{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:    $\mathbf{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:    $\mathbf{n}$ – IntegerInput

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

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

4:    $\mathbf{vl}$ – doubleInput

5:    $\mathbf{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:    $\mathbf{il}$ – IntegerInput

7:    $\mathbf{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:    $\mathbf{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:    $\mathbf{d}\left[\mathit{dim}\right]$ – 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:  $\mathbf{e}\left[\mathit{dim}\right]$ – 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:  $\mathbf{m}$ – Integer *Output

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

12:  $\mathbf{nsplit}$ – Integer *Output

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

13:  $\mathbf{w}\left[\mathbf{n}\right]$ – 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:  $\mathbf{iblock}\left[\mathbf{n}\right]$ – 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:  $\mathbf{isplit}\left[\mathbf{n}\right]$ – 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:  $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 2.7 in How to Use the NAG Library and its Documentation).

6  Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.

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.

An unexpected error has been triggered by this function. Please contact NAG.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example