?trevc3

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

Download PDF

ID 766686

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-BF5DAB23-821E-4BA1-B2A6-41D1F69A7DDE

View Details

?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, 3n)` for real flavors, and at least `max(1, 2n)` 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. 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 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.

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

?trevc3

Syntax

Include Files

Description

Input Parameters

Output Parameters

Application Notes

See Also