?hsein

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

Download PDF

ID 766686

Date 12/16/2022

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

call shsein(side, eigsrc, initv, select, n, h, ldh, wr, wi, vl, ldvl, vr, ldvr, mm, m, work, ifaill, ifailr, info)

call dhsein(side, eigsrc, initv, select, n, h, ldh, wr, wi, vl, ldvl, vr, ldvr, mm, m, work, ifaill, ifailr, info)

call chsein(side, eigsrc, initv, select, n, h, ldh, w, vl, ldvl, vr, ldvr, mm, m, work, rwork, ifaill, ifailr, info)

call zhsein(side, eigsrc, initv, select, n, h, ldh, w, vl, ldvl, vr, ldvr, mm, m, work, rwork, ifaill, ifailr, info)

call hsein(h, wr, wi, select [, vl] [,vr] [,ifaill] [,ifailr] [,initv] [,eigsrc] [,m] [,info])

call hsein(h, w, select [,vl] [,vr] [,ifaill] [,ifailr] [,initv] [,eigsrc] [,m] [,info])

Include Files

mkl.fi, lapack.f90

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

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

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

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

LOGICAL.

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

To select the complex eigenvector corresponding to the complex eigenvalue (wr(j), wi(j)) with complex conjugate (wr(j+1), wi(j+1)), set select(j) and/or select(j+1) to .TRUE.; 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 .TRUE.

n

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

h, vl, vr, work

REAL for shsein

DOUBLE PRECISION for dhsein

COMPLEX for chsein

DOUBLE COMPLEX for zhsein.

Arrays:

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

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

vl(ldvl,*)

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

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

ldh

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

w

COMPLEX for chsein

DOUBLE COMPLEX for zhsein.

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

REAL for shsein

DOUBLE PRECISION for dhsein

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

INTEGER. The leading dimension of vl.

If side = 'L' or 'B', ldvl≥ max(1,n) .

If side = 'R', ldvl≥ 1.

ldvr

INTEGER. The leading dimension of vr.

If side = 'R' or 'B', ldvr≥ max(1,n) .

If side = 'L', ldvr≥1.

mm

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

rwork

REAL for chsein

DOUBLE PRECISION for zhsein.

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

Output Parameters

select

Overwritten for real flavors only.

If a complex eigenvector was selected as specified above, then select(j) is set to .TRUE. and select(j + 1) to .FALSE.

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

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

INTEGER.

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

ifaill(i) = 0 if the ith column of vl converged;

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

ifailr(i) = 0 if the ith column of vr converged;

ifailr(i) = 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) and ifaill(i + 1) 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'.

info

INTEGER.

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.

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

h

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

wr

Holds the vector of length n. Used in real flavors only.

wi

Holds the vector of length n. Used in real flavors only.

w

Holds the vector of length n. Used in complex flavors only.

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

ifaill

Holds the vector of length (mm). Note that there will be an error condition if ifaill is present and vl is omitted.

ifailr

Holds the vector of length (mm). Note that there will be an error condition if ifailr is present and vr is omitted.

initv

Must be 'N' or 'U'. The default value is 'N'.

eigsrc

Must be 'N' or 'Q'. The default value is 'N'.

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.

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 Fortran

?hsein