Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 0.9
  • 09/09/2020
  • Public Content
Contents

?trevc

Computes selected eigenvectors of an upper (quasi-) triangular matrix computed by
?hseqr
.

Syntax

lapack_int LAPACKE_strevc
(
int
matrix_layout
,
char
side
,
char
howmny
,
lapack_logical*
select
,
lapack_int
n
,
const float*
t
,
lapack_int
ldt
,
float*
vl
,
lapack_int
ldvl
,
float*
vr
,
lapack_int
ldvr
,
lapack_int
mm
,
lapack_int*
m
);
lapack_int LAPACKE_dtrevc
(
int
matrix_layout
,
char
side
,
char
howmny
,
lapack_logical*
select
,
lapack_int
n
,
const double*
t
,
lapack_int
ldt
,
double*
vl
,
lapack_int
ldvl
,
double*
vr
,
lapack_int
ldvr
,
lapack_int
mm
,
lapack_int*
m
);
lapack_int LAPACKE_ctrevc
(
int
matrix_layout
,
char
side
,
char
howmny
,
const lapack_logical*
select
,
lapack_int
n
,
lapack_complex_float*
t
,
lapack_int
ldt
,
lapack_complex_float*
vl
,
lapack_int
ldvl
,
lapack_complex_float*
vr
,
lapack_int
ldvr
,
lapack_int
mm
,
lapack_int*
m
);
lapack_int LAPACKE_ztrevc
(
int
matrix_layout
,
char
side
,
char
howmny
,
const lapack_logical*
select
,
lapack_int
n
,
lapack_complex_double*
t
,
lapack_int
ldt
,
lapack_complex_double*
vl
,
lapack_int
ldvl
,
lapack_complex_double*
vr
,
lapack_int
ldvr
,
lapack_int
mm
,
lapack_int*
m
);
Include Files
  • mkl.h
Description
The routine computes some or all of the right and/or left eigenvectors of an upper triangular matrix
T
 (or, for real flavors, an upper quasi-triangular matrix
T
). Matrices of this type are produced by the Schur factorization of a general matrix:
A
 =
Q
*
T
*
Q
H
, as computed by hseqr.
The right eigenvector
x
 and the left eigenvector
y
 of
T
 corresponding to an eigenvalue
w
, are defined by:
T
*
x
 =
w
*
x
,
y
H
*
T
 =
w
*
y
H
, where
y
H
 denotes the conjugate transpose of
y
.
The eigenvalues are not input to this routine, but are read directly from the diagonal blocks of
T
.
This routine returns the matrices
X
 and/or
Y
 of right and left eigenvectors of
T
, or the products
Q
*
X
 and/or
Q*
Y
, where
Q
 is an input matrix.
If
Q
 is the orthogonal/unitary factor that reduces a matrix
A
 to Schur form
T
, then
Q
*
X
 and
Q
*
Y
 are the matrices of right and left eigenvectors of
A
.
Input Parameters
matrix_layout
Specifies whether matrix storage layout is row major (
LAPACK_ROW_MAJOR
) or column major (
LAPACK_COL_MAJOR
).
side
Must be
'R'
 or
'L'
 or
'B'
.
If
side
 =
'R'
, then only right eigenvectors are computed.
If
side
 =
'L'
, then only left eigenvectors are computed.
If
side
 =
'B'
, then all eigenvectors are computed.
howmny
Must be
'A'
 or
'B'
 or
'S'
.
If
howmny
 =
'A'
, then all eigenvectors (as specified by
side
) are computed.
If
howmny
 =
'B'
, then all eigenvectors (as specified by
side
) are computed and backtransformed by the matrices supplied in
vl
 and
vr
.
If
howmny
 =
'S'
, then selected eigenvectors (as specified by
side
 and
select
) are computed.
select
Array, size at least max (1,
n
).
If
howmny
 =
'S'
,
select
 specifies which eigenvectors are to be computed.
If
howmny
 =
'A'
 or
'B'
,
select
 is not referenced.
For real flavors
:
If
omega
[
j
]
 is a real eigenvalue, the corresponding real eigenvector is computed if
select
[
j
]
 is
1
.
If
omega
[
j
 - 1]
 and
omega
[
j
]
 are the real and imaginary parts of a complex eigenvalue, the corresponding complex eigenvector is computed if either
select
[
j
 - 1]
 or
select
[
j
]
 is
1
, and on exit
select
[
j
 - 1]
 is set to
1
and
select
[
j
]
 is set to
0
.
For complex flavors:
The eigenvector corresponding to the
j
-th eigenvalue is computed if
select
[
j
 - 1]
 is
1
.
n
The order of the matrix
T
 (
n
≥
 0
).
t
,
vl
,
vr
Arrays:
t
(size max(1,
ldt
*
n
))
 contains the
n
-by-
n
 matrix
T
 in Schur canonical form. For complex flavors
ctrevc
 and
ztrevc
, contains the upper triangular matrix
T
.
vl
(size max(1,
ldvl
*
mm
) for column major layout and max(1,
ldvl
*
n
) for row major layout)
If
howmny
 =
'B'
 and
side
 =
'L'
 or
'B'
, then
vl
 must contain an
n
-by-
n
 matrix
Q
 (usually the matrix of Schur vectors returned by
?hseqr
).
If
howmny
 =
'A'
 or
'S'
, then
vl
 need not be set.
The array
vl
 is not referenced if
side
 =
'R'
.
vr
(size max(1,
ldvr
*
mm
) for column major layout and max(1,
ldvr
*
n
) for row major layout)
If
howmny
 =
'B'
 and
side
 =
'R'
 or
'B'
, then
vr
 must contain an
n
-by-
n
 matrix
Q
 (usually the matrix of Schur vectors returned by
?hseqr
). .
If
howmny
 =
'A'
 or
'S'
, then
vr
 need not be set.
The array
vr
 is not referenced if
side
 =
'L'
.
ldt
The leading dimension of
t
; at least max(1,
n
).
ldvl
The leading dimension of
vl
.
If
side
 =
'L'
 or
'B'
,
ldvl
≥
n
.
If
side
 =
'R'
,
ldvl
≥
 1
.
ldvr
The leading dimension of
vr
.
If
side
 =
'R'
 or
'B'
,
ldvr
≥
n
.
If
side
 =
'L'
,
ldvr
≥
 1
.
mm
The number of columns in the arrays
vl
 and/or
vr
. Must be at least
m
 (the precise number of columns required).
If
howmny
 =
'A'
 or
'B'
,
mm
 =
n
.
If
howmny
 =
'S'
:
for real flavors
,
mm
 is obtained by counting 1 for each selected real eigenvector and 2 for each selected complex eigenvector;
for complex flavors
,
mm
 is the number of selected eigenvectors (see
select
).
Constraint:
0
≤
mm
≤
n
.
Output Parameters
select
If a complex eigenvector of a real matrix was selected as specified above, then
select
[
j
]
 is set to
1
 and
select
[
j
 + 1]
 to
0
t
ctrevc
/
ztrevc
 modify the
t
 array, which is restored on exit.
vl
,
vr
If
side
 =
'L'
 or
'B'
,
vl
 contains the computed left eigenvectors (as specified by
howmny
 and
select
).
If
side
 =
'R'
 or
'B'
,
vr
 contains the computed right eigenvectors (as specified by
howmny
 and
select
).
The eigenvectors treated column-wise form a rectangular
n
-by-
mm
 matrix.
For real flavors
: a real eigenvector corresponding to a real eigenvalue occupies one column of the matrix; a complex eigenvector corresponding to a complex eigenvalue occupies two columns: the first column holds the real part of the eigenvector and the second column holds the imaginary part of the eigenvector. The matrix is stored in a one-dimensional array as described by
matrix_layout
 (using either column major or row major layout).
m
For complex flavors
: the number of selected eigenvectors.
If
howmny
 =
'A'
 or
'B'
,
m
 is set to
n
.
For real flavors
: the number of columns of
vl
 and/or
vr
 actually used to store the selected eigenvectors.
If
howmny
 =
'A'
 or
'B'
,
m
 is set to
n
.
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.
Application Notes
If
x
i
 is an exact right eigenvector and
y
i
 is the corresponding computed eigenvector, then the angle
θ
(
y
i
,
x
i
)
 between them is bounded as follows:
θ
(
y
i
,
x
i
)
≤
(
c
(
n
)
ε
||
T
||
2
)/sep
i
 where sep
i
 is the reciprocal condition number of
x
i
. The condition number sep
i
 may be computed by calling
?trsna
.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804