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

?geevx

Computes the eigenvalues and left and right eigenvectors of a general matrix, with preliminary matrix balancing, and computes reciprocal condition numbers for the eigenvalues and right eigenvectors.

Syntax

lapack_int LAPACKE_sgeevx( int matrix_layout, char balanc, char jobvl, char jobvr, char sense, lapack_int n, float* a, lapack_int lda, float* wr, float* wi, float* vl, lapack_int ldvl, float* vr, lapack_int ldvr, lapack_int* ilo, lapack_int* ihi, float* scale, float* abnrm, float* rconde, float* rcondv );

lapack_int LAPACKE_dgeevx( int matrix_layout, char balanc, char jobvl, char jobvr, char sense, lapack_int n, double* a, lapack_int lda, double* wr, double* wi, double* vl, lapack_int ldvl, double* vr, lapack_int ldvr, lapack_int* ilo, lapack_int* ihi, double* scale, double* abnrm, double* rconde, double* rcondv );

lapack_int LAPACKE_cgeevx( int matrix_layout, char balanc, char jobvl, char jobvr, char sense, lapack_int n, lapack_complex_float* a, lapack_int lda, lapack_complex_float* w, lapack_complex_float* vl, lapack_int ldvl, lapack_complex_float* vr, lapack_int ldvr, lapack_int* ilo, lapack_int* ihi, float* scale, float* abnrm, float* rconde, float* rcondv );

lapack_int LAPACKE_zgeevx( int matrix_layout, char balanc, char jobvl, char jobvr, char sense, lapack_int n, lapack_complex_double* a, lapack_int lda, lapack_complex_double* w, lapack_complex_double* vl, lapack_int ldvl, lapack_complex_double* vr, lapack_int ldvr, lapack_int* ilo, lapack_int* ihi, double* scale, double* abnrm, double* rconde, double* rcondv );

Include Files

  • mkl.h

Description

The routine computes for an n-by-n real/complex nonsymmetric matrix A, the eigenvalues and, optionally, the left and/or right eigenvectors.

Optionally also, it computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors (ilo, ihi, scale, and abnrm), reciprocal condition numbers for the eigenvalues (rconde), and reciprocal condition numbers for the right eigenvectors (rcondv).

The right eigenvector v of A satisfies

A·v = λ·v

where λ is its eigenvalue.

The left eigenvector u of A satisfies

uHA = λuH

where uH denotes the conjugate transpose of u. The computed eigenvectors are normalized to have Euclidean norm equal to 1 and largest component real.

Balancing a matrix means permuting the rows and columns to make it more nearly upper triangular, and applying a diagonal similarity transformation D*A*inv(D), where D is a diagonal matrix, to make its rows and columns closer in norm and the condition numbers of its eigenvalues and eigenvectors smaller. The computed reciprocal condition numbers correspond to the balanced matrix. Permuting rows and columns will not change the condition numbers in exact arithmetic) but diagonal scaling will. For further explanation of balancing, see [LUG], Section 4.10.

Input Parameters

matrix_layout

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

balanc

Must be 'N', 'P', 'S', or 'B'. Indicates how the input matrix should be diagonally scaled and/or permuted to improve the conditioning of its eigenvalues.

If balanc = 'N', do not diagonally scale or permute;

If balanc = 'P', perform permutations to make the matrix more nearly upper triangular. Do not diagonally scale;

If balanc = 'S', diagonally scale the matrix, i.e. replace A by D*A*inv(D), where D is a diagonal matrix chosen to make the rows and columns of A more equal in norm. Do not permute;

If balanc = 'B', both diagonally scale and permute A.

Computed reciprocal condition numbers will be for the matrix after balancing and/or permuting. Permuting does not change condition numbers (in exact arithmetic), but balancing does.

jobvl

Must be 'N' or 'V'.

If jobvl = 'N', left eigenvectors of A are not computed;

If jobvl = 'V', left eigenvectors of A are computed.

If sense = 'E' or 'B', then jobvl must be 'V'.

jobvr

Must be 'N' or 'V'.

If jobvr = 'N', right eigenvectors of A are not computed;

If jobvr = 'V', right eigenvectors of A are computed.

If sense = 'E' or 'B', then jobvr must be 'V'.

sense

Must be 'N', 'E', 'V', or 'B'. Determines which reciprocal condition number are computed.

If sense = 'N', none are computed;

If sense = 'E', computed for eigenvalues only;

If sense = 'V', computed for right eigenvectors only;

If sense = 'B', computed for eigenvalues and right eigenvectors.

If sense is 'E' or 'B', both left and right eigenvectors must also be computed (jobvl = 'V' and jobvr = 'V').

n

The order of the matrix A (n 0).

a

Arrays:

a (size at least max(1, lda*n)) is an array containing the n-by-n matrix A.

lda

The leading dimension of the array a. Must be at least max(1, n).

ldvl, ldvr

The leading dimensions of the output arrays vl and vr, respectively.

Constraints:

ldvl 1; ldvr 1.

If jobvl = 'V', ldvl max(1, n);

If jobvr = 'V', ldvr max(1, n).

Output Parameters

a

On exit, this array is overwritten.

If jobvl = 'V' or jobvr = 'V', it contains the real-Schur/Schur form of the balanced version of the input matrix A.

wr, wi

Arrays, size at least max (1, n) each. Contain the real and imaginary parts, respectively, of the computed eigenvalues. Complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having positive imaginary part first.

w

Array, size at least max(1, n). Contains the computed eigenvalues.

vl, vr

Arrays:

vl (size at least max(1, ldvl*n)) .

If jobvl = 'N', vl is not referenced.

For real flavors:

If the j-th eigenvalue is real,the i-th component of the j-th eigenvector uj is stored in vl[(i - 1) + (j - 1)*ldvl] for column major layout and in vl[(i - 1)*ldvl + (j - 1)] for row major layout..

If the j-th and (j+1)-st eigenvalues form a complex conjugate pair, then for i = sqrt(-1), the k-th component of the j-th eigenvector uj is vl[(k - 1) + (j - 1)*ldvl] + i*vl[(k - 1) + j*ldvl] for column major layout and as vl[(k - 1)*ldvl + (j - 1)] + i*vl[(k-1)*ldvl + j] for row major layout. Similarly, the k-th component of vector (j+1) uj + 1 is vl[(k - 1) + (j - 1)*ldvl] - i*vl[(k - 1) + j*ldvl] for column major layout and as vl[(k - 1)*ldvl + (j - 1)] -i*vl[(k - 1)*ldvl + j] for row major layout. .

For complex flavors:

The i-th component of the j-th eigenvector uj is stored in vl[(i - 1) + (j - 1)*ldvl] for column major layout and in vl[(i - 1)*ldvl+(j - 1)] for row major layout.

vr (size at least max(1, ldvr*n)).

If jobvr = 'N', vr is not referenced.

For real flavors:

If the j-th eigenvalue is real, then the i-th component of j-th eigenvector vj is stored in vr[(i - 1) + (j - 1)*ldvr] for column major layout and in vr[(i - 1)*ldvr + (j - 1)] for row major layout..

If the j-th and (j+1)-st eigenvalues form a complex conjugate pair, then for i = sqrt(-1), the k-th component of the j-th eigenvector vj is vr[(k - 1) + (j - 1)*ldvr] +i*vr[(k - 1) + j*ldvr] for column major layout and as vr[(k - 1)*ldvr + (j - 1)] + i*vr[(k - 1)*ldvr + j] for row major layout. Similarly, the k-th component of vector j + 1) vj + 1 is vr[(k - 1) + (j - 1)*ldvr] - i*vr[(k - 1) + j*ldvr] for column major layout and as vr[(k - 1)*ldvr + (j - 1)] - i*vr[(k - 1)*ldvr + j] for row major layout.

For complex flavors:

The i-th component of the j-th eigenvector vj is stored in vr[(i - 1) + (j - 1)*ldvr] for column major layout and in vr[(i - 1)*ldvr + (j - 1)] for row major layout.

ilo, ihi

ilo and ihi are integer values determined when A was balanced.

The balanced A(i,j) = 0 if i > j and j = 1,..., ilo-1 or i = ihi+1,..., n.

If balanc = 'N' or 'S', ilo = 1 and ihi = n.

scale

Array, size at least max(1, n). Details of the permutations and scaling factors applied when balancing A.

If P[j - 1] is the index of the row and column interchanged with row and column j, and D[j - 1] is the scaling factor applied to row and column j, then

scale[j - 1] = P[j - 1], for j = 1,...,ilo-1

= D[j - 1], for j = ilo,...,ihi

= P[j - 1] for j = ihi+1,..., n.

The order in which the interchanges are made is n to ihi+1, then 1 to ilo-1.

abnrm

The one-norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column).

rconde, rcondv

Arrays, size at least max(1, n) each.

rconde[j - 1] is the reciprocal condition number of the j-th eigenvalue.

rcondv[j - 1] is the reciprocal condition number of the j-th right eigenvector.

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.

If info = i, the QR algorithm failed to compute all the eigenvalues, and no eigenvectors or condition numbers have been computed; elements 1:ilo-1 and i+1:n of wr and wi (for real flavors) or w (for complex flavors) contain eigenvalues which have converged.