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_zggesx (f08xp)

## Purpose

nag_lapack_zggesx (f08xp) 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)$.
Estimates of condition numbers for selected generalized eigenvalue clusters and Schur vectors are also computed.

## Syntax

[a, b, sdim, alpha, beta, vsl, vsr, rconde, rcondv, info] = f08xp(jobvsl, jobvsr, sort, selctg, sense, a, b, 'n', n)
[a, b, sdim, alpha, beta, vsl, vsr, rconde, rcondv, info] = nag_lapack_zggesx(jobvsl, jobvsr, sort, selctg, sense, 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_zggesx (f08xp) 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_zggesx (f08xp) computes T$T$ to have real non-negative diagonal entries. The generalized Schur factorization, before reordering, is computed by the QZ$QZ$ algorithm.
The reciprocals of the condition estimates, the reciprocal values of the left and right projection norms, are returned in rconde(1) ${\mathbf{rconde}}\left(1\right)$ and rconde(2) ${\mathbf{rconde}}\left(2\right)$ respectively, for the selected generalized eigenvalues, together with reciprocal condition estimates for the corresponding left and right deflating subspaces, in rcondv(1) ${\mathbf{rcondv}}\left(1\right)$ and rcondv(2) ${\mathbf{rcondv}}\left(2\right)$. See Section 4.11 of Anderson et al. (1999) for further information.

## 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_zggesx (f08xp), 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:     sense – string (length ≥ 1)
Determines which reciprocal condition numbers are computed.
sense = 'N'${\mathbf{sense}}=\text{'N'}$
None are computed.
sense = 'E'${\mathbf{sense}}=\text{'E'}$
Computed for average of selected eigenvalues only.
sense = 'V'${\mathbf{sense}}=\text{'V'}$
Computed for selected deflating subspaces only.
sense = 'B'${\mathbf{sense}}=\text{'B'}$
Computed for both.
If sense = 'E'${\mathbf{sense}}=\text{'E'}$, 'V'$\text{'V'}$ or 'B'$\text{'B'}$, sort = 'S'${\mathbf{sort}}=\text{'S'}$.
Constraint: sense = 'N'${\mathbf{sense}}=\text{'N'}$, 'E'$\text{'E'}$, 'V'$\text{'V'}$ or 'B'$\text{'B'}$.
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 first of the pair of matrices, A$A$.
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 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 and the second dimension of the arrays a, b. (An error is raised if these dimensions are not equal.)
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 iwork liwork 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(j\right)$ and beta(j),j = 1,2,,n${\mathbf{beta}}\left(j\right),j=1,2,\dots ,{\mathbf{n}}$ are the diagonals of the complex Schur form (S,T)$\left(S,T\right)$. 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:     rconde(2$2$) – double array
If sense = 'E'${\mathbf{sense}}=\text{'E'}$ or 'B'$\text{'B'}$, rconde(1)${\mathbf{rconde}}\left(1\right)$ and rconde(2)${\mathbf{rconde}}\left(2\right)$ contain the reciprocal condition numbers for the average of the selected eigenvalues.
If sense = 'N'${\mathbf{sense}}=\text{'N'}$ or 'V'$\text{'V'}$, rconde is not referenced.
9:     rcondv(2$2$) – double array
If sense = 'V'${\mathbf{sense}}=\text{'V'}$ or 'B'$\text{'B'}$, rcondv(1) ${\mathbf{rcondv}}\left(1\right)$ and rcondv(2) ${\mathbf{rcondv}}\left(2\right)$ contain the reciprocal condition numbers for the selected deflating subspaces.
if sense = 'N'${\mathbf{sense}}=\text{'N'}$ or 'E'$\text{'E'}$, rcondv is not referenced.
10:   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: sense, 6: n, 7: a, 8: lda, 9: b, 10: ldb, 11: sdim, 12: alpha, 13: beta, 14: vsl, 15: ldvsl, 16: vsr, 17: ldvsr, 18: rconde, 19: rcondv, 20: work, 21: lwork, 22: rwork, 23: iwork, 24: liwork, 25: bwork, 26: 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 ZT ,   B + F = QT ZT , $A+E = QS ZT , B+F = QT ZT ,$
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_dggesx (f08xb).

## Example

```function nag_lapack_zggesx_example
jobvsl = 'Vectors (left)';
jobvsr = 'Vectors (right)';
sortp = 'Sort';
selctg = @(a, b) (abs(a) < 6*abs(b));
sense = 'Both reciprocal condition numbers';
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, rconde, rcondv, info] = ...
nag_lapack_zggesx(jobvsl, jobvsr, sortp, selctg, sense, a, b)
```
```

aOut =

1.0e+02 *

0.1070 - 0.2674i  -0.7269 - 0.1571i  -1.2235 - 0.1408i   0.9900 - 0.3874i
0.0000 + 0.0000i   0.1101 - 0.0367i   0.0422 + 0.3157i  -0.1903 - 0.3856i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.2104 - 0.6313i   0.1256 + 0.3220i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.2187 - 0.2734i

bOut =

5.3490 + 0.0000i  -0.1267 - 1.0111i  -1.1949 - 3.2556i   4.4160 + 1.9056i
0.0000 + 0.0000i   3.6701 + 0.0000i  -1.9413 + 2.2087i   2.8993 - 6.1707i
0.0000 + 0.0000i   0.0000 + 0.0000i   7.0147 + 0.0000i  -2.6653 + 4.8354i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   5.4681 + 0.0000i

sdim =

2

alpha =

10.6980 -26.7450i
11.0103 - 3.6701i
21.0441 -63.1323i
21.8722 -27.3403i

beta =

5.3490 + 0.0000i
3.6701 + 0.0000i
7.0147 + 0.0000i
5.4681 + 0.0000i

vsl =

-0.3733 + 0.8687i   0.2117 - 0.1177i  -0.2156 + 0.0104i   0.0144 - 0.0212i
-0.1606 + 0.0762i  -0.7130 - 0.5203i   0.1568 - 0.3985i  -0.0087 - 0.0767i
-0.1864 + 0.0164i  -0.2349 + 0.0826i   0.2003 + 0.6054i  -0.1464 - 0.6892i
-0.0137 - 0.1978i   0.0473 - 0.3131i  -0.5982 + 0.0746i  -0.7049 - 0.0133i

vsr =

-0.9697 - 0.2276i   0.0340 + 0.0612i   0.0530 - 0.0126i   0.0000 + 0.0000i
-0.0052 + 0.0023i   0.0189 - 0.6299i   0.7066 + 0.3218i  -0.0000 - 0.0000i
-0.0610 - 0.0143i  -0.2882 - 0.4647i  -0.4385 + 0.0694i   0.7034 - 0.0728i
0.0143 - 0.0610i   0.4647 - 0.2882i  -0.0694 - 0.4385i  -0.0728 - 0.7034i

rconde =

0.1205
0.1625

rcondv =

0.4770
0.4690

info =

0

```
```function f08xp_example
jobvsl = 'Vectors (left)';
jobvsr = 'Vectors (right)';
sortp = 'Sort';
selctg = @(a, b) (abs(a) < 6*abs(b));
sense = 'Both reciprocal condition numbers';
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, rconde, rcondv, info] = ...
f08xp(jobvsl, jobvsr, sortp, selctg, sense, a, b)
```
```

aOut =

1.0e+02 *

0.1070 - 0.2674i  -0.7269 - 0.1571i  -1.2235 - 0.1408i   0.9900 - 0.3874i
0.0000 + 0.0000i   0.1101 - 0.0367i   0.0422 + 0.3157i  -0.1903 - 0.3856i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.2104 - 0.6313i   0.1256 + 0.3220i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.2187 - 0.2734i

bOut =

5.3490 + 0.0000i  -0.1267 - 1.0111i  -1.1949 - 3.2556i   4.4160 + 1.9056i
0.0000 + 0.0000i   3.6701 + 0.0000i  -1.9413 + 2.2087i   2.8993 - 6.1707i
0.0000 + 0.0000i   0.0000 + 0.0000i   7.0147 + 0.0000i  -2.6653 + 4.8354i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   5.4681 + 0.0000i

sdim =

2

alpha =

10.6980 -26.7450i
11.0103 - 3.6701i
21.0441 -63.1323i
21.8722 -27.3403i

beta =

5.3490 + 0.0000i
3.6701 + 0.0000i
7.0147 + 0.0000i
5.4681 + 0.0000i

vsl =

-0.3733 + 0.8687i   0.2117 - 0.1177i  -0.2156 + 0.0104i   0.0144 - 0.0212i
-0.1606 + 0.0762i  -0.7130 - 0.5203i   0.1568 - 0.3985i  -0.0087 - 0.0767i
-0.1864 + 0.0164i  -0.2349 + 0.0826i   0.2003 + 0.6054i  -0.1464 - 0.6892i
-0.0137 - 0.1978i   0.0473 - 0.3131i  -0.5982 + 0.0746i  -0.7049 - 0.0133i

vsr =

-0.9697 - 0.2276i   0.0340 + 0.0612i   0.0530 - 0.0126i   0.0000 + 0.0000i
-0.0052 + 0.0023i   0.0189 - 0.6299i   0.7066 + 0.3218i  -0.0000 - 0.0000i
-0.0610 - 0.0143i  -0.2882 - 0.4647i  -0.4385 + 0.0694i   0.7034 - 0.0728i
0.0143 - 0.0610i   0.4647 - 0.2882i  -0.0694 - 0.4385i  -0.0728 - 0.7034i

rconde =

0.1205
0.1625

rcondv =

0.4770
0.4690

info =

0

```