f12jb: FL CL CPP AD

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.

Keyword Search:

NAG Library Manual, Mark 28.3

Interfaces: FL CL CPP AD

NAG FL Interface Introduction

F12 (Sparseig) Chapter Contents

F12 (Sparseig) Chapter Introduction

f12jb: FL CL CPP AD

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

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:

–a mandatory keyword;
–a phrase that qualifies the keyword;
–a number that specifies an integer.

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

−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

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.

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

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.

Advisory

i

Default

= advisory message unit number

The destination for advisory messages.

Contour Points Hermitian

i

Default

= 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

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

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 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 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 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 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 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 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 (f12juf and f12jvf).

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 routines f12jef or f12jff. If a custom contour is required (using the contour setting routine f12jgf) 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 x02bef

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

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 28.3

Interfaces: FL CL CPP AD

NAG FL Interface Introduction

F12 (Sparseig) Chapter Contents

F12 (Sparseig) Chapter Introduction

f12jb: FL CL CPP AD