Purpose
=======
LA_GGEV computes for a pair of n by n real or complex matrices (A,B)
the generalized eigenvalues in the form of scalar pairs (alpha, beta)
and, optionally, the left and/or right generalized eigenvectors.
A generalized eigenvalue of the pair (A,B) is, roughly
speaking, a scalar of the form lambda=alpha/beta such that the matrix
A-lambda*B is singular. It is usually represented as the pair
(alpha; beta), as there is a reasonable interpretation of the case
beta = 0 (even if alpha = 0).
A right generalized eigenvector corresponding to a generalized
eigenvalue lambda is a vector v such that (A-lambda*B)*v=0. A left
generalized eigenvector is a vector u such that u^H*(A-lambda*B)=0,
where u^H is the conjugate-transpose of u.
The computation is based on the (generalized) real or complex
Schur form of (A,B). (See LA_GGES for details of this form.)
=========
SUBROUTINE LA_GGEV( A, B, , BETA, VL=vl, &
VR=vr, INFO=info )
(), INTENT(INOUT) :: A(:,:), B(:,:)
(), INTENT(OUT) :: , BETA(:)
(), INTENT(OUT), OPTIONAL :: VL(:,:), VR(:,:)
INTEGER, INTENT(OUT), OPTIONAL :: INFO
where
::= REAL | COMPLEX
::= KIND(1.0) | KIND(1.0D0)
::= ALPHAR, ALPHAI | ALPHA
::= ALPHAR(:), ALPHAI(:) | ALPHA(:)
Arguments
=========
A (input/output) REAL or COMPLEX square array, shape (:,:).
On entry, the matrix A.
On exit, A has been destroyed.
B (input/output) REAL or COMPLEX square array, shape (:,:) with
size(B,1) = size(A,1).
On entry, the matrix B.
On exit, B has been destroyed.
(output) REAL or COMPLEX array, shape (:) with size(alpha) =
size(A,1).
The values of alpha.
alpha(:) ::= ALPHAR(:), ALPHAI(:) | ALPHA(:),
where
ALPHAR(:), ALPHAI(:) are of REAL type (for the real and
imaginary parts) and ALPHA(:) is of COMPLEX type.
BETA (output) REAL or COMPLEX array, shape (:) with size(BETA) =
size(A,1).
The values of beta.
Note: The generalized eigenvalues of the pair (A,B) are the
scalars lambda(j)=alpha(j)/beta(j). These quotients may easily
over- or underflow, and beta(j) may even be zero. Thus, the
user should avoid computing them naively.
Note: If A and B are real then complex eigenvalues occur in
complex conjugate pairs. Each pair is stored consecutively.
Thus a complex conjugate pair is given by
lambda(j) = (ALPHAR(j) + i*ALPHAI(j))/BETA(j)
lambda(j+1) = (ALPHAR(j+1) + i*ALPHAI(j+1))/BETA(j+1)
where
ALPHAI(j)/BETA(j) = -(ALPHAI(j+1)/BETA(j+1))
VL Optional (output) REAL or COMPLEX square array, shape (:,:)
with size(VL,1) = size(A,1).
The left generalized eigenvectors u(j) are stored in the
columns of VL in the order of their eigenvalues. Each
eigenvector is scaled so the largest component has
|realpart| + |imag.part| = 1,
except that for eigenvalues with alpha = beta = 0, a zero
vector is returned as the corresponding eigenvector.
Note: If A and B are real then complex eigenvectors, like
their eigenvalues, occur in complex conjugate pairs. The real
and imaginary parts of the first eigenvector of the pair are
stored in VL(:,j) and VL(:,j+1) . Thus a complex conjugate
pair is given by
u(j) = VL(:,j) + i*VL(:,j+1), u(j+1) = VL(:,j) - i*VL(:,j+1)
VR Optional (output) REAL or COMPLEX square array, shape (:,:)
with size(VR,1) = size(A,1).
The right generalized eigenvectors v(j) are stored in the
columns of VR in the order of their eigenvalues. Each
eigenvector is scaled so the largest component has
|realpart| + |imag:part| = 1,
except that for eigenvalues with alpha = beta = 0, a zero
vector is returned as the corresponding eigenvector.
Note: If A and B are real then complex eigenvectors, like
their eigenvalues, occur in complex conjugate pairs. The real
and imaginary parts of the first eigenvector of the pair are
stored in VR(:,j) and VR(:,j+1) . Thus a complex conjugate
pair is given by
v(j) = VR(:,j) + i*VR(:,j+1), v(j+1) = VR(:,j) - i*VR(:,j+1)
INFO Optional (output) INTEGER.
= 0: successful exit.
< 0: if INFO = -i, the i-th argument had an illegal value.
> 0: if INFO = i, and i is
<= n: The QZ iteration failed. No eigenvectors have been
calculated, but (alpha(j), BETA(j)) should be
correct for j = INFO+1, ..., n.
= n+1: another part of the algorithm failed.
= n+2: a failure occurred during the computation of the
generalized eigenvectors.
If INFO is not present and an error occurs, then the program
is terminated with an error message.