naginterfaces.library.lapackeig.dhgeqz

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

dhgeqz implements the $QZ$ method for finding generalized eigenvalues of the real 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 f08xe

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f08/f08xef.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 dggbal() 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 dggbal() if the matrix pair was previously balanced; otherwise, $ilo=1$ and $ihi=n$.

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

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

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

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

qfloat, 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 dgghd3().

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

zfloat, 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 dgghd3().

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

Returns

afloat, 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.

bfloat, 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.

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

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

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

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

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

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

qfloat, ndarray, shape $(:,:)$

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

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

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

Warns

NagAlgorithmicWarning

(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

dhgeqz implements a single-double-shift version of the $QZ$ method for finding the generalized eigenvalues of the real 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 dgghd3() should be called before invoking dhgeqz.

This problem is mathematically equivalent to solving the 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 matrix $B$ is upper triangular and the transformed matrix $A$ is block upper triangular, where the diagonal blocks are either $1\times 1$ or $2\times 2$. The $1\times 1$ blocks provide generalized eigenvalues which are real and the $2\times 2$ blocks give complex generalized eigenvalues.

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 orthogonal 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^{T}AZ\\ B\leftarrow Q^{T}BZ\end{array}\end{array}$$

The $2\times 2$ upper-triangular diagonal blocks of $B$ corresponding to $2\times 2$ blocks of $a$ will be reduced to non-negative diagonal matrices. That is, if $a[j,j-1]$ is nonzero, then $b[j,j-1]=b[j-1,j]=0$ and $b[j-1,j-1]$ and $b[j,j]$ will be non-negative.

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 orthogonal 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'}$ and not $compq\ne \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 on 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