Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 12/16/2022
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

lapack_int LAPACKE_stgevc (int matrix_layout, char side, char howmny, const lapack_logical* select, lapack_int n, const float* s, lapack_int lds, const float* p, lapack_int ldp, float* vl, lapack_int ldvl, float* vr, lapack_int ldvr, lapack_int mm, lapack_int* m);

lapack_int LAPACKE_dtgevc (int matrix_layout, char side, char howmny, const lapack_logical* select, lapack_int n, const double* s, lapack_int lds, const double* p, lapack_int ldp, double* vl, lapack_int ldvl, double* vr, lapack_int ldvr, lapack_int mm, lapack_int* m);

lapack_int LAPACKE_ctgevc (int matrix_layout, char side, char howmny, const lapack_logical* select, lapack_int n, const lapack_complex_float* s, lapack_int lds, const lapack_complex_float* p, lapack_int ldp, lapack_complex_float* vl, lapack_int ldvl, lapack_complex_float* vr, lapack_int ldvr, lapack_int mm, lapack_int* m);

lapack_int LAPACKE_ztgevc (int matrix_layout, char side, char howmny, const lapack_logical* select, lapack_int n, const lapack_complex_double* s, lapack_int lds, const lapack_complex_double* p, lapack_int ldp, 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 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
matrix_layout

Specifies whether matrix storage layout is row major (LAPACK_ROW_MAJOR) or column major (LAPACK_COL_MAJOR).

side

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

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

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

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 1, and on exit select[j] is set to 1and select[j + 1] is set to 0.

For complex flavors:

The eigenvector corresponding to the j-th eigenvalue is computed if select[j] is 1.

n

The order of the matrices S and P (n 0).

s, p, vl, vr

Arrays:

s (size max(1, lds*n)) 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.

p (size max(1, ldp*n)) 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.

If side = 'L' or 'B' and howmny = 'B', vl(size max(1, ldvl*mm) for column major layout and max(1, ldvl*n) for row major layout) must contain an n-by-n matrix Q (usually the orthogonal/unitary matrix Q of left Schur vectors returned by ?hgeqz).

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

If side = 'R' or 'B' and howmny = 'B', vr(size max(1, ldvr*mm) for column major layout and max(1, ldvr*n) for row major layout) must contain an n-by-n matrix Z (usually the orthogonal/unitary matrix Z of right Schur vectors returned by ?hgeqz).

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

lds

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

ldp

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

ldvl

The leading dimension of vl;

If side = 'L' or 'B', then ldvln for column major layout and ldvl max(1, mm) for row major layout.

If side = 'R', then ldvl 1 .

ldvr

The leading dimension of vr;

If side = 'R' or 'B', then ldvrn for column major layout and ldvr max(1, mm) for row major layout.

If side = 'L', then ldvr 1.

mm

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

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

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.

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.

For real flavors:

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