f12jb: FL CL CPP AD PY MB

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.

Keyword Search:

NAG Library Manual, Mark 29.2

Interfaces: FL CL CPP AD PY MB

NAG CL Interface Introduction

F12 (Sparseig) Chapter Contents

F12 (Sparseig) Chapter Introduction

f12jb: FL CL CPP AD PY MB

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

▸▿ 9 Further Comments

9.1 Additional Licensor

10 Example

▸▿ 11 Optional Parameters

11.1 Description of the Optional Parameters

Settings help

CL Name Style:
Short (a00aac)
Long (impl_details)
Full (nag_info_impl_details)

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:

–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.

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

Background information to multithreading can be found in the Multithreading documentation.

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.

Advisory
Contour Points Hermitian
Contour Points Non-Hermitian
Convergence Criteria
Defaults
Eigenvectors
Ellipse Contour Ratio
Ellipse Rotation Angle
Execution Mode
Integration Type
List
Max Iter
Nolist
Print Level
Subspace
Tolerance

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:

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.,

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 Hermitian

i

Default

= 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

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

i

Default

= 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

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 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

= 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 Ratio

i

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 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 Angle

i

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 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

= 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 Type

a

Default

= 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 Iter

i

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

Default

List

Optional parameter

List

enables printing of each optional parameter specification as it is supplied.

Nolist

suppresses this printing.

Print Level

i

Default

= 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.

Tolerance

r

Default

= 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.

Eigenvectors

a

Default

= 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.

Subspace

a

Default

= 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.

NAG Library Manual, Mark 29.2

Interfaces: FL CL CPP AD PY MB

NAG CL Interface Introduction

F12 (Sparseig) Chapter Contents

F12 (Sparseig) Chapter Introduction

f12jb: FL CL CPP AD PY MB