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_dgges (f08xa)

## Purpose

nag_lapack_dgges (f08xa) computes the generalized eigenvalues, the generalized real 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$ real nonsymmetric matrices (A,B) $\left(A,B\right)$.

## Syntax

[a, b, sdim, alphar, alphai, beta, vsl, vsr, info] = f08xa(jobvsl, jobvsr, sort, selctg, a, b, 'n', n)
[a, b, sdim, alphar, alphai, beta, vsl, vsr, info] = nag_lapack_dgges(jobvsl, jobvsr, sort, selctg, a, b, 'n', n)

## Description

The generalized Schur factorization for a pair of real matrices (A,B) $\left(A,B\right)$ is given by
 A = QSZT ,   B = QTZT , $A = QSZT , B = QTZT ,$
where Q$Q$ and Z$Z$ are orthogonal, T$T$ is upper triangular and S$S$ is upper quasi-triangular with 1$1$ by 1$1$ and 2$2$ by 2$2$ diagonal blocks. The generalized eigenvalues, λ $\lambda$, of (A,B) $\left(A,B\right)$ are computed from the diagonals of S$S$ and T$T$ 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_dgges (f08xa) 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_dgges (f08xa) computes T$T$ to have non-negative diagonal elements, and the 2$2$ by 2$2$ blocks of S$S$ correspond to complex conjugate pairs of generalized eigenvalues. 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_dgges (f08xa), and may be called with the string 'f08xaz'.
[result] = selctg(ar, ai, b)

Input Parameters

1:     ar – double scalar
2:     ai – double scalar
3:     b – double scalar
An eigenvalue (ar(j) + sqrt(1) × ai(j)) / b(j) $\left({\mathbf{ar}}\left(j\right)+\sqrt{-1}×{\mathbf{ai}}\left(j\right)\right)/{\mathbf{b}}\left(j\right)$ is selected if selctg (ar(j),ai(j),b(j)) = true ${\mathbf{selctg}}\left({\mathbf{ar}}\left(j\right),{\mathbf{ai}}\left(j\right),{\mathbf{b}}\left(j\right)\right)=\mathbf{true}$. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.
Note that in the ill-conditioned case, a selected complex generalized eigenvalue may no longer satisfy selctg (ar(j),ai(j),b(j)) = true ${\mathbf{selctg}}\left({\mathbf{ar}}\left(j\right),{\mathbf{ai}}\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, : $:$) – 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 first of the pair of matrices, A$A$.
6:     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 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 bwork

### 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)$.
a stores its generalized Schur form S$S$.
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)$.
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. (Complex conjugate pairs for which selctg is true for either eigenvalue count as 2$2$.)
4:     alphar(n) – double array
See the description of beta.
5:     alphai(n) – double array
See the description of beta.
6:     beta(n) – double array
(alphar(j) + alphai(j) × i) / beta(j)$\left({\mathbf{alphar}}\left(\mathit{j}\right)+{\mathbf{alphai}}\left(\mathit{j}\right)×i\right)/{\mathbf{beta}}\left(\mathit{j}\right)$, for j = 1,2,,n$\mathit{j}=1,2,\dots ,{\mathbf{n}}$, will be the generalized eigenvalues. alphar(j) + alphai(j) × i${\mathbf{alphar}}\left(\mathit{j}\right)+{\mathbf{alphai}}\left(\mathit{j}\right)×i$, 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 (S,T)$\left(S,T\right)$ that would result if the 2$2$ by 2$2$ diagonal blocks of the real Schur form of (A,B)$\left(A,B\right)$ were further reduced to triangular form using 2$2$ by 2$2$ complex unitary transformations.
If alphai(j)${\mathbf{alphai}}\left(j\right)$ is zero, then the j$j$th eigenvalue is real; if positive, then the j$j$th and (j + 1)$\left(j+1\right)$st eigenvalues are a complex conjugate pair, with alphai(j + 1)${\mathbf{alphai}}\left(j+1\right)$ negative.
Note:  the quotients alphar(j) / beta(j)${\mathbf{alphar}}\left(j\right)/{\mathbf{beta}}\left(j\right)$ and alphai(j) / beta(j)${\mathbf{alphai}}\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, alphar and alphai will always be less than and usually comparable with a2${‖{\mathbf{a}}‖}_{2}$ in magnitude, and beta will always be less than and usually comparable with b2${‖{\mathbf{b}}‖}_{2}$.
7:     vsl(ldvsl, : $:$) – double 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.
8:     vsr(ldvsr, : $:$) – double 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.
9:     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: alphar, 12: alphai, 13: beta, 14: vsl, 15: ldvsl, 16: vsr, 17: ldvsr, 18: work, 19: lwork, 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 alphar(j)${\mathbf{alphar}}\left(j\right)$, alphai(j)${\mathbf{alphai}}\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_dhgeqz (f08xe).
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 complex analogue of this function is nag_lapack_zgges (f08xn).

## Example

```function nag_lapack_dgges_example
jobvsl = 'Vectors (left)';
jobvsr = 'Vectors (right)';
sortp = 'Sort';
selctg = @(ar, ai, b) (ai == 0) ;
a = [3.9, 12.5, -34.5, -0.5;
4.3, 21.5, -47.5, 7.5;
4.3, 21.5, -43.5, 3.5;
4.4, 26, -46, 6];
b = [1, 2, -3, 1;
1, 3, -5, 4;
1, 3, -4, 3;
1, 3, -4, 4];
[aOut, bOut, sdim, alphar, alphai, beta, vsl, vsr, info] = ...
nag_lapack_dgges(jobvsl, jobvsr, sortp, selctg, a, b)
```
```

aOut =

3.8009  -69.4505  -50.3135   43.2884
0    9.2033    0.2001   -5.9881
0         0    1.4279    4.4453
0         0   -0.9019    1.1962

bOut =

1.9005  -10.2285   -0.8658    5.2134
0    2.3008   -0.7915   -0.4262
0         0    0.8101         0
0         0         0    0.2823

sdim =

2

alphar =

3.8009
9.2033
0.8571
0.8571

alphai =

0
0
1.1429
-1.1429

beta =

1.9005
2.3008
0.2857
0.2857

vsl =

0.4642    0.7886   -0.2915   -0.2786
0.5002   -0.5986   -0.5638   -0.2713
0.5002    0.0154    0.0107    0.8657
0.5331   -0.1395    0.7727   -0.3151

vsr =

0.9961   -0.0014   -0.0887    0.0026
0.0057   -0.0404    0.0938    0.9948
0.0626    0.7194    0.6908   -0.0363
0.0626   -0.6934    0.7114   -0.0956

info =

0

```
```function f08xa_example
jobvsl = 'Vectors (left)';
jobvsr = 'Vectors (right)';
sortp = 'Sort';
selctg = @(ar, ai, b) (ai == 0) ;
a = [3.9, 12.5, -34.5, -0.5;
4.3, 21.5, -47.5, 7.5;
4.3, 21.5, -43.5, 3.5;
4.4, 26, -46, 6];
b = [1, 2, -3, 1;
1, 3, -5, 4;
1, 3, -4, 3;
1, 3, -4, 4];
[aOut, bOut, sdim, alphar, alphai, beta, vsl, vsr, info] = ...
f08xa(jobvsl, jobvsr, sortp, selctg, a, b)
```
```

aOut =

3.8009  -69.4505  -50.3135   43.2884
0    9.2033    0.2001   -5.9881
0         0    1.4279    4.4453
0         0   -0.9019    1.1962

bOut =

1.9005  -10.2285   -0.8658    5.2134
0    2.3008   -0.7915   -0.4262
0         0    0.8101         0
0         0         0    0.2823

sdim =

2

alphar =

3.8009
9.2033
0.8571
0.8571

alphai =

0
0
1.1429
-1.1429

beta =

1.9005
2.3008
0.2857
0.2857

vsl =

0.4642    0.7886   -0.2915   -0.2786
0.5002   -0.5986   -0.5638   -0.2713
0.5002    0.0154    0.0107    0.8657
0.5331   -0.1395    0.7727   -0.3151

vsr =

0.9961   -0.0014   -0.0887    0.0026
0.0057   -0.0404    0.0938    0.9948
0.0626    0.7194    0.6908   -0.0363
0.0626   -0.6934    0.7114   -0.0956

info =

0

```