Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_lapack_dstebz (f08jj)

## Purpose

nag_lapack_dstebz (f08jj) computes some (or all) of the eigenvalues of a real symmetric tridiagonal matrix, by bisection.

## Syntax

[m, nsplit, w, iblock, isplit, info] = f08jj(range, order, vl, vu, il, iu, abstol, d, e, 'n', n)
[m, nsplit, w, iblock, isplit, info] = nag_lapack_dstebz(range, order, vl, vu, il, iu, abstol, d, e, 'n', n)

## Description

nag_lapack_dstebz (f08jj) uses bisection to compute some or all of the eigenvalues of a real symmetric tridiagonal matrix T$T$.
It searches for zero or negligible off-diagonal elements of T$T$ to see if the matrix splits into block diagonal form:
T =
 T1 T2 . . . Tp
.
$T = T1 T2 . . . Tp .$
It performs bisection on each of the blocks Ti${T}_{i}$ and returns the block index of each computed eigenvalue, so that a subsequent call to nag_lapack_dstein (f08jk) to compute eigenvectors can also take advantage of the block structure.

## References

Kahan W (1966) Accurate eigenvalues of a symmetric tridiagonal matrix Report CS41 Stanford University

## Parameters

### Compulsory Input Parameters

1:     range – string (length ≥ 1)
Indicates which eigenvalues are required.
range = 'A'${\mathbf{range}}=\text{'A'}$
All the eigenvalues are required.
range = 'V'${\mathbf{range}}=\text{'V'}$
All the eigenvalues in the half-open interval (vl,vu] are required.
range = 'I'${\mathbf{range}}=\text{'I'}$
Eigenvalues with indices il to iu are required.
Constraint: range = 'A'${\mathbf{range}}=\text{'A'}$, 'V'$\text{'V'}$ or 'I'$\text{'I'}$.
2:     order – string (length ≥ 1)
Indicates the order in which the eigenvalues and their block numbers are to be stored.
order = 'B'${\mathbf{order}}=\text{'B'}$
The eigenvalues are to be grouped by split-off block and ordered from smallest to largest within each block.
order = 'E'${\mathbf{order}}=\text{'E'}$
The eigenvalues for the entire matrix are to be ordered from smallest to largest.
Constraint: order = 'B'${\mathbf{order}}=\text{'B'}$ or 'E'$\text{'E'}$.
3:     vl – double scalar
4:     vu – double scalar
If range = 'V'${\mathbf{range}}=\text{'V'}$, the lower and upper bounds, respectively, of the half-open interval
(vl,vu] within which the required eigenvalues lie.
If range = 'A'${\mathbf{range}}=\text{'A'}$ or 'I'$\text{'I'}$, vl is not referenced.
Constraint: if range = 'V'${\mathbf{range}}=\text{'V'}$, vl < vu${\mathbf{vl}}<{\mathbf{vu}}$.
5:     il – int64int32nag_int scalar
6:     iu – int64int32nag_int scalar
If range = 'I'${\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 range = 'A'${\mathbf{range}}=\text{'A'}$ or 'V'$\text{'V'}$, il is not referenced.
Constraint: if range = 'I'${\mathbf{range}}=\text{'I'}$, 1 il iu n $1\le {\mathbf{il}}\le {\mathbf{iu}}\le {\mathbf{n}}$.
7:     abstol – double scalar
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 $\text{}\le {\mathbf{abstol}}$. If abstol0.0${\mathbf{abstol}}\le 0.0$, then the tolerance is taken as machine precision × T1.
8:     d( : $:$) – double array
Note: the dimension of the array d must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The diagonal elements of the tridiagonal matrix T$T$.
9:     e( : $:$) – double array
Note: the dimension of the array e must be at least max (1,n1)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}-1\right)$.
The off-diagonal elements of the tridiagonal matrix T$T$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The first dimension of the array d and the second dimension of the array d. (An error is raised if these dimensions are not equal.)
n$n$, the order of the matrix T$T$.
Constraint: n0${\mathbf{n}}\ge 0$.

work iwork

### Output Parameters

1:     m – int64int32nag_int scalar
m$m$, the actual number of eigenvalues found.
2:     nsplit – int64int32nag_int scalar
The number of diagonal blocks which constitute the tridiagonal matrix T$T$.
3:     w(n) – double array
The required eigenvalues of the tridiagonal matrix T$T$ stored in w(1)${\mathbf{w}}\left(1\right)$ to w(m)${\mathbf{w}}\left(m\right)$.
4:     iblock(n) – int64int32nag_int array
At each row/column j$j$ where e(j)${\mathbf{e}}\left(j\right)$ is zero or negligible, T$T$ is considered to split into a block diagonal matrix and iblock(i)${\mathbf{iblock}}\left(\mathit{i}\right)$ contains the block number of the eigenvalue stored in w(i)${\mathbf{w}}\left(\mathit{i}\right)$, for i = 1,2,,m$\mathit{i}=1,2,\dots ,m$. Note that iblock(i) < 0${\mathbf{iblock}}\left(\mathit{i}\right)<0$ for some i$i$ whenever ${\mathbf{INFO}}={\mathbf{1}}$ or 3${\mathbf{3}}$ (see Section [Error Indicators and Warnings]) and range = 'A'${\mathbf{range}}=\text{'A'}$ or 'V'$\text{'V'}$.
5:     isplit(n) – int64int32nag_int array
The leading nsplit elements contain the points at which T$T$ splits up into sub-matrices as follows. The first sub-matrix consists of rows/columns 1$1$ to isplit(1)${\mathbf{isplit}}\left(1\right)$, the second sub-matrix consists of rows/columns isplit(1) + 1${\mathbf{isplit}}\left(1\right)+1$ to isplit(2)${\mathbf{isplit}}\left(2\right)$, $\dots$, and the nsplit(th) sub-matrix consists of rows/columns isplit(nsplit1) + 1${\mathbf{isplit}}\left({\mathbf{nsplit}}-1\right)+1$ to ${\mathbf{isplit}}\left({\mathbf{nsplit}}\right)$ ( = n$\text{}=n$).
6:     info – int64int32nag_int scalar
info = 0${\mathbf{info}}=0$ unless the function detects an error (see Section [Error Indicators and Warnings]).

## Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

info = i${\mathbf{info}}=-i$
If info = i${\mathbf{info}}=-i$, parameter i$i$ had an illegal value on entry. The parameters are numbered as follows:
1: range, 2: order, 3: n, 4: vl, 5: vu, 6: il, 7: iu, 8: abstol, 9: d, 10: e, 11: m, 12: nsplit, 13: w, 14: iblock, 15: isplit, 16: work, 17: iwork, 18: info.
It is possible that info refers to a parameter that is omitted from the MATLAB interface. This usually indicates that an error in one of the other input parameters has caused an incorrect value to be inferred.
W INFO = 1${\mathbf{INFO}}=1$
If range = 'A'${\mathbf{range}}=\text{'A'}$ or 'V'$\text{'V'}$, the algorithm failed to compute some (or all) of the required eigenvalues to the required accuracy. More precisely, iblock(i) < 0${\mathbf{iblock}}\left(i\right)<0$ indicates that eigenvalue i$i$ (stored in w(i)${\mathbf{w}}\left(i\right)$) failed to converge.
INFO = 2${\mathbf{INFO}}=2$
If range = 'I'${\mathbf{range}}=\text{'I'}$, the algorithm failed to compute some (or all) of the required eigenvalues. Try calling the function again with range = 'A'${\mathbf{range}}=\text{'A'}$.
INFO = 3${\mathbf{INFO}}=3$
If range = 'I'${\mathbf{range}}=\text{'I'}$, see the description above for info = 2${\mathbf{info}}=2$.
If range = 'A'${\mathbf{range}}=\text{'A'}$ or 'V'$\text{'V'}$, see the description above for info = 1${\mathbf{info}}=1$.
INFO = 4${\mathbf{INFO}}=4$
No eigenvalues have been computed. The floating point arithmetic on the computer is not behaving as expected.
If failures with info1${\mathbf{info}}\ge 1$ are causing persistent trouble and you have checked that the function is being called correctly, please contact NAG.

## Accuracy

The eigenvalues of T$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$QR$ method. However, the reduction to tridiagonal form (prior to calling the function) may exclude the possibility of obtaining high relative accuracy in the small eigenvalues of the original matrix if its eigenvalues vary widely in magnitude.

There is no complex analogue of this function.

## Example

```function nag_lapack_dstebz_example
range = 'I';
order = 'B';
vl = 0;
vu = 0;
il = int64(1);
iu = int64(2);
abstol = 0;
d = [2.07;
1.474093708197552;
-0.6491595075457843;
-1.694934200651768];
e = [-5.825753170191817;
2.624045178795586;
0.9162727563219193];
[m, nsplit, w, iblock, isplit, info] = ...
nag_lapack_dstebz(range, order, vl, vu, il, iu, abstol, d, e)
```
```

m =

2

nsplit =

1

w =

-5.0034
-1.9987
0
0

iblock =

1
1
0
0

isplit =

4
0
0
0

info =

0

```
```function f08jj_example
range = 'I';
order = 'B';
vl = 0;
vu = 0;
il = int64(1);
iu = int64(2);
abstol = 0;
d = [2.07;
1.474093708197552;
-0.6491595075457843;
-1.694934200651768];
e = [-5.825753170191817;
2.624045178795586;
0.9162727563219193];
[m, nsplit, w, iblock, isplit, info] = ...
f08jj(range, order, vl, vu, il, iu, abstol, d, e)
```
```

m =

2

nsplit =

1

w =

-5.0034
-1.9987
0
0

iblock =

1
1
0
0

isplit =

4
0
0
0

info =

0

```

Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013