naginterfaces.library.lapackeig.dstegr

naginterfaces.library.lapackeig.dstegr(jobz, erange, d, e, vl, vu, il, iu)

dstegr computes selected eigenvalues and, optionally, the corresponding eigenvectors of a real $n\times n$ symmetric tridiagonal matrix.

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

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

Parameters

jobzstr, length 1

Indicates whether eigenvectors are computed.

$jobz=\text{'N'}$

Only eigenvalues are computed.

$jobz=\text{'V'}$

Eigenvalues and eigenvectors are computed.

erangestr, length 1

Indicates which eigenvalues should be returned.

$erange=\text{'A'}$

All eigenvalues will be found.

$erange=\text{'V'}$

All eigenvalues in the half-open interval $(vl,vu]$ will be found.

$erange=\text{'I'}$

The $il$th through $iu$th eigenvectors will be found.

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

The $n$ diagonal elements of the tridiagonal matrix $T$.

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

$e\left[0\right]$ to $e[n-2]$ are the subdiagonal elements of the tridiagonal matrix $T$. $e[n-1]$ need not be set.

vlfloat

If $erange=\text{'V'}$, $vl$ and $vu$ contain the lower and upper bounds respectively of the interval to be searched for eigenvalues.

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

vufloat

If $erange=\text{'V'}$, $vl$ and $vu$ contain the lower and upper bounds respectively of the interval to be searched for eigenvalues.

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

ilint

If $erange=\text{'I'}$, $il$ and $iu$ specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

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

iuint

If $erange=\text{'I'}$, $il$ and $iu$ specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

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

Returns

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

$d$ is overwritten.

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

$e$ is overwritten.

mint

The total number of eigenvalues found. $0\le m\le n$.

If $erange=\text{'A'}$, $m=n$.

If $erange=\text{'I'}$, $m=iu-il+1$.

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

The eigenvalues in ascending order.

zfloat, ndarray, shape $(:,:)$

If $jobz=\text{'V'}$, then if no exception or warning is raised, the columns of $z$ contain the orthonormal eigenvectors of the matrix $T$, with the $i$th column of $Z$ holding the eigenvector associated with $w[i-1]$.

If $jobz=\text{'N'}$, $z$ is not referenced.

Note: you must ensure that at least $max(1,m)$ columns are supplied in the array $z$; if $erange=\text{'V'}$, the exact value of $m$ is not known in advance and an upper bound of at least $\text{n}$ must be used.

isuppzint, ndarray, shape $(:)$

The support of the eigenvectors in $Z$, i.e., the indices indicating the nonzero elements in $Z$. The $i$th eigenvector is nonzero only in elements $isuppz[2\times i-2]$ through $isuppz[2\times i-1]$.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $jobz$.

Constraint: $jobz=\text{'N'}$ or $\text{'V'}$.

(errno $-2$)

On entry, error in parameter $erange$.

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

(errno $-3$)

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

Constraint: $n\ge 0$.

(errno $-7$)

On entry, error in parameter $vu$.

Constraint: $vl<vu$.

(errno $-9$)

On entry, error in parameter $iu$.

Constraint: $1\le il\le iu\le n$.

(errno $-9$)

On entry, error in parameter $iu$.

Constraint: $il=1$ and $iu=0$.

(errno $i=1$)

The $dqds$ algorithm failed to converge.

(errno $i=2$)

Inverse iteration failed to converge.

Notes

dstegr computes selected eigenvalues and, optionally, the corresponding eigenvectors, of a real symmetric tridiagonal matrix $T$. That is, the function computes the (partial) spectral factorization of $T$ given by

$$Z\Lambda Z^T\text{,}$$

where $\Lambda$ is a diagonal matrix whose diagonal elements are the selected eigenvalues, ${\lambda }_i$, of $T$ and $Z$ is an orthogonal matrix whose columns are the corresponding eigenvectors, $z_i$, of $T$. Thus

$$T{z}_i={\lambda }_i{z}_i\text{,}i=1,2,\dots ,m$$

where $m$ is the number of selected eigenvalues computed.

The function may also be used to compute selected eigenvalues and eigenvectors of a real symmetric matrix $A$ which has been reduced to tridiagonal form $T$:

$$\left(QZ\right)\Lambda {\left(QZ\right)}^T\text{, where}Q\text{is orthogonal.}$$

In this case, the matrix $Q$ must be explicitly applied to the output matrix $Z$. The functions which must be called to perform the reduction to tridiagonal form and apply $Q$ are:

full matrix	dsytrd() and dormtr()
full matrix, packed storage	dsptrd() and dopmtr()
band matrix	dsbtrd() with $\text{vect}=\text{'V'}$ and blas.dgemm.

This function uses the dqds and the Relatively Robust Representation algorithms to compute the eigenvalues and eigenvectors respectively; see for example Parlett and Dhillon (2000) and Dhillon and Parlett (2004) for further details. dstegr can usually compute all the eigenvalues and eigenvectors in $O\left(n^2\right)$ floating-point operations and so, for large matrices, is often considerably faster than the other symmetric tridiagonal functions in this module when all the eigenvectors are required, particularly so compared to those functions that are based on the $QR$ algorithm.

References

Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, LAPACK Users’ Guide, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

Barlow, J and Demmel, J W, 1990, Computing accurate eigensystems of scaled diagonally dominant matrices, SIAM J. Numer. Anal. (27), 762–791

Dhillon, I S and Parlett, B N, 2004, Orthogonal eigenvectors and relative gaps, SIAM J. Appl. Math. (25), 858–899

Parlett, B N and Dhillon, I S, 2000, Relatively robust representations of symmetric tridiagonals, Linear Algebra Appl. (309), 121–151