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_zhgeqz (f08xs)

## Purpose

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

## Syntax

[a, b, alpha, beta, q, z, info] = f08xs(job, compq, compz, ilo, ihi, a, b, q, z, 'n', n)
[a, b, alpha, beta, q, z, info] = nag_lapack_zhgeqz(job, compq, compz, ilo, ihi, a, b, q, z, 'n', n)

## Description

nag_lapack_zhgeqz (f08xs) implements a single-shift version of the QZ$QZ$ method for finding the generalized eigenvalues of the complex 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_zgghrd (f08ws) should be called before invoking nag_lapack_zhgeqz (f08xs).
This problem is mathematically equivalent to solving the matrix 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 matrices A$A$ and B$B$ are upper triangular and the diagonal values of A$A$ and B$B$ provide α$\alpha$ and β$\beta$.
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 unitary transformation (usually called Q$Q$) on the left and another (usually called Z$Z$) on the right. That is,
 A ← QHAZ B ← QHBZ
$A←QHAZ B←QHBZ$
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 unitary 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'}$ rather than compq = 'N'${\mathbf{compq}}=\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 in 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_zggbal (f08wv) 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, : $:$) – complex 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, : $:$) – complex 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, : $:$) – complex 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_zgghrd (f08ws).
If compq = 'N'${\mathbf{compq}}=\text{'N'}$, q is not referenced.
9:     z(ldz, : $:$) – complex 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_zgghrd (f08ws).
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 rwork

### Output Parameters

1:     a(lda, : $:$) – complex 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, : $:$) – complex 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:     alpha(n) – complex array
αj${\alpha }_{\mathit{j}}$, for j = 1,2,,n$\mathit{j}=1,2,\dots ,n$.
4:     beta(n) – complex array
βj${\beta }_{\mathit{j}}$, for j = 1,2,,n$\mathit{j}=1,2,\dots ,n$.
5:     q(ldq, : $:$) – complex 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$.
6:     z(ldz, : $:$) – complex 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$.
7:     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

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: alpha, 12: beta, 13: q, 14: ldq, 15: z, 16: ldz, 17: work, 18: lwork, 19: rwork, 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.
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_zhgeqz (f08xs) is the fifth step in the solution of the complex generalized eigenvalue problem and is called after nag_lapack_zgghrd (f08ws).
The number of floating point operations taken by this function is proportional to n3${n}^{3}$.
The real analogue of this function is nag_lapack_dhgeqz (f08xe).

## Example

```function nag_lapack_zhgeqz_example
job = 'E';
compq = 'N';
compz = 'N';
ilo = int64(1);
ihi = int64(4);
a = [ -2.867890104378767 - 1.594524360587801i, ...
-0.809337098604556 - 0.3276607283529636i,  -4.900373446187322 - 0.9865105961392747i, ...
-0.04834623303205134 + 1.162636735910666i;
-2.671939461604618 + 0.5945064559939077i, ...
-0.7895240421486864 + 0.04903482075256903i,  -4.954929775736532 - 0.1634387045312732i, ...
-0.4386325532444865 - 0.5739313215365673i;
0 + 0i,  -0.09825782595897961 - 0.01149417965898412i, ...
-1.167669110453865 - 0.1365936851015428i,  -1.756232676852781 - 0.2054437263770907i;
0 + 0i,  0 + 0i,  0.08729329881919053 + 0.003819531014388017i, ...
0.03170217359735389 + 0.001387133226909417i];
b = [-1.774823934929885,  -0.7210490086119171 + 0.04290055077107185i, ...
-5.020721861715561 + 1.189845102979979i,  -0.1450254390211963 + 0.7257437885879333i;
0 + 0i,  -0.2176281526219798 + 0.03516041416104906i, ...
-2.541102900685018 - 0.1458063680541886i,  -0.8228500482725508 - 0.4184333588843852i;
0 + 0i,  0 + 0i,  -1.395782135347712 - 0.1632782984144689i, ...
-1.747484189780436 - 0.2044203302132494i;
0 + 0i,  0 + 0i,  0 + 0i,  -0.09963146114886638 - 0.004359389105629694i];
q = [complex(0)];
z = [complex(0)];
[aOut, bOut, alpha, beta, qOut, zOut, info] = ...
nag_lapack_zhgeqz(job, compq, compz, ilo, ihi, a, b, q, z)
```
```

aOut =

-0.1438 + 0.3741i  -1.7000 + 0.1473i  -1.4170 - 1.0916i  -6.6330 - 0.8784i
0.0000 + 0.0000i   0.2824 + 0.5209i  -1.5812 + 0.5647i   1.9829 - 3.4956i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.1522 - 0.2800i   1.1701 - 1.7439i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.8591 - 0.0636i

bOut =

0.2263 + 0.0000i   0.2959 + 0.6808i  -0.9706 + 0.3572i  -3.4142 + 1.1586i
0.0000 + 0.0000i   0.5723 + 0.0000i  -1.7815 + 0.5004i   1.7329 - 3.4482i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.3323 + 0.0000i   1.7834 - 2.2524i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   1.2738 + 0.0000i

alpha =

-0.1438 + 0.3741i
0.2824 + 0.5209i
0.1522 - 0.2800i
0.8591 - 0.0636i

beta =

0.2263 + 0.0000i
0.5723 + 0.0000i
0.3323 + 0.0000i
1.2738 + 0.0000i

qOut =

0.0000 + 0.0000i

zOut =

0.0000 + 0.0000i

info =

0

```
```function f08xs_example
job = 'E';
compq = 'N';
compz = 'N';
ilo = int64(1);
ihi = int64(4);
a = [ -2.867890104378767 - 1.594524360587801i, ...
-0.809337098604556 - 0.3276607283529636i,  -4.900373446187322 - 0.9865105961392747i, ...
-0.04834623303205134 + 1.162636735910666i;
-2.671939461604618 + 0.5945064559939077i, ...
-0.7895240421486864 + 0.04903482075256903i,  -4.954929775736532 - 0.1634387045312732i, ...
-0.4386325532444865 - 0.5739313215365673i;
0 + 0i,  -0.09825782595897961 - 0.01149417965898412i, ...
-1.167669110453865 - 0.1365936851015428i,  -1.756232676852781 - 0.2054437263770907i;
0 + 0i,  0 + 0i,  0.08729329881919053 + 0.003819531014388017i, ...
0.03170217359735389 + 0.001387133226909417i];
b = [-1.774823934929885,  -0.7210490086119171 + 0.04290055077107185i, ...
-5.020721861715561 + 1.189845102979979i,  -0.1450254390211963 + 0.7257437885879333i;
0 + 0i,  -0.2176281526219798 + 0.03516041416104906i, ...
-2.541102900685018 - 0.1458063680541886i,  -0.8228500482725508 - 0.4184333588843852i;
0 + 0i,  0 + 0i,  -1.395782135347712 - 0.1632782984144689i, ...
-1.747484189780436 - 0.2044203302132494i;
0 + 0i,  0 + 0i,  0 + 0i,  -0.09963146114886638 - 0.004359389105629694i];
q = [complex(0)];
z = [complex(0)];
[aOut, bOut, alpha, beta, qOut, zOut, info] = ...
f08xs(job, compq, compz, ilo, ihi, a, b, q, z)
```
```

aOut =

-0.1438 + 0.3741i  -1.7000 + 0.1473i  -1.4170 - 1.0916i  -6.6330 - 0.8784i
0.0000 + 0.0000i   0.2824 + 0.5209i  -1.5812 + 0.5647i   1.9829 - 3.4956i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.1522 - 0.2800i   1.1701 - 1.7439i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.8591 - 0.0636i

bOut =

0.2263 + 0.0000i   0.2959 + 0.6808i  -0.9706 + 0.3572i  -3.4142 + 1.1586i
0.0000 + 0.0000i   0.5723 + 0.0000i  -1.7815 + 0.5004i   1.7329 - 3.4482i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.3323 + 0.0000i   1.7834 - 2.2524i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   1.2738 + 0.0000i

alpha =

-0.1438 + 0.3741i
0.2824 + 0.5209i
0.1522 - 0.2800i
0.8591 - 0.0636i

beta =

0.2263 + 0.0000i
0.5723 + 0.0000i
0.3323 + 0.0000i
1.2738 + 0.0000i

qOut =

0.0000 + 0.0000i

zOut =

0.0000 + 0.0000i

info =

0

```