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_scsrgv/?feast_hcsrgv

Extended Eigensolver interface for generalized eigenvalue problem with sparse matrices.

Syntax

void sfeast_scsrgv (const char * uplo, const MKL_INT * n, const float * a, const MKL_INT * ia, const MKL_INT * ja, const float * b, const MKL_INT * ib, const MKL_INT * jb, MKL_INT * fpm, float * epsout, MKL_INT * loop, const float * emin, const float * emax, MKL_INT * m0, float * e, float * x, MKL_INT * m, float * res, MKL_INT * info);

void dfeast_scsrgv (const char * uplo, const MKL_INT * n, const double * a, const MKL_INT * ia, const MKL_INT * ja, const double * b, const MKL_INT * ib, const MKL_INT * jb, MKL_INT * fpm, double * epsout, MKL_INT * loop, const double * emin, const double * emax, MKL_INT * m0, double * e, double * x, MKL_INT * m, double * res, MKL_INT * info);

void cfeast_hcsrgv (const char * uplo, const MKL_INT * n, const MKL_Complex8 * a, const MKL_INT * ia, const MKL_INT * ja, const MKL_Complex8 * b, const MKL_INT * ib, const MKL_INT * jb, MKL_INT * fpm, float * epsout, MKL_INT * loop, const float * emin, const float * emax, MKL_INT * m0, float * e, MKL_Complex8 * x, MKL_INT * m, float * res, MKL_INT * info);

void zfeast_hcsrgv (const char * uplo, const MKL_INT * n, const MKL_Complex16 * a, const MKL_INT * ia, const MKL_INT * ja, const MKL_Complex16 * b, const MKL_INT * ib, const MKL_INT * jb, MKL_INT * fpm, double * epsout, MKL_INT * loop, const double * emin, const double * emax, MKL_INT * m0, double * e, MKL_Complex16 * x, MKL_INT * m, double * res, MKL_INT * info);

Include Files

  • mkl.h

Description

The routines compute all the eigenvalues and eigenvectors for generalized eigenvalue problems, Ax = λBx, within a given search interval.

NOTE:

Both matrices A and B must use the same family of storage format. The position of the non-zero elements can be different (CSR coordinates ib and jb can be different from ia and ja).

Input Parameters

uplo

Must be 'U' or 'L' or 'F' .

If UPLO = 'U', a and b store the upper triangular parts of A and B respectively.

If UPLO = 'L', a and b store the lower triangular parts of A and B respectively.

If UPLO= 'F', a and b store the full matrices A and B respectively.

n

Sets the size of the problem. n > 0.

a

Array containing the nonzero elements of either the full matrix A or the upper or lower triangular part of the matrix A, as specified by uplo.

ia

Array of length n + 1, containing indices of elements in the array a , such that ia[i - 1] is the index in the array a of the first non-zero element from the row i . The value of the last element ia[n] is equal to the number of non-zeros plus one.

ja

Array containing the column indices for each non-zero element of the matrix A being represented in the array a . Its length is equal to the length of the array a.

b

Array of dimension ldb by *, contains the nonzero elements of either the full matrix B or the upper or lower triangular part of the matrix B, as specified by uplo.

ib

Array of length n + 1, containing indices of elements in the array b , such that ib[i - 1] is the index in the array b of the first non-zero element from the row i . The value of the last element ib[n] is equal to the number of non-zeros plus one.

jb

Array containing the column indices for each non-zero element of the matrix B being represented in the array b . Its length is equal to the length of the array b.

fpm

Array, dimension 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 dimension 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.

x

On entry, if fpm[4]=1, the array x of size n by m contains a basis of guess subspace where n is the order of the input matrix.

Output Parameters

fpm

On output, the last 64 values correspond to Intel® oneAPI Math Kernel Library (oneMKL) PARDISOiparm[0] to iparm[63] (regardless of the value of fpm[63] on input).

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.

e

Array of length m0. On output, the first m entries of e are eigenvalues found in the interval.

x

On output, the first m columns of x contain the orthonormal eigenvectors corresponding to the computed eigenvalues e, with the i-th column of x holding the eigenvector associated with e[i].

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:

for i=1, 2, …, m, 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.