NAG CL Interface
f12jvc (feast_​poly_​gen_​solve)

Note: this function uses optional parameters to define choices in the problem specification. If you wish to use default settings for all of the optional parameters, then the option setting function f12jbc need not be called. If, however, you wish to reset some or all of the settings please refer to Section 11 in f12jbc for a detailed description of the specification of the optional parameters.
Settings help

CL Name Style:


1 Purpose

f12jvc is an iterative solver used to find some of the eigenvalues and the corresponding eigenvectors of a polynomial eigenvalue problem defined by complex nonsymmetric matrices. This is part of a suite of functions that also includes f12jac, f12jbc, f12jfc and f12jgc.

2 Specification

#include <nag.h>
void  f12jvc (void *handle, Integer *irevcm, Integer deg, Complex *ze, Integer n, Complex x[], Integer pdx, Complex y[], Integer pdy, Integer *k, Integer *m0, Integer *nconv, Complex d[], Complex z[], Integer pdz, double *eps, Integer *iter, double resid[], NagError *fail)
The function may be called by the names: f12jvc or nag_sparseig_feast_poly_gen_solve.

3 Description

The suite of functions is designed to calculate some of the eigenvalues, λ , and the corresponding eigenvectors, x , of a polynomial eigenvalue problem i=0 p λi Aix = 0 where the coefficient matrices Ai are sparse, complex and nonsymmetric. The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale, dense problems.
f12jvc is a reverse communication function, based on the FEAST eigensolver, described in Polizzi (2009), which finds eigenvalues using contour integration. Prior to calling f12jvc, one of the contour definition functions f12jfc or f12jgc must be used to define nodes and weights for a contour around a region in the complex plane within which eigenvalues will be sought. f12jfc or f12jgc uses this interval to define nodes and weights for the contour to be used by f12jvc.
The setup function f12jac and one of the contour definition functions f12jfc or f12jgc must be called before f12jvc. Between the calls to f12jac and f12jfc or f12jgc, options may be set by calls to the option setting function f12jbc.
f12jvc uses reverse communication, i.e., it returns repeatedly to the calling program with the argument irevcm (see Section 5) set to specified values which require the calling program to carry out one of the following tasks:
The number of contour points, the number of iterations, and other options can all be set using the option setting function f12jbc (see Section 11.1 in f12jbc for details on setting options and of the default settings). The search contour itself is defined by a call to f12jfc or f12jgc.

4 References

Gavin B, Międlar A and Polizzi E (2018) FEAST Eigensolver for Nonlinear Eigenvalue Problems J. Comput. Phys. 27 107
Polizzi E (2009) Density-Matrix-Based Algorithms for Solving Eigenvalue Problems Phys. Rev. B. 79 115112

5 Arguments

Note: this function uses reverse communication. Its use involves an initial entry, intermediate exits and re-entries, and a final exit, as indicated by the argument irevcm. Between intermediate exits and re-entries, all arguments other than x and y must remain unchanged.
1: handle void * Input
On entry: the handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by f12jac. It must not be changed between calls to the NAG FEAST suite.
2: irevcm Integer * Input/Output
On initial entry: irevcm=0, otherwise an error condition will be raised.
On intermediate re-entry: must be unchanged from its previous exit value. Changing irevcm to any other value between calls will result in an error.
On intermediate exit: has the following meanings.
irevcm=1
The calling program must compute a factorization of the matrix i=0 p zei Ai suitable for solving a linear system, for example using f11dnc which computes an incomplete LU factorization of a complex sparse matrix. All arguments to the routine must remain unchanged.
Note:  the factorization can be computed in single precision.
irevcm=2
The calling program must compute the solution to the linear system ( i=0 p zeiAi)w=y, overwriting y with the result w. The matrix i=0 p zei Ai has previously been factorized (when irevcm=1 was returned) and this factorization can be reused here.
Note:  the solve can be performed in single precision.
irevcm=3
Optionally, the calling program must compute a factorization of the matrix ( i=0 p zeiAi)H. This need only be done if it is not possible to use the factorization computed when irevcm=1 was returned to solve linear systems involving ( i=0 p zeiAi)H. If this factorization is to be computed, then the factorization from irevcm=1 must not be overwritten.
Note:  the factorization can be performed in single precision.
irevcm=4
The calling program must compute the solution to the linear system ( i=0 p zeiAi)Hw=y, overwriting y with the result w. If it is not possible to use the factorization of i=0 p zei Ai (computed when irevcm=1 was returned) then the factorization of ( i=0 p zeiAi)H (computed when irevcm=2 was returned) should be used here.
Note:  the factorization can be performed in single precision.
irevcm=5
The calling program must compute Akz, storing the result in x.
irevcm=6
The calling program must compute AkHz, storing the result in x.
On final exit: irevcm=0: f12jvc has completed its tasks. The value of fail determines whether the iteration has been successfully completed, or whether errors have been detected.
Constraint: on initial entry, irevcm=0; on re-entry irevcm must remain unchanged.
Note: the matrices x, y and z referred to in this section are all of size n×m0 and are stored in the arrays x, y and z, respectively.
Note: any values you return to f12jvc as part of the reverse communication procedure should not include floating-point NaN (Not a Number) or infinity values, since these are not handled by f12jvc. If your code inadvertently does return any NaNs or infinities, f12jvc is likely to produce unexpected results.
3: deg Integer Input
On entry: the degree, p, of the polynomial eigenvalue problem.
Constraint: deg>0.
4: ze Complex * Input/Output
On initial entry: need not be set.
On intermediate exit: contains the current point on the contour.
  • If irevcm=1, then this must be used by the calling program to form a factorization of the matrix i=0 p zei Ai .
  • If irevcm=3, then, optionally, this can be used to form a factorization of ( i=0 p zeiAi)H.
5: n Integer Input
On entry: the order of the matrices Ai that define the eigenvalue problem.
Constraint: n1.
6: x[dim] Complex Input/Output
Note: the dimension, dim, of the array x must be at least pdx×2×m0.
The (i,j)th element of the matrix X is stored in x[(j-1)×pdx+i-1].
On initial entry: need not be set.
On intermediate exit:
  • if irevcm=5, the calling program must compute Akz, storing the result in x prior to re-entry.
  • If irevcm=6, the calling program must compute AkHz, storing the result in x prior to re-entry.
Note: the matrices x and z are stored in the first m0 columns of the arrays x and z, respectively.
7: pdx Integer Input
On entry: the stride separating matrix row elements in the array x.
Constraint: pdxn.
8: y[dim] Complex Input/Output
Note: the dimension, dim, of the array y must be at least pdy×m0.
The (i,j)th element of the matrix Y is stored in y[(j-1)×pdy+i-1].
On initial entry: need not be set.
On intermediate exit:
  • if irevcm=2, the calling program must compute the solution to the linear system ( i=0 p zeiAi)w=y, overwriting y with the result w, prior to re-entry. The linear system has m0 right-hand sides.
  • If irevcm=4, the calling program must compute the solution to the linear system ( i=0 p zeiAi)Hw=y, overwriting y with the result w, prior to re-entry. The linear system has m0 right-hand sides.
9: pdy Integer Input
On entry: the stride separating matrix row elements in the array y.
Constraint: pdyn.
10: k Integer * Output
On intermediate exit:
  • if irevcm=5, denotes which of the coefficient matrices Ak needs to be used to form Akz.
  • If irevcm=6, denotes which of the coefficient matrices Ak needs to be used to form AkHz.
11: m0 Integer * Input/Output
On initial entry: the size of the search subspace used to find the eigenvalues. This should exceed the number of eigenvalues within the search contour. See Section 9 for further details.
On intermediate re-entry: m0 must remain unchanged.
On exit: if the initial search subspace was found by f12jvc to be too large, then a new smaller suitable choice is returned.
Constraint: 0<m0n.
12: nconv Integer * Output
On exit: the number of eigenvalues found within the search contour.
13: d[dim] Complex Input/Output
Note: the dimension, dim, of the array d must be at least m0.
On initial entry: if the option Subspace=Yes was set using the option setting function f12jbc, then d should contain an initial guess at the eigenvalues lying within the eigenvector search subspace (this subspace should be specified by z), otherwise d need not be set.
On final exit: the first nconv entries in d contain the eigenvalues.
Note: if the option Subspace=Yes was set using the option setting function f12jbc, then on final exit d contains an estimate of the eigenvalues after a single contour integral.
14: z[dim] Complex Input/Output
Note: the dimension, dim, of the array z must be at least pdz×2×m0.
The (i,j)th element of the matrix Z is stored in z[(j-1)×pdz+i-1].
On initial entry: if the option Subspace=Yes was set using the option setting function f12jbc, then z should contain an initial guess at the eigenvector search subspace, otherwise z need not be set.
Note: if the option Subspace=Yes was set but only right eigenvectors are to be computed, then only the first m0 columns of z need to be set. However, if the optional parameter Eigenvectors=Two-sided was set using f12jbc, so that both left and right eigenvectors are returned, then the first m0 columns of z should contain the initial guess for the right eigenvector search subspace and the remaining m0 columns should contain an initial guess for the left eigenvector search subspace.
On intermediate exit: must not be changed.
On final exit: the first nconv columns of z contain the right eigenvectors corresponding to the eigenvalues found within the contour. If the option Eigenvectors=Two-sided was set in the option setting function f12jbc, the columns m0+1:m0+nconv of z contain the left eigenvectors corresponding to the eigenvalues found within the contour.
Note: if the option Execution Mode=Subspace was set using the option setting function f12jbc, then on final exit columns 1:m0 of z contain the current search subspace after one contour integral.
15: pdz Integer Input
On entry: the stride separating matrix row elements in the array z.
Constraint: pdzn.
16: eps double * Input/Output
On initial entry: need not be set.
On exit: the relative error on the trace. At iteration k, eps is given by the expression |tracek-tracek-1|/(|Emid|+r), where tracek is the sum of the eigenvalues found at the kth iteration, Emid is the centre of mass of the contour and r is the radius of the circle, centred at Emid which just encloses the contour.
17: iter Integer * Input/Output
On initial entry: need not be set.
On exit: the number of subspace iterations performed.
18: resid[dim] double Input/Output
Note: the dimension, dim, of the array resid must be at least 2×m0.
On initial entry: need not be set.
On final exit: for i=1,,nconv, resid[i-1] contains the relative residual, in the 1-norm, of the ith eigenpair found, that is resid[i-1]= ( j=0 p λijAj)zi / (λpApzi×(|Emid|+r)) , where Emid is the centre of mass of the contour and r is the radius of the circle, centred at Emid which just encloses the contour.
If the optional parameter Eigenvectors=Two-sided was set in the option setting function f12jbc, the entries m0+1:m0+nconv of resid contain corresponding residuals for the left eigenvectors, resid[i-1]= ( j=0 p λijAj)Hzi / (λpApHzi×(|Emid|+r)) .
19: fail NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_EIGENVALUES
No eigenvalues were found within the search contour.
NE_HANDLE
Either one of the contour setting functions f12jfc or f12jgc has not been called prior to the first call of this function or the supplied handle has become corrupted.
NE_INT
On entry, deg=value.
Constraint: deg>0.
On entry, n=value.
Constraint: n1.
On initial entry, irevcm=value.
Constraint: irevcm=0.
On intermediate entry, irevcm=value.
Constraint: irevcm=1, 2, 3, 4, 5 or 6.
NE_INT_2
On entry, m0=value and n=value.
Constraint: 0<m0n.
On entry, pdx=value and n=value.
Constraint: pdxn.
On entry, pdy=value and n=value.
Constraint: pdyn.
On entry, pdz=value and n=value.
Constraint: pdzn.
NE_INTERNAL_EIGVAL_FAIL
An internal error occurred in the reduced eigenvalue solver. Please contact NAG.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
NE_NO_SOLUTION
The optional parameter Execution Mode=Estimate was set using f12jbc. nconv contains a stochastic estimate of the number of eigenvalues within the contour.
The optional parameter Execution Mode=Subspace was set using f12jbc. Columns 1:m0 of z contain the search subspace after one contour integral and d contains an estimate of the eigenvalues.
NE_TOO_MANY_ITER
The function did not converge after the maximum number of iterations. The results returned may still be useful, however they might be improved by increasing the maximum number of iterations using the option setting routine f12jbc, increasing the size of the eigenvector search subspace, m0, or experimenting with the choice of contour. Note that the returned eigenvalues and eigenvectors, together with the returned value of m0, can be used as the initial estimates for a new iteration of the solver.
NE_TOO_SMALL
The size of the eigenvector search subspace, m0, is too small.
NE_ZERO_VALUE
The option Subspace=Yes was set using the option setting function f12jbc but no nonzero elements were found in the supplied subspace.

7 Accuracy

A gauge on the accuracy of the computation can be obtained by looking at eps, the relative error on the trace, and the residuals, stored in resid.
Note: the factorizations and linear system solves required when irevcm=1, 2, 3 or 4 can be performed in single precision, without any loss of accuracy in the final eigenvalues and eigenvectors.

8 Parallelism and Performance

f12jvc is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
f12jvc makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

Ideally, when using f12jvc you should have an idea of the distribution of the eigenvalue spectrum to allow good choices of the search contour and m0 to be made. For best performance, m0 should exceed the number of eigenvalues in the search contour by a factor of approximately 1.5. Note that a polynomial eigenvalue problem of order n and degree p can have up to n×p eigenvalues. However m0 must not exceed n.
The complex allocatable memory required by f12jvc is approximately 2×m0×m0×deg×deg.

9.1 Additional Licensor

Parts of the code for f12jvc are distributed under the BSD software License. Please refer to Library Licensors for further details.

10 Example

This example solves the quadratic eigenproblem (λ2A2+λA1+A0)x=0, where
A0= ( -0.0+0.0i -7.5+0.0i -0.0+0.0i -0.0+0.0i -1.7+0.0i -0.0+0.0i -0.0+0.0i -0.0+0.0i -0.0+0.0i -0.0+0.0i -0.0+0.4i -0.2+0.0i -0.0+0.0i -1.6+0.0i -0.0+0.0i -0.0+0.0i ) ,  
A1= ( -0.0+1.0i -0.0+0.0i -0.0+1.2i -0.0+0.0i -0.0+0.0i -0.0+2.9i -0.0+0.0i -0.0-3.4i -0.0+0.0i -0.0+0.0i -0.0+0.1i -0.0+0.0i -0.0+0.0i -0.0+0.0i -0.0+0.0i -0.0+1.2i ) ,  
and
A2= ( -1.0+0.0i -0.0+0.0i -0.0+0.0i -0.0+0.0i -0.0+0.0i -1.7+0.0i -0.0+0.0i -0.0+0.0i -0.0+0.0i -0.0+0.0i -0.2+0.0i -0.0+0.0i -0.0+0.0i -0.0+0.0i -0.0+0.0i -5.8+0.0i ) .  
The matrices are stored in coordinate storage format and appropriate sparse linear algebra routines are used throughout. The contour within which eigenvalues are sought is a semicircle connecting the points -0.5+1.5i and -1.5-0.5i.

10.1 Program Text

Program Text (f12jvce.c)

10.2 Program Data

Program Data (f12jvce.d)

10.3 Program Results

Program Results (f12jvce.r)