f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_dggesx (f08xbc)

## 1  Purpose

nag_dggesx (f08xbc) computes the generalized eigenvalues, the generalized real Schur form $\left(S,T\right)$ and, optionally, the left and/or right generalized Schur vectors for a pair of $n$ by $n$ real nonsymmetric matrices $\left(A,B\right)$.
Estimates of condition numbers for selected generalized eigenvalue clusters and Schur vectors are also computed.

## 2  Specification

 #include #include
void  nag_dggesx (Nag_OrderType order, Nag_LeftVecsType jobvsl, Nag_RightVecsType jobvsr, Nag_SortEigValsType sort,
 Nag_Boolean (*selctg)(double ar, double ai, double b),
Nag_RCondType sense, Integer n, double a[], Integer pda, double b[], Integer pdb, Integer *sdim, double alphar[], double alphai[], double beta[], double vsl[], Integer pdvsl, double vsr[], Integer pdvsr, double rconde[], double rcondv[], NagError *fail)

## 3  Description

The generalized real Schur factorization of $\left(A,B\right)$ is given by
 $A = QSZT , B = QTZT ,$
where $Q$ and $Z$ are orthogonal, $T$ is upper triangular and $S$ is upper quasi-triangular with $1$ by $1$ and $2$ by $2$ diagonal blocks. 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_dggesx (f08xbc) 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_dggesx (f08xbc) computes $T$ to have non-negative diagonal elements, and the $2$ by $2$ blocks of $S$ correspond to complex conjugate pairs of generalized eigenvalues. 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[0\right]$ and ${\mathbf{rconde}}\left[1\right]$ respectively, for the selected generalized eigenvalues, together with reciprocal condition estimates for the corresponding left and right deflating subspaces, in ${\mathbf{rcondv}}\left[0\right]$ and ${\mathbf{rcondv}}\left[1\right]$. See Section 4.11 of Anderson et al. (1999) for further information.

## 4  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

## 5  Arguments

1:     orderNag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or Nag_ColMajor.
2:     jobvslNag_LeftVecsTypeInput
On entry: if ${\mathbf{jobvsl}}=\mathrm{Nag_NotLeftVecs}$, do not compute the left Schur vectors.
If ${\mathbf{jobvsl}}=\mathrm{Nag_LeftVecs}$, compute the left Schur vectors.
Constraint: ${\mathbf{jobvsl}}=\mathrm{Nag_NotLeftVecs}$ or $\mathrm{Nag_LeftVecs}$.
3:     jobvsrNag_RightVecsTypeInput
On entry: if ${\mathbf{jobvsr}}=\mathrm{Nag_NotRightVecs}$, do not compute the right Schur vectors.
If ${\mathbf{jobvsr}}=\mathrm{Nag_RightVecs}$, compute the right Schur vectors.
Constraint: ${\mathbf{jobvsr}}=\mathrm{Nag_NotRightVecs}$ or $\mathrm{Nag_RightVecs}$.
4:     sortNag_SortEigValsTypeInput
On entry: specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.
${\mathbf{sort}}=\mathrm{Nag_NoSortEigVals}$
Eigenvalues are not ordered.
${\mathbf{sort}}=\mathrm{Nag_SortEigVals}$
Eigenvalues are ordered (see selctg).
Constraint: ${\mathbf{sort}}=\mathrm{Nag_NoSortEigVals}$ or $\mathrm{Nag_SortEigVals}$.
5:     selctgfunction, supplied by the userExternal Function
If ${\mathbf{sort}}=\mathrm{Nag_SortEigVals}$, selctg is used to select generalized eigenvalues to the top left of the generalized Schur form.
If ${\mathbf{sort}}=\mathrm{Nag_NoSortEigVals}$, selctg is not referenced by nag_dggesx (f08xbc), and may be specified as NULLFN.
The specification of selctg is:
 Nag_Boolean selctg (double ar, double ai, double b)
1:     ardoubleInput
2:     aidoubleInput
3:     bdoubleInput
On entry: an eigenvalue $\left({\mathbf{ar}}\left[j-1\right]+\sqrt{-1}×{\mathbf{ai}}\left[j-1\right]\right)/{\mathbf{b}}\left[j-1\right]$ is selected if ${\mathbf{selctg}}\left({\mathbf{ar}}\left[j-1\right],{\mathbf{ai}}\left[j-1\right],{\mathbf{b}}\left[j-1\right]\right)$ is Nag_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 ${\mathbf{selctg}}\left({\mathbf{ar}}\left[j-1\right],{\mathbf{ai}}\left[j-1\right],{\mathbf{b}}\left[j-1\right]\right)=\mathrm{Nag_TRUE}$ after ordering. NE_SCHUR_REORDER_SELECT in this case.
6:     senseNag_RCondTypeInput
On entry: determines which reciprocal condition numbers are computed.
${\mathbf{sense}}=\mathrm{Nag_NotRCond}$
None are computed.
${\mathbf{sense}}=\mathrm{Nag_RCondEigVals}$
Computed for average of selected eigenvalues only.
${\mathbf{sense}}=\mathrm{Nag_RCondEigVecs}$
Computed for selected deflating subspaces only.
${\mathbf{sense}}=\mathrm{Nag_RCondBoth}$
Computed for both.
If ${\mathbf{sense}}=\mathrm{Nag_RCondEigVals}$, $\mathrm{Nag_RCondEigVecs}$ or $\mathrm{Nag_RCondBoth}$, ${\mathbf{sort}}=\mathrm{Nag_SortEigVals}$.
Constraint: ${\mathbf{sense}}=\mathrm{Nag_NotRCond}$, $\mathrm{Nag_RCondEigVals}$, $\mathrm{Nag_RCondEigVecs}$ or $\mathrm{Nag_RCondBoth}$.
7:     nIntegerInput
On entry: $n$, the order of the matrices $A$ and $B$.
Constraint: ${\mathbf{n}}\ge 0$.
8:     a[$\mathit{dim}$]doubleInput/Output
Note: the dimension, dim, of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pda}}×{\mathbf{n}}\right)$.
The $\left(i,j\right)$th element of the matrix $A$ is stored in
• ${\mathbf{a}}\left[\left(j-1\right)×{\mathbf{pda}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{a}}\left[\left(i-1\right)×{\mathbf{pda}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the first of the pair of matrices, $A$.
On exit: a has been overwritten by its generalized Schur form $S$.
9:     pdaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraint: ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
10:   b[$\mathit{dim}$]doubleInput/Output
Note: the dimension, dim, of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdb}}×{\mathbf{n}}\right)$.
The $\left(i,j\right)$th element of the matrix $B$ is stored in
• ${\mathbf{b}}\left[\left(j-1\right)×{\mathbf{pdb}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{b}}\left[\left(i-1\right)×{\mathbf{pdb}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the second of the pair of matrices, $B$.
On exit: b has been overwritten by its generalized Schur form $T$.
11:   pdbIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array b.
Constraint: ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
12:   sdimInteger *Output
On exit: if ${\mathbf{sort}}=\mathrm{Nag_NoSortEigVals}$, ${\mathbf{sdim}}=0$.
If ${\mathbf{sort}}=\mathrm{Nag_SortEigVals}$, ${\mathbf{sdim}}=\text{}$ number of eigenvalues (after sorting) for which selctg is Nag_TRUE. (Complex conjugate pairs for which selctg is Nag_TRUE for either eigenvalue count as $2$.)
13:   alphar[n]doubleOutput
On exit: see the description of beta.
14:   alphai[n]doubleOutput
On exit: see the description of beta.
15:   beta[n]doubleOutput
On exit: $\left({\mathbf{alphar}}\left[\mathit{j}-1\right]+{\mathbf{alphai}}\left[\mathit{j}-1\right]×i\right)/{\mathbf{beta}}\left[\mathit{j}-1\right]$, for $\mathit{j}=1,2,\dots ,{\mathbf{n}}$, will be the generalized eigenvalues. ${\mathbf{alphar}}\left[\mathit{j}-1\right]+{\mathbf{alphai}}\left[\mathit{j}-1\right]×i$, and ${\mathbf{beta}}\left[\mathit{j}-1\right]$, for $\mathit{j}=1,2,\dots ,{\mathbf{n}}$, are the diagonals of the complex Schur form $\left(S,T\right)$ that would result if the $2$ by $2$ diagonal blocks of the real Schur form of $\left(A,B\right)$ were further reduced to triangular form using $2$ by $2$ complex unitary transformations.
If ${\mathbf{alphai}}\left[j-1\right]$ is zero, then the $j$th eigenvalue is real; if positive, then the $j$th and $\left(j+1\right)$st eigenvalues are a complex conjugate pair, with ${\mathbf{alphai}}\left[j\right]$ negative.
Note:  the quotients ${\mathbf{alphar}}\left[j-1\right]/{\mathbf{beta}}\left[j-1\right]$ and ${\mathbf{alphai}}\left[j-1\right]/{\mathbf{beta}}\left[j-1\right]$ may easily overflow or underflow, and ${\mathbf{beta}}\left[j-1\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 ${‖{\mathbf{a}}‖}_{2}$ in magnitude, and beta will always be less than and usually comparable with ${‖{\mathbf{b}}‖}_{2}$.
16:   vsl[$\mathit{dim}$]doubleOutput
Note: the dimension, dim, of the array vsl must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdvsl}}×{\mathbf{n}}\right)$ when ${\mathbf{jobvsl}}=\mathrm{Nag_LeftVecs}$;
• $1$ otherwise.
The $i$th element of the $j$th vector is stored in
• ${\mathbf{vsl}}\left[\left(j-1\right)×{\mathbf{pdvsl}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{vsl}}\left[\left(i-1\right)×{\mathbf{pdvsl}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On exit: if ${\mathbf{jobvsl}}=\mathrm{Nag_LeftVecs}$, vsl will contain the left Schur vectors, $Q$.
If ${\mathbf{jobvsl}}=\mathrm{Nag_NotLeftVecs}$, vsl is not referenced.
17:   pdvslIntegerInput
On entry: the stride used in the array vsl.
Constraints:
• if ${\mathbf{jobvsl}}=\mathrm{Nag_LeftVecs}$, ${\mathbf{pdvsl}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise ${\mathbf{pdvsl}}\ge 1$.
18:   vsr[$\mathit{dim}$]doubleOutput
Note: the dimension, dim, of the array vsr must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdvsr}}×{\mathbf{n}}\right)$ when ${\mathbf{jobvsr}}=\mathrm{Nag_RightVecs}$;
• $1$ otherwise.
The $i$th element of the $j$th vector is stored in
• ${\mathbf{vsr}}\left[\left(j-1\right)×{\mathbf{pdvsr}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{vsr}}\left[\left(i-1\right)×{\mathbf{pdvsr}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On exit: if ${\mathbf{jobvsr}}=\mathrm{Nag_RightVecs}$, vsr will contain the right Schur vectors, $Z$.
If ${\mathbf{jobvsr}}=\mathrm{Nag_NotRightVecs}$, vsr is not referenced.
19:   pdvsrIntegerInput
On entry: the stride used in the array vsr.
Constraints:
• if ${\mathbf{jobvsr}}=\mathrm{Nag_RightVecs}$, ${\mathbf{pdvsr}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise ${\mathbf{pdvsr}}\ge 1$.
20:   rconde[$2$]doubleOutput
On exit: if ${\mathbf{sense}}=\mathrm{Nag_RCondEigVals}$ or $\mathrm{Nag_RCondBoth}$, ${\mathbf{rconde}}\left[0\right]$ and ${\mathbf{rconde}}\left[1\right]$ contain the reciprocal condition numbers for the average of the selected eigenvalues.
If ${\mathbf{sense}}=\mathrm{Nag_NotRCond}$ or $\mathrm{Nag_RCondEigVecs}$, rconde is not referenced.
21:   rcondv[$2$]doubleOutput
On exit: if ${\mathbf{sense}}=\mathrm{Nag_RCondEigVecs}$ or $\mathrm{Nag_RCondBoth}$, ${\mathbf{rcondv}}\left[0\right]$ and ${\mathbf{rcondv}}\left[1\right]$ contain the reciprocal condition numbers for the selected deflating subspaces.
if ${\mathbf{sense}}=\mathrm{Nag_NotRCond}$ or $\mathrm{Nag_RCondEigVals}$, rcondv is not referenced.
22:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_ENUM_INT_2
On entry, ${\mathbf{jobvsl}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdvsl}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{jobvsl}}=\mathrm{Nag_LeftVecs}$, ${\mathbf{pdvsl}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
otherwise ${\mathbf{pdvsl}}\ge 1$.
On entry, ${\mathbf{jobvsr}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdvsr}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{jobvsr}}=\mathrm{Nag_RightVecs}$, ${\mathbf{pdvsr}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
otherwise ${\mathbf{pdvsr}}\ge 1$.
NE_INT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 0$.
On entry, ${\mathbf{pda}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pda}}>0$.
On entry, ${\mathbf{pdb}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdb}}>0$.
On entry, ${\mathbf{pdvsl}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdvsl}}>0$.
On entry, ${\mathbf{pdvsr}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdvsr}}>0$.
NE_INT_2
On entry, ${\mathbf{pda}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
On entry, ${\mathbf{pdb}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_ITERATION_QZ
The $QZ$ iteration failed. No eigenvectors have been calculated but ${\mathbf{alphar}}\left[j\right]$, ${\mathbf{alphai}}\left[j\right]$, and ${\mathbf{beta}}\left[j\right]$ should be correct from element $〈\mathit{\text{value}}〉$.
The $QZ$ iteration failed with an unexpected error, please contact NAG.
NE_SCHUR_REORDER
The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).
NE_SCHUR_REORDER_SELECT
After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the generalized Schur form no longer satisfy ${\mathbf{selctg}}=\mathrm{Nag_TRUE}$. This could also be caused by underflow due to scaling.

## 7  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 complex analogue of this function is nag_zggesx (f08xpc).

## 9  Example

This example finds the generalized Schur factorization of the matrix pair $\left(A,B\right)$, where
 $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.0 -46.0 6.0 and B= 1.0 2.0 -3.0 1.0 1.0 3.0 -5.0 4.0 1.0 3.0 -4.0 3.0 1.0 3.0 -4.0 4.0 ,$
such that the real eigenvalues of $\left(A,B\right)$ 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.

### 9.1  Program Text

Program Text (f08xbce.c)

### 9.2  Program Data

Program Data (f08xbce.d)

### 9.3  Program Results

Program Results (f08xbce.r)