Developer Reference

Contents

?ggevx

Computes the generalized eigenvalues, and, optionally, the left and/or right generalized eigenvectors.

Syntax

lapack_int LAPACKE_sggevx
(
int
matrix_layout
,
char
balanc
,
char
jobvl
,
char
jobvr
,
char
sense
,
lapack_int
n
,
float*
a
,
lapack_int
lda
,
float*
b
,
lapack_int
ldb
,
float*
alphar
,
float*
alphai
,
float*
beta
,
float*
vl
,
lapack_int
ldvl
,
float*
vr
,
lapack_int
ldvr
,
lapack_int*
ilo
,
lapack_int*
ihi
,
float*
lscale
,
float*
rscale
,
float*
abnrm
,
float*
bbnrm
,
float*
rconde
,
float*
rcondv
);
lapack_int LAPACKE_dggevx
(
int
matrix_layout
,
char
balanc
,
char
jobvl
,
char
jobvr
,
char
sense
,
lapack_int
n
,
double*
a
,
lapack_int
lda
,
double*
b
,
lapack_int
ldb
,
double*
alphar
,
double*
alphai
,
double*
beta
,
double*
vl
,
lapack_int
ldvl
,
double*
vr
,
lapack_int
ldvr
,
lapack_int*
ilo
,
lapack_int*
ihi
,
double*
lscale
,
double*
rscale
,
double*
abnrm
,
double*
bbnrm
,
double*
rconde
,
double*
rcondv
);
lapack_int LAPACKE_cggevx
(
int
matrix_layout
,
char
balanc
,
char
jobvl
,
char
jobvr
,
char
sense
,
lapack_int
n
,
lapack_complex_float*
a
,
lapack_int
lda
,
lapack_complex_float*
b
,
lapack_int
ldb
,
lapack_complex_float*
alpha
,
lapack_complex_float*
beta
,
lapack_complex_float*
vl
,
lapack_int
ldvl
,
lapack_complex_float*
vr
,
lapack_int
ldvr
,
lapack_int*
ilo
,
lapack_int*
ihi
,
float*
lscale
,
float*
rscale
,
float*
abnrm
,
float*
bbnrm
,
float*
rconde
,
float*
rcondv
);
lapack_int LAPACKE_zggevx
(
int
matrix_layout
,
char
balanc
,
char
jobvl
,
char
jobvr
,
char
sense
,
lapack_int
n
,
lapack_complex_double*
a
,
lapack_int
lda
,
lapack_complex_double*
b
,
lapack_int
ldb
,
lapack_complex_double*
alpha
,
lapack_complex_double*
beta
,
lapack_complex_double*
vl
,
lapack_int
ldvl
,
lapack_complex_double*
vr
,
lapack_int
ldvr
,
lapack_int*
ilo
,
lapack_int*
ihi
,
double*
lscale
,
double*
rscale
,
double*
abnrm
,
double*
bbnrm
,
double*
rconde
,
double*
rcondv
);
Include Files
  • mkl.h
Description
The routine computes for a pair of
n
-by-
n
real/complex nonsymmetric matrices (
A
,
B
), the generalized eigenvalues, and optionally, the left and/or right generalized eigenvectors.
Optionally also, it computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors (
ilo
,
ihi
,
lscale
,
rscale
,
abnrm
, and
bbnrm
), reciprocal condition numbers for the eigenvalues (
rconde
), and reciprocal condition numbers for the right eigenvectors (
rcondv
).
A generalized eigenvalue for a pair of matrices (
A
,
B
) is a scalar
λ
or a ratio
alpha
/
beta
=
λ
, such that
A
-
λ
*
B
is singular. It is usually represented as the pair (
alpha
,
beta
), as there is a reasonable interpretation for
beta
=0
and even for both being zero. The right generalized eigenvector
v
(j)
corresponding to the generalized eigenvalue
λ
(j)
of (
A
,
B
) satisfies
A
*
v
(j) =
λ
(j)*
B
*
v
(j)
.
The left generalized eigenvector
u
(j)
corresponding to the generalized eigenvalue
λ
(j)
of (
A
,
B
) satisfies
u
(j)
H
*
A
=
λ
(j)*
u
(j)
H
*
B
where
u
(j)
H
denotes the conjugate transpose of
u
(j)
.
Input Parameters
matrix_layout
Specifies whether matrix storage layout is row major (
LAPACK_ROW_MAJOR
) or column major (
LAPACK_COL_MAJOR
).
balanc
Must be
'N'
,
'P'
,
'S'
, or
'B'
. Specifies the balance option to be performed.
If
balanc
=
'N'
, do not diagonally scale or permute;
If
balanc
=
'P'
, permute only;
If
balanc
=
'S'
, scale only;
If
balanc
=
'B'
, both permute and scale.
Computed reciprocal condition numbers will be for the matrices after balancing and/or permuting. Permuting does not change condition numbers (in exact arithmetic), but balancing does.
jobvl
Must be
'N'
or
'V'
.
If
jobvl
=
'N'
, the left generalized eigenvectors are not computed;
If
jobvl
=
'V'
, the left generalized eigenvectors are computed.
jobvr
Must be
'N'
or
'V'
.
If
jobvr
=
'N'
, the right generalized eigenvectors are not computed;
If
jobvr
=
'V'
, the right generalized eigenvectors are computed.
sense
Must be
'N'
,
'E'
,
'V'
, or
'B'
. Determines which reciprocal condition number are computed.
If
sense
=
'N'
, none are computed;
If
sense
=
'E'
, computed for eigenvalues only;
If
sense
=
'V'
, computed for eigenvectors only;
If
sense
=
'B'
, computed for eigenvalues and eigenvectors.
n
The order of the matrices
A
,
B
,
vl
, and
vr
(
n
0
).
a
,
b
Arrays:
a
(size at least max(1,
lda
*
n
))
is an array containing the
n
-by-
n
matrix
A
(first of the pair of matrices).
b
(size at least max(1,
ldb
*
n
))
is an array containing the
n
-by-
n
matrix
B
(second of the pair of matrices).
lda
The leading dimension of the array
a
.
Must be at least max(1,
n
).
ldb
The leading dimension of the array
b
.
Must be at least max(1,
n
).
ldvl
,
ldvr
The leading dimensions of the output matrices
vl
and
vr
, respectively.
Constraints:
ldvl
1
. If
jobvl
=
'V'
,
ldvl
max(1,
n
)
.
ldvr
1
. If
jobvr
=
'V'
,
ldvr
max(1,
n
)
.
Output Parameters
a
,
b
On exit, these arrays have been overwritten.
If
jobvl
=
'V'
or
jobvr
=
'V'
or both, then
a
contains the first part of the real Schur form of the "balanced" versions of the input
A
and
B
, and
b
contains its second part.
alphar
,
alphai
Arrays, size at least max(1,
n
) each. Contain values that form generalized eigenvalues in real flavors.
See
beta
.
alpha
Array, size at least max(1,
n
). Contain values that form generalized eigenvalues in complex flavors. See
beta
.
beta
Array, size at least max(1,
n
).
For real flavors
:
On exit,
(
alphar
[
j
] +
alphai
[
j
]*i)/
beta
[
j
],
j
=0,...,
n
- 1
, will be the generalized eigenvalues.
If
alphai
[
j
]
is zero, then the
j
-th eigenvalue is real; if positive, then the
j
-th and (
j
+1)-st eigenvalues are a complex conjugate pair, with
alphai
[
j
+1]
negative.
For complex flavors:
On exit,
alpha
[
j
]/
beta
[
j
],
j
=0,...,
n
- 1
, will be the generalized eigenvalues.
See also
Application Notes
below.
vl
,
vr
Arrays:
vl
(size at least max(1,
ldvl
*
n
))
.
If
jobvl
=
'V'
, the left generalized eigenvectors
u
(j)
are stored one after another in the columns of
vl
, in the same order as their eigenvalues. Each eigenvector will be scaled so the largest component have abs(Re) + abs(Im) = 1.
If
jobvl
=
'N'
,
vl
is not referenced.
For real flavors
:
If the j-th eigenvalue is real, then
k
-th component of
j
-th left eigenvector
u
j
is stored in
vl
[(
k
- 1) + (j - 1)*
ldvl
]
for column major layout and in
vl
[(
k
- 1)*
ldvl
+ (
j
- 1)]
for row major layout.
.
If the j-th and (j+1)-st eigenvalues form a complex conjugate pair, then for
i
= sqrt(-1)
,
the
k
-th components of the
j
-th left eigenvector
u
j
can be computed as
vl
[(
k
- 1) + (
j
- 1)*
ldvl
]
+ i*
vl
[(
k
- 1) +
j
*
ldvl
]
for column major layout and
vl
[(
k
- 1)*
ldvl
+ (
j
- 1)]
+ i*
vl
[(
k
- 1)*
ldvl
+
j
]
for row major layout. Similarly, the
k
-th components of the left eigenvector
j
+1
u
j
+1
can be computed as
vl
[(
k
- 1) + (
j
- 1)*
ldvl
]
- i*
vl
[(
k
- 1) +
j
*
ldvl
]
for column major layout and
vl
[(
k
- 1)*
ldvl
+ (
j
- 1)]
- i*
vl
[(
k
- 1)*
ldvl
+
j
]
for row major layout.
.
For complex flavors
:
The
k
-th component of the
j
-th left eigenvector
u
j
is stored in
vl
[(
k
- 1) + (
j
- 1)*
ldvl
]
for column major layout and in
vl
[(
k
- 1)*
ldvl
+ (
j
- 1)]
for row major layout.
vr
(size at least max(1,
ldvr
*
n
))
.
If
jobvr
=
'V'
, the right generalized eigenvectors
v
(j) are stored one after another in the columns of
vr
, in the same order as their eigenvalues. Each eigenvector will be scaled so the largest component have abs(Re) + abs(Im) = 1.
If
jobvr
=
'N'
,
vr
is not referenced.
For real flavors
:
If the j-th eigenvalue is real, then
the
k
-th component of the
j
-th right eigenvector
v
j
is stored in
vr
[(
k
- 1) + (
j
- 1)*
ldvr
]
for column major layout and in
vr
[(
k
- 1)*
ldvr
+ (
j
- 1)]
for row major layout.
.
If the j-th and (j+1)-st eigenvalues form a complex conjugate pair, then
The
k
-th components of the
j
-th right eigenvector
v
j
can be computed as
vr
[(
k
- 1) + (
j
- 1)*
ldvr
]
+ i*
vr
[(
k
- 1) +
j
*
ldvr
]
for column major layout and
vr
[(
k
- 1)*
ldvr
+ (
j
- 1)]
+ i*
vr
[(
k
- 1)*
ldvr
+
j
]
for row major layout. Respectively, the
k
-th components of right eigenvector
j
+1
v
j
+ 1
can be computed as
vr
[(
k
- 1) + (
j
- 1)*
ldvr
]
- i*
vr
[(
k
- 1) +
j
*
ldvr
]
for column major layout and
vr
[(
k
- 1)*
ldvr
+ (
j
- 1)]
- i*
vr
[(
k
- 1)*
ldvr
+
j
]
for row major layout.
.
For complex flavors
:
The
k
-th component of the
j
-th right eigenvector
v
j
is stored in
vr
[(
k
- 1) + (
j
- 1)*
ldvr
]
for column major layout and in
vr
[(
k
- 1)*
ldvr
+ (
j
- 1)]
for row major layout.
ilo
,
ihi
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'
,
ilo
= 1
and
ihi
=
n
.
lscale
,
rscale
Arrays, size at least max(1,
n
) each.
lscale
contains 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
lscale
[
j
- 1]
=
PL
(j)
, for
j = 1,...,
ilo
-1
=
DL
(j)
, for
j =
ilo
,...,
ihi
=
PL
(j)
for
j =
ihi
+1,...,
n
.
The order in which the interchanges are made is
n
to
ihi
+1, then 1 to
ilo
-1.
rscale
contains 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
rscale
[
j
- 1]
=
PR
(j)
, for
j = 1,...,
ilo
-1
=
DR
(j)
, for
j =
ilo
,...,
ihi
=
PR
(j)
for
j =
ihi
+1,...,
n
.
The order in which the interchanges are made is
n
to
ihi
+1, then 1 to
ilo
-1.
abnrm
,
bbnrm
The one-norms of the balanced matrices
A
and
B
, respectively.
rconde
,
rcondv
Arrays, size at least max(1,
n
) each.
If
sense
=
'E'
, or
'B'
,
rconde
contains the reciprocal condition numbers of the eigenvalues, stored in consecutive elements of the array. For a complex conjugate pair of eigenvalues two consecutive elements of
rconde
are set to the same value. Thus
rconde
[
j
]
,
rcondv
[
j
]
, and the
j
-th columns of
vl
and
vr
all correspond to the same eigenpair (but not in general the
j
-th eigenpair, unless all eigenpairs are selected).
If
sense
=
'N'
, or
'V'
,
rconde
is not referenced.
If
sense
=
'V'
, or
'B'
,
rcondv
contains the estimated reciprocal condition numbers of the eigenvectors, stored in consecutive elements of the array. For a complex eigenvector two consecutive elements of
rcondv
are set to the same value.
If the eigenvalues cannot be reordered to compute ,
rcondv
[
j
]
is set to 0; this can only occur when the true value would be very small anyway.
If
sense
=
'N'
, or
'E'
,
rcondv
is not referenced.
Return Values
This function returns a value
info
.
If
info
=0
, the execution is successful.
If
info
=
-i
, the
i
-th parameter had an illegal value.
If
info
=
i
, and
i
n
: the
QZ
iteration failed. No eigenvectors have been calculated, but
alphar
[
j
],
alphai
[
j
] (for real flavors), or
alpha
[
j
] (for complex flavors), and
beta
[
j
],
j=
info
,...,
n
- 1
should be correct.
i
>
n
: errors that usually indicate LAPACK problems:
i
=
n
+1
: other than
QZ
iteration failed in hgeqz ;
i
=
n
+2
: error return from tgevc .
Application Notes
The quotients
alphar
[
j
]/
beta
[
j
]
and
alphai
[
j
]/
beta
[
j
]
may easily over- or underflow, and
beta
[
j
]
may even be zero. Thus, you should avoid simply computing the ratio. However,
alphar
and
alphai
(for real flavors) or
alpha
(for complex flavors) will be always less than and usually comparable with norm(
A
) in magnitude, and
beta
always less than and usually comparable with norm(
B
).