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


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index