NAG CL Interface
f12jbc (feast_​option)

Note: this function 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 function 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

CL Name Style:


1 Purpose

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

2 Specification

#include <nag.h>
void  f12jbc (void *handle, const char *str, NagError *fail)
The function may be called by the names: f12jbc or nag_sparseig_feast_option.

3 Description

After the handle has been initialized (e.g., f12jac has been called), f12jbc may be used to supply values for optional parameters to f12jec, f12jfc, f12jgc, f12jjc, f12jkc, f12jrc, f12jsc, f12jtc, f12juc and f12jvc. It is only necessary to call f12jbc for those arguments whose values are to be different from their default values. One call to f12jbc 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 functions of which f12jbc 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, f12jbc 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. f12jbc is intended to make the passing of options more transparent and follows the same principle as the single option setting functions in Chapter E04.
The initialization function f12jac must be called prior to the first call to f12jbc and all calls to f12jbc must precede the first call to the contour setting functions f12jec, f12jfc and f12jgc, and the reverse communication solvers f12jjc, f12jkc, f12jrc, f12jsc, f12jtc, f12juc and f12jvc, and the deallocation function f12jzc.
A complete list of optional parameters, their abbreviations, synonyms and default values is given in Section 11.

4 References

None.

5 Arguments

1: handle void * Input
On entry: the handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by f12jac. It must not be changed between calls to the NAG FEAST suite.
2: str const char * Input
On entry: a single valid option string (as described in Section 3 and Section 11).
3: fail NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_HANDLE
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.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_INVALID_OPTION
Ambiguous keyword: value
Keyword not recognized: value
Second keyword not recognized: value
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
NE_PREV_CALL
A contour setting function has already been called. All calls to this option setting routine must be made prior to any calls to the contour setting functions.

7 Accuracy

Not applicable.

8 Parallelism and Performance

f12jbc is not threaded in any implementation.

9 Further Comments

9.1 Additional Licensor

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

10 Example

See the example for f12jjc.

11 Optional Parameters

Several optional parameters for the contour definition functions f12jec, f12jfc and f12jgc, and the reverse communication solvers f12jjc, f12jkc, f12jrc, f12jsc, f12jtc, f12juc and f12jvc, define choices in the problem specification or the algorithm logic. In order to reduce the number of formal arguments for these functions, 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 f12jbc before a call to f12jec, f12jfc and f12jgc, but after a call to f12jac. 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 functions 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.
Optional parameters used to specify files (e.g., Advisory) have type Nag_FileID. This ID value must either be set to 0 (the default value) in which case there will be no output, or will be as returned by a call of x04acc.
Advisory Default =0
(See Section 3.1.1 in the Introduction to the NAG Library CL Interface for further information on NAG data types.)
Advisory messages are output to Nag_FileID Advisory during the solution of the problem.
Contour Points HermitianiDefault =8
For real symmetric (f12jjc) or Hermitian (f12jrc) 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 (f12jkc), symmetric complex (f12jsc, f12juc) or general complex (f12jtc, f12jvc) 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 functions f12jec or f12jfc are used. If a custom contour is required (using the contour setting routine f12jgc) 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 functions f12jec or f12jfc.
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 function f12jfc and the reverse communication solvers f12jkc, f12jsc, f12jtc, f12juc and f12jvc (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 (f12juc and f12jvc).
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 functions f12jec or f12jfc. If a custom contour is required (using the contour setting routine f12jgc) 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 X02BEC
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 f12jkc, f12jtc and f12jvc, which deal with non-symmetric eigenvalue problems. For the symmetric/Hermitian solvers (f12jjc, f12jrc, f12jsc and f12juc) 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.