Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 7/13/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of 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 dfeast_srci (MKL_INT* ijob, const MKL_INT* n, MKL_Complex16* ze, double* work, MKL_Complex16* workc, double* aq, double* sq, MKL_INT* fpm, double* epsout, MKL_INT* loop, const double* emin, const double* emax, MKL_INT* m0, double* lambda, double* q, MKL_INT* m, double* 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; eminemax.

NOTE:
Users are advised to avoid situations in which eigenvalues nearly coincide with the interval endpoints. This may lead to unpredictable selection or omission of such eigenvalues. Users should instead specify a slightly larger interval than needed and, if required, pick valid eigenvalues and their corresponding eigenvectors for subsequent use.
m0

On entry, specifies the initial guess for subspace size to be used, 0 < m0n. Set m0m 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 Ze*B - A at a given contour point Ze and return the control to the ?feast_srci/?feast_hrci routine where Ze 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 (Ze*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 (Ze*B - A)H at a given contour point Ze and return the control to the ?feast_srci/?feast_hrci routine where Ze is a complex number meaning contour point and its value is defined internally in ?feast_srci/?feast_hrci.

    The symbol XH means transpose conjugate of matrix X.

  • ijob = 21 - solve the complex linear system(Ze*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 XH mean transpose conjugate of matrix X.

  • ijob = 30 - multiply matrix A by Qj..Qi, 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 Qj..Qi, 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: |tracei - tracei-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 ≤ mm0.

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.