naginterfaces.library.lapackeig.dstebz

naginterfaces.library.lapackeig.dstebz(erange, order, vl, vu, il, iu, abstol, d, e)

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

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

https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f08/f08jjf.html

Parameters

erangestr, length 1

Indicates which eigenvalues are required.

$erange=\text{'A'}$

All the eigenvalues are required.

$erange=\text{'V'}$

All the eigenvalues in the half-open interval ($vl$,$vu$] are required.

$erange=\text{'I'}$

Eigenvalues with indices $il$ to $iu$ are required.

orderstr, length 1

Indicates the order in which the eigenvalues and their block numbers are to be stored.

$order=\text{'B'}$

The eigenvalues are to be grouped by split-off block and ordered from smallest to largest within each block.

$order=\text{'E'}$

The eigenvalues for the entire matrix are to be ordered from smallest to largest.

vlfloat

If $erange=\text{'V'}$, the lower and upper bounds, respectively, of the half-open interval $(vl,vu]$ within which the required eigenvalues lie.

If $erange=\text{'A'}$ or $\text{'I'}$, $vl$ is not referenced.

vufloat

If $erange=\text{'V'}$, the lower and upper bounds, respectively, of the half-open interval $(vl,vu]$ within which the required eigenvalues lie.

If $erange=\text{'A'}$ or $\text{'I'}$, $vu$ is not referenced.

ilint

If $erange=\text{'I'}$, the indices of the first and last eigenvalues, respectively, to be computed (assuming that the eigenvalues are in ascending order).

If $erange=\text{'A'}$ or $\text{'V'}$, $il$ is not referenced.

iuint

If $erange=\text{'I'}$, the indices of the first and last eigenvalues, respectively, to be computed (assuming that the eigenvalues are in ascending order).

If $erange=\text{'A'}$ or $\text{'V'}$, $iu$ is not referenced.

abstolfloat

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 abstol$. If $abstol\le 0.0$, the tolerance is taken as $\text{machine precision}\times {\parallel T\parallel }_1$.

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

The diagonal elements of the tridiagonal matrix $T$.

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

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

Returns

mint

$m$, the actual number of eigenvalues found.

nsplitint

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

wfloat, ndarray, shape $\left(n\right)$

The required eigenvalues of the tridiagonal matrix $T$ stored in $w\left[0\right]$ to $w[m-1]$.

iblockint, ndarray, shape $\left(n\right)$

At each row/column $j$ where $e[j-1]$ is zero or negligible, $T$ is considered to split into a block diagonal matrix and $iblock[\text{i}-1]$ contains the block number of the eigenvalue stored in $w[\text{i}-1]$, for $\text{i}=1,2,\dots ,m$. Note that $iblock[\text{i}-1]<0$ for some $i$ whenever $errno$ = 1 or 3 (see Exceptions) and $erange=\text{'A'}$ or $\text{'V'}$.

isplitint, ndarray, shape $\left(n\right)$

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 $isplit\left[0\right]$, the second sub-matrix consists of rows/columns $isplit\left[0\right]+1$ to $isplit\left[1\right]$, $\dots$, and the $nsplit$(th) sub-matrix consists of rows/columns $isplit[nsplit-2]+1$ to $isplit[nsplit-1]$ ($=n$).

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $erange$.

Constraint: $erange=\text{'A'}$, $\text{'V'}$ or $\text{'I'}$.

(errno $-2$)

On entry, error in parameter $order$.

Constraint: $order=\text{'B'}$ or $\text{'E'}$.

(errno $-3$)

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

Constraint: $n\ge 0$.

(errno $-5$)

On entry, error in parameter $vu$.

Constraint: $vl<vu$.

(errno $-6$)

On entry, error in parameter $il$.

Constraint: $il\ge 1$ and $il\le max(1,n)$.

(errno $-7$)

On entry, error in parameter $iu$.

Constraint: $iu\le n$ and $iu\ge min(n,il)$.

(errno $2$)

If $erange=\text{'I'}$, the algorithm failed to compute some (or all) of the required eigenvalues. Try calling the function again with $erange=\text{'A'}$.

(errno $3$)

If $erange=\text{'I'}$, the algorithm failed to compute some (or all) of the required eigenvalues. Try calling the function again with $erange=\text{'A'}$. If $erange=\text{'A'}$ or $\text{'V'}$, the algorithm failed to compute some (or all) of the required eigenvalues to the required accuracy. More precisely, $iblock[⟨value⟩]<0$ indicates that eigenvalue $⟨value⟩$ (stored in $w[⟨value⟩]$) failed to converge.

(errno $4$)

No eigenvalues have been computed. The floating-point arithmetic on the computer is not behaving as expected.

Warns

NagAlgorithmicWarning

(errno $1$)

If $erange=\text{'A'}$ or $\text{'V'}$, the algorithm failed to compute some (or all) of the required eigenvalues to the required accuracy. More precisely, $iblock[⟨value⟩]<0$ indicates that eigenvalue $⟨value⟩$ (stored in $w[⟨value⟩]$) failed to converge.

Notes

dstebz uses bisection to compute some or all of the eigenvalues of a real symmetric tridiagonal matrix $T$.

It searches for zero or negligible off-diagonal elements of $T$ to see if the matrix splits into block diagonal form:

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

It performs bisection on each of the blocks $T_i$ and returns the block index of each computed eigenvalue, so that a subsequent call to dstein() 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