NAG Toolbox: nag_lapack_dstebz (f08jj)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{range}$ – string (length ≥ 1)

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:     $\mathrm{order}$ – string (length ≥ 1)

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:     $\mathrm{vl}$ – double scalar

4:     $\mathrm{vu}$ – double scalar

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}$.

5:     $\mathrm{il}$ – int64int32nag_int scalar

6:     $\mathrm{iu}$ – int64int32nag_int scalar

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}$.

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

8:     $\mathrm{d}\left(:\right)$ – double array

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

The diagonal elements of the tridiagonal matrix $T$.

9:     $\mathrm{e}\left(:\right)$ – double array

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

The off-diagonal elements of the tridiagonal matrix $T$.

Optional Input Parameters

1:     $\mathrm{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$, the order of the matrix $T$.

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

Output Parameters

1:     $\mathrm{m}$ – int64int32nag_int scalar

$m$, the actual number of eigenvalues found.

2:     $\mathrm{nsplit}$ – int64int32nag_int scalar

The number of diagonal blocks which constitute the tridiagonal matrix $T$.

3:     $\mathrm{w}\left(\mathbf{n}\right)$ – double array

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

4:     $\mathrm{iblock}\left(\mathbf{n}\right)$ – int64int32nag_int array

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 Error Indicators and Warnings) and $\mathbf{range}=\text{'A'}$ or $\text{'V'}$.

5:     $\mathrm{isplit}\left(\mathbf{n}\right)$ – int64int32nag_int array

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$).

6:     $\mathrm{info}$ – int64int32nag_int scalar

$\mathbf{info}=0$ unless the function detects an error (see 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.

   $\mathbf{info}=-i$

If $\mathbf{info}=-i$, parameter $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  $\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 function 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.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f08jj_example

function f08jj_example


fprintf('f08jj example results\n\n');

% Find eigenvalues 1:2 of Symmetric matrix A
a = [ 2.07,  0,    0,     0;
      3.87, -0.21, 0,     0;
      4.20,  1.87, 1.15,  0;
     -1.15,  0.63, 2.06, -1.81];

% Reduce to tridiagonal form
uplo = 'L';
[apt, d, e, tau, info] = f08fe( ...
				uplo, a);

% Get eigenvalues 1:2 of T (= eigenvalues of A)
vl = 0;
vu = 0;
il = int64(1);
iu = int64(2);
abstol = 0;
[m, ~, w, iblock, isplit, info] = ...
f08jj(...
       'I', 'B', vl, vu, il, iu, abstol, d, e);

% Get corresponding eigenvectors of T
[v, ifailv, info] = f08jk( ...
			   d, e, m, w, iblock, isplit);

% Transform Q*V to get eigenvectors of A 
side = 'Left';
trans = 'No transpose';
[z, info] = f08fg( ...
                   side, uplo, trans, apt, tau, v);

% Normalize eigenvectors: largest element positive
for j = 1:m
  [~,k] = max(abs(z(:,j)));
  if z(k,j) < 0;
    z(:,j) = -z(:,j);
  end
end                            

fprintf(' Eigenvalues numbered 1 to 2 are:\n   ');
fprintf(' %7.4f',w(1:m));
fprintf('\n\n');

[ifail] = x04ca( ...
		 'General', ' ', z, 'Corresponding eigenvectors of A');

f08jj example results

 Eigenvalues numbered 1 to 2 are:
    -5.0034 -1.9987

 Corresponding eigenvectors of A
          1       2
 1   0.5658 -0.2328
 2  -0.3478  0.7994
 3  -0.4740 -0.4087
 4   0.5781  0.3737