Developer Reference for Intel® oneAPI Math Kernel Library for C
?trevc
Computes selected eigenvectors of an upper (quasi-) triangular matrix computed by ?hseqr .
Syntax
lapack_int LAPACKE_strevc ( intmatrix_layout , charside , charhowmny , lapack_logical*select , lapack_intn , const float*t , lapack_intldt , float*vl , lapack_intldvl , float*vr , lapack_intldvr , lapack_intmm , lapack_int*m );
lapack_int LAPACKE_dtrevc ( intmatrix_layout , charside , charhowmny , lapack_logical*select , lapack_intn , const double*t , lapack_intldt , double*vl , lapack_intldvl , double*vr , lapack_intldvr , lapack_intmm , lapack_int*m );
lapack_int LAPACKE_ctrevc ( intmatrix_layout , charside , charhowmny , const lapack_logical*select , lapack_intn , lapack_complex_float*t , lapack_intldt , lapack_complex_float*vl , lapack_intldvl , lapack_complex_float*vr , lapack_intldvr , lapack_intmm , lapack_int*m );
lapack_int LAPACKE_ztrevc ( intmatrix_layout , charside , charhowmny , const lapack_logical*select , lapack_intn , lapack_complex_double*t , lapack_intldt , lapack_complex_double*vl , lapack_intldvl , lapack_complex_double*vr , lapack_intldvr , lapack_intmm , lapack_int*m );
Include Files
mkl.h
Description
strevc dtrevc ctrevc ztrevc trevc
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:code:`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
-
REAL for strevc DOUBLE PRECISION for dtrevc COMPLEX for ctrevc DOUBLE COMPLEX for ztrevc . 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 .
The second dimension of t must be at least max(1, n ).
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 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 (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 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. size at least max (1, 3* n ) for real flavors and at least max (1, 2* n ) for complex flavors.
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 .
- rwork
-
REAL for ctrevc DOUBLE PRECISION for ztrevc . Workspace array, size at least max (1, 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
-
COMPLEX for ctrevc DOUBLE COMPLEX for ztrevc .
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.
LAPACK 95 Interface Notes
There exist FORTRAN 77 and FORTRAN 95 interfaces for this routine. See the Intel® oneMKL Fortran Developer Reference for details.
Application Notes
If xi is an exact right eigenvector and yi is the corresponding computed eigenvector, then the angle \(\theta(y_{i}, x_{i})\) between them is bounded as follows: \(\theta(y_{i},x_{i})\leq(c(n)\varepsilon||T||_{2})/sep_{i}\) where sep i is the reciprocal condition number of xi . The condition number sep i may be computed by calling ?trsna .