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 $\left(S,T\right)$ and, optionally, the left and/or right generalized Schur vectors for a pair of $n$ by $n$ complex nonsymmetric matrices $\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 $\left(A,B\right)$ is given by
 $A = QSZH , B = QTZH ,$
where $Q$ and $Z$ are unitary, $T$ and $S$ are upper triangular. The generalized eigenvalues, $\lambda$, of $\left(A,B\right)$ are computed from the diagonals of $T$ and $S$ and satisfy
 $Az = λBz ,$
where $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$ and $Z$ are the left and right generalized Schur vectors of $\left(A,B\right)$.
Optionally, nag_lapack_zggesx (f08xp) can order the generalized eigenvalues on the diagonals of $\left(S,T\right)$ so that selected eigenvalues are at the top left. The leading columns of $Q$ and $Z$ then form an orthonormal basis for the corresponding eigenspaces, the deflating subspaces.
nag_lapack_zggesx (f08xp) computes $T$ to have real non-negative diagonal entries. The generalized Schur factorization, before reordering, is computed by the $QZ$ algorithm.
The reciprocals of the condition estimates, the reciprocal values of the left and right projection norms, are returned in ${\mathbf{rconde}}\left(1\right)$ and ${\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 ${\mathbf{rcondv}}\left(1\right)$ and ${\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:     $\mathrm{jobvsl}$ – string (length ≥ 1)
If ${\mathbf{jobvsl}}=\text{'N'}$, do not compute the left Schur vectors.
If ${\mathbf{jobvsl}}=\text{'V'}$, compute the left Schur vectors.
Constraint: ${\mathbf{jobvsl}}=\text{'N'}$ or $\text{'V'}$.
2:     $\mathrm{jobvsr}$ – string (length ≥ 1)
If ${\mathbf{jobvsr}}=\text{'N'}$, do not compute the right Schur vectors.
If ${\mathbf{jobvsr}}=\text{'V'}$, compute the right Schur vectors.
Constraint: ${\mathbf{jobvsr}}=\text{'N'}$ or $\text{'V'}$.
3:     $\mathrm{sort}$ – string (length ≥ 1)
Specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.
${\mathbf{sort}}=\text{'N'}$
Eigenvalues are not ordered.
${\mathbf{sort}}=\text{'S'}$
Eigenvalues are ordered (see selctg).
Constraint: ${\mathbf{sort}}=\text{'N'}$ or $\text{'S'}$.
4:     $\mathrm{selctg}$ – function handle or string containing name of m-file
If ${\mathbf{sort}}=\text{'S'}$, selctg is used to select generalized eigenvalues to the top left of the generalized Schur form.
If ${\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:     $\mathrm{a}$ – complex scalar
2:     $\mathrm{b}$ – complex scalar
An eigenvalue ${\mathbf{a}}\left(j\right)/{\mathbf{b}}\left(j\right)$ is selected if ${\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 ${\mathbf{selctg}}\left({\mathbf{a}}\left(j\right),{\mathbf{b}}\left(j\right)\right)=\mathit{true}$ after ordering. ${\mathbf{info}}=\mathbf{n}+{\mathbf{2}}$ in this case.

Output Parameters

1:     $\mathrm{result}$ – logical scalar
$\mathbf{result}=\mathit{true}$ for selected eigenvalues.
5:     $\mathrm{sense}$ – string (length ≥ 1)
Determines which reciprocal condition numbers are computed.
${\mathbf{sense}}=\text{'N'}$
None are computed.
${\mathbf{sense}}=\text{'E'}$
Computed for average of selected eigenvalues only.
${\mathbf{sense}}=\text{'V'}$
Computed for selected deflating subspaces only.
${\mathbf{sense}}=\text{'B'}$
Computed for both.
If ${\mathbf{sense}}=\text{'E'}$, $\text{'V'}$ or $\text{'B'}$, ${\mathbf{sort}}=\text{'S'}$.
Constraint: ${\mathbf{sense}}=\text{'N'}$, $\text{'E'}$, $\text{'V'}$ or $\text{'B'}$.
6:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The first of the pair of matrices, $A$.
7:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array
The first dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second of the pair of matrices, $B$.

### Optional Input Parameters

1:     $\mathrm{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$, the order of the matrices $A$ and $B$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
a stores its generalized Schur form $S$.
2:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array
The first dimension of the array b will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
b stores its generalized Schur form $T$.
3:     $\mathrm{sdim}$int64int32nag_int scalar
If ${\mathbf{sort}}=\text{'N'}$, ${\mathbf{sdim}}=0$.
If ${\mathbf{sort}}=\text{'S'}$, ${\mathbf{sdim}}=\text{}$ number of eigenvalues (after sorting) for which selctg is true.
4:     $\mathrm{alpha}\left({\mathbf{n}}\right)$ – complex array
See the description of beta.
5:     $\mathrm{beta}\left({\mathbf{n}}\right)$ – complex array
${\mathbf{alpha}}\left(\mathit{j}\right)/{\mathbf{beta}}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,{\mathbf{n}}$, will be the generalized eigenvalues. ${\mathbf{alpha}}\left(j\right)$ and ${\mathbf{beta}}\left(j\right),j=1,2,\dots ,{\mathbf{n}}$ are the diagonals of the complex Schur form $\left(S,T\right)$. ${\mathbf{beta}}\left(j\right)$ will be non-negative real.
Note:  the quotients ${\mathbf{alpha}}\left(j\right)/{\mathbf{beta}}\left(j\right)$ may easily overflow or underflow, and ${\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 $‖{\mathbf{a}}‖$ in magnitude, and beta will always be less than and usually comparable with $‖{\mathbf{b}}‖$.
6:     $\mathrm{vsl}\left(\mathit{ldvsl},:\right)$ – complex array
The first dimension, $\mathit{ldvsl}$, of the array vsl will be
• if ${\mathbf{jobvsl}}=\text{'V'}$, $\mathit{ldvsl}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldvsl}=1$.
The second dimension of the array vsl will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{jobvsl}}=\text{'V'}$ and $1$ otherwise.
If ${\mathbf{jobvsl}}=\text{'V'}$, vsl will contain the left Schur vectors, $Q$.
If ${\mathbf{jobvsl}}=\text{'N'}$, vsl is not referenced.
7:     $\mathrm{vsr}\left(\mathit{ldvsr},:\right)$ – complex array
The first dimension, $\mathit{ldvsr}$, of the array vsr will be
• if ${\mathbf{jobvsr}}=\text{'V'}$, $\mathit{ldvsr}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldvsr}=1$.
The second dimension of the array vsr will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{jobvsr}}=\text{'V'}$ and $1$ otherwise.
If ${\mathbf{jobvsr}}=\text{'V'}$, vsr will contain the right Schur vectors, $Z$.
If ${\mathbf{jobvsr}}=\text{'N'}$, vsr is not referenced.
8:     $\mathrm{rconde}\left(2\right)$ – double array
If ${\mathbf{sense}}=\text{'E'}$ or $\text{'B'}$, ${\mathbf{rconde}}\left(1\right)$ and ${\mathbf{rconde}}\left(2\right)$ contain the reciprocal condition numbers for the average of the selected eigenvalues.
If ${\mathbf{sense}}=\text{'N'}$ or $\text{'V'}$, rconde is not referenced.
9:     $\mathrm{rcondv}\left(2\right)$ – double array
If ${\mathbf{sense}}=\text{'V'}$ or $\text{'B'}$, ${\mathbf{rcondv}}\left(1\right)$ and ${\mathbf{rcondv}}\left(2\right)$ contain the reciprocal condition numbers for the selected deflating subspaces.
if ${\mathbf{sense}}=\text{'N'}$ or $\text{'E'}$, rcondv is not referenced.
10:   $\mathrm{info}$int64int32nag_int scalar
${\mathbf{info}}=0$ unless the function detects an error (see 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.

${\mathbf{info}}=-i$
If ${\mathbf{info}}=-i$, parameter $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  ${\mathbf{info}}=1 \text{to} {\mathbf{n}}$
The $QZ$ iteration failed. $\left(A,B\right)$ are not in Schur form, but ${\mathbf{alpha}}\left(j\right)$ and ${\mathbf{beta}}\left(j\right)$ should be correct for $j={\mathbf{info}}+1,\dots ,{\mathbf{n}}$.
${\mathbf{info}}={\mathbf{n}}+1$
Unexpected error returned from nag_lapack_zhgeqz (f08xs).
W  ${\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 ${\mathbf{selctg}}=\mathit{true}$. This could also be caused by underflow due to scaling.
W  ${\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 ,$
where
 $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 ${n}^{3}$.
The real analogue of this function is nag_lapack_dggesx (f08xb).

## Example

This example finds the generalized Schur factorization of the matrix pair $\left(A,B\right)$, where
 $A = -21.10-22.50i 53.50-50.50i -34.50+127.50i 7.50+00.50i -0.46-07.78i -3.50-37.50i -15.50+058.50i -10.50-01.50i 4.30-05.50i 39.70-17.10i -68.50+012.50i -7.50-03.50i 5.50+04.40i 14.40+43.30i -32.50-046.00i -19.00-32.50i$
and
 $B = 1.00-5.00i 1.60+1.20i -3.00+0.00i 0.00-1.00i 0.80-0.60i 3.00-5.00i -4.00+3.00i -2.40-3.20i 1.00+0.00i 2.40+1.80i -4.00-5.00i 0.00-3.00i 0.00+1.00i -1.80+2.40i 0.00-4.00i 4.00-5.00i ,$
such that the eigenvalues of $\left(A,B\right)$ for which $\left|\lambda \right|<6$ correspond to the top left diagonal elements of the generalized Schur form, $\left(S,T\right)$. Estimates of the condition numbers for the selected eigenvalue cluster and corresponding deflating subspaces are also returned.
Note that the block size (NB) of $64$ assumed in this example is not realistic for such a small problem, but should be suitable for large problems.
```function f08xp_example

fprintf('f08xp example results\n\n');

% Matrix pair (A,B)
A = [ -21.10 - 22.50i,  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.30 -  5.50i,  39.7 - 17.1i,  -68.5 +  12.5i,  -7.5 -  3.5i;
5.50 +  4.40i,  14.4 + 43.3i,  -32.5 -  46i,   -19.0 - 32.5i];
B = [ 1   - 5i,    1.6 + 1.2i, -3 + 0i,  0   - 1i;
0.8 - 0.6i,  3.0 - 5.0i, -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];

% Generalized Schur form (S,T) of (A,B), generalized eigenvalues
% and Schur vectors Q and Z with sorting: select eigenvalues for which
% the diagonal of T is at least 6 times bigger than the corresponding
% diagonal of S.
jobvsl = 'Vectors (left)';
jobvsr = 'Vectors (right)';
sortp = 'Sort';
selctg = @(a, b) (abs(a) < 6*abs(b));
sense = 'Both reciprocal condition numbers';
[S, T, sdim, alpha, beta, VSL, VSR, rconde, rcondv, info] = ...
f08xp( ...
jobvsl, jobvsr, sortp, selctg, sense, A, B);

fprintf('Number of selected eigenvalues = %4d\n\n', sdim);
disp('Generalized eigenvalues');
eigs = alpha./beta;
disp(eigs(1:sdim));

fprintf('%s\n%s\n%s = %8.1e, %s = %8.1e\n\n', ...
'Reciprocals of left and right projection norms onto', ...
'the deflating subspaces for the selected eigenvalues', ...
'rconde(1)', rconde(1), 'rconde(2)', rconde(2));
fprintf('%s\n%s\n%s = %8.1e, %s = %8.1e\n\n', ...
'Reciprocals condition numbers for the left and right', ...
'deflating subspaces', 'rcondv(1)', rcondv(1), ...
'rcondv(2)', rcondv(2));

anorm = norm(A,2);
bnorm = norm(B,2);
abnorm = sqrt(anorm^2+bnorm^2);
fprintf('%s = %8.1e\n', ...
'Approximate asymptotic error bound for selected eigenvalues   ', ...
x02aj*abnorm/rconde(1));
fprintf('%s = %8.1e\n', ...
'Approximate asymptotic error bound for the deflating subspaces', ...
x02aj*abnorm/rcondv(2));

```
```f08xp example results

Number of selected eigenvalues =    2

Generalized eigenvalues
2.0000 - 5.0000i
3.0000 - 1.0000i

Reciprocals of left and right projection norms onto
the deflating subspaces for the selected eigenvalues
rconde(1) =  1.2e-01, rconde(2) =  1.6e-01

Reciprocals condition numbers for the left and right
deflating subspaces
rcondv(1) =  4.8e-01, rcondv(2) =  4.7e-01

Approximate asymptotic error bound for selected eigenvalues    =  1.8e-13
Approximate asymptotic error bound for the deflating subspaces =  4.7e-14
```