Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 2021.1
  • 12/04/2020
  • Public Content
Contents

?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(|Re
x
i
| + |Im
x
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
.
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
 -
λ
i
x
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.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.