Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

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

?trevc3

Computes selected eigenvectors of an upper (quasi-) triangular matrix computed by
?hseqr
 using Level 3 BLAS

Syntax

call
strevc3
(
side
,
howmny
,
select
,
n
,
t
,
ldt
,
vl
,
ldvl
,
vr
,
ldvr
,
mm
,
m
,
work
,
lwork
,
info
)
call
dtrevc3
(
side
,
howmny
,
select
,
n
,
t
,
ldt
,
vl
,
ldvl
,
vr
,
ldvr
,
mm
,
m
,
work
,
lwork
,
info
)
call
ctrevc3
(
side
,
howmny
,
select
,
n
,
t
,
ldt
,
vl
,
ldvl
,
vr
,
ldvr
,
mm
,
m
,
work
,
lwork
,
rwork
,
lrwork
,
info
)
call
ztrevc3
(
side
,
howmny
,
select
,
n
,
t
,
ldt
,
vl
,
ldvl
,
vr
,
ldvr
,
mm
,
m
,
work
,
lwork
,
rwork
,
lrwork
,
info
)
Include Files
  • mkl.fi
Description
This routine computes some or all of the right and left eigenvectors of an upper triangular matrix
T
 (or, for real flavors, an upper quasi-triangular matrix
T
) using Level 3 BLAS. Matrices of this type are produced by the Schur factorization of a general matrix:
A =Q*T*QH
, as computed by
hseqr
.
The right eigenvector
x
 and the left eigenvector
y
 of
T
 corresponding to an eigenvalue
w
 are defined by the following:
T*x = w*x, y
H
*T = w*y
H
where y
H
 denotes the conjugate transpose of
y
.
The eigenvalues are not passed to this routine but are read directly from the diagonal blocks of
T
.
This routine returns one or both of the matrices
X
 and
Y
 of the right and left eigenvectors of
T
, or one or both of the products
Q*X
 and
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 the right and left eigenvectors of
A
.
Input Parameters
side
CHARACTER*1
Must be
'R'
,
'L'
, or
'B'
.
  • If
    side
     =
    'R'
    , only right eigenvectors are computed.
  • If
    side
     =
    'L'
    , only left eigenvectors are computed.
  • If
    side
     =
    'B'
    , all eigenvectors are computed.
howmny
CHARACTER*1
Must be
'A'
,
'B'
, or
'S'
.
  • If
    howmny
     =
    'A'
    , all eigenvectors (as specified by
    side
    ) are computed.
  • If
    howmny
     =
    'B'
    , all eigenvectors (as specified by
    side
    ) are computed and back-transformed by the matrices supplied in
    vl
     and
    vr
    .
  • If
    howmny
     =
    'S'
    , selected eigenvectors (as specified by
    side
     and
    select
    ) are computed.
select
Array with a size of at least
max (1, n)
If
howmny
 =
'S'
,
select
 specifies which eigenvectors are to be computed. If
howmny
 =
'A'
 or
howmny
 =
'B'
,
select
 is not referenced.
For real flavors:
  • If
    omega(j)
     is a real eigenvalue and
    select(j)
     is
    .TRUE.
    , the corresponding real eigenvector is computed.
  • If
    omega(j)
     and
    omega(j + 1)
     are the real and imaginary parts of a complex eigenvalue and either
    select(j)
     or
    select(j + 1)
     is
    .TRUE.
    , the corresponding complex eigenvector is computed, and on exit
    select(j)
     is set to
    .TRUE.
     and
    select(j + 1)
     is set to
    .FALSE.
    .
For complex flavors:
  • If
    select(j)
     is
    .TRUE.
    , the eigenvector corresponding to the
    j
    th
     eigenvalue is computed.
n
INTEGER
The order of the matrix
T (n≥ 0)
.
t
,
vl
,
vr
,
work
  • REAL
     for
    strevc3
  • DOUBLE PRECISION
     for
    dtrevc3
  • COMPLEX
     for
    ctrevc3
  • DOUBLE COMPLEX
     for
    ztrevc3
Arrays:
  • t(ldt,*)
     contains the
    n
    -by-
    n
     matrix
    T
     in Schur canonical form. For complex flavors
    ctrevc3
     and
    ztrevc3
    , the array contains the upper triangular matrix
    T
    .
    The second dimension of
    t
     must be at least
    max(1, n)
    .
  • vl(ldvl,*)
    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'
    ,
    vl
     need not be set.
    The second dimension of
    vl
     must be at least
    max(1, mm)
     if
    side
     =
    'L'
     or
    'B'
    , and at least
    1
     if
    side
     =
    'R'
    .
    The array
    vl
     is not referenced if
    side
     =
    'R'
    .
  • vr(ldvr,*)
    If
    howmny
     =
    'B'
     and
    side
     =
    'R'
     or
    'B'
    ,
    vr
     must contain an
    n
    -by-
    n
     matrix
    Q
     (usually the matrix of Schur vectors returned by
    ?hseqr
    ).
    If
    howmny
     =
    'A'
     or
    'S'
    ,
    vr
     need not be set.
    The second dimension of
    vr
     must be at least
    max(1, mm)
     if
    side
     =
    'R'
     or
    'B'
    , and at least
    1
     if
    side
     =
    'L'
    .
    The array
    vr
     is not referenced if
    side
     =
    'L'
    .
  • work(*)
     is a workspace array, and its dimension is
    max (1, lwork)
    .
lwork
INTEGER
The size of the work array. Must be at least
max(1, 3*n)
 for real flavors, and at least
max(1, 2*n)
 for complex flavors.
If
lwork
 =
-1
, a workspace query is assumed; the routine calculates only the optimal size of the work array and returns this value as the first entry of the work array, and no error message related to
lwork
 is issued by xerbla. For details, see "Application Notes" below.
ldt
INTEGER
The leading dimension of
t
. It is at least
max(1, n)
.
ldvl
INTEGER
The leading dimension of
vl
.
  • If
    side
     =
    'L'
     or
    'B'
    ,
    ldvl≥n
    .
  • If
    side
     =
    'R'
    ,
    ldvl≥ 1
    .
ldvr
INTEGER
The leading dimension of
vr
.
  • If
    side
     =
    'R'
     or
    'B'
    ,
    ldvr≥n
    .
  • If
    side
     =
    'L'
    ,
    ldvr≥ 1
    .
mm
INTEGER
The number of columns in one or both of the arrays
vl
 and
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
.
rwork
  • REAL
     for
    ctrevc3
  • DOUBLE PRECISION
     for
    ztrevc3
The workspace array is used in complex flavors only. Its dimensionis
max (1, lrwork)
.
lrwork
INTEGER
The size of the
rwork
 array. It must be at least
max(1, n)
.
If
lrwork
 =
-1
, a workspace query is assumed; the routine calculates only the optimal size of the work array and returns this value as the first entry of the
rwork
 array, and no error message related to
lrwork
 is issued by xerbla. For details, see "Application Notes" below.
Output Parameters
select
If a complex eigenvector of a real matrix was selected as specified above, then
select(j)
 is set to
.TRUE.
 and
select(j + 1)
 is set to
.FALSE.
.
t
COMPLEX
 for
ctrevc3
DOUBLE COMPLEX
 for
ztrevc3
ctrevc3
 or
ztrevc3
 modifies the
t(ldt,*)
 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
).
Treated column-wise, the eigenvectors form a rectangular
n
-by-
mm
 matrix.
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
INTEGER
The number of selected eigenvectors. If
howmny
 =
'A'
 or
'B'
,
m
 is set to
n
.
The number of columns of one or both of
vl
 and
vr
 actually used to store the selected eigenvectors. If
howmny
 =
'A'
 or
'B'
,
m
 is set to
n
.
work(1)
On exit, if
info
 =
0
,
work(1)
 returns the required optimal size of
lwork
.
rwork(1)
On exit, if
info
 =
0
, then
rwork(1)
 returns the required optimal size of
lrwork
.
info
INTEGER
If
info
 =
0
, the execution is successful.
If
info
 =
-
i
, the
i
th
 parameter contained an illegal value.
Application Notes
If
xi
 is an exact right eigenvector and
yi
 is the corresponding computed eigenvector, the angle
θ(yi, xi)
 between them is bounded as follows:
θ(yi,xi)≤(c(n)ε||T||2)/sepi
where
sepi
 is the reciprocal condition number of
xi
. You can compute the condition number
sepi
 by calling
?trsna
.

Product and Performance Information

1

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