Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

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

?feast_srci/?feast_hrci

Extended Eigensolver RCI interface.

Syntax

void sfeast_srci
(
MKL_INT*
ijob
,
const MKL_INT*
n
,
MKL_Complex8*
ze
,
float*
work
,
MKL_Complex8*
workc
,
float*
aq
,
float*
sq
,
MKL_INT*
fpm
,
float*
epsout
,
MKL_INT*
loop
,
const float*
emin
,
const float*
emax
,
MKL_INT*
m0
,
float*
lambda
,
float*
q
,
MKL_INT*
m
,
float*
res
,
MKL_INT*
info
)
;
void cfeast_hrci
(
MKL_INT*
ijob
,
const MKL_INT*
n
,
MKL_Complex8*
ze
,
MKL_Complex8*
work
,
MKL_Complex8*
workc
,
MKL_Complex8*
aq
,
MKL_Complex8*
sq
,
MKL_INT*
fpm
,
float*
epsout
,
MKL_INT*
loop
,
const float*
emin
,
const float*
emax
,
MKL_INT*
m0
,
float*
lambda
,
MKL_Complex8*
q
,
MKL_INT*
m
,
float*
res
,
MKL_INT*
info
)
;
void zfeast_hrci
(
MKL_INT*
ijob
,
const MKL_INT*
n
,
MKL_Complex16*
ze
,
MKL_Complex16*
work
,
MKL_Complex16*
workc
,
MKL_Complex16*
aq
,
MKL_Complex16*
sq
,
MKL_INT*
fpm
,
double*
epsout
,
MKL_INT*
loop
,
const double*
emin
,
const double*
emax
,
MKL_INT*
m0
,
double*
lambda
,
MKL_Complex16*
q
,
MKL_INT*
m
,
double*
res
,
MKL_INT*
info
)
;
Include Files
  • mkl.h
Description
Compute eigenvalues as described in Extended Eigensolver RCI Interface Description.
Input Parameters
ijob
Job indicator variable. On entry, a call to
?feast_srci
/
?feast_hrci
 with
ijob
=-1 initializes the eigensolver.
n
Sets the size of the problem.
n
 > 0.
work
Workspace array of size
n
 by
m0
.
workc
Workspace array of size
n
 by
m0
.
aq
,
sq
Workspace arrays of size
m0
 by
m0
.
fpm
Array, size of 128. This array is used to pass various parameters to Extended Eigensolver routines. See Extended Eigensolver Input Parameters for a complete description of the parameters and their default values.
emin
,
emax
The lower and upper bounds of the interval to be searched for eigenvalues;
emin
 ≤
emax.
m0
On entry, specifies the initial guess for subspace size to be used,
0 <
m0
≤
n
. Set
m0
 ≥
m
 where
m
 is the total number of eigenvalues located in the interval [
emin
,
emax
]. If the initial guess is wrong, Extended Eigensolver routines return
info
=3.
q
On entry, if
fpm
[4]
=1, the array
q
 of size
n
 by
m
 contains a basis of guess subspace where
n
 is the order of the input matrix.
Output Parameters
ijob
On exit, the parameter carries the status flag that indicates the condition of the return. The status information is divided into three categories:
  1. A zero value indicates successful completion of the task.
  2. A positive value indicates that the solver requires a matrix-vector multiplication or solving a specific system with a complex coefficient.
  3. A negative value indicates successful initiation.
A non-zero value of
ijob
 specifically means the following:
  • ijob
     = 10
     - factorize the complex matrix
    Z
    e
    *
    B
     -
    A
     at a given contour point
    Z
    e
     and return the control to the
    ?feast_srci
    /
    ?feast_hrci
     routine where
    Z
    e
     is a complex number meaning contour point and its value is defined internally in
    ?feast_srci
    /
    ?feast_hrci
    .
  • ijob
     =11
     - solve the complex linear system
    (
    Z
    e
    *
    B
     -
    A
    )*
    y
     =
    workc
    , put the solution in
    workc
     and return the control to the
    ?feast_srci
    /
    ?feast_hrci
     routine.
  • ijob
     =20
     - factorize the complex matrix (
    Z
    e
    *
    B
     -
    A
    )
    H
     at a given contour point
    Z
    e
     and return the control to the
    ?feast_srci
    /
    ?feast_hrci
     routine where
    Z
    e
     is a complex number meaning contour point and its value is defined internally in
    ?feast_srci
    /
    ?feast_hrci
    .
    The symbol
    X
    H
     means transpose conjugate of matrix
    X
    .
  • ijob
     = 21
     - solve the complex linear system
    (
    Z
    e
    *
    B
     -
    A
    )
    H
    *
    y
     =
    workc
    , put the solution in
    workc
     and return the control to the
    ?feast_srci
    /
    ?feast_hrci
     routine. The case
    ijob
    =20 becomes obsolete if the solve can be performed using the factorization computed for
    ijob
    =10.
    The symbol
    X
    H
     mean transpose conjugate of matrix
    X
    .
  • ijob
     = 30
     - multiply matrix
    A
     by
    Q
    j
    ..
    Q
    i
    , put the result in
    work
    +
    N
    *(
    i
     - 1)
    , and return the control to the
    ?feast_srci
    /
    ?feast_hrci
     routine.
    i
     is
    fpm
    [24]
    , and
    j
     is
    fpm
    [23]
     +
    fpm
    [24]
     - 1.
  • ijob
     = 40
     - multiply matrix
    B
     by
    Q
    j
    ..
    Q
    i
    , put the result in
    work
    +
    N
    *(
    i
     - 1)
     and return the control to the
    ?feast_srci
    /
    ?feast_hrci
     routine. If a standard eigenvalue problem is solved, just return
    work
     =
    q
    .
    i
     is
    fpm
    [24]
    , and
    j
     is
    fpm
    [23]
     +
    fpm
    [24]
     - 1.
  • ijob
     = -2
     - rerun the
    ?feast_srci
    /
    ?feast_hrci
     task with the same parameters.
ze
Defines the coordinate along the complex contour. All values of
ze
 are generated by
?feast_srci
/
?feast_hrci
 internally.
fpm
On output, contains coordinates of columns of work array needed for iterative refinement. (See Extended Eigensolver RCI Interface Description.)
epsout
On output, contains the relative error on the trace: |
trace
i
 -
trace
i-1
| /max(|
emin
|, |
emax
|)
loop
On output, contains the number of refinement loop executed. Ignored on input.
lambda
Array of length
m0
. On output, the first
m
 entries of
lambda
 are eigenvalues found in the interval.
q
On output,
q
 contains all eigenvectors corresponding to
lambda
.
m
The total number of eigenvalues found in the interval [
emin
,
emax
]: 0 ≤
m
 ≤
m0
.
res
Array of length
m0
. On exit, the first
m
 components contain the relative residual vector:
  • generalized eigenvalue problem:
  • standard eigenvalue problem:
for
i
=
0, 1, …,
m
 - 1
, and where
m
 is the total number of eigenvalues found in the search interval.
info
If
info
=0, the execution is successful. If
info
 ≠ 0, see Output Eigensolver info Details.

Product and Performance Information

1

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