naginterfaces.library.lapackeig.zsteqr

naginterfaces.library.lapackeig.zsteqr(compz, d, e, z)

zsteqr computes all the eigenvalues and, optionally, all the eigenvectors of a complex Hermitian matrix which has been reduced to tridiagonal form.

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

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

Parameters

compzstr, length 1

Indicates whether the eigenvectors are to be computed.

$compz=\text{'N'}$

Only the eigenvalues are computed (and the array $z$ is not referenced).

$compz=\text{'V'}$

The eigenvalues and eigenvectors of $A$ are computed (and the array $z$ must contain the matrix $Q$ on entry).

$compz=\text{'I'}$

The eigenvalues and eigenvectors of $T$ are computed (and the array $z$ is initialized by the function).

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

zcomplex, array-like, shape $(:,:)$

Note: the required extent for this argument in dimension 1 is determined as follows: if $compz\text{in}(\text{'V'},\text{'I'})$: $max(1,n)$; if $compz=\text{'N'}$: $1$; otherwise: $0$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $compz\text{in}(\text{'V'},\text{'I'})$: $n$; if $compz=\text{'N'}$: $1$; otherwise: $0$.

If $compz=\text{'V'}$, $z$ must contain the unitary matrix $Q$ from the reduction to tridiagonal form.

If $compz=\text{'I'}$, $z$ need not be set.

Returns

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

The $n$ eigenvalues in ascending order, unless $errno$ > 0 (in which case see Exceptions).

efloat, ndarray, shape $(max(1,n-1))$

$e$ is overwritten.

zcomplex, ndarray, shape $(:,:)$

If $compz=\text{'V'}$ or $\text{'I'}$, the $n$ required orthonormal eigenvectors stored as columns of $Z$; the $i$th column corresponds to the $i$th eigenvalue, where $i=1,2,\dots ,n$, unless $errno$ > 0.

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

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $compz$.

Constraint: $compz=\text{'N'}$, $\text{'V'}$ or $\text{'I'}$.

(errno $-2$)

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

Constraint: $n\ge 0$.

Warns

NagAlgorithmicWarning

(errno $i>0$)

The algorithm has failed to find all the eigenvalues after a total of $30\times n$ iterations. In this case, $d$ and $e$ contain on exit the diagonal and off-diagonal elements, respectively, of a tridiagonal matrix unitarily similar to $T$. $⟨value⟩$ off-diagonal elements have not converged to zero.

Notes

zsteqr computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric tridiagonal matrix $T$. In other words, it can compute the spectral factorization of $T$ as

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

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

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

The function stores the real orthogonal matrix $Z$ in a complex array, so that it may also be used to compute all the eigenvalues and eigenvectors of a complex Hermitian matrix $A$ which has been reduced to tridiagonal form $T$:

$$\begin{array}{c}\begin{array}{cc}A& =QT{Q}^H\text{, where}Q\text{is unitary}\\ & =\left(QZ\right)\Lambda {\left(QZ\right)}^H\text{.}\end{array}\end{array}$$

In this case, the matrix $Q$ must be formed explicitly and passed to zsteqr, which must be called with $compz=\text{'V'}$. The functions which must be called to perform the reduction to tridiagonal form and form $Q$ are:

full matrix	zhetrd() and zungtr()
full matrix, packed storage	zhptrd() and zupgtr()
band matrix	zhbtrd() with $\text{vect}=\text{'V'}$.

zsteqr uses the implicitly shifted $QR$ algorithm, switching between the $QR$ and $QL$ variants in order to handle graded matrices effectively (see Greenbaum and Dongarra (1980)). The eigenvectors are normalized so that ${\parallel z_i\parallel }_2=1$, but are determined only to within a complex factor of absolute value $1$.

If only the eigenvalues of $T$ are required, it is more efficient to call dsterf() instead. If $T$ is positive definite, small eigenvalues can be computed more accurately by zpteqr().

References

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

Greenbaum, A and Dongarra, J J, 1980, Experiments with QR/QL methods for the symmetric triangular eigenproblem, LAPACK Working Note No. 17 (Technical Report CS-89-92), University of Tennessee, Knoxville, https://www.netlib.org/lapack/lawnspdf/lawn17.pdf

Parlett, B N, 1998, The Symmetric Eigenvalue Problem, SIAM, Philadelphia