naginterfaces.library.sparseig.feast_poly_symm_solve¶
- naginterfaces.library.sparseig.feast_poly_symm_solve(handle, irevcm, deg, ze, x, y, m0, d, z, eps, itera, resid, io_manager=None)[source]¶
feast_poly_symm_solve
is an iterative solver used to find some of the eigenvalues and the corresponding eigenvectors of a polynomial eigenvalue problem defined by complex symmetric matrices. This is part of a suite of functions that also includesfeast_init()
,feast_option()
,feast_gen_contour()
andfeast_custom_contour()
.For full information please refer to the NAG Library document for f12ju
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f12/f12juf.html
- Parameters
- handleHandle
The handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by
feast_init()
. It must not be changed between calls to the NAG FEAST suite.- irevcmint
On initial entry: , otherwise an error condition will be raised.
On intermediate entry: must be unchanged from its previous exit value. Changing to any other value between calls will result in an error.
Note: the matrices , and referred to in this section are all of size and are stored in the arrays , and , respectively.
- degint
The degree, , of the polynomial eigenvalue problem.
- zecomplex
On initial entry: need not be set.
- xcomplex, ndarray, shape , modified in place
On initial entry: need not be set.
On intermediate exit:
if , the calling program must compute , storing the result in prior to re-entry.
Note: the matrices , and referred to in this section are all of size and are stored in the arrays , and , respectively.
Note: the matrices and are stored in the first columns of the arrays and , respectively.
- ycomplex, ndarray, shape , modified in place
On initial entry: need not be set.
On intermediate exit:
if , the calling program must compute the solution to the linear system , overwriting with the result , prior to re-entry. The linear system has right-hand sides.
- m0int
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 Further Comments for further details.
On intermediate entry: must remain unchanged.
- dcomplex, ndarray, shape , modified in place
On initial entry: if the option was set using the option setting function
feast_option()
, then should contain an initial guess at the eigenvalues lying within the eigenvector search subspace (this subspace should be specified by ), otherwise need not be set.On final exit: the first entries in contain the eigenvalues.
Note: if the option was set using the option setting function
feast_option()
, then on final exit contains an estimate of the eigenvalues after a single contour integral.- zcomplex, ndarray, shape , modified in place
On initial entry: if the option was set using the option setting function
feast_option()
, then should contain an initial guess at the eigenvector search subspace, otherwise need not be set.On intermediate exit: must not be changed.
On final exit: the first columns of contain the eigenvectors corresponding to the eigenvalues found within the contour.
Note: if the option was set using the option setting function
feast_option()
, then on final exit columns of contain the current search subspace after one contour integral.- epsfloat
On initial entry: need not be set.
- iteraint
On initial entry: need not be set.
- residfloat, ndarray, shape , modified in place
On initial entry: need not be set.
On final exit: for , contains the relative residual, in the -norm, of the th eigenpair found, that is , where is the centre of mass of the contour and is the radius of the circle, centred at which just encloses the contour.
- io_managerFileObjManager, optional
Manager for I/O in this routine.
- Returns
- irevcmint
On intermediate exit: has the following meanings.
The calling program must compute a factorization of the matrix suitable for solving a linear system, for example using
sparse.complex_gen_precon_ilu
which computes an incomplete factorization of a complex sparse matrix. All arguments to the routine must remain unchanged.Note: the factorization can be computed in single precision.
The calling program must compute the solution to the linear system , overwriting with the result . The matrix has previously been factorized (when was returned) and this factorization can be reused here.
Note: the solve can be performed in single precision.
The calling program must compute , storing the result in .
On final exit: :
feast_poly_symm_solve
has completed its tasks. The value of determines whether the iteration has been successfully completed, or whether errors have been detected.Note: the matrices , and referred to in this section are all of size and are stored in the arrays , and , respectively.
- zecomplex
On intermediate exit: contains the current point on the contour.
If , then this must be used by the calling program to form a factorization of the matrix .
- kint
On intermediate exit:
if , denotes which of the coefficient matrices needs to be used to form .
- m0int
If the initial search subspace was found by
feast_poly_symm_solve
to be too large, then a new smaller suitable choice is returned.- nconvint
The number of eigenvalues found within the search contour.
- epsfloat
The relative error on the trace. At iteration , is given by the expression , where is the sum of the eigenvalues found at the th iteration, is the centre of mass of the contour and is the radius of the circle, centred at which just encloses the contour.
- iteraint
The number of subspace iterations performed.
- Raises
- NagValueError
- (errno )
Either the contour setting function
feast_symm_contour()
has not been called prior to the first call of this function or the supplied has become corrupted.- (errno )
An internal error occurred in the reduced eigenvalue solver. Please contact NAG.
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, and .
Constraint: .
- (errno )
On initial entry, .
Constraint: .
- (errno )
On intermediate entry, .
Constraint: , , , , or .
- (errno )
On entry, .
Constraint: .
- (errno )
The option was set using the option setting function
feast_option()
but no nonzero elements were found in the supplied subspace.
- Warns
- NagAlgorithmicWarning
- (errno )
No eigenvalues were found within the search contour.
- (errno )
The function did not converge after the maximum number of iterations.
- (errno )
The size of the eigenvector search subspace, , is too small.
- (errno )
The option was set using
feast_option()
. Columns of contain the search subspace after one contour integral and contains an estimate of the eigenvalues.- (errno )
The option was set using
feast_option()
. contains a stochastic estimate of the number of eigenvalues within the contour.
- Notes
The suite of functions is designed to calculate some of the eigenvalues, , and the corresponding eigenvectors, , of a polynomial eigenvalue problem where the coefficient matrices are sparse, complex and symmetric. The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale, dense problems.
feast_poly_symm_solve
is a reverse communication function, based on the FEAST eigensolver, described in Polizzi (2009), which finds eigenvalues using contour integration. Prior to callingfeast_poly_symm_solve
, one of the contour definition functionsfeast_gen_contour()
orfeast_custom_contour()
must be used to define nodes and weights for a contour around a region in the complex plane within which eigenvalues will be sought.feast_gen_contour()
orfeast_custom_contour()
uses this interval to define nodes and weights for the contour to be used byfeast_poly_symm_solve
.The setup function
feast_init()
and one of the contour definition functionsfeast_gen_contour()
orfeast_custom_contour()
must be called beforefeast_poly_symm_solve
. Between the calls tofeast_init()
andfeast_gen_contour()
orfeast_custom_contour()
, options may be set by calls to the option setting functionfeast_option()
.feast_poly_symm_solve
uses reverse communication, i.e., it returns repeatedly to the calling program with the argument (see Parameters) set to specified values which require the calling program to carry out one of the following tasks:compute a factorization of the matrix , where is a point on the search contour;
solve a linear system involving using the factorizations above;
compute the matrix product , for a given value of ;
notify the completion of the computation.
The number of contour points, the number of iterations, and other options can all be set using the option setting function
feast_option()
(see Other Parameters for feast_option for details on setting options and of the default settings). The search contour itself is defined by a call tofeast_gen_contour()
orfeast_custom_contour()
.
- 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