naginterfaces.library.lapackeig.dstein

naginterfaces.library.lapackeig.dstein(d, e, m, w, iblock, isplit)

dstein computes the eigenvectors of a real symmetric tridiagonal matrix corresponding to specified eigenvalues, by inverse iteration.

For full information please refer to the NAG Library document for f08jk

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08jkf.html

Parameters

dfloat, array-like, shape $\left(n\right)$

The diagonal elements of the tridiagonal matrix $T$.

efloat, array-like, shape $(n-1)$

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

mint

$m$, the number of eigenvectors to be returned.

wfloat, array-like, shape $\left(n\right)$

The eigenvalues of the tridiagonal matrix $T$ stored in $w\left[0\right]$ to $w[m-1]$, as returned by dstebz() with $\text{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.

iblockint, array-like, shape $\left(n\right)$

The first $m$ elements must contain the sub-matrix indices associated with the specified eigenvalues, as returned by dstebz() with $\text{order}=\text{'B'}$. If the eigenvalues were not computed by dstebz() with $\text{order}=\text{'B'}$, set $iblock[\text{i}-1]$ to $1$, for $\text{i}=1,2,\dots ,m$.

isplitint, array-like, shape $\left(n\right)$

The points at which $T$ breaks up into sub-matrices, as returned by dstebz() with $\text{order}=\text{'B'}$. If the eigenvalues were not computed by dstebz() with $\text{order}=\text{'B'}$, set $isplit\left[0\right]$ to $\text{n}$.

Returns

zfloat, ndarray, shape $(n,m)$

The $m$ eigenvectors, stored as columns of $Z$; the $i$th column corresponds to the $i$th specified eigenvalue, unless $errno$ > 0 (in which case see Exceptions).

ifailvint, ndarray, shape $\left(m\right)$

If $\text{errno}=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$.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $\text{n}$.

Constraint: $n\ge 0$.

(errno $-4$)

On entry, error in parameter $m$.

Constraint: $0\le m\le n$.

(errno -5)

On entry, error in parameter $w$.

Constraint: $w\left[\text{i}\right]\le w[\text{i}+1]$.

(errno -6)

On entry, error in parameter $iblock$.

Constraint: $iblock\left[\text{i}\right]\le iblock[\text{i}+1]$.

Warns

NagAlgorithmicWarning

(errno $i>0$)

$⟨value⟩$ eigenvectors (as indicated by argument $ifailv$) each failed to converge in five iterations. The current iterate after five iterations is stored in the corresponding column of $z$.

Notes

dstein computes the eigenvectors of a real symmetric tridiagonal matrix $T$ corresponding to specified eigenvalues, by inverse iteration (see Jessup and Ipsen (1992)). It is designed to be used in particular after the specified eigenvalues have been computed by dstebz() with $\text{order}=\text{'B'}$, but may also be used when the eigenvalues have been computed by other functions in submodule lapackeig or submodule eigen.

If $T$ has been formed by reduction of a full real symmetric matrix $A$ to tridiagonal form, then eigenvectors of $T$ may be transformed to eigenvectors of $A$ by a call to dormtr() or dopmtr().

dstebz() determines whether the matrix $T$ splits into block diagonal form:

$$\begin{array}{c}T=\left(\begin{array}{cccccc}{T}_1& & & & & \\ & T_2& & & & \\ & & .& & & \\ & & & .& & \\ & & & & .& \\ & & & & & T_p\end{array}\right)\end{array}$$

and passes details of the block structure to this function in the arrays $iblock$ and $isplit$. This function can then take advantage of the block structure by performing inverse iteration on each block $T_i$ separately, which is more efficient than using the whole matrix.

References

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore

Jessup, E and Ipsen, I C F, 1992, Improving the accuracy of inverse iteration, SIAM J. Sci. Statist. Comput. (13), 550–572