naginterfaces.library.lapackeig.zhpgvx

naginterfaces.library.lapackeig.zhpgvx(itype, jobz, erange, uplo, n, ap, bp, vl, vu, il, iu, abstol)

zhpgvx computes selected eigenvalues and, optionally, eigenvectors of a complex generalized Hermitian-definite eigenproblem, of the form

$$Az=\lambda Bz\text{,}ABz=\lambda z\text{or}BAz=\lambda z\text{,}$$

where $A$ and $B$ are Hermitian, stored in packed format, and $B$ is also positive definite. 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 f08tp

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/f08/f08tpf.html

Parameters

itypeint

Specifies the problem type to be solved.

$itype=1$

$Az=\lambda Bz$.

$itype=2$

$ABz=\lambda z$.

$itype=3$

$BAz=\lambda z$.

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.

uplostr, length 1

If $uplo=\text{'U'}$, the upper triangles of $A$ and $B$ are stored.

If $uplo=\text{'L'}$, the lower triangles of $A$ and $B$ are stored.

nint

$n$, the order of the matrices $A$ and $B$.

apcomplex, array-like, shape $(n\times (n+1)/2)$

The upper or lower triangle of the $n\times n$ Hermitian matrix $A$, packed by columns.

bpcomplex, array-like, shape $(n\times (n+1)/2)$

The upper or lower triangle of the $n\times n$ Hermitian matrix $B$, packed by columns.

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 tridiagonal matrix obtained by reducing $C$ to tridiagonal form. Eigenvalues will be computed most accurately when $abstol$ is set to twice the underflow threshold $2\times \text{machine.real\_safe}\left(\right)$, not zero. If this function returns with $errno$ = 1 … $n$, indicating that some eigenvectors did not converge, try setting $abstol$ to $2\times \text{machine.real\_safe}\left(\right)$. See Demmel and Kahan (1990).

Returns

apcomplex, ndarray, shape $(n\times (n+1)/2)$

The contents of $ap$ are destroyed.

bpcomplex, ndarray, shape $(n\times (n+1)/2)$

The triangular factor $U$ or $L$ from the Cholesky factorization $B=U^{H}U$ or $B=L{L}^H$, in the same storage format as $B$.

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'}$, then

if no exception or warning is raised, 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]$. The eigenvectors are normalized as follows:

if $itype=1$ or $2$, $Z^{H}BZ=I$;

if $itype=3$, $Z^H{B}^{-1}Z=I$;

if an eigenvector fails to converge ($errno$ = 1 … $n$), then that column of $Z$ contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in $jfail$.

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 $n$ must be used.

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

If $jobz=\text{'V'}$, then

if no exception or warning is raised, the first $m$ elements of $jfail$ are zero;

if $errno$ = 1 … $n$, the first $\text{errno}$ elements of $jfail$ contains the indices of the eigenvectors that failed to converge.

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

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $itype$.

Constraint: $itype=1$, $2$ or $3$.

(errno $-2$)

On entry, error in parameter $jobz$.

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

(errno $-3$)

On entry, error in parameter $erange$.

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

(errno $-4$)

On entry, error in parameter $uplo$.

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

(errno $-5$)

On entry, error in parameter $n$.

Constraint: $n\ge 0$.

(errno $-9$)

On entry, error in parameter $vu$.

Constraint: $vl<vu$.

(errno $-10$)

On entry, error in parameter $il$.

(errno $-11$)

On entry, error in parameter $iu$.

(errno $i>n$)

If $\text{errno}=n+⟨value⟩$, for $1\le ⟨value⟩\le n$, then the leading minor of order $⟨value⟩$ of $B$ is not positive definite. The factorization of $B$ could not be completed and no eigenvalues or eigenvectors were computed.

Warns

NagAlgorithmicWarning

(errno $i\le n$)

The algorithm failed to converge; $⟨value⟩$ eigenvectors failed to converge.

Notes

zhpgvx first performs a Cholesky factorization of the matrix $B$ as $B=U^{H}U$, when $uplo=\text{'U'}$ or $B=L{L}^H$, when $uplo=\text{'L'}$. The generalized problem is then reduced to a standard symmetric eigenvalue problem

$$Cx=\lambda x\text{,}$$

which is solved for the desired eigenvalues and eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

For the problem $Az=\lambda Bz$, the eigenvectors are normalized so that the matrix of eigenvectors, $Z$, satisfies

$$Z^{H}AZ=\Lambda \text{and}{Z}^{H}BZ=I\text{,}$$

where $\Lambda$ is the diagonal matrix whose diagonal elements are the eigenvalues. For the problem $ABz=\lambda z$ we correspondingly have

$$Z^{-1}A{Z}^{-H}=\Lambda \text{and}{Z}^{H}BZ=I\text{,}$$

and for $BAz=\lambda z$ we have

$$Z^{H}AZ=\Lambda \text{and}{Z}^H{B}^{-1}Z=I\text{.}$$

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

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

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