naginterfaces.library.lapackeig.zhgeqz

naginterfaces.library.lapackeig.zhgeqz(job, compq, compz, ilo, ihi, a, b, q, z)

zhgeqz implements the $QZ$ method for finding generalized eigenvalues of the complex matrix pair $(A,B)$ of order $n$, which is in the generalized upper Hessenberg form.

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

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

Parameters

jobstr, length 1

Specifies the operations to be performed on $(A,B)$.

$job=\text{'E'}$

The matrix pair $(A,B)$ on exit might not be in the generalized Schur form.

$job=\text{'S'}$

The matrix pair $(A,B)$ on exit will be in the generalized Schur form.

compqstr, length 1

Specifies the operations to be performed on $Q$:

$compq=\text{'N'}$

The array $q$ is unchanged.

$compq=\text{'V'}$

The left transformation $Q$ is accumulated on the array $q$.

$compq=\text{'I'}$

The array $q$ is initialized to the identity matrix before the left transformation $Q$ is accumulated in $q$.

compzstr, length 1

Specifies the operations to be performed on $Z$.

$compz=\text{'N'}$

The array $z$ is unchanged.

$compz=\text{'V'}$

The right transformation $Z$ is accumulated on the array $z$.

$compz=\text{'I'}$

The array $z$ is initialized to the identity matrix before the right transformation $Z$ is accumulated in $z$.

iloint

The indices $i_{lo}$ and $i_{hi}$, respectively which define the upper triangular parts of $A$. The submatrices $A(1:i_{lo}-1,1:i_{lo}-1)$ and $A(i_{hi}+1:n,i_{hi}+1:n)$ are then upper triangular. These arguments are provided by zggbal() if the matrix pair was previously balanced; otherwise, $ilo=1$ and $ihi=n$.

ihiint

The indices $i_{lo}$ and $i_{hi}$, respectively which define the upper triangular parts of $A$. The submatrices $A(1:i_{lo}-1,1:i_{lo}-1)$ and $A(i_{hi}+1:n,i_{hi}+1:n)$ are then upper triangular. These arguments are provided by zggbal() if the matrix pair was previously balanced; otherwise, $ilo=1$ and $ihi=n$.

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

The $n\times n$ upper Hessenberg matrix $A$. The elements below the first subdiagonal must be set to zero.

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

The $n\times n$ upper triangular matrix $B$. The elements below the diagonal must be zero.

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

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

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

If $compq=\text{'V'}$, the matrix $Q_0$. The matrix $Q_0$ is usually the matrix $Q$ returned by zgghd3().

If $compq=\text{'N'}$, $q$ is not referenced.

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'})$: $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'}$, the matrix $Z_0$. The matrix $Z_0$ is usually the matrix $Z$ returned by zgghd3().

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

Returns

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

If $job=\text{'S'}$, the matrix pair $(A,B)$ will be simultaneously reduced to generalized Schur form.

If $job=\text{'E'}$, the $1\times 1$ and $2\times 2$ diagonal blocks of the matrix pair $(A,B)$ will give generalized eigenvalues but the remaining elements will be irrelevant.

bcomplex, ndarray, shape $(n,n)$

If $job=\text{'S'}$, the matrix pair $(A,B)$ will be simultaneously reduced to generalized Schur form.

If $job=\text{'E'}$, the $1\times 1$ and $2\times 2$ diagonal blocks of the matrix pair $(A,B)$ will give generalized eigenvalues but the remaining elements will be irrelevant.

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

${\alpha }_{\text{j}}$, for $\text{j}=1,2,\dots ,n$.

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

${\beta }_{\text{j}}$, for $\text{j}=1,2,\dots ,n$.

qcomplex, ndarray, shape $(:,:)$

If $compq=\text{'V'}$, $q$ contains the matrix product $Q{Q}_0$.

If $compq=\text{'I'}$, $q$ contains the transformation matrix $Q$.

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

If $compz=\text{'V'}$, $z$ contains the matrix product $Z{Z}_0$.

If $compz=\text{'I'}$, $z$ contains the transformation matrix $Z$.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $job$.

Constraint: $job=\text{'E'}$ or $\text{'S'}$.

(errno $-2$)

On entry, error in parameter $compq$.

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

(errno $-3$)

On entry, error in parameter $compz$.

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

(errno $-4$)

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

Constraint: $n\ge 0$.

(errno $-6$)

On entry, error in parameter $ihi$.

Constraint: $1\le ilo\le ihi\le n$.

(errno $-6$)

On entry, error in parameter $ihi$.

Constraint: $ilo=1$ and $ihi=0$.

(errno $i<n$)

The $QZ$ iteration did not converge and the matrix pair $(A,B)$ is not in the generalized Schur form. The computed ${\alpha }_i$ and ${\beta }_i$ should be correct for $i=⟨value⟩,\dots ,⟨value⟩$.

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

The computation of shifts failed and the matrix pair $(A,B)$ is not in the generalized Schur form. The computed ${\alpha }_i$ and ${\beta }_i$ should be correct for $i=⟨value⟩,\dots ,⟨value⟩$.

(errno $i>2\times n$)

An unexpected Library error has occurred.

Notes

zhgeqz implements a single-shift version of the $QZ$ method for finding the generalized eigenvalues of the complex matrix pair $(A,B)$ which is in the generalized upper Hessenberg form. If the matrix pair $(A,B)$ is not in the generalized upper Hessenberg form, then the function zgghd3() should be called before invoking zhgeqz.

This problem is mathematically equivalent to solving the matrix equation

$$det(A-\lambda B)=0\text{.}$$

Note that, to avoid underflow, overflow and other arithmetic problems, the generalized eigenvalues ${\lambda }_j$ are never computed explicitly by this function but defined as ratios between two computed values, ${\alpha }_j$ and ${\beta }_j$:

$${\lambda }_j={\alpha }_j/{\beta }_j\text{.}$$

The arguments ${\alpha }_j$, in general, are finite complex values and ${\beta }_j$ are finite real non-negative values.

If desired, the matrix pair $(A,B)$ may be reduced to generalized Schur form. That is, the transformed matrices $A$ and $B$ are upper triangular and the diagonal values of $A$ and $B$ provide $\alpha$ and $\beta$.

The argument $job$ specifies two options. If $job=\text{'S'}$ then the matrix pair $(A,B)$ is simultaneously reduced to Schur form by applying one unitary transformation (usually called $Q$) on the left and another (usually called $Z$) on the right. That is,

$$\begin{array}{c}\begin{array}{c}A\leftarrow Q^{H}AZ\\ B\leftarrow Q^{H}BZ\end{array}\end{array}$$

If $job=\text{'E'}$, then at each iteration the same transformations are computed but they are only applied to those parts of $A$ and $B$ which are needed to compute $\alpha$ and $\beta$. This option could be used if generalized eigenvalues are required but not generalized eigenvectors.

If $job=\text{'S'}$ and $compq=\text{'V'}$ or $\text{'I'}$, and $compz=\text{'V'}$ or $\text{'I'}$, then the unitary transformations used to reduce the pair $(A,B)$ are accumulated into the input arrays $q$ and $z$. If generalized eigenvectors are required then $job$ must be set to $job=\text{'S'}$ and if left (right) generalized eigenvectors are to be computed then $compq$ ($compz$) must be set to $compq=\text{'V'}$ or $\text{'I'}$ rather than $compq=\text{'N'}$.

If $compq=\text{'I'}$, then eigenvectors are accumulated on the identity matrix and on exit the array $q$ contains the left eigenvector matrix $Q$. However, if $compq=\text{'V'}$ then the transformations are accumulated in the user-supplied matrix $Q_0$ in array $q$ on entry and thus on exit $q$ contains the matrix product $Q{Q}_0$. A similar convention is used for $compz$.

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

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

Moler, C B and Stewart, G W, 1973, An algorithm for generalized matrix eigenproblems, SIAM J. Numer. Anal. (10), 241–256

Stewart, G W and Sun, J-G, 1990, Matrix Perturbation Theory, Academic Press, London