NAG FL Interface
f12jbf (feast_​option)

Note: this routine uses optional parameters to define choices in the problem specification. If you wish to use default settings for all of the optional parameters, then this routine need not be called. If, however, you wish to reset some or all of the settings please refer to Section 11 for a detailed description of the specification of the optional parameters.
Settings help

FL Name Style:


FL Specification Language:


1 Purpose

f12jbf is part of NAG FEAST suite of routines and may be used to supply individual optional parameters to either the contour setting routines or the reverse communication solvers.

2 Specification

Fortran Interface
Subroutine f12jbf ( handle, str, ifail)
Integer, Intent (Inout) :: ifail
Character (*), Intent (In) :: str
Type (c_ptr), Intent (In) :: handle
C Header Interface
#include <nag.h>
void  f12jbf_ (void **handle, const char *str, Integer *ifail, const Charlen length_str)
The routine may be called by the names f12jbf or nagf_sparseig_feast_option.

3 Description

After the handle has been initialized (e.g., f12jaf has been called), f12jbf may be used to supply values for optional parameters to f12jef, f12jff, f12jgf, f12jjf, f12jkf, f12jrf, f12jsf, f12jtf, f12juf and f12jvf. It is only necessary to call f12jbf for those arguments whose values are to be different from their default values. One call to f12jbf sets one argument value.
Each optional parameter 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 optional parameter. For each option the string contains one or more of the following items:
The NAG FEAST suite of routines of which f12jbf 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, f12jbf itself does not have an equivalent routine in the FEAST package, which passes options by directly setting values to scalar arguments or to specific elements of array arguments. f12jbf is intended to make the passing of options more transparent and follows the same principle as the single option setting routines in Chapter E04.
The initialization routine f12jaf must be called prior to the first call to f12jbf and all calls to f12jbf must precede the first call to the contour setting routines f12jef, f12jff and f12jgf, and the reverse communication solvers f12jjf, f12jkf, f12jrf, f12jsf, f12jtf, f12juf and f12jvf, and the deallocation routine f12jzf.
A complete list of optional parameters, their abbreviations, synonyms and default values is given in Section 11.

4 References

None.

5 Arguments

1: handle Type (c_ptr) Input
On entry: the handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by f12jaf. It must not be changed between calls to the NAG FEAST suite.
2: str Character(*) Input
On entry: a single valid option string (as described in Section 3 and Section 11).
3: ifail Integer Input/Output
On entry: ifail must be set to 0, −1 or 1 to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of 0 causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of −1 means that an error message is printed while a value of 1 means that it is not.
If halting is not appropriate, the value −1 or 1 is recommended. If message printing is undesirable, then the value 1 is recommended. Otherwise, the value 0 is recommended. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry ifail=0 or −1, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
ifail=1
Ambiguous keyword: value
ifail=2
Keyword not recognized: value
ifail=3
Second keyword not recognized: value
ifail=4
The supplied handle does not define a valid handle to the data structure used by the NAG FEAST suite. It has not been properly initialized or it has been corrupted.
ifail=5
One of the contour setting routines f12jef, f12jff or f12jgf has already been called. All calls to f12jbf must be made prior to calling the contour setting routines.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
f12jbf is not threaded in any implementation.

9 Further Comments

9.1 Additional Licensor

Parts of the code for f12jbf are distributed under the BSD software License. Please refer to Library Licensors for further details.

10 Example

See the example for f12jjf.

11 Optional Parameters

Several optional parameters for the contour definition routines f12jef, f12jff and f12jgf, and the reverse communication solvers f12jjf, f12jkf, f12jrf, f12jsf, f12jtf, f12juf and f12jvf, define choices in the problem specification or the algorithm logic. In order to reduce the number of formal arguments for these routines, these optional parameters have associated default values that are appropriate for most problems. Therefore, you need only specify those optional parameters whose values are to be different from their default values.
The remainder of this section can be skipped if you wish to use the default values for all optional parameters.
The following is a list of the optional parameters available. A full description of each optional parameter is provided in Section 11.1.
Optional parameters may be specified by calling f12jbf before a call to f12jef, f12jff and f12jgf, but after a call to f12jaf. One call is necessary for each optional parameter.
All optional parameters you do not specify are set to their default values. Optional parameters you do specify are unaltered by the contour definition routines and the reverse communication solvers (unless they define invalid values) and remain in effect for subsequent calls unless you alter them.

11.1 Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
Keywords and character values are case and white space insensitive.
AdvisoryiDefault =advisory message unit number
The destination for advisory messages.
Contour Points HermitianiDefault =8
For real symmetric (f12jjf) or Hermitian (f12jrf) 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 120, 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-HermitianiDefault =8
For general real (f12jkf), symmetric complex (f12jsf, f12juf) or general complex (f12jtf, f12jvf) 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 240 (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 routines f12jef or f12jff are used. If a custom contour is required (using the contour setting routine f12jgf) then this option is not relevant.
Convergence CriteriaaDefault =Residual
These are the convergence criteria used to test for convergence of eigenpairs in the search region.
Convergence Criteria=Trace
The relative error of the trace of the eigenproblem in the search subspace is tested against δ.
Convergence Criteria=Residual
The relative maximum residual over all eigenpairs found is tested against δ.
Note: the value of δ is controlled using the optional parameter Tolerance.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Ellipse Contour RatioiDefault =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 routines f12jef or f12jff.
Note: for a Hermitian eigenvalue problem, if the optional parameter Integration Type is set to Zol then a circular contour is used and this option is not referenced.
Ellipse Rotation AngleiDefault =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 routine f12jff and the reverse communication solvers f12jkf, f12jsf, f12jtf, f12juf and f12jvf (which deal with problems that are neither real symmetric nor complex Hermitian).
Execution ModeaDefault =Normal
The execution mode used by the reverse communication solvers.
Execution Mode=Normal
Normal execution.
Execution Mode=Subspace
Return the search subspace and an estimate of the eigenvalues after one contour integral.
Execution Mode=Estimate
Return an estimate of the number of eigenvalues inside the search contour. Note that this option is not available for polynomial eigenvalue problems (f12juf and f12jvf).
Integration TypeaDefault =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 routines f12jef or f12jff. If a custom contour is required (using the contour setting routine f12jgf) then this option is not relevant.
Max IteriDefault =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 Default
List
Optional parameter List enables printing of each optional parameter specification as it is supplied. Nolist suppresses this printing.
Print LeveliDefault =0
This controls the amount of printing produced by the contour definition routines and the reverse communication solvers.
Print Level=0
No output.
Print Level=1
Print runtime comments to the advisory channel.
TolerancerDefault =x-3, where x is the value returned by x02bef
The stopping criterion, δ, used to determine convergence of the eigensolver. If a value of k is supplied then δ=10-k is used.
EigenvectorsaDefault =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 f12jkf, f12jtf and f12jvf, which deal with non-symmetric eigenvalue problems. For the symmetric/Hermitian solvers (f12jjf, f12jrf, f12jsf and f12juf) the left eigenvectors can be obtained from the right eigenvectors by complex conjugation.
Eigenvectors=Two-sided
Both left and right eigenvectors are computed.
Eigenvectors=One-sided
Only right eigenvectors are computed.
SubspaceaDefault =No
This option determines whether or not you will supply an initial guess for the eigenvector search subspace.
Subspace=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.
Subspace=No
Random initial vectors will be used for the search subspace.