Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

ID 766686
Date 11/07/2023
Public

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

Document Table of Contents

?tgevc

Computes some or all of the right and/or left generalized eigenvectors of a pair of upper triangular matrices.

Syntax

call stgevc(side, howmny, select, n, s, lds, p, ldp, vl, ldvl, vr, ldvr, mm, m, work, info)

call dtgevc(side, howmny, select, n, s, lds, p, ldp, vl, ldvl, vr, ldvr, mm, m, work, info)

call ctgevc(side, howmny, select, n, s, lds, p, ldp, vl, ldvl, vr, ldvr, mm, m, work, rwork, info)

call ztgevc(side, howmny, select, n, s, lds, p, ldp, vl, ldvl, vr, ldvr, mm, m, work, rwork, info)

call tgevc(s, p [,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 a pair of real/complex matrices (S,P), where S is quasi-triangular (for real flavors) or upper triangular (for complex flavors) and P is upper triangular.

Matrix pairs of this type are produced by the generalized Schur factorization of a real/complex matrix pair (A,B):

A = Q*S*ZH, B = Q*P*ZH

as computed by ?gghrd plus ?hgeqz.

The right eigenvector x and the left eigenvector y of (S,P) corresponding to an eigenvalue w are defined by:

S*x = w*P*x, yH*S = w*yH*P

The eigenvalues are not input to this routine, but are computed directly from the diagonal blocks or diagonal elements of S and P.

This routine returns the matrices X and/or Y of right and left eigenvectors of (S,P), or the products Z*X and/or Q*Y, where Z and Q are input matrices.

If Q and Z are the orthogonal/unitary factors from the generalized Schur factorization of a matrix pair (A,B), then Z*X and Q*Y are the matrices of right and left eigenvectors of (A,B).

Input Parameters

side

CHARACTER*1. Must be 'R', 'L', or 'B'.

If side = 'R', compute right eigenvectors only.

If side = 'L', compute left eigenvectors only.

If side = 'B', compute both right and left eigenvectors.

howmny

CHARACTER*1. Must be 'A', 'B', or 'S'.

If howmny = 'A', compute all right and/or left eigenvectors.

If howmny = 'B', compute all right and/or left eigenvectors, backtransformed by the matrices in vr and/or vl.

If howmny = 'S', compute selected right and/or left eigenvectors, specified by the logical array select.

select

LOGICAL.

Array, size at least max (1, n).

If howmny = 'S', select specifies the eigenvectors to be computed.

If howmny = 'A'or 'B', select is not referenced.

For real flavors:

If w(j) is a real eigenvalue, the corresponding real eigenvector is computed if select(j) is .TRUE..

If w(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 matrices S and P (n 0).

s, p, vl, vr, work

REAL for stgevc

DOUBLE PRECISION for dtgevc

COMPLEX for ctgevc

DOUBLE COMPLEX for ztgevc.

Arrays:

s(lds,*) contains the matrix S from a generalized Schur factorization as computed by ?hgeqz. This matrix is upper quasi-triangular for real flavors, and upper triangular for complex flavors.

The second dimension of s must be at least max(1, n).

p(ldp,*) contains the upper triangular matrix P from a generalized Schur factorization as computed by ?hgeqz.

For real flavors, 2-by-2 diagonal blocks of P corresponding to 2-by-2 blocks of S must be in positive diagonal form.

For complex flavors, P must have real diagonal elements. The second dimension of p must be at least max(1, n).

If side = 'L' or 'B' and howmny = 'B', vl(ldvl,*) must contain an n-by-n matrix Q (usually the orthogonal/unitary matrix Q of left Schur vectors returned by ?hgeqz). The second dimension of vl must be at least max(1, mm).

If side = 'R', vl is not referenced.

If side = 'R' or 'B' and howmny = 'B', vr(ldvr,*) must contain an n-by-n matrix Z (usually the orthogonal/unitary matrix Z of right Schur vectors returned by ?hgeqz). The second dimension of vr must be at least max(1, mm).

If side = 'L', vr is not referenced.

work(*) is a workspace array.

size at least max (1, 6*n) for real flavors and at least max (1, 2*n) for complex flavors.

lds

INTEGER. The leading dimension of s; at least max(1, n).

ldp

INTEGER. The leading dimension of p; at least max(1, n).

ldvl

INTEGER. The leading dimension of vl;

If side = 'L' or 'B', then ldvln.

If side = 'R', then ldvl 1 .

ldvr

INTEGER. The leading dimension of vr;

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

If side = 'L', then ldvr 1.

mm

INTEGER. The number of columns in the arrays vl and/or vr (mmm).

rwork

REAL for ctgevc DOUBLE PRECISION for ztgevc. Workspace array, size at least max (1, 2*n). Used in complex flavors only.

Output Parameters

vl

On exit, if side = 'L' or 'B', vl contains:

if howmny = 'A', the matrix Y of left eigenvectors of (S,P);

if howmny = 'B', the matrix Q*Y;

if howmny = 'S', the left eigenvectors of (S,P) specified by select, stored consecutively in the columns of vl, in the same order as their eigenvalues.

For real flavors:

A complex eigenvector corresponding to a complex eigenvalue is stored in two consecutive columns, the first holding the real part, and the second the imaginary part.

vr

On exit, if side = 'R' or 'B', vr contains:

if howmny = 'A', the matrix X of right eigenvectors of (S,P);

if howmny = 'B', the matrix Z*X;

if howmny = 'S', the right eigenvectors of (S,P) specified by select, stored consecutively in the columns of vr, in the same order as their eigenvalues.

For real flavors:

A complex eigenvector corresponding to a complex eigenvalue is stored in two consecutive columns, the first holding the real part, and the second the imaginary part.

m

INTEGER. The number of columns in the arrays vl and/or vr actually used to store the eigenvectors.

If howmny = 'A' or 'B', m is set to n.

For real flavors:

Each selected real eigenvector occupies one column and each selected complex eigenvector occupies two columns.

For complex flavors:

Each selected eigenvector occupies one column.

info

INTEGER.

If info = 0, the execution is successful.

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

For real flavors:

if info = i>0, the 2-by-2 block (i:i+1) does not have a complex eigenvalue.

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 tgevc interface are the following:

s

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

p

Holds the matrix P 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

Restored based on the presence of arguments vl and vr as follows:

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

side = 'L', if vl is present and vr omitted,

side = 'R', if vl is omitted and vr present,

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 = 'S', if select is present,

howmny = 'A', if select is omitted.

If present, howmny must be equal to 'A' or 'B' and the argument select must be omitted.

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