naginterfaces.library.lapackeig.zpteqr

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

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

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

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/f08/f08juf.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 descending order, unless $errno$ > 0, in which case $d$ is overwritten.

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

(errno $i>0\text{and}i\le n$)

The leading minor of order $⟨value⟩$ is not positive definite and the Cholesky factorization of $T$ could not be completed. Hence $T$ itself is not positive definite.

(errno $i>n$)

The algorithm to compute the singular values of the Cholesky factor $B$ failed to converge; $⟨value⟩$ off-diagonal elements did not converge to zero.

Notes

zpteqr computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric positive definite 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 be used to compute all the eigenvalues and eigenvectors of a complex Hermitian positive definite 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 zpteqr, 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'}$.

zpteqr first factorizes $T$ as $LD{L}^H$ where $L$ is unit lower bidiagonal and $D$ is diagonal. It forms the bidiagonal matrix $B=L{D}^{\frac{1}{2}}$, and then calls zbdsqr() to compute the singular values of $B$ which are the same as the eigenvalues of $T$. The method used by the function allows high relative accuracy to be achieved in the small eigenvalues of $T$. 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$.

References

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