naginterfaces.library.sparseig.feast_​custom_​contour

naginterfaces.library.sparseig.feast_custom_contour(handle, nedge, tedge, zedge)

feast_custom_contour is a setup function in a suite of functions consisting of feast_init(), feast_option(), feast_custom_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_custom_contour. In addition calls to feast_option() can be made to supply individual options to feast_custom_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 f12jg

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

nedgeint, array-like, shape $\left(\text{ccn}\right)$

$nedge[i-1]$ specifies how many integration nodes and weights feast_custom_contour should use for the $i$th piece of the contour.

tedgeint, array-like, shape $\left(\text{ccn}\right)$

$tedge[i-1]$ specifies what shape the $i$th piece of the contour should be.

$tedge[i-1]=0$

The $i$th piece of the contour is straight.

$tedge[i-1]>0$

The $i$th piece of the contour is a (convex) half-ellipse, with $tedge[i-1]/100=a/b$, where $a$ is the primary radius from the endpoints of the piece, and $b$ is the radius perpendicular to this. Thus, if $tedge[i-1]=100$, then the $i$th piece of the contour is a semicircle.

zedgecomplex, array-like, shape $\left(\text{ccn}\right)$

$zedge$ specifies the endpoints of the contour piece.

The $i$th piece has endpoints at $zedge[i-1]$ and $zedge[i+1-1]$, for $i=1,\dots ,\text{ccn}-1$.

The last piece has endpoints at $zedge[\text{ccn}-1]$ and $zedge\left[0\right]$.

Note: the contour should be described in a clockwise direction..

Raises

NagValueError

(errno $1$)

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

(errno $2$)

On entry, $\text{ccn}=⟨value⟩$.

Constraint: $\text{ccn}>1$.

(errno $3$)

On entry, one or more elements of $nedge$ were less than or equal to zero.

(errno $4$)

On entry, one or more elements of $tedge$ were negative.

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_custom_contour is used to specify a closed contour in the complex plane within which eigenvalues will be sought. The contour can be made up of a combination of line segments and half ellipses. feast_custom_contour uses this information to create a polygonal representation of the contour and to then define the integration nodes and weights 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().

The arrays $zedge$, $tedge$ and $nedge$ are used to define the geometry of your contour. Each array is of size $\text{ccn}$, where $\text{ccn}$ is the number of pieces that make up the contour. The entries in $zedge$ specify the endpoints in the complex plane of each piece of the contour. The entries in $tedge$ specify whether each piece of the contour is a line segment or a half ellipse. Finally, entries in $nedge$ specify the number of integration points to use for each piece of the contour. See the individual argument descriptions in Parameters for further details.

Prior to calling feast_custom_contour, the option setting function feast_option() can be called to specify various options for the solution of the eigenproblem. For details of the 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

See also

naginterfaces.library.examples.sparseig.feast_poly_gen_solve_ex.main()