# NAG CL Interfacef12jbc (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:

## 1Purpose

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.

## 2Specification

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

## 3Description

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 $\left[=\right]$. 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:
• a mandatory keyword;
• a phrase that qualifies the keyword;
• a number that specifies an Integer.
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.

None.

## 5Arguments

1: $\mathbf{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: $\mathbf{str}$const char * Input
On entry: a single valid option string (as described in Section 3 and Section 11).
3: $\mathbf{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

## 6Error 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.
On entry, argument $⟨\mathit{\text{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: $⟨\mathit{\text{value}}⟩$
Keyword not recognized: $⟨\mathit{\text{value}}⟩$
Second keyword not recognized: $⟨\mathit{\text{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.

Not applicable.

## 8Parallelism and Performance

f12jbc is not threaded in any implementation.

## 10Example

See the example for f12jjc.

## 11Optional 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.1Description 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:
• the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
• a parameter value, where the letters $a$, $i$ and $r$ denote options that take character, integer and real values respectively;
• the default value.
Keywords and character values are case and white space insensitive.
Optional parameters used to specify files (e.g., ${\mathbf{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 $\text{}=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 ${\mathbf{Advisory}}$ during the solution of the problem.
 Contour Points Hermitian $i$ Default $\text{}=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 ${\mathbf{Integration Type}}$ is set to $\mathrm{Gauss}$ or $\mathrm{Zol}$, the values permitted are $1$$20$, $24$, $32$, $40$, $48$, $56$. If the option ${\mathbf{Integration Type}}$ is set to $\mathrm{Trap}$, then all values greater than or equal to $1$ are permitted.
 Contour Points Non-Hermitian $i$ Default $\text{}=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 ${\mathbf{Integration Type}}$ is set to $\mathrm{Gauss}$, the values permitted are $2$$40$ (even values only), $48$, $64$, $80$, $96$, $112$. If the option ${\mathbf{Integration Type}}$ is set to $\mathrm{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 Criteria $a$ Default $\text{}=\mathrm{Residual}$
These are the convergence criteria used to test for convergence of eigenpairs in the search region.
${\mathbf{Convergence Criteria}}=\mathrm{Trace}$
The relative error of the trace of the eigenproblem in the search subspace is tested against $\delta$.
${\mathbf{Convergence Criteria}}=\mathrm{Residual}$
The relative maximum residual over all eigenpairs found is tested against $\delta$.
Note: the value of $\delta$ is controlled using the optional parameter ${\mathbf{Tolerance}}$.
 Defaults
This special keyword may be used to reset all optional parameters to their default values.
 Ellipse Contour Ratio $i$ Default $\text{}=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 ${\mathbf{Integration Type}}$ is set to $\mathrm{Zol}$ then a circular contour is used and this option is not referenced.
 Ellipse Rotation Angle $i$ Default $\text{}=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 Mode $a$ Default $\text{}=\mathrm{Normal}$
The execution mode used by the reverse communication solvers.
${\mathbf{Execution Mode}}=\mathrm{Normal}$
Normal execution.
${\mathbf{Execution Mode}}=\mathrm{Subspace}$
Return the search subspace and an estimate of the eigenvalues after one contour integral.
${\mathbf{Execution Mode}}=\mathrm{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 Type $a$ Default $\text{}=\mathrm{Gauss}$
The integration type. The allowed values are $\mathrm{Gauss}$, $\mathrm{Trap}$ (Trapezoidal) or $\mathrm{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 Iter $i$ Default $\text{}=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 ${\mathbf{List}}$ enables printing of each optional parameter specification as it is supplied. ${\mathbf{Nolist}}$ suppresses this printing.
 Print Level $i$ Default $\text{}=0$
This controls the amount of printing produced by the contour definition routines and the reverse communication solvers.
${\mathbf{Print Level}}=\mathrm{0}$
No output.
${\mathbf{Print Level}}=\mathrm{1}$
 Tolerance $r$ Default $\text{}=x-3$, where $x$ is the value returned by X02BEC
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 $a$ Default $\text{}=\mathrm{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.
${\mathbf{Eigenvectors}}=\mathrm{Two-sided}$
Both left and right eigenvectors are computed.
${\mathbf{Eigenvectors}}=\mathrm{One-sided}$
Only right eigenvectors are computed.
 Subspace $a$ Default $\text{}=\mathrm{No}$
This option determines whether or not you will supply an initial guess for the eigenvector search subspace.
${\mathbf{Subspace}}=\mathrm{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.
${\mathbf{Subspace}}=\mathrm{No}$
Random initial vectors will be used for the search subspace.