Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
Public

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

Document Table of 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*QH, 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, yH*T = w*yH, where yH 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', ldvln.

If side = 'R', ldvl 1.

ldvr

The leading dimension of vr.

If side = 'R' or 'B', ldvrn.

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 mmn.

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 xi is an exact right eigenvector and yi is the corresponding computed eigenvector, then 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. The condition number sepi may be computed by calling ?trsna.