NAG Library Routine Document

F08JXF (ZSTEIN)

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     N – INTEGERInput

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

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

2:     D($*$) – 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$.

3:     E($*$) – 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$.

4:     M – INTEGERInput

On entry: $m$, the number of eigenvectors to be returned.

Constraint: $0\le \mathbf{M}\le \mathbf{N}$.

5:     W($*$) – REAL (KIND=nag_wp) arrayInput

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

On entry: the eigenvalues of the tridiagonal matrix $T$ stored in $\mathbf{W}\left(1\right)$ to $\mathbf{W}\left(m\right)$, as returned by F08JJF (DSTEBZ) with $\mathbf{ORDER}=\text{'B'}$. Eigenvalues associated with the first sub-matrix must be supplied first, in nondecreasing order; then those associated with the second sub-matrix, again in nondecreasing order; and so on.

Constraint: if $\mathbf{IBLOCK}\left(\mathit{i}\right)=\mathbf{IBLOCK}\left(\mathit{i}+1\right)$, $\mathbf{W}\left(\mathit{i}\right)\le \mathbf{W}\left(\mathit{i}+1\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{M}-1$.

6:     IBLOCK($*$) – INTEGER arrayInput

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

On entry: the first $m$ elements must contain the sub-matrix indices associated with the specified eigenvalues, as returned by F08JJF (DSTEBZ) with $\mathbf{ORDER}=\text{'B'}$. If the eigenvalues were not computed by F08JJF (DSTEBZ) with $\mathbf{ORDER}=\text{'B'}$, set $\mathbf{IBLOCK}\left(\mathit{i}\right)$ to $1$, for $\mathit{i}=1,2,\dots ,m$.

Constraint: $\mathbf{IBLOCK}\left(\mathit{i}\right)\le \mathbf{IBLOCK}\left(\mathit{i}+1\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{M}-1$.

7:     ISPLIT($*$) – INTEGER arrayInput

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

On entry: the points at which $T$ breaks up into sub-matrices, as returned by F08JJF (DSTEBZ) with $\mathbf{ORDER}=\text{'B'}$. If the eigenvalues were not computed by F08JJF (DSTEBZ) with $\mathbf{ORDER}=\text{'B'}$, set $\mathbf{ISPLIT}\left(1\right)$ to N.

8:     Z(LDZ,$*$) – COMPLEX (KIND=nag_wp) arrayOutput

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

On exit: the $m$ eigenvectors, stored as columns of $Z$; the $i$th column corresponds to the $i$th specified eigenvalue, unless $\mathbf{INFO}>\mathbf{0}$ (in which case see Section 6).

9:     LDZ – INTEGERInput

On entry: the first dimension of the array Z as declared in the (sub)program from which F08JXF (ZSTEIN) is called.

Constraint: $\mathbf{LDZ}\ge \max \left(1,\mathbf{N}\right)$.

10:   WORK($5\times \mathbf{N}$) – REAL (KIND=nag_wp) arrayWorkspace

11:   IWORK(N) – INTEGER arrayWorkspace

12:   IFAILV(M) – INTEGER arrayOutput

On exit: if $\mathbf{INFO}=i>0$, the first $i$ elements of IFAILV contain the indices of any eigenvectors which have failed to converge. The rest of the first M elements of IFAILV are set to $0$.

13:   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}>0$

If $\mathbf{INFO}=i$, then $i$ eigenvectors (as indicated by the parameter IFAILV above) each failed to converge in five iterations. The current iterate after five iterations is stored in the corresponding column of Z.

7  Accuracy

8  Further Comments

9  Example