naginterfaces.library.sparseig.feast_​gen_​contour

naginterfaces.library.sparseig.feast_gen_contour(handle, emid, r)

feast_gen_contour is a setup function in a suite of functions consisting of feast_init(), feast_option(), feast_gen_contour, feast_real_gen_solve(), feast_complex_symm_solve(), feast_complex_gen_solve(), feast_poly_symm_solve() and feast_poly_gen_solve(). It is used to find some of the eigenvalues, and the corresponding eigenvectors, of a standard, generalized or polynomial eigenvalue problem. The initialization function feast_init() must have been called prior to calling feast_gen_contour. In addition calls to feast_option() can be made to supply individual options to feast_gen_contour.

The suite of functions is suitable for the solution of large sparse eigenproblems where only a few eigenvalues from a selected range of the spectrum are required.

For full information please refer to the NAG Library document for f12jf

https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f12/f12jff.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.

emidcomplex

The centre of the ellipse.

rfloat

The radius of the horizontal axis of the ellipse (that is, the axis that would be horizontal if the rotation angle of the ellipse was set to zero).

Raises

NagValueError

(errno $1$)

$handle$ has not been initialized properly or is corrupted.

(errno $2$)

An invalid number of integration points was specified. For Gauss integration, the values permitted are $2$–$40$ (even values only), $48$, $64$, $80$, $96$, $112$.

(errno $3$)

The option ‘Integration Type’ was set to ‘Zol’. For non-Hermitian eigenvalue problems the allowed values are ‘Gauss’ or ‘Trap’.

(errno $4$)

On entry, $r=⟨value⟩$.

Constraint: $r>0.0$.

Notes

The suite of functions is designed to calculate some of the eigenvalues, $\lambda$, and the corresponding eigenvectors, $x$, of a standard eigenvalue problem $Ax=\lambda x$, a generalized eigenvalue problem $Ax=\lambda Bx$, or a polynomial eigenvalue problem ${\sum }_i{\lambda }^i{A}_{i}x=0$, where the coefficient matrices are large and sparse. The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense problems.

feast_gen_contour is used to specify a circle or ellipse in the complex plane within which eigenvalues will be sought. By default, a circle centred at $\text{emid}$ with a radius of $r$ is created. Optionally, feast_option() can be called prior to calling feast_gen_contour, using the options ‘Ellipse Contour Ratio’, ‘Ellipse Rotation Angle’ to change the eccentricity of the ellipse and the inclination angle of its axis. feast_gen_contour uses these details to define nodes and weights for the elliptical contour, to be used by the solvers feast_real_gen_solve(), feast_complex_symm_solve(), feast_complex_gen_solve(), feast_poly_symm_solve() or feast_poly_gen_solve().

For details of the other options available and how to set them see Other Parameters for feast_option.

References

Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112