Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 2021.1
  • 12/04/2020
  • Public Content
Contents

?geevx

Computes the eigenvalues and left and right eigenvectors of a general matrix, with preliminary matrix balancing, and computes reciprocal condition numbers for the eigenvalues and right eigenvectors.

Syntax

lapack_int LAPACKE_sgeevx
(
int
matrix_layout
,
char
balanc
,
char
jobvl
,
char
jobvr
,
char
sense
,
lapack_int
n
,
float*
a
,
lapack_int
lda
,
float*
wr
,
float*
wi
,
float*
vl
,
lapack_int
ldvl
,
float*
vr
,
lapack_int
ldvr
,
lapack_int*
ilo
,
lapack_int*
ihi
,
float*
scale
,
float*
abnrm
,
float*
rconde
,
float*
rcondv
);
lapack_int LAPACKE_dgeevx
(
int
matrix_layout
,
char
balanc
,
char
jobvl
,
char
jobvr
,
char
sense
,
lapack_int
n
,
double*
a
,
lapack_int
lda
,
double*
wr
,
double*
wi
,
double*
vl
,
lapack_int
ldvl
,
double*
vr
,
lapack_int
ldvr
,
lapack_int*
ilo
,
lapack_int*
ihi
,
double*
scale
,
double*
abnrm
,
double*
rconde
,
double*
rcondv
);
lapack_int LAPACKE_cgeevx
(
int
matrix_layout
,
char
balanc
,
char
jobvl
,
char
jobvr
,
char
sense
,
lapack_int
n
,
lapack_complex_float*
a
,
lapack_int
lda
,
lapack_complex_float*
w
,
lapack_complex_float*
vl
,
lapack_int
ldvl
,
lapack_complex_float*
vr
,
lapack_int
ldvr
,
lapack_int*
ilo
,
lapack_int*
ihi
,
float*
scale
,
float*
abnrm
,
float*
rconde
,
float*
rcondv
);
lapack_int LAPACKE_zgeevx
(
int
matrix_layout
,
char
balanc
,
char
jobvl
,
char
jobvr
,
char
sense
,
lapack_int
n
,
lapack_complex_double*
a
,
lapack_int
lda
,
lapack_complex_double*
w
,
lapack_complex_double*
vl
,
lapack_int
ldvl
,
lapack_complex_double*
vr
,
lapack_int
ldvr
,
lapack_int*
ilo
,
lapack_int*
ihi
,
double*
scale
,
double*
abnrm
,
double*
rconde
,
double*
rcondv
);
Include Files
  • mkl.h
Description
The routine computes for an
n
-by-
n
 real/complex nonsymmetric matrix
A
, the eigenvalues and, optionally, the left and/or right eigenvectors.
Optionally also, it computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors (
ilo
,
ihi
,
scale
, and
abnrm
), reciprocal condition numbers for the eigenvalues (
rconde
), and reciprocal condition numbers for the right eigenvectors (
rcondv
).
The right eigenvector
v
 of
A
 satisfies
A
·
v
 =
λ
·
v
where
λ
 is its eigenvalue.
The left eigenvector
u
 of
A
 satisfies
u
H
A
 =
λ
u
H
where
u
H
 denotes the conjugate transpose of
u
. The computed eigenvectors are normalized to have Euclidean norm equal to 1 and largest component real.
Balancing a matrix means permuting the rows and columns to make it more nearly upper triangular, and applying a diagonal similarity transformation
D
*A
*inv(
D
), where
D
 is a diagonal matrix, to make its rows and columns closer in norm and the condition numbers of its eigenvalues and eigenvectors smaller. The computed reciprocal condition numbers correspond to the balanced matrix. Permuting rows and columns will not change the condition numbers in exact arithmetic) but diagonal scaling will. For further explanation of balancing, see [LUG], Section 4.10.
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'
. Indicates how the input matrix should be diagonally scaled and/or permuted to improve the conditioning of its eigenvalues.
If
balanc
 =
'N'
, do not diagonally scale or permute;
If
balanc
 =
'P'
, perform permutations to make the matrix more nearly upper triangular. Do not diagonally scale;
If
balanc
 =
'S'
, diagonally scale the matrix, i.e. replace
A
 by
D
*
A
*
inv(
D
)
, where
D
 is a diagonal matrix chosen to make the rows and columns of
A
 more equal in norm. Do not permute;
If
balanc
 =
'B'
, both diagonally scale and permute
A
.
Computed reciprocal condition numbers will be for the matrix 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'
, left eigenvectors of
A
 are not computed;
If
jobvl
 =
'V'
, left eigenvectors of
A
 are computed.
If
sense
 =
'E'
 or
'B'
, then
jobvl
 must be
'V'
.
jobvr
Must be
'N'
 or
'V'
.
If
jobvr
 =
'N'
, right eigenvectors of
A
 are not computed;
If
jobvr
 =
'V'
, right eigenvectors of
A
 are computed.
If
sense
 =
'E'
 or
'B'
, then
jobvr
 must be
'V'
.
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 right eigenvectors only;
If
sense
 =
'B'
, computed for eigenvalues and right eigenvectors.
If
sense
 is
'E'
 or
'B'
, both left and right eigenvectors must also be computed (
jobvl
 =
'V'
 and
jobvr
 =
'V'
).
n
The order of the matrix
A
 (
n
≥
 0
).
a
Arrays:
a
(size at least max(1,
lda
*
n
))
 is an array containing the
n
-by-
n
 matrix
A
.
lda
The leading dimension of the array
a
. Must be at least max(1,
n
).
ldvl
,
ldvr
The leading dimensions of the output arrays
vl
 and
vr
, respectively.
Constraints:
ldvl
≥
 1
;
ldvr
≥
 1
.
If
jobvl
 =
'V'
,
ldvl
≥
 max
(1,
n
);
If
jobvr
 =
'V'
,
ldvr
≥
 max
(1,
n
).
Output Parameters
a
On exit, this array is overwritten.
If
jobvl
 =
'V'
 or
jobvr
 =
'V'
, it contains the real-Schur/Schur form of the balanced version of the input matrix
A
.
wr
,
wi
Arrays, size at least max (1,
n
) each. Contain the real and imaginary parts, respectively, of the computed eigenvalues. Complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having positive imaginary part first.
w
Array, size at least max(1,
n
). Contains the computed eigenvalues.
vl
,
vr
Arrays:
vl
(size at least max(1,
ldvl
*
n
))
 .
If
jobvl
 =
'N'
,
vl
 is not referenced.
For real flavors
:
If the
j
-th eigenvalue is real,
the
i
-th component of the
j
-th eigenvector
u
j
 is stored in
vl
[(
i
 - 1) + (
j
 - 1)*
ldvl
]
 for column major layout and in
vl
[(
i
 - 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 component of the
j
-th eigenvector
u
j
 is
vl
[(
k
 - 1) + (
j
 - 1)*
ldvl
] + i*
vl
[(
k
 - 1) +
j
*
ldvl
] for column major layout and as
vl
[(
k
 - 1)*
ldvl
 + (
j
 - 1)] + i*
vl
[(
k
-1)*
ldvl
 +
j
] for row major layout. Similarly, the
k
-th component of vector (
j
+1)
u
j
 + 1
 is
vl
[(
k
 - 1) + (
j
 - 1)*
ldvl
] - i*
vl
[(
k
 - 1) +
j
*
ldvl
] for column major layout and as
vl
[(
k
 - 1)*
ldvl
 + (
j
 - 1)] -i*
vl
[(
k
 - 1)*
ldvl
 +
j
] for row major layout.
.
For complex flavors
:
The
i
-th component of the
j
-th eigenvector
u
j
 is stored in
vl
[(
i
 - 1) + (
j
 - 1)*
ldvl
]
 for column major layout and in
vl
[(
i
 - 1)*
ldvl
+(
j
 - 1)]
 for row major layout.
vr
(size at least max(1,
ldvr
*
n
))
.
If
jobvr
 =
'N'
,
vr
 is not referenced.
For real flavors
:
If the
j
-th eigenvalue is real, then
the
i
-th component of
j
-th eigenvector
v
j
 is stored in
vr
[(
i
 - 1) + (
j
 - 1)*
ldvr
]
 for column major layout and in
vr
[(
i
 - 1)*
ldvr
 + (
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 component of the
j
-th eigenvector
v
j
 is
vr
[(
k
 - 1) + (
j
 - 1)*
ldvr
] +i*
vr
[(
k
 - 1) +
j
*
ldvr
] for column major layout and as
vr
[(
k
 - 1)*
ldvr
 + (
j
 - 1)] + i*
vr
[(
k
 - 1)*
ldvr
 +
j
] for row major layout. Similarly, the
k
-th component of vector
j
 + 1)
v
j
 + 1
 is
vr
[(
k
 - 1) + (
j
 - 1)*
ldvr
] - i*
vr
[(
k
 - 1) +
j
*
ldvr
] for column major layout and as
vr
[(
k
 - 1)*
ldvr
 + (
j
 - 1)] - i*
vr
[(
k
 - 1)*
ldvr
 +
j
] for row major layout
.
For complex flavors
:
The
i
-th component of the
j
-th eigenvector
v
j
 is stored in
vr
[(
i
 - 1) + (
j
 - 1)*
ldvr
]
 for column major layout and in
vr
[(
i
 - 1)*
ldvr
 + (
j
 - 1)]
 for row major layout.
ilo
,
ihi
ilo
 and
ihi
 are integer values determined when
A
 was balanced.
The balanced
A
(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
.
scale
Array, size at least max(1,
n
). Details of the permutations and scaling factors applied when balancing
A
.
If
P
[
j
 - 1]
 is the index of the row and column interchanged with row and column
j
, and
D
[
j
 - 1]
 is the scaling factor applied to row and column
j
, then
scale
[
j
 - 1]
 =
P
[
j
 - 1]
, for
j
 = 1,...,
ilo
-1
=
D
[
j
 - 1]
, for
j
 =
ilo
,...,
ihi
=
P
[
j
 - 1]
 for
j
 =
ihi
+1,...,
n
.
The order in which the interchanges are made is
n
 to
ihi
+1, then 1 to
ilo
-1.
abnrm
The one-norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column).
rconde
,
rcondv
Arrays, size at least max(1,
n
) each.
rconde
[
j
 - 1]
 is the reciprocal condition number of the
j
-th eigenvalue.
rcondv
[
j
 - 1]
 is the reciprocal condition number of the
j
-th right eigenvector.
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