Computes selected eigenvectors of an upper Hessenberg matrix that correspond to specified eigenvalues.
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])
C:
lapack_int LAPACKE_shsein( int matrix_order, char job, 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_order, char job, 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_order, char job, 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_order, char job, 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 );
The FORTRAN 77 interfaces are specified in the mkl_lapack.fi and mkl_lapack.h include files, the Fortran 95 interfaces are specified in the lapack.f90 include file, and the C interfaces are specified in the mkl_lapacke.h include file.
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 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.
The data types are given for the Fortran interface. A <datatype> placeholder, if present, is used for the C interface data types in the C interface section above. See C Interface Conventions for the C interface principal conventions and type definitions.
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.
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.
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.
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.
INTEGER. The order of the matrix H (n ≥ 0).
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.
INTEGER. The leading dimension of h; at least max(1, n).
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.
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.
INTEGER. The leading dimension of vl.
If job = 'L' or 'B', ldvl ≥ max(1,n).
If job = 'R', ldvl ≥ 1.
INTEGER. The leading dimension of vr.
If job = 'R' or 'B', ldvr ≥ max(1,n).
If job = 'L', ldvr ≥1.
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.
REAL for chsein
DOUBLE PRECISION for zhsein.
Array, DIMENSION at least max (1, n).
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.
The real parts of some elements of w may be modified, as close eigenvalues are perturbed slightly in searching for independent eigenvectors.
Some elements of wr may be modified, as close eigenvalues are perturbed slightly in searching for independent eigenvectors.
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.
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.
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'.
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.
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:
Holds the matrix H of size (n,n).
Holds the vector of length n. Used in real flavors only.
Holds the vector of length n. Used in real flavors only.
Holds the vector of length n. Used in complex flavors only.
Holds the vector of length n.
Holds the matrix VL of size (n,mm).
Holds the matrix VR of size (n,mm).
Holds the vector of length (mm). Note that there will be an error condition if ifaill is present and vl is omitted.
Holds the vector of length (mm). Note that there will be an error condition if ifailr is present and vr is omitted.
Must be 'N' or 'U'. The default value is 'N'.
Must be 'N' or 'Q'. The default value is 'N'.
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.
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.
Copyright © 1994 - 2011, Intel Corporation. All rights reserved.