naginterfaces.library.lapackeig.zheevr

naginterfaces.library.lapackeig.zheevr(jobz, erange, uplo, a, vl, vu, il, iu, abstol)

zheevr computes selected eigenvalues and, optionally, eigenvectors of a complex $n\times n$ Hermitian matrix $A$. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08frf.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

If $erange=\text{'A'}$, all eigenvalues will be found.

If $erange=\text{'V'}$, all eigenvalues in the half-open interval $(vl,vu]$ will be found.

If $erange=\text{'I'}$, the $il$th to $iu$th eigenvalues will be found.

For $erange=\text{'V'}$ or $\text{'I'}$ and $iu-il<n-1$, dstebz() and zstein() are called.

uplostr, length 1

If $uplo=\text{'U'}$, the upper triangular part of $A$ is stored.

If $uplo=\text{'L'}$, the lower triangular part of $A$ is stored.

acomplex, array-like, shape $(n,n)$

The $n\times n$ Hermitian matrix $A$.

vlfloat

If $erange=\text{'V'}$, the lower and upper bounds 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'}$, the lower and upper bounds 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.

abstolfloat

The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval $[a,b]$ of width less than or equal to

$$abstol+ϵmax(\left|a\right|,\left|b\right|)\text{,}$$

where $ϵ$ is the machine precision. If $abstol$ is less than or equal to zero, then $ϵ{\parallel T\parallel }_1$ will be used in its place, where $T$ is the real tridiagonal matrix obtained by reducing $A$ to tridiagonal form. See Demmel and Kahan (1990).

If high relative accuracy is important, set $abstol$ to $\text{machine.real\_safe}\left(\right)$, although doing so does not currently guarantee that eigenvalues are computed to high relative accuracy.

See Barlow and Demmel (1990) for a discussion of which matrices can define their eigenvalues to high relative accuracy.

Returns

acomplex, ndarray, shape $(n,n)$

The lower triangle (if $uplo=\text{'L'}$) or the upper triangle (if $uplo=\text{'U'}$) of $a$, including the diagonal, 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 first $m$ elements contain the selected eigenvalues in ascending order.

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

If $jobz=\text{'V'}$, the first $m$ columns of $Z$ contain the orthonormal eigenvectors of the matrix $A$ corresponding to the selected eigenvalues, 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]$. Implemented only for $erange=\text{'A'}$ or $erange=\text{'I'}$ and $iu-il=n-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 $uplo$.

Constraint: $uplo=\text{'U'}$ or $\text{'L'}$.

(errno $-4$)

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

Constraint: $n\ge 0$.

(errno $-8$)

On entry, error in parameter $vu$.

Constraint: $vl<vu$.

(errno $-9$)

On entry, error in parameter $il$.

(errno $-10$)

On entry, error in parameter $iu$.

(errno $i>0$)

zheevr failed to converge.

Notes

The Hermitian matrix is first reduced to a real tridiagonal matrix $T$, using unitary similarity transformations. Then whenever possible, zheevr computes the eigenspectrum using Relatively Robust Representations. zheevr computes eigenvalues by the dqds algorithm, while orthogonal eigenvectors are computed from various ‘good’ $LD{L}^T$ representations (also known as Relatively Robust Representations). Gram–Schmidt orthogonalization is avoided as far as possible. More specifically, the various steps of the algorithm are as follows. For the $i$th unreduced block of $T$:

1. compute $T-{\sigma }_{i}I=L_i{D}_i{L}_i^T$, such that $L_i{D}_i{L}_i^T$ is a relatively robust representation,

2. compute the eigenvalues, ${\lambda }_j$, of $L_i{D}_i{L}_i^T$ to high relative accuracy by the dqds algorithm,

3. if there is a cluster of close eigenvalues, ‘choose’ ${\sigma }_i$ close to the cluster, and go to (a),

4. given the approximate eigenvalue ${\lambda }_j$ of $L_i{D}_i{L}_i^T$, compute the corresponding eigenvector by forming a rank-revealing twisted factorization.

The desired accuracy of the output can be specified by the argument $abstol$. For more details, see Dhillon (1997) and Parlett and Dhillon (2000).

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

Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873–912

Dhillon, I, 1997, A new $O\left(n^2\right)$ algorithm for the symmetric tridiagonal eigenvalue/eigenvector problem, Computer Science Division Technical Report No. UCB//CSD-97-971, UC Berkeley

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

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