naginterfaces.library.sparseig.feast_option¶
- naginterfaces.library.sparseig.feast_option(handle, optstr, io_manager=None)[source]¶
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.1/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
The destination for advisory messages.
- ‘Contour Points Hermitian’int
Default
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 –, , , , , . If the option ‘Integration Type’ is set to ‘Trap’, then all values greater than or equal to are permitted.- ‘Contour Points Non-Hermitian’int
Default
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 – (even values only), , , , , . If the option ‘Integration Type’ is set to ‘Trap’, then all values greater than or equal to are permitted. Note this option is only relevant if the contour definition functionsfeast_symm_contour()
orfeast_gen_contour()
are used. If a custom contour is required (using the contour setting routinefeast_custom_contour()
) then this option is not relevant.- ‘Convergence Criteria’str
Default
These are the convergence criteria used to test for convergence of eigenpairs in the search region.
The relative error of the trace of the eigenproblem in the search subspace is tested against .
The relative maximum residual over all eigenpairs found is tested against .
Note: the value of 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
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()
orfeast_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
The rotation angle in degrees from the horizontal (between and ) 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 solversfeast_real_gen_solve()
,feast_complex_symm_solve()
,feast_complex_gen_solve()
,feast_poly_symm_solve()
andfeast_poly_gen_solve()
(which deal with problems that are neither real symmetric nor complex Hermitian).- ‘Execution Mode’str
Default
The execution mode used by the reverse communication solvers.
Normal execution.
Return the search subspace and an estimate of the eigenvalues after one contour integral.
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()
andfeast_poly_gen_solve()
).
- ‘Integration Type’str
Default
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()
orfeast_gen_contour()
. If a custom contour is required (using the contour setting routinefeast_custom_contour()
) then this option is not relevant.- ‘Max Iter’int
Default
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
This controls the amount of printing produced by the contour definition routines and the reverse communication solvers.
No output.
Print runtime comments to the advisory channel.
- ‘Tolerance’float
Default , where is the value returned by
machine.decimal_digits
The stopping criterion, , used to determine convergence of the eigensolver. If a value of is supplied then is used.
- ‘Eigenvectors’str
Default
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()
andfeast_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()
andfeast_poly_symm_solve()
) the left eigenvectors can be obtained from the right eigenvectors by complex conjugation.Both left and right eigenvectors are computed.
Only right eigenvectors are computed.
- ‘Subspace’str
Default
This option determines whether or not you will supply an initial guess for the eigenvector search subspace.
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.
Random initial vectors will be used for the search subspace.
- Raises
- NagValueError
- (errno )
Ambiguous keyword:
- (errno )
Keyword not recognized:
- (errno )
Second keyword not recognized:
- (errno )
has not been initialized properly or is corrupted.
- (errno )
One of the contour setting functions
feast_symm_contour()
,feast_gen_contour()
orfeast_custom_contour()
has already been called. All calls tofeast_option
must be made prior to calling the contour setting functions.
- Notes
After the has been initialized (e.g.,
feast_init()
has been called),feast_option
may be used to supply values for options tofeast_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()
andfeast_poly_gen_solve()
. It is only necessary to callfeast_option
for those arguments whose values are to be different from their default values. One call tofeast_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 submoduleopt
.The initialization function
feast_init()
must be called prior to the first call tofeast_option
and all calls tofeast_option
must precede the first call to the contour setting functionsfeast_symm_contour()
,feast_gen_contour()
andfeast_custom_contour()
, and the reverse communication solversfeast_real_symm_solve()
,feast_real_gen_solve()
,feast_complex_herm_solve()
,feast_complex_symm_solve()
,feast_complex_gen_solve()
,feast_poly_symm_solve()
andfeast_poly_gen_solve()
, and the deallocation functionfeast_free()
.A complete list of options, their abbreviations, synonyms and default values is given in Other Parameters.