?trevc

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 11/07/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-3F64CC21-485F-4485-B9D0-184F3DF08EC4

View Details

?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 1and 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||₂)/sep_i where sep_i is the reciprocal condition number of x_i. The condition number sep_i may be computed by calling ?trsna.

Parent topic: Nonsymmetric Eigenvalue Problems: LAPACK Computational Routines

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for C

?trevc

Syntax

Include Files

Description

Input Parameters

Output Parameters

Return Values

Application Notes