Purpose
=======
LA_GGEVX 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.)
Optionally, LA_GGEVX also computes a balancing transformation
(to improve the conditioning of the eigenvalues and eigenvectors),
reciprocal condition numbers for the eigenvalues, and reciprocal
condition numbers for the right eigenvectors. The balancing
transformation consists of a permutation of rows and columns and/or a
scaling of rows and columns.
==========
SUBROUTINE LA_GGEVX( A, B, , BETA, VL=vl, &
VR=vr, BALANC=balanc, ILO=ilo, IHI=ihi, &
LSCALE=lscale, RSCALE=rscale, ABNRM=abnrm, &
BBNRM=bbnrm, RCONDE=rconde, RCONDV=rcondv, &
INFO=info )
(), INTENT(INOUT) :: A(:,:), B(:,:)
(), INTENT(OUT) :: , BETA(:)
(), INTENT(OUT), OPTIONAL :: VL(:,:), VR(:,:)
CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: BALANC
INTEGER, INTENT(OUT), OPTIONAL :: ILO, IHI
REAL(), INTENT(OUT), OPTIONAL :: LSCALE(:),
RSCALE(:), RCONDE(:), RCONDV(:)
REAL(), INTENT(OUT), OPTIONAL :: ABNRM, BBNRM
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 overwritten. If the left, the right or
both generalized eigenvectors are computed, then A contains
the first part of the real/complex Schur form of the
"balanced" versions of the matrix pair (A, B).
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 overwritten. If the left, the right or
both generalized eigenvectors are computed, then B contains
the second part of the real/complex Schur form of the "bal-
anced" versions of the matrix pair (A, B).
(output) REAL or COMPLEX array, shape (:) with
size() = size(A, 1).
The values of 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)
BALANC Optional (input) CHARACTER(LEN=1).
Specifies the balance option to be performed.
= 'N': do not permute or scale;
= 'P': permute only;
= 'S': scale only;
= 'B': both permute and scale.
Default value: 'N".
Note: Computed reciprocal condition numbers will be for the
matrices after balancing. Permuting does not change condition
numbers (in exact arithmetic), but scaling does.
ILO,IHI Optional (output) INTEGER.
ILO and IHI are integer values such that on exit A(i,j) = 0
and B(i,j) = 0 if i > j and j =1,...,ILO-1 or
i = IHI+1,...,n.
If BALANC = 'N' or 'S', then ILO = 1 and IHI = n.
LSCALE Optional (output) REAL array, shape (:) with size(LSCALE) =
size(A, 1).
Details of the permutations and scaling factors applied to
the left side of A and B. If PL(j) is the index of the row
interchanged with row j, and DL(j) is the scaling factor
applied to row j, then
PL(j) = LSCALE(j), j = 1,...,ILO-1 and IHI+1,..., n
and
DL(j) = LSCALE(j), j = ILO, ..., IHI
RSCALE Optional (output) REAL array, shape (:), size(RSCALE) =
size(A, 1).
Details of the permutations and scaling factors applied to the
right side of A and B. If PR(j) is the index of the column
interchanged with column j, and DR(j) is the scaling factor
applied to column j, then
PR(j) = RSCALE(j), j = 1,...,ILO-1 and IHI+1,..., n
and
DR(j) = RSCALE(j), j = ILO, ..., IHI
ABNRM Optional (output) REAL.
The l1 norm of A after balancing.
BBNRM Optional (output) REAL.
The l 1 norm of B after balancing.
RCONDE Optional (output) REAL array, shape (:) with size(RCONDE) =
size(A, 1).
The reciprocal condition numbers of the eigenvalues.
RCONDV Optional (output) REAL array, shape (:) with size(RCONDE) =
size(A, 1).
The estimated reciprocal condition numbers of the right
eigenvectors. If the eigenvalues cannot be reordered to
compute RCONDV(j) then RCONDV(j) is set to 0. This can only
occur when the true value would be very small.
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.