?hsein

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 6/24/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-5A0CBA9E-754E-4738-8ECD-32503DA5398D

View Details

?hsein

Computes selected eigenvectors of an upper Hessenberg matrix that correspond to specified eigenvalues.

Syntax

lapack_int LAPACKE_shsein( int matrix_layout, char side, char eigsrc, char initv, lapack_logical* select, lapack_int n, const float* h, lapack_int ldh, float* wr, const float* wi, float* vl, lapack_int ldvl, float* vr, lapack_int ldvr, lapack_int mm, lapack_int* m, lapack_int* ifaill, lapack_int* ifailr );

lapack_int LAPACKE_dhsein( int matrix_layout, char side, char eigsrc, char initv, lapack_logical* select, lapack_int n, const double* h, lapack_int ldh, double* wr, const double* wi, double* vl, lapack_int ldvl, double* vr, lapack_int ldvr, lapack_int mm, lapack_int* m, lapack_int* ifaill, lapack_int* ifailr );

lapack_int LAPACKE_chsein( int matrix_layout, char side, char eigsrc, char initv, const lapack_logical* select, lapack_int n, const lapack_complex_float* h, lapack_int ldh, lapack_complex_float* w, lapack_complex_float* vl, lapack_int ldvl, lapack_complex_float* vr, lapack_int ldvr, lapack_int mm, lapack_int* m, lapack_int* ifaill, lapack_int* ifailr );

lapack_int LAPACKE_zhsein( int matrix_layout, char side, char eigsrc, char initv, const lapack_logical* select, lapack_int n, const lapack_complex_double* h, lapack_int ldh, lapack_complex_double* w, lapack_complex_double* vl, lapack_int ldvl, lapack_complex_double* vr, lapack_int ldvr, lapack_int mm, lapack_int* m, lapack_int* ifaill, lapack_int* ifailr );

Include Files

mkl.h

Description

The routine computes left and/or right eigenvectors of an upper Hessenberg matrix H, corresponding to selected eigenvalues.

The right eigenvector x and the left eigenvector y, corresponding to an eigenvalue λ, are defined by: H*x = λ*x and y^H*H = λ*y^H (or H^H*y = λ^**y). Here λ^* denotes the conjugate of λ.

The eigenvectors are computed by inverse iteration. They are scaled so that, for a real eigenvector x, max|x_i| = 1, and for a complex eigenvector, max(|Rex_i| + |Imx_i|) = 1.

If H has been formed by reduction of a general matrix A to upper Hessenberg form, then eigenvectors of H may be transformed to eigenvectors of A by ormhr or unmhr.

Input Parameters

side

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.

eigsrc

Must be 'Q' or 'N'.

If eigsrc = 'Q', then the eigenvalues of H were found using hseqr; thus if H has any zero sub-diagonal elements (and so is block triangular), then the j-th eigenvalue can be assumed to be an eigenvalue of the block containing the j-th row/column. This property allows the routine to perform inverse iteration on just one diagonal block. If eigsrc = 'N', then no such assumption is made and the routine performs inverse iteration using the whole matrix.

initv

Must be 'N' or 'U'.

If initv = 'N', then no initial estimates for the selected eigenvectors are supplied.

If initv = 'U', then initial estimates for the selected eigenvectors are supplied in vl and/or vr.

select

Array, size at least max (1, n). Specifies which eigenvectors are to be computed.

For real flavors:

To obtain the real eigenvector corresponding to the real eigenvalue wr[j], set select[j] to 1

To select the complex eigenvector corresponding to the complex eigenvalue (wr[j - 1], wi[j - 1]) with complex conjugate (wr[j], wi[j]), set select[j - 1] and/or select[j] to 1; the eigenvector corresponding to the first eigenvalue in the pair is computed.

For complex flavors:

To select the eigenvector corresponding to the eigenvalue w[j], set select[j] to 1

n

The order of the matrix H (n≥ 0).

h, vl, vr

Arrays:

h (size max(1, ldh*n)) The n-by-n upper Hessenberg matrix H. If an NAN value is detected in h, the routine returns with info = -6.

vl(size max(1, ldvl*mm) for column major layout and max(1, ldvl*n) for row major layout)

If initv = 'V' and side = 'L' or 'B', then vl must contain starting vectors for inverse iteration for the left eigenvectors. Each starting vector must be stored in the same column or columns as will be used to store the corresponding eigenvector.

If initv = 'N', then vl need not be set.

The array vl is not referenced if side = 'R'.

vr(size max(1, ldvr*mm) for column major layout and max(1, ldvr*n) for row major layout)

If initv = 'V' and side = 'R' or 'B', then vr must contain starting vectors for inverse iteration for the right eigenvectors. Each starting vector must be stored in the same column or columns as will be used to store the corresponding eigenvector.

If initv = 'N', then vr need not be set.

The array vr is not referenced if side = 'L'.

ldh

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

w

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

Contains the eigenvalues of the matrix H.

If eigsrc = 'Q', the array must be exactly as returned by ?hseqr.

wr, wi

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

Contain the real and imaginary parts, respectively, of the eigenvalues of the matrix H. Complex conjugate pairs of values must be stored in consecutive elements of the arrays. If eigsrc = 'Q', the arrays must be exactly as returned by ?hseqr.

ldvl

The leading dimension of vl.

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

If side = 'R', ldvl≥ 1.

ldvr

The leading dimension of vr.

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

If side = 'L', ldvr≥1.

mm

The number of columns in vl and/or vr.

Must be at least m, the actual number of columns required (see Output Parameters below).

For real flavors, m is obtained by counting 1 for each selected real eigenvector and 2 for each selected complex eigenvector (see select).

For complex flavors, m is the number of selected eigenvectors (see select).

Constraint:

0 ≤mm≤n.

Output Parameters

select

Overwritten for real flavors only.

If a complex eigenvector was selected as specified above, then select[j - 1] is set to 1 and select[j] to 0

w

The real parts of some elements of w may be modified, as close eigenvalues are perturbed slightly in searching for independent eigenvectors.

wr

Some elements of wr may be modified, as close eigenvalues are perturbed slightly in searching for independent eigenvectors.

vl, vr

If side = 'L' or 'B', vl contains the computed left eigenvectors (as specified by select).

If side = 'R' or 'B', vr contains the computed right eigenvectors (as specified by 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

For real flavors: the number of columns of vl and/or vr required to store the selected eigenvectors.

For complex flavors: the number of selected eigenvectors.

ifaill, ifailr

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

ifaill[i - 1] = 0 if the ith column of vl converged;

ifaill[i - 1] = j > 0 if the eigenvector stored in the i-th column of vl (corresponding to the jth eigenvalue) failed to converge.

ifailr[i - 1] = 0 if the ith column of vr converged;

ifailr[i - 1] = j > 0 if the eigenvector stored in the i-th column of vr (corresponding to the jth eigenvalue) failed to converge.

For real flavors: if the ith and (i+1)th columns of vl contain a selected complex eigenvector, then ifaill[i - 1] and ifaill[i] are set to the same value. A similar rule holds for vr and ifailr.

The array ifaill is not referenced if side = 'R'. The array ifailr is not referenced if side = 'L'.

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 > 0, then i eigenvectors (as indicated by the parameters ifaill and/or ifailr above) failed to converge. The corresponding columns of vl and/or vr contain no useful information.

Application Notes

Each computed right eigenvector x i is the exact eigenvector of a nearby matrix A + E_i, such that ||E_i|| < O(ε)||A||. Hence the residual is small:

||Ax_i - λ_ix_i|| = O(ε)||A||.

However, eigenvectors corresponding to close or coincident eigenvalues may not accurately span the relevant subspaces.

Similar remarks apply to computed left eigenvectors.

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 C

?hsein

Syntax

Include Files

Description

Input Parameters

Output Parameters

Return Values

Application Notes