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_zgges (f08xn)

## Purpose

nag_lapack_zgges (f08xn) computes the generalized eigenvalues, the generalized Schur form (S,T) $\left(S,T\right)$ and, optionally, the left and/or right generalized Schur vectors for a pair of n$n$ by n$n$ complex nonsymmetric matrices (A,B) $\left(A,B\right)$.

## Syntax

[a, b, sdim, alpha, beta, vsl, vsr, info] = f08xn(jobvsl, jobvsr, sort, selctg, a, b, 'n', n)
[a, b, sdim, alpha, beta, vsl, vsr, info] = nag_lapack_zgges(jobvsl, jobvsr, sort, selctg, a, b, 'n', n)

## Description

The generalized Schur factorization for a pair of complex matrices (A,B) $\left(A,B\right)$ is given by
 A = QSZH ,   B = QTZH , $A = QSZH , B = QTZH ,$
where Q$Q$ and Z$Z$ are unitary, T$T$ and S$S$ are upper triangular. The generalized eigenvalues, λ $\lambda$, of (A,B) $\left(A,B\right)$ are computed from the diagonals of T$T$ and S$S$ and satisfy
 Az = λBz , $Az = λBz ,$
where z$z$ is the corresponding generalized eigenvector. λ $\lambda$ is actually returned as the pair (α,β) $\left(\alpha ,\beta \right)$ such that
 λ = α / β $λ = α/β$
since β $\beta$, or even both α $\alpha$ and β $\beta$ can be zero. The columns of Q$Q$ and Z$Z$ are the left and right generalized Schur vectors of (A,B) $\left(A,B\right)$.
Optionally, nag_lapack_zgges (f08xn) can order the generalized eigenvalues on the diagonals of (S,T) $\left(S,T\right)$ so that selected eigenvalues are at the top left. The leading columns of Q$Q$ and Z$Z$ then form an orthonormal basis for the corresponding eigenspaces, the deflating subspaces.
nag_lapack_zgges (f08xn) computes T$T$ to have real non-negative diagonal entries. The generalized Schur factorization, before reordering, is computed by the QZ$QZ$ algorithm.

## 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 http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## Parameters

### Compulsory Input Parameters

1:     jobvsl – string (length ≥ 1)
If jobvsl = 'N'${\mathbf{jobvsl}}=\text{'N'}$, do not compute the left Schur vectors.
If jobvsl = 'V'${\mathbf{jobvsl}}=\text{'V'}$, compute the left Schur vectors.
Constraint: jobvsl = 'N'${\mathbf{jobvsl}}=\text{'N'}$ or 'V'$\text{'V'}$.
2:     jobvsr – string (length ≥ 1)
If jobvsr = 'N'${\mathbf{jobvsr}}=\text{'N'}$, do not compute the right Schur vectors.
If jobvsr = 'V'${\mathbf{jobvsr}}=\text{'V'}$, compute the right Schur vectors.
Constraint: jobvsr = 'N'${\mathbf{jobvsr}}=\text{'N'}$ or 'V'$\text{'V'}$.
3:     sort – string (length ≥ 1)
Specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.
sort = 'N'${\mathbf{sort}}=\text{'N'}$
Eigenvalues are not ordered.
sort = 'S'${\mathbf{sort}}=\text{'S'}$
Eigenvalues are ordered (see selctg).
Constraint: sort = 'N'${\mathbf{sort}}=\text{'N'}$ or 'S'$\text{'S'}$.
4:     selctg – function handle or string containing name of m-file
If sort = 'S'${\mathbf{sort}}=\text{'S'}$, selctg is used to select generalized eigenvalues to the top left of the generalized Schur form.
If sort = 'N'${\mathbf{sort}}=\text{'N'}$, selctg is not referenced by nag_lapack_zgges (f08xn), and may be called with the string 'f08xnz'.
[result] = selctg(a, b)

Input Parameters

1:     a – complex scalar
2:     b – complex scalar
An eigenvalue a(j) / b(j) ${\mathbf{a}}\left(j\right)/{\mathbf{b}}\left(j\right)$ is selected if selctg (a(j),b(j)) ${\mathbf{selctg}}\left({\mathbf{a}}\left(j\right),{\mathbf{b}}\left(j\right)\right)$ is true.
Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy selctg (a(j),b(j)) = true ${\mathbf{selctg}}\left({\mathbf{a}}\left(j\right),{\mathbf{b}}\left(j\right)\right)=\mathbf{true}$ after ordering. ${\mathbf{INFO}}=\mathbf{n}+{\mathbf{2}}$ in this case.

Output Parameters

1:     result – logical scalar
The result of the function.
5:     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 first of the pair of matrices, A$A$.
6:     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 second of the pair of matrices, B$B$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The first dimension of the arrays a, b The second dimension of the arrays a, b.
n$n$, the order of the matrices A$A$ and B$B$.
Constraint: n0${\mathbf{n}}\ge 0$.

### Input Parameters Omitted from the MATLAB Interface

lda ldb ldvsl ldvsr work lwork rwork bwork

### 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)$.
a stores its generalized Schur form S$S$.
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)$.
b stores its generalized Schur form T$T$.
3:     sdim – int64int32nag_int scalar
If sort = 'N'${\mathbf{sort}}=\text{'N'}$, sdim = 0${\mathbf{sdim}}=0$.
If sort = 'S'${\mathbf{sort}}=\text{'S'}$, sdim = ${\mathbf{sdim}}=\text{}$ number of eigenvalues (after sorting) for which selctg is true.
4:     alpha(n) – complex array
See the description of beta.
5:     beta(n) – complex array
alpha(j) / beta(j)${\mathbf{alpha}}\left(\mathit{j}\right)/{\mathbf{beta}}\left(\mathit{j}\right)$, for j = 1,2,,n$\mathit{j}=1,2,\dots ,{\mathbf{n}}$, will be the generalized eigenvalues. alpha(j)${\mathbf{alpha}}\left(\mathit{j}\right)$, for j = 1,2,,n$\mathit{j}=1,2,\dots ,{\mathbf{n}}$ and beta(j)${\mathbf{beta}}\left(\mathit{j}\right)$, for j = 1,2,,n$\mathit{j}=1,2,\dots ,{\mathbf{n}}$, are the diagonals of the complex Schur form (A,B)$\left(A,B\right)$ output by nag_lapack_zgges (f08xn). The beta(j)${\mathbf{beta}}\left(j\right)$ will be non-negative real.
Note:  the quotients alpha(j) / beta(j)${\mathbf{alpha}}\left(j\right)/{\mathbf{beta}}\left(j\right)$ may easily overflow or underflow, and beta(j)${\mathbf{beta}}\left(j\right)$ may even be zero. Thus, you should avoid naively computing the ratio α / β$\alpha /\beta$. However, alpha will always be less than and usually comparable with a$‖{\mathbf{a}}‖$ in magnitude, and beta will always be less than and usually comparable with b$‖{\mathbf{b}}‖$.
6:     vsl(ldvsl, : $:$) – complex array
The first dimension, ldvsl, of the array vsl will be
• if jobvsl = 'V'${\mathbf{jobvsl}}=\text{'V'}$, ldvsl max (1,n) $\mathit{ldvsl}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise ldvsl1$\mathit{ldvsl}\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 jobvsl = 'V'${\mathbf{jobvsl}}=\text{'V'}$, and at least 1$1$ otherwise
If jobvsl = 'V'${\mathbf{jobvsl}}=\text{'V'}$, vsl will contain the left Schur vectors, Q$Q$.
If jobvsl = 'N'${\mathbf{jobvsl}}=\text{'N'}$, vsl is not referenced.
7:     vsr(ldvsr, : $:$) – complex array
The first dimension, ldvsr, of the array vsr will be
• if jobvsr = 'V'${\mathbf{jobvsr}}=\text{'V'}$, ldvsr max (1,n) $\mathit{ldvsr}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise ldvsr1$\mathit{ldvsr}\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 jobvsr = 'V'${\mathbf{jobvsr}}=\text{'V'}$, and at least 1$1$ otherwise
If jobvsr = 'V'${\mathbf{jobvsr}}=\text{'V'}$, vsr will contain the right Schur vectors, Z$Z$.
If jobvsr = 'N'${\mathbf{jobvsr}}=\text{'N'}$, vsr is not referenced.
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: jobvsl, 2: jobvsr, 3: sort, 4: selctg, 5: n, 6: a, 7: lda, 8: b, 9: ldb, 10: sdim, 11: alpha, 12: beta, 13: vsl, 14: ldvsl, 15: vsr, 16: ldvsr, 17: work, 18: lwork, 19: rwork, 20: bwork, 21: 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 = 1ton${\mathbf{INFO}}=1 \text{to} {\mathbf{n}}$
The QZ$QZ$ iteration failed. (A,B)$\left(A,B\right)$ are not in Schur form, but alpha(j)${\mathbf{alpha}}\left(j\right)$ and beta(j)${\mathbf{beta}}\left(j\right)$ should be correct for j = info + 1,,n$j={\mathbf{info}}+1,\dots ,{\mathbf{n}}$.
INFO = N + 1${\mathbf{INFO}}={\mathbf{N}}+1$
Unexpected error returned from nag_lapack_zhgeqz (f08xs).
W INFO = N + 2${\mathbf{INFO}}={\mathbf{N}}+2$
After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the generalized Schur form no longer satisfy selctg = true${\mathbf{selctg}}=\mathbf{true}$. This could also be caused by underflow due to scaling.
W INFO = N + 3${\mathbf{INFO}}={\mathbf{N}}+3$
The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

## Accuracy

The computed generalized Schur factorization satisfies
 A + E = QS ZH ,   B + F = QT ZH , $A+E = QS ZH , B+F = QT ZH ,$
where
 ‖(E,F)‖F = O(ε) ‖(A,B)‖F $‖(E,F)‖ F = O(ε) ‖(A,B)‖ F$
and ε$\epsilon$ is the machine precision. See Section 4.11 of Anderson et al. (1999) for further details.

The total number of floating point operations is proportional to n3${n}^{3}$.
The real analogue of this function is nag_lapack_dgges (f08xa).

## Example

```function nag_lapack_zgges_example
jobvsl = 'Vectors (left)';
jobvsr = 'Vectors (right)';
sortp = 'No sort';
a = [ -21.1 - 22.5i,  53.5 - 50.5i,  -34.5 + 127.5i,  7.5 + 0.5i;
-0.46 - 7.78i,  -3.5 - 37.5i,  -15.5 + 58.5i,  -10.5 - 1.5i;
4.3 - 5.5i,  39.7 - 17.1i,  -68.5 + 12.5i,  -7.5 - 3.5i;
5.5 + 4.4i,  14.4 + 43.3i,  -32.5 - 46i,  -19 - 32.5i];
b = [ 1 - 5i,  1.6 + 1.2i,  -3 + 0i,  0 - 1i;
0.8 - 0.6i,  3 - 5i,  -4 + 3i,  -2.4 - 3.2i;
1 + 0i,  2.4 + 1.8i,  -4 - 5i,  0 - 3i;
0 + 1i,  -1.8 + 2.4i,  0 - 4i,  4 - 5i];
[aOut, bOut, sdim, alpha, beta, vsl, vsr, info] = ...
nag_lapack_zgges(jobvsl, jobvsr, sortp, @selctg, a, b)
```
```

aOut =

1.0e+02 *

0.1903 - 0.5710i   0.5359 - 0.8982i  -0.8131 - 0.6323i   1.0666 - 0.4479i
0.0000 + 0.0000i   0.1188 - 0.2970i   0.0356 + 0.2763i  -0.0067 - 0.1642i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.1096 - 0.0365i  -0.2502 - 0.0820i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.2187 - 0.2734i

bOut =

6.3443 + 0.0000i   3.3986 + 0.7119i  -0.5152 - 2.3820i   6.5818 + 2.4299i
0.0000 + 0.0000i   5.9409 + 0.0000i  -2.4480 - 0.3427i   5.7385 - 0.7017i
0.0000 + 0.0000i   0.0000 + 0.0000i   3.6536 + 0.0000i  -1.4096 - 3.9326i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   5.4681 + 0.0000i

sdim =

0

alpha =

19.0329 -57.0986i
11.8818 -29.7045i
10.9609 - 3.6536i
21.8722 -27.3403i

beta =

6.3443 + 0.0000i
5.9409 + 0.0000i
3.6536 + 0.0000i
5.4681 + 0.0000i

vsl =

-0.3347 + 0.7387i   0.2872 - 0.4789i   0.1725 + 0.0093i   0.0144 - 0.0212i
-0.1277 + 0.2493i  -0.0282 + 0.4999i   0.1541 - 0.8008i  -0.0087 - 0.0767i
-0.3557 + 0.0396i  -0.4615 - 0.0822i  -0.3939 + 0.0258i  -0.1464 - 0.6892i
-0.0126 - 0.3682i   0.1508 - 0.4417i   0.1517 - 0.3555i  -0.7049 - 0.0133i

vsr =

-0.9240 - 0.1977i   0.2460 + 0.2090i  -0.0054 + 0.0542i   0.0000 + 0.0000i
-0.1716 + 0.0793i  -0.5943 + 0.0905i   0.7467 - 0.2127i  -0.0000 - 0.0000i
-0.0793 - 0.1716i   0.0943 - 0.5082i   0.0102 - 0.4438i   0.7034 - 0.0728i
0.1716 - 0.0793i   0.5082 + 0.0943i   0.4438 + 0.0102i  -0.0728 - 0.7034i

info =

0

```
```function f08xn_example
jobvsl = 'Vectors (left)';
jobvsr = 'Vectors (right)';
sortp = 'No sort';
a = [ -21.1 - 22.5i,  53.5 - 50.5i,  -34.5 + 127.5i,  7.5 + 0.5i;
-0.46 - 7.78i,  -3.5 - 37.5i,  -15.5 + 58.5i,  -10.5 - 1.5i;
4.3 - 5.5i,  39.7 - 17.1i,  -68.5 + 12.5i,  -7.5 - 3.5i;
5.5 + 4.4i,  14.4 + 43.3i,  -32.5 - 46i,  -19 - 32.5i];
b = [ 1 - 5i,  1.6 + 1.2i,  -3 + 0i,  0 - 1i;
0.8 - 0.6i,  3 - 5i,  -4 + 3i,  -2.4 - 3.2i;
1 + 0i,  2.4 + 1.8i,  -4 - 5i,  0 - 3i;
0 + 1i,  -1.8 + 2.4i,  0 - 4i,  4 - 5i];
[aOut, bOut, sdim, alpha, beta, vsl, vsr, info] = ...
f08xn(jobvsl, jobvsr, sortp, @selctg, a, b)
```
```

aOut =

1.0e+02 *

0.1903 - 0.5710i   0.5359 - 0.8982i  -0.8131 - 0.6323i   1.0666 - 0.4479i
0.0000 + 0.0000i   0.1188 - 0.2970i   0.0356 + 0.2763i  -0.0067 - 0.1642i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.1096 - 0.0365i  -0.2502 - 0.0820i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.2187 - 0.2734i

bOut =

6.3443 + 0.0000i   3.3986 + 0.7119i  -0.5152 - 2.3820i   6.5818 + 2.4299i
0.0000 + 0.0000i   5.9409 + 0.0000i  -2.4480 - 0.3427i   5.7385 - 0.7017i
0.0000 + 0.0000i   0.0000 + 0.0000i   3.6536 + 0.0000i  -1.4096 - 3.9326i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   5.4681 + 0.0000i

sdim =

0

alpha =

19.0329 -57.0986i
11.8818 -29.7045i
10.9609 - 3.6536i
21.8722 -27.3403i

beta =

6.3443 + 0.0000i
5.9409 + 0.0000i
3.6536 + 0.0000i
5.4681 + 0.0000i

vsl =

-0.3347 + 0.7387i   0.2872 - 0.4789i   0.1725 + 0.0093i   0.0144 - 0.0212i
-0.1277 + 0.2493i  -0.0282 + 0.4999i   0.1541 - 0.8008i  -0.0087 - 0.0767i
-0.3557 + 0.0396i  -0.4615 - 0.0822i  -0.3939 + 0.0258i  -0.1464 - 0.6892i
-0.0126 - 0.3682i   0.1508 - 0.4417i   0.1517 - 0.3555i  -0.7049 - 0.0133i

vsr =

-0.9240 - 0.1977i   0.2460 + 0.2090i  -0.0054 + 0.0542i   0.0000 + 0.0000i
-0.1716 + 0.0793i  -0.5943 + 0.0905i   0.7467 - 0.2127i  -0.0000 - 0.0000i
-0.0793 - 0.1716i   0.0943 - 0.5082i   0.0102 - 0.4438i   0.7034 - 0.0728i
0.1716 - 0.0793i   0.5082 + 0.0943i   0.4438 + 0.0102i  -0.0728 - 0.7034i

info =

0

```