Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 2021.1
  • 12/04/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

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.