# ?hsein

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

## Syntax

FORTRAN 77:

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

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

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

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

Fortran 95:

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

## Description

This 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 `yH*H = λ*yH` (or `HH*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|xi| = 1`, and for a complex eigenvector, `max(|Rexi| + |Imxi|) = 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

job

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

  If `job = 'R'`, then only right eigenvectors are computed.

  If `job = 'L'`, then only left eigenvectors are computed.

  If `job = '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, DIMENSION 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,

  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.

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

  (ldvl,*)

  If `initv = 'V'` and `job = '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 `job = 'L'` or 'B' and at least 1 if `job = 'R'`.

  The array vl is not referenced if `job = 'R'`.

  vr(ldvr,*)

  If `initv = 'V'` and `job = '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 `job = 'R'` or 'B' and at least 1 if `job = 'L'`.

  The array vr is not referenced if `job = 'L'`.

  work(*) is a workspace array.

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

ldh

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

w

  COMPLEX for chsein

  DOUBLE COMPLEX for zhsein.

  Array, DIMENSION 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, DIMENSION 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 first dimension of vl.

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

  If `job = 'R'`, `ldvl ≥ 1`.

ldvr

  INTEGER. The first dimension of vr.

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

  If `job = '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, DIMENSION 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 `job = 'L'` or 'B', vl contains the computed left eigenvectors (as specified by select).

  If `job = 'R'` or 'B', vr contains the computed right eigenvectors (as specified by select).

  The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues.

  For real flavors: a real eigenvector corresponding to a selected real eigenvalue occupies one column; a complex eigenvector corresponding to a selected complex eigenvalue occupies two columns: the first column holds the real part and the second column holds the imaginary part.

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, DIMENSION 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 `job = 'R'`. The array ifailr is not referenced if `job = '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.

## Fortran 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 Fortran 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'.

job

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

  `job = 'B'`, if both vl and vr are present,

  `job = 'L'`, if vl is present and vr omitted,

  `job = '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 + Ei`, such that `||Ei|| < O(ε)||A||`. Hence the residual is small:

`||Axi - λixi|| = 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