?trevc

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

Download PDF

ID 766686

Date 3/22/2024

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

call strevc(side, howmny, select, n, t, ldt, vl, ldvl, vr, ldvr, mm, m, work, info)

call dtrevc(side, howmny, select, n, t, ldt, vl, ldvl, vr, ldvr, mm, m, work, info)

call ctrevc(side, howmny, select, n, t, ldt, vl, ldvl, vr, ldvr, mm, m, work, rwork, info)

call ztrevc(side, howmny, select, n, t, ldt, vl, ldvl, vr, ldvr, mm, m, work, rwork, info)

call trevc(t [, howmny] [,select] [,vl] [,vr] [,m] [,info])

Include Files

mkl.fi, lapack.f90

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

side

CHARACTER*1. 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

CHARACTER*1. 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

LOGICAL.

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

If omega(j) and omega(j + 1) are the real and imaginary parts of a complex eigenvalue, the corresponding complex eigenvector is computed if either select(j) or select(j + 1) is .TRUE., and on exit select(j) is set to .TRUE.and select(j + 1) is set to .FALSE..

For complex flavors:

The eigenvector corresponding to the j-th eigenvalue is computed if select(j) is .TRUE..

n

INTEGER. 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(ldt,*) 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(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', 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(ldvr,*)

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

INTEGER. The leading dimension of t; 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 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 .TRUE. and select(j + 1) to .FALSE.

t

COMPLEX for ctrevc

DOUBLE COMPLEX for ztrevc.

ctrevc/ztrevc modify 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).

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

INTEGER.

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.

info

INTEGER.

If info = 0, the execution is successful.

If info = -i, the i-th parameter had an illegal value.

LAPACK 95 Interface Notes

Routines in Fortran 95 interface have fewer arguments in the calling sequence than their FORTRAN 77 counterparts. For general conventions applied to skip redundant or restorable arguments, see LAPACK 95 Interface Conventions.

Specific details for the routine trevc interface are the following:

t

Holds the matrix T of size (n,n).

select

Holds the vector of length n.

vl

Holds the matrix VL of size (n,mm).

vr

Holds the matrix VR of size (n,mm).

side

If omitted, this argument is restored based on the presence of arguments vl and vr as follows:

side = 'B', if both vl and vr are present,

side = 'L', if vr is omitted,

side = 'R', if vl is omitted.

Note that there will be an error condition if both vl and vr are omitted.

howmny

If omitted, this argument is restored based on the presence of argument select as follows:

howmny = 'V', if q is present,

howmny = 'N', if q is omitted.

If present, vect = 'V' or 'U' and the argument q must also be present.

Note that there will be an error condition if both select and howmny are present.

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 Fortran

?trevc

Syntax

Include Files

Description

Input Parameters

Output Parameters

LAPACK 95 Interface Notes

Application Notes