naginterfaces.library.sparseig.feast_​option

naginterfaces.library.sparseig.feast_option(handle, optstr, io_manager=None)

feast_option is part of NAG FEAST suite of functions and may be used to supply individual options to either the contour setting functions or the reverse communication solvers.

Note: this function uses optional algorithmic parameters, see also: feast_symm_contour(), feast_gen_contour(), feast_custom_contour(), feast_real_symm_solve(), feast_real_gen_solve(), feast_complex_herm_solve(), feast_complex_symm_solve(), feast_complex_gen_solve(), feast_poly_symm_solve(), feast_poly_gen_solve(), feast_init().

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

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

optstrstr

A single valid option string (as described in Notes and Other Parameters).

io_managerFileObjManager, optional

Manager for I/O in this routine.

Other Parameters

‘Advisory’int

Default $=\text{advisory message unit number}$

The destination for advisory messages.

‘Contour Points Hermitian’int

Default $=8$

For real symmetric (feast_real_symm_solve()) or Hermitian (feast_complex_herm_solve()) eigenproblems, this is the number of points used on the half-contour which defines the contour integral. If the option ‘Integration Type’ is set to ‘Gauss’ or ‘Zol’, the values permitted are $1$–$20$, $24$, $32$, $40$, $48$, $56$. If the option ‘Integration Type’ is set to ‘Trap’, then all values greater than or equal to $1$ are permitted.

‘Contour Points Non-Hermitian’int

Default $=8$

For general real (feast_real_gen_solve()), symmetric complex (feast_complex_symm_solve(), feast_poly_symm_solve()) or general complex (feast_complex_gen_solve(), feast_poly_gen_solve()) eigenproblems, this is the number of integration points used on the circular or elliptical contour within which eigenvalues are sought. If the option ‘Integration Type’ is set to ‘Gauss’, the values permitted are $2$–$40$ (even values only), $48$, $64$, $80$, $96$, $112$. If the option ‘Integration Type’ is set to ‘Trap’, then all values greater than or equal to $2$ are permitted. Note this option is only relevant if the contour definition functions feast_symm_contour() or feast_gen_contour() are used. If a custom contour is required (using the contour setting routine feast_custom_contour()) then this option is not relevant.

‘Convergence Criteria’str

Default $=\text{'Residual'}$

These are the convergence criteria used to test for convergence of eigenpairs in the search region.

$\text{‘Convergence Criteria'}=\text{'Trace'}$

The relative error of the trace of the eigenproblem in the search subspace is tested against $\delta$.

$\text{‘Convergence Criteria'}=\text{'Residual'}$

The relative maximum residual over all eigenpairs found is tested against $\delta$.

Note: the value of $\delta$ is controlled using the option ‘Tolerance’.

‘Defaults’valueless

This special keyword may be used to reset all options to their default values.

‘Ellipse Contour Ratio’int

Default $=100$

The ratio, as a percentage, of the length of the vertical axis to the length of the horizontal axis if an elliptical contour is to be used in the contour integral. This option should be set prior to a call to either of the contour definition functions feast_symm_contour() or feast_gen_contour().

Note: For a Hermitian eigenvalue problem, if the option ‘Integration Type’ is set to ‘Zol’ then a circular contour is used and this option is not referenced.

‘Ellipse Rotation Angle’int

Default $=0$

The rotation angle in degrees from the horizontal (between $-180$ and $180$) of the major axis if an elliptical contour is to be used in the contour integral. This option should be set prior to calls to the contour definition function feast_gen_contour() and the reverse communication solvers feast_real_gen_solve(), feast_complex_symm_solve(), feast_complex_gen_solve(), feast_poly_symm_solve() and feast_poly_gen_solve() (which deal with problems that are neither real symmetric nor complex Hermitian).

‘Execution Mode’str

Default $=\text{'Normal'}$

The execution mode used by the reverse communication solvers.

$\text{‘Execution Mode'}=\text{'Normal'}$

Normal execution.

$\text{‘Execution Mode'}=\text{'Subspace'}$

Return the search subspace and an estimate of the eigenvalues after one contour integral.

$\text{‘Execution Mode'}=\text{'Estimate'}$

Return an estimate of the number of eigenvalues inside the search contour. Note that this option is not available for polynomial eigenvalue problems (feast_poly_symm_solve() and feast_poly_gen_solve()).

‘Integration Type’str

Default $=\text{'Gauss'}$

The integration type. The allowed values are ‘Gauss’, ‘Trap’ (Trapezoidal) or ‘Zol’ (Zolotarev). Note that Zolotarev can only be used for real symmetric or complex Hermitian eigenproblems. This option should be set prior to a call to either of the contour definition functions feast_symm_contour() or feast_gen_contour(). If a custom contour is required (using the contour setting routine feast_custom_contour()) then this option is not relevant.

‘Max Iter’int

Default $=20$

The maximum number of iterations used in the reverse communication solvers. If this is set to a negative value then no maximum will be used.

‘Nolist’valueless

Default

Option ‘List’ enables printing of each option specification as it is supplied. ‘Nolist’ suppresses this printing.

‘List’valueless

Option ‘List’ enables printing of each option specification as it is supplied. ‘Nolist’ suppresses this printing.

‘Print Level’int

Default $=0$

This controls the amount of printing produced by the contour definition routines and the reverse communication solvers.

$\text{‘Print Level'}=\text{'0'}$

No output.

$\text{‘Print Level'}=\text{'1'}$

Print runtime comments to the advisory channel.

‘Tolerance’float

Default $=x-3$, where $x$ is the value returned by machine.decimal_digits

The stopping criterion, $\delta$, used to determine convergence of the eigensolver. If a value of $k$ is supplied then $\delta ={10}^{-k}$ is used.

‘Eigenvectors’str

Default $=\text{'Two-sided'}$

Determines whether both left and right eigenvectors are computed or whether just right eigenvectors are computed.

Note: this option only applies to the solvers feast_real_gen_solve(), feast_complex_gen_solve() and feast_poly_gen_solve(), which deal with non-symmetric eigenvalue problems. For the symmetric/Hermitian solvers (feast_real_symm_solve(), feast_complex_herm_solve(), feast_complex_symm_solve() and feast_poly_symm_solve()) the left eigenvectors can be obtained from the right eigenvectors by complex conjugation.

$\text{‘Eigenvectors'}=\text{'Two-sided'}$

Both left and right eigenvectors are computed.

$\text{‘Eigenvectors'}=\text{'One-sided'}$

Only right eigenvectors are computed.

‘Subspace’str

Default $=\text{'No'}$

This option determines whether or not you will supply an initial guess for the eigenvector search subspace.

$\text{‘Subspace'}=\text{'Yes'}$

The reverse communication solvers will use your initial guess for the search subspace and the eigenvalues therein. This option is useful if a previous run of the FEAST routines has yielded a partially converged answer to your eigenproblem.

$\text{‘Subspace'}=\text{'No'}$

Random initial vectors will be used for the search subspace.

Raises

NagValueError

(errno $1$)

Ambiguous keyword: $⟨value⟩$

(errno $2$)

Keyword not recognized: $⟨value⟩$

(errno $3$)

Second keyword not recognized: $⟨value⟩$

(errno $4$)

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

(errno $5$)

One of the contour setting functions feast_symm_contour(), feast_gen_contour() or feast_custom_contour() has already been called. All calls to feast_option must be made prior to calling the contour setting functions.

Notes

After the $handle$ has been initialized (e.g., feast_init() has been called), feast_option may be used to supply values for options to feast_symm_contour(), feast_gen_contour(), feast_custom_contour(), feast_real_symm_solve(), feast_real_gen_solve(), feast_complex_herm_solve(), feast_complex_symm_solve(), feast_complex_gen_solve(), feast_poly_symm_solve() and feast_poly_gen_solve(). It is only necessary to call feast_option for those arguments whose values are to be different from their default values. One call to feast_option sets one argument value.

Each option is defined by a single character string consisting of one or more items. The items associated with a given option must be separated by spaces or equals signs $[=]$. Alphabetic characters may be upper or lower case. The string

'Integration type = Gauss'

is an example of a string used to set an option. For each option the string contains one or more of the following items:

• a mandatory keyword;

• a phrase that qualifies the keyword;

• a number that specifies an int.

The NAG FEAST suite of functions of which feast_option is a part is based on the FEAST library, which solves eigenproblems using contour integration to find eigenvalues with a given contour in the complex plane. However, feast_option itself does not have an equivalent function in the FEAST package, which passes options by directly setting values to scalar arguments or to specific elements of array arguments. feast_option is intended to make the passing of options more transparent and follows the same principle as the single option setting functions in submodule opt.

The initialization function feast_init() must be called prior to the first call to feast_option and all calls to feast_option must precede the first call to the contour setting functions feast_symm_contour(), feast_gen_contour() and feast_custom_contour(), and the reverse communication solvers feast_real_symm_solve(), feast_real_gen_solve(), feast_complex_herm_solve(), feast_complex_symm_solve(), feast_complex_gen_solve(), feast_poly_symm_solve() and feast_poly_gen_solve(), and the deallocation function feast_free().

A complete list of options, their abbreviations, synonyms and default values is given in Other Parameters.

See also

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