## Stata 15 help for mf_geigensystem

```
[M-5] geigensystem() -- Generalized eigenvectors and eigenvalues

Syntax

void                geigensystem(A, B, X, w, b)

void            leftgeigensystem(A, B, X, w, b)

void         geigensystemselectr(A, B, range, X, w, b)

void     leftgeigensystemselectr(A, B, range, X, w, b)

void         geigensystemselecti(A, B, index, X, w, b)

void     leftgeigensystemselecti(A, B, index, X, w, b)

void         geigensystemselectf(A, B, f, X, w, b)

void     leftgeigensystemselectf(A, B, f, X, w, b)

where inputs are

A:  numeric matrix
B:  numeric matrix
range:  real vector     (range of generalized eigenvalues to be
selected)
index:  real vector     (indices of generalized eigenvalues to be
selected)
f:  pointer scalar  (points to a function used to select
generalized eigenvalues)

and outputs are

X:  numeric matrix of generalized eigenvectors
w:  numeric vector (numerators of generalized eigenvalues)
b:  numeric vector (denominators of generalized eigenvalues)

The following routines are used in implementing the above routines:

void _geigensystem_la(numeric matrix H, R, XL, XR, w, b, string
scalar side)

void _geigenselectr_la(numeric matrix H, R, XL, XR, w, b, range,
string scalar side)

void _geigenselecti_la(numeric matrix H, R, XL, XR, w, b, index,
string scalar side)

void _geigenselectf_la(numeric matrix H, R, XL, XR, w, b, pointer
scalar f, string scalar side)

real scalar _geigen_la(numeric matrix H, R, XL, XR, w, select, string
scalar side, string scalar howmany)

Description

geigensystem(A, B, X, w, b) computes generalized eigenvectors of two
general, real or complex, square matrices, A and B, along with their
corresponding generalized eigenvalues.

o A and B are two general, real or complex, square matrices with the
same dimensions.

o X contains generalized eigenvectors.

o w contains numerators of generalized eigenvalues.

o b contains denominators of generalized eigenvalues.

leftgeigensystem(A, B, X, w, b) mirrors geigensystem(), the difference
being that leftgeigensystem() computes left, generalized eigenvectors.

geigensystemselectr(A, B, range, X, w, b) computes selected generalized
eigenvectors of two general, real or complex, square matrices, A and B,
along with their corresponding generalized eigenvalues.  Only the
generalized eigenvectors corresponding to selected generalized
eigenvalues are computed.  Generalized eigenvalues that lie in a range
are selected.  The selected generalized eigenvectors are returned in X,
and their corresponding generalized eigenvalues are returned in (w, b).

range is a vector of length 2.  All finite, generalized eigenvalues
with absolute value in the half-open interval (range[1], range[2]]
are selected.

leftgeigensystemselectr(A, B, range, X, w, b) mirrors
geigensystemselectr(), the difference being that leftgeigensystemr()
computes left, generalized eigenvectors.

geigensystemselecti(A, B, index, X, w, b) computes selected right,
generalized eigenvectors of two general, real or complex, square
matrices, A and B, along with their corresponding generalized
eigenvalues.  Only the generalized eigenvectors corresponding to selected
generalized eigenvalues are computed. Generalized eigenvalues are
selected by an index.  The selected generalized eigenvectors are returned
in X, and the selected generalized eigenvalues are returned in (w, b).

The finite, generalized eigenvalues are sorted by their absolute
values, in descending order, followed by the infinite, generalized
eigenvalues.  There is no particular order among infinite,
generalized eigenvalues.

index is a vector of length 2.  The generalized eigenvalues in
elements index[1] through index[2], inclusive, are selected.

leftgeigensystemselecti(A, B, index, X, w, b) mirrors
geigensystemselecti(), the difference being that leftgeigensystemi()
computes left, generalized eigenvectors.

geigensystemselectf(A, B, f, X, w, b) computes selected generalized
eigenvectors of two general, real or complex, square matrices A and B
along with their corresponding generalized eigenvalues.  Only the
generalized eigenvectors corresponding to selected generalized
eigenvalues are computed.  Generalized eigenvalues are selected by a
user-written function described below.  The selected generalized
eigenvectors are returned in X, and the selected generalized eigenvalues
are returned in (w, b).

leftgeigensystemselectf(A, B, f, X, w, b) mirrors geigensystemselectf(),
the difference being that leftgeigensystemselectf() computes selected
left, generalized eigenvectors.

_geigen_la(), _geigensystem_la(), _geigenselectr_la(),
_geigenselecti_la(), and _geigenselectf_la() are the interfaces into the
LAPACK routines used to implement the above functions; see [M-1] LAPACK.
Their direct use is not recommended.

Remarks

Remarks are presented under the following headings:

Generalized eigenvalues
Generalized eigenvectors
Criterion selection
Range selection
Index selection

Generalized eigenvalues

A scalar, l (usually denoted by lambda), is said to be a generalized
eigenvalue of a pair of n x n square, numeric matrices (A, B) if there is
a nonzero column vector x: n x 1 (called the generalized eigenvector)
such that

Ax = lBx                                                    (1)

(1) can also be written as

(A - lB)x = 0

A nontrivial solution to this system of n linear homogeneous equations
exists if and only if

det(A - lB) = 0                                             (2)

In practice, the generalized eigenvalue problem for the matrix pair (A,
B) is usually formulated as finding a pair of scalars (w, b) and a
nonzero column vector x such that

wAx = bBx

The scalar w/b is a finite, generalized eigenvalue if b is not zero. The
pair (w, b) represents an infinite, generalized eigenvalue if b is zero
or numerically close to zero.  This situation may arise if B is singular.

The Mata functions that compute generalized eigenvalues return them in
two complex vectors, w and b, of length n.  If b[i]=0, the ith
generalized eigenvalue is infinite; otherwise, the ith generalized
eigenvalue is w[i]/b[i].

Generalized eigenvectors

A column vector, x, is a right, generalized eigenvector or simply a
generalized eigenvector of a generalized eigenvalue (w, b) for a pair of
matrices, A and B, if

wAx=bBx

A row vector, v, is a left, generalized eigenvector of a generalized
eigenvalue (w, b) for a pair of matrices, A and B, if

wvA=bvB

For instance, let's consider the linear system

dx/dt = A1*x + A2*u
dy/dt = A3*x + A4*u

where

: A1 = (-4, -3 \ 2, 1)
: A2 = (3 \ 1)
: A3 = (1, 2)

and

: A4 = 0

The finite solutions of zeros for the transfer function

g(s) = A3*(sI-A1)^(-1)*A2+A4                                        (3)

of this linear time-invariant state-space model is given by the finite,
generalized eigenvalues of A and B where

: A = (A1, A2 \ A3, A4)

and

: B = (1, 0, 0 \ 0, 1, 0 \ 0, 0, 0)

We obtain generalized eigenvectors in X and generalized eigenvalues in w
and b by using

: geigensystem(A, B, X=., w=., b=.)

: X
1    2            3
+------------------------+
1 |  -1   0   2.9790e-16   |
2 |  .5   0   9.9301e-17   |
3 |  .1   1            1   |
+------------------------+

: w
1             2             3
+------------------------------------------+
1 |  -1.97989899   3.16227766    2.23606798  |
+------------------------------------------+

: b
1             2             3
+------------------------------------------+
1 | .7071067812             0             0  |
+------------------------------------------+

The only finite, generalized eigenvalue of A and B is

: w[1,1]/b[1,1]
-2.8

In this simple example, (3) can be explicitly written out as

g(s) = (5s+14)/(s^2+3s+2)

which clearly has the solution of zero at -2.8.

Criterion selection

We sometimes want to compute only those generalized eigenvectors whose
corresponding generalized eigenvalues satisfy certain criterion.  We can
use geigensystemselectf() to solve these problems.

We must pass geigensystemselectf() a pointer to a function that
implements our conditions.  The function must accept two numeric scalar
arguments so that it can receive the numerator w and the denominator b of
a generalized eigenvalue, and it must return the real value 0 to indicate
rejection and a nonzero real value to indicate selection.

In this example, we want to compute only finite, generalized eigenvalues
for each of which b is not zero.  After deciding that anything smaller
than 1e-15 is zero, we define our function to be

: real scalar finiteonly(numeric scalar w, numeric scalar b)
> {
>         return((abs(b)>=1e-15))
> }

By using

: geigensystemselectf(A, B, &finiteonly(), X=., w=., b=.)

we get the only finite, generalized eigenvalue of A and B in (w, b) and
its corresponding eigenvector in X:

: X
1
+---------------+
1 |  -.894427191  |
2 |   .447213595  |
3 |   .089442719  |
+---------------+

: w
-1.97989899

: b
.7071067812

: w:/b
-2.8

Range selection

We can use geigensystemselectr() to compute only those generalized
eigenvectors whose generalized eigenvalues have absolute values that fall
in a half-open interval.

For instance,

: A = (-132, -88, 84, 104 \ -158.4, -79.2, 76.8, 129.6 \ 129.6, 81.6,
-79.2, -100.8 \ 160, 84, -80, -132)

: B = (-60, -50, 40, 50\-69, -46.4, 38, 58.2 \ 58.8, 46, -37.6, -48
\70, 50, -40, -60)

: range = (0.99, 2.1)

We obtain generalized eigenvectors in X and generalized eigenvalues in w
and b by using

: geigensystemselectr(A, B, range, X=., w=., b=.)

: X
1            2
+---------------------------+
1 |  .089442719    .02236068  |
2 |   .04472136   .067082039  |
3 |   .04472136   .067082039  |
4 |  .089442719    .02236068  |
+---------------------------+

: w
1            2
+---------------------------+
1 |  .02820603   .170176379   |
+---------------------------+

: b
1             2
+-----------------------------+
1 |  .0141030148   .1701763791  |
+-----------------------------+

The generalized eigenvalues have absolute values in the half-open
interval (0.99, 2.1].

: abs(w:/b)
1   2
+---------+
1 |   2   1 |
+---------+

Index selection

geigensystemselect() sorts the finite, generalized eigenvalues using
their absolute values, in descending order, placing the infinite,
generalized eigenvalues after the finite, generalized eigenvalues.  There
is no particular order among infinite, generalized eigenvalues.

If we want to compute only generalized eigenvalues whose ranks are
index[1] through index[2] in the list of generalized eigenvalues obtained
by geigensystemselect(), we can use geigensystemselecti().

To compute the first two generalized eigenvalues and generalized
eigenvectors in this example, we can specify

: index = (1, 2)

: geigensystemselecti(A, B, index, X=., w=., b=.)

The results are

: X
1              2
+------------------------------+
1 |    .02981424    -.059628479  |
2 |    .04472136    -.059628479  |
3 |   .089442719     -.02981424  |
4 |    .01490712    -.119256959  |
+------------------------------+

: w
1            2
+---------------------------+
1 |  .012649111   .379473319  |
+---------------------------+

: b
1             2
+-----------------------------+
1 |  .0031622777   .1264911064  |
+-----------------------------+

: w:/b
1   2
+---------+
1 |  4   3  |
+---------+

Conformability

geigensystem(A, B, X, w, b):
input:
A:  n x n
B:  n x n
output:
X:  n x n
w:  1 x n
b:  1 x n

leftgeigensystem(A, B, X, w, b):
input:
A:  n x n
B:  n x n
output:
X:  n x n
w:  1 x n
b:  1 x n

geigensystemselectr(A, B, range, X, w, b):
input:
A:  n x n
B:  n x n
range:  1 x 2 or 2 x 1
output:
X:  n x m
w:  1 x m
b:  1 x m

leftgeigensystemselectr(A, B, range, X, w, b):
input:
A:  n x n
B:  n x n
range:  1 x 2 or 2 x 1
output:
X:  m x n
w:  1 x m
b:  1 x m

geigensystemselecti(A, B, index, X, w, b):
input:
A:  n x n
B:  n x n
index:  1 x 2 or 2 x 1
output:
X:  n x m
w:  1 x m
b:  1 x m

leftgeigensystemselecti(A, B, index, X, w, b):
input:
A:  n x n
B:  n x n
index:  1 x 2 or 2 x 1
output:
X:  m x n
w:  1 x m
b:  1 x m

geigensystemselectf(A, B, f, X, w, b):
input:
A:  n x n
B:  n x n
f:  1 x 1
output:
X:  n x m
w:  1 x m
b:  1 x m

leftgeigensystemselectf(A, B, f, X, w, b):
input:
A:  n x n
B:  n x n
f:  1 x 1
output:
X:  m x n
w:  1 x m
b:  1 x m

Diagnostics

All functions return missing-value results if A or B has missing values.

Source code

geigensystem.mata, leftgeigensystem.mata, geigensystemselectr.mata,
leftgeigensystemselectr.mata, geigensystemselecti.mata,
leftgeigensystemselecti.mata, geigensystemselectf.mata,
leftgeigensystemselectf.mata

```