Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_lapack_dhgeqz (f08xe)

## Purpose

nag_lapack_dhgeqz (f08xe) implements the QZ$QZ$ method for finding generalized eigenvalues of the real matrix pair (A,B)$\left(A,B\right)$ of order n$n$, which is in the generalized upper Hessenberg form.

## Syntax

[a, b, alphar, alphai, beta, q, z, info] = f08xe(job, compq, compz, ilo, ihi, a, b, q, z, 'n', n)
[a, b, alphar, alphai, beta, q, z, info] = nag_lapack_dhgeqz(job, compq, compz, ilo, ihi, a, b, q, z, 'n', n)

## Description

nag_lapack_dhgeqz (f08xe) implements a single-double-shift version of the QZ$QZ$ method for finding the generalized eigenvalues of the real matrix pair (A,B)$\left(A,B\right)$ which is in the generalized upper Hessenberg form. If the matrix pair (A,B)$\left(A,B\right)$ is not in the generalized upper Hessenberg form, then the function nag_lapack_dgghrd (f08we) should be called before invoking nag_lapack_dhgeqz (f08xe).
This problem is mathematically equivalent to solving the equation
 det(A − λB) = 0. $det(A-λB)=0.$
Note that, to avoid underflow, overflow and other arithmetic problems, the generalized eigenvalues λj${\lambda }_{j}$ are never computed explicitly by this function but defined as ratios between two computed values, αj${\alpha }_{j}$ and βj${\beta }_{j}$:
 λj = αj / βj. $λj=αj/βj.$
The parameters αj${\alpha }_{j}$, in general, are finite complex values and βj${\beta }_{j}$ are finite real non-negative values.
If desired, the matrix pair (A,B)$\left(A,B\right)$ may be reduced to generalized Schur form. That is, the transformed matrix B$B$ is upper triangular and the transformed matrix A$A$ is block upper triangular, where the diagonal blocks are either 1$1$ by 1$1$ or 2$2$ by 2$2$. The 1$1$ by 1$1$ blocks provide generalized eigenvalues which are real and the 2$2$ by 2$2$ blocks give complex generalized eigenvalues.
The parameter job specifies two options. If job = 'S'${\mathbf{job}}=\text{'S'}$ then the matrix pair (A,B)$\left(A,B\right)$ is simultaneously reduced to Schur form by applying one orthogonal transformation (usually called Q$Q$) on the left and another (usually called Z$Z$) on the right. That is,
 A ← QTAZ B ← QTBZ
$A←QTAZ B←QTBZ$
The 2$2$ by 2$2$ upper-triangular diagonal blocks of B$B$ corresponding to 2$2$ by 2$2$ blocks of a will be reduced to non-negative diagonal matrices. That is, if a(j + 1,j)${\mathbf{a}}\left(j+1,j\right)$ is nonzero, then b(j + 1,j) = b(j,j + 1) = 0${\mathbf{b}}\left(j+1,j\right)={\mathbf{b}}\left(j,j+1\right)=0$ and b(j,j)${\mathbf{b}}\left(j,j\right)$ and b(j + 1,j + 1)${\mathbf{b}}\left(j+1,j+1\right)$ will be non-negative.
If job = 'E'${\mathbf{job}}=\text{'E'}$, then at each iteration the same transformations are computed but they are only applied to those parts of A$A$ and B$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 = 'S'${\mathbf{job}}=\text{'S'}$ and compq = 'V'${\mathbf{compq}}=\text{'V'}$ or 'I'$\text{'I'}$, and compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$, then the orthogonal transformations used to reduce the pair (A,B)$\left(A,B\right)$ are accumulated into the input arrays q and z. If generalized eigenvectors are required then job must be set to job = 'S'${\mathbf{job}}=\text{'S'}$ and if left (right) generalized eigenvectors are to be computed then compq (compz) must be set to compq = 'V'${\mathbf{compq}}=\text{'V'}$ or 'I'$\text{'I'}$ and not compq'N'${\mathbf{compq}}\ne \text{'N'}$.
If compq = 'I'${\mathbf{compq}}=\text{'I'}$, then eigenvectors are accumulated on the identity matrix and on exit the array q contains the left eigenvector matrix Q$Q$. However, if compq = 'V'${\mathbf{compq}}=\text{'V'}$ then the transformations are accumulated on the user-supplied matrix Q0${Q}_{0}$ in array q on entry and thus on exit q contains the matrix product QQ0$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

## Parameters

### Compulsory Input Parameters

1:     job – string (length ≥ 1)
Specifies the operations to be performed on (A,B)$\left(A,B\right)$.
job = 'E'${\mathbf{job}}=\text{'E'}$
The matrix pair (A,B)$\left(A,B\right)$ on exit might not be in the generalized Schur form.
job = 'S'${\mathbf{job}}=\text{'S'}$
The matrix pair (A,B)$\left(A,B\right)$ on exit will be in the generalized Schur form.
Constraint: job = 'E'${\mathbf{job}}=\text{'E'}$ or 'S'$\text{'S'}$.
2:     compq – string (length ≥ 1)
Specifies the operations to be performed on Q$Q$:
compq = 'N'${\mathbf{compq}}=\text{'N'}$
The array q is unchanged.
compq = 'V'${\mathbf{compq}}=\text{'V'}$
The left transformation Q$Q$ is accumulated on the array q.
compq = 'I'${\mathbf{compq}}=\text{'I'}$
The array q is initialized to the identity matrix before the left transformation Q$Q$ is accumulated in q.
Constraint: compq = 'N'${\mathbf{compq}}=\text{'N'}$, 'V'$\text{'V'}$ or 'I'$\text{'I'}$.
3:     compz – string (length ≥ 1)
Specifies the operations to be performed on Z$Z$.
compz = 'N'${\mathbf{compz}}=\text{'N'}$
The array z is unchanged.
compz = 'V'${\mathbf{compz}}=\text{'V'}$
The right transformation Z$Z$ is accumulated on the array z.
compz = 'I'${\mathbf{compz}}=\text{'I'}$
The array z is initialized to the identity matrix before the right transformation Z$Z$ is accumulated in z.
Constraint: compz = 'N'${\mathbf{compz}}=\text{'N'}$, 'V'$\text{'V'}$ or 'I'$\text{'I'}$.
4:     ilo – int64int32nag_int scalar
5:     ihi – int64int32nag_int scalar
The indices ilo${i}_{\mathrm{lo}}$ and ihi${i}_{\mathrm{hi}}$, respectively which define the upper triangular parts of A$A$. The submatrices A(1 : ilo1,1 : ilo1)$A\left(1:{i}_{\mathrm{lo}}-1,1:{i}_{\mathrm{lo}}-1\right)$ and A(ihi + 1 : n,ihi + 1 : n)$A\left({i}_{\mathrm{hi}}+1:n,{i}_{\mathrm{hi}}+1:n\right)$ are then upper triangular. These parameters are provided by nag_lapack_dggbal (f08wh) if the matrix pair was previously balanced; otherwise, ilo = 1${\mathbf{ilo}}=1$ and ihi = n${\mathbf{ihi}}={\mathbf{n}}$.
Constraints:
• if n > 0${\mathbf{n}}>0$, 1 ilo ihi n $1\le {\mathbf{ilo}}\le {\mathbf{ihi}}\le {\mathbf{n}}$;
• if n = 0${\mathbf{n}}=0$, ilo = 1${\mathbf{ilo}}=1$ and ihi = 0${\mathbf{ihi}}=0$.
6:     a(lda, : $:$) – double array
The first dimension of the array a must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The second dimension of the array must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The n$n$ by n$n$ upper Hessenberg matrix A$A$. The elements below the first subdiagonal must be set to zero.
7:     b(ldb, : $:$) – double array
The first dimension of the array b must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The second dimension of the array must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The n$n$ by n$n$ upper triangular matrix B$B$. The elements below the diagonal must be zero.
8:     q(ldq, : $:$) – double array
The first dimension, ldq, of the array q must satisfy
• if compq = 'V'${\mathbf{compq}}=\text{'V'}$ or 'I'$\text{'I'}$, ldqn$\mathit{ldq}\ge {\mathbf{n}}$;
• if compq = 'N'${\mathbf{compq}}=\text{'N'}$, ldq1$\mathit{ldq}\ge 1$.
The second dimension of the array must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if compq = 'V'${\mathbf{compq}}=\text{'V'}$ or 'I'$\text{'I'}$ and at least 1$1$ if compq = 'N'${\mathbf{compq}}=\text{'N'}$
If compq = 'V'${\mathbf{compq}}=\text{'V'}$, the matrix Q0${Q}_{0}$. The matrix Q0${Q}_{0}$ is usually the matrix Q$Q$ returned by nag_lapack_dgghrd (f08we).
If compq = 'N'${\mathbf{compq}}=\text{'N'}$, q is not referenced.
9:     z(ldz, : $:$) – double array
The first dimension, ldz, of the array z must satisfy
• if compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$, ldzn$\mathit{ldz}\ge {\mathbf{n}}$;
• if compz = 'N'${\mathbf{compz}}=\text{'N'}$, ldz1$\mathit{ldz}\ge 1$.
The second dimension of the array must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$ and at least 1$1$ if compz = 'N'${\mathbf{compz}}=\text{'N'}$
If compz = 'V'${\mathbf{compz}}=\text{'V'}$, the matrix Z0${Z}_{0}$. The matrix Z0${Z}_{0}$ is usually the matrix Z$Z$ returned by nag_lapack_dgghrd (f08we).
If compz = 'N'${\mathbf{compz}}=\text{'N'}$, z is not referenced.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The second dimension of the arrays a, b, q, z and the first dimension of the arrays a, b, q, z. (An error is raised if these dimensions are not equal.)
n$n$, the order of the matrices A$A$, B$B$, Q$Q$ and Z$Z$.
Constraint: n0${\mathbf{n}}\ge 0$.

### Input Parameters Omitted from the MATLAB Interface

lda ldb ldq ldz work lwork

### Output Parameters

1:     a(lda, : $:$) – double array
The first dimension of the array a will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The second dimension of the array will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
ldamax (1,n)$\mathit{lda}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
If job = 'S'${\mathbf{job}}=\text{'S'}$, the matrix pair (A,B)$\left(A,B\right)$ will be simultaneously reduced to generalized Schur form.
If job = 'E'${\mathbf{job}}=\text{'E'}$, the 1$1$ by 1$1$ and 2$2$ by 2$2$ diagonal blocks of the matrix pair (A,B)$\left(A,B\right)$ will give generalized eigenvalues but the remaining elements will be irrelevant.
2:     b(ldb, : $:$) – double array
The first dimension of the array b will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The second dimension of the array will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
ldbmax (1,n)$\mathit{ldb}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
If job = 'S'${\mathbf{job}}=\text{'S'}$, the matrix pair (A,B)$\left(A,B\right)$ will be simultaneously reduced to generalized Schur form.
If job = 'E'${\mathbf{job}}=\text{'E'}$, the 1$1$ by 1$1$ and 2$2$ by 2$2$ diagonal blocks of the matrix pair (A,B)$\left(A,B\right)$ will give generalized eigenvalues but the remaining elements will be irrelevant.
3:     alphar(n) – double array
The real parts of αj${\alpha }_{\mathit{j}}$, for j = 1,2,,n$\mathit{j}=1,2,\dots ,n$.
4:     alphai(n) – double array
The imaginary parts of αj${\alpha }_{\mathit{j}}$, for j = 1,2,,n$\mathit{j}=1,2,\dots ,n$.
5:     beta(n) – double array
βj${\beta }_{\mathit{j}}$, for j = 1,2,,n$\mathit{j}=1,2,\dots ,n$.
6:     q(ldq, : $:$) – double array
The first dimension, ldq, of the array q will be
• if compq = 'V'${\mathbf{compq}}=\text{'V'}$ or 'I'$\text{'I'}$, ldqn$\mathit{ldq}\ge {\mathbf{n}}$;
• if compq = 'N'${\mathbf{compq}}=\text{'N'}$, ldq1$\mathit{ldq}\ge 1$.
The second dimension of the array will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if compq = 'V'${\mathbf{compq}}=\text{'V'}$ or 'I'$\text{'I'}$ and at least 1$1$ if compq = 'N'${\mathbf{compq}}=\text{'N'}$
If compq = 'V'${\mathbf{compq}}=\text{'V'}$, q contains the matrix product QQ0$Q{Q}_{0}$.
If compq = 'I'${\mathbf{compq}}=\text{'I'}$, q contains the transformation matrix Q$Q$.
7:     z(ldz, : $:$) – double array
The first dimension, ldz, of the array z will be
• if compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$, ldzn$\mathit{ldz}\ge {\mathbf{n}}$;
• if compz = 'N'${\mathbf{compz}}=\text{'N'}$, ldz1$\mathit{ldz}\ge 1$.
The second dimension of the array will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$ and at least 1$1$ if compz = 'N'${\mathbf{compz}}=\text{'N'}$
If compz = 'V'${\mathbf{compz}}=\text{'V'}$, z contains the matrix product ZZ0$Z{Z}_{0}$.
If compz = 'I'${\mathbf{compz}}=\text{'I'}$, z contains the transformation matrix Z$Z$.
8:     info – int64int32nag_int scalar
info = 0${\mathbf{info}}=0$ unless the function detects an error (see Section [Error Indicators and Warnings]).

## Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

info = i${\mathbf{info}}=-i$
If info = i${\mathbf{info}}=-i$, parameter i$i$ had an illegal value on entry. The parameters are numbered as follows:
1: job, 2: compq, 3: compz, 4: n, 5: ilo, 6: ihi, 7: a, 8: lda, 9: b, 10: ldb, 11: alphar, 12: alphai, 13: beta, 14: q, 15: ldq, 16: z, 17: ldz, 18: work, 19: lwork, 20: info.
It is possible that info refers to a parameter that is omitted from the MATLAB interface. This usually indicates that an error in one of the other input parameters has caused an incorrect value to be inferred.
W INFO > 0${\mathbf{INFO}}>0$
If 1infon$1\le {\mathbf{info}}\le {\mathbf{n}}$, the QZ$QZ$ iteration did not converge and the matrix pair (A,B)$\left(A,B\right)$ is not in the generalized Schur form at exit. However, if ${\mathbf{info}}<{\mathbf{n}}$, then the computed αi${\alpha }_{i}$ and βi${\beta }_{i}$ should be correct for i = info + 1,,n$i={\mathbf{info}}+1,\dots ,{\mathbf{n}}$.
If n + 1info2 × n${\mathbf{n}}+1\le {\mathbf{info}}\le 2×{\mathbf{n}}$, the computation of shifts failed and the matrix pair (A,B)$\left(A,B\right)$ is not in the generalized Schur form at exit. However, if info < 2 × n${\mathbf{info}}<2×{\mathbf{n}}$, then the computed αi${\alpha }_{i}$ and βi${\beta }_{i}$ should be correct for i = infon + 1,,n$i={\mathbf{info}}-{\mathbf{n}}+1,\dots ,{\mathbf{n}}$.
If info > 2 × n${\mathbf{info}}>2×{\mathbf{n}}$, then an unexpected Library error has occurred. Please contact NAG with details of your program.

## Accuracy

Please consult Section 4.11 of the LAPACK Users' Guide (see Anderson et al. (1999)) and Chapter 6 of Stewart and Sun (1990), for more information.

nag_lapack_dhgeqz (f08xe) is the fifth step in the solution of the real generalized eigenvalue problem and is called after nag_lapack_dgghrd (f08we).
The complex analogue of this function is nag_lapack_zhgeqz (f08xs).

## Example

function nag_lapack_dhgeqz_example
job = 'E';
compq = 'N';
compz = 'N';
ilo = int64(1);
ihi = int64(5);
a = [-2.189810707792021, -0.3180631496384764, 2.054737360337475, 4.737051060297061, -4.624850206812896;
-0.8394814256667084, -0.04260743300187281, 1.713177967213399, 7.519359344321846, -17.18497520550213;
0, -0.2846066329550604, -1.010138844149892, -7.592717358895769, 26.44987440544933;
0, 0, 0.03760479481131811, 1.406985307241882, -3.364334058817744;
0, 0, 0, 0.3813286811696227, -0.9937277052627631];
b = [-1.424780684877501, -0.3475888720966965, 2.117452772490474, 5.581290451976649, -3.926921758179354;
0, -0.07815942868997351, 0.1189259258468025, 8.094037761230025, -15.29282773410979;
0, 0, 1.002063542716526, -10.93557202634477, 26.59706530085059;
0, 0, 0, 0.5820029710844786, -0.07301489821533858;
0, 0, 0, 0, 0.5321375124277468];
q = [0];
z = [0];
[aOut, bOut, alphar, alphai, beta, qOut, zOut, info] = ...
nag_lapack_dhgeqz(job, compq, compz, ilo, ihi, a, b, q, z)

aOut =

-0.4330    0.6639    0.9146   -2.7880   29.4287
0    2.2720   -0.7786    3.8072   13.4928
0    0.6959    0.0160    2.1786   -9.1764
0         0         0    0.7767   -3.6815
0         0         0         0   -0.1777

bOut =

0.1777   -0.2721   -1.8961   -5.7730   30.3016
0    1.9594         0    4.4074   11.8279
0         0    0.2951    1.4584   -7.7335
0         0         0    0.7767   -0.2075
0         0         0         0    0.4330

alphar =

-0.4330
0.4809
0.4427
0.7767
-0.1777

alphai =

0
0.6299
-0.5798
0
0

beta =

0.1777
0.7925
0.7295
0.7767
0.4330

qOut =

0

zOut =

0

info =

0

function f08xe_example
job = 'E';
compq = 'N';
compz = 'N';
ilo = int64(1);
ihi = int64(5);
a = [-2.189810707792021, -0.3180631496384764, 2.054737360337475, 4.737051060297061, -4.624850206812896;
-0.8394814256667084, -0.04260743300187281, 1.713177967213399, 7.519359344321846, -17.18497520550213;
0, -0.2846066329550604, -1.010138844149892, -7.592717358895769, 26.44987440544933;
0, 0, 0.03760479481131811, 1.406985307241882, -3.364334058817744;
0, 0, 0, 0.3813286811696227, -0.9937277052627631];
b = [-1.424780684877501, -0.3475888720966965, 2.117452772490474, 5.581290451976649, -3.926921758179354;
0, -0.07815942868997351, 0.1189259258468025, 8.094037761230025, -15.29282773410979;
0, 0, 1.002063542716526, -10.93557202634477, 26.59706530085059;
0, 0, 0, 0.5820029710844786, -0.07301489821533858;
0, 0, 0, 0, 0.5321375124277468];
q = [0];
z = [0];
[aOut, bOut, alphar, alphai, beta, qOut, zOut, info] = ...
f08xe(job, compq, compz, ilo, ihi, a, b, q, z)

aOut =

-0.4330    0.6639    0.9146   -2.7880   29.4287
0    2.2720   -0.7786    3.8072   13.4928
0    0.6959    0.0160    2.1786   -9.1764
0         0         0    0.7767   -3.6815
0         0         0         0   -0.1777

bOut =

0.1777   -0.2721   -1.8961   -5.7730   30.3016
0    1.9594         0    4.4074   11.8279
0         0    0.2951    1.4584   -7.7335
0         0         0    0.7767   -0.2075
0         0         0         0    0.4330

alphar =

-0.4330
0.4809
0.4427
0.7767
-0.1777

alphai =

0
0.6299
-0.5798
0
0

beta =

0.1777
0.7925
0.7295
0.7767
0.4330

qOut =

0

zOut =

0

info =

0