Parameter File Syntax

A parameter file (or par file) is used to control the behaviour of a Cactus executable. It specifies initial values for parameters as defined in the various thorns' param.ccl files (see Chapter B5). The name of a parameter file is often given the suffix .par, but this is not mandatory.

A parameter file is a text file whose lines are either comments or parameter statements. Comments are blank lines or lines that begin with either `#' or `!'. A parameter statement consists of one or more parameter names, followed by an `=', followed by the value(s) for this (these) parameter(s). Note that all string parameters are case insensitive.

The first parameter statement in any parameter file should set ActiveThorns, which is a special parameter that tells the program which thorns are to be activated. Only parameters from active thorns can be set (and only those routines scheduled by active thorns are run). By default, all thorns are inactive. For example, the first entry in a parameter file which is using just the two thorns CactusPUGH/PUGH and CactusBase/CartGrid3D, should be

ActiveThorns = "PUGH CartGrid3D"

All parameters following the ActiveThorns parameter have names whose syntax depends on the scope (see Section B5.2) of the parameter:

Global parameters

Just the name of the parameter itself. Global parameters are to be avoided; there are none in the flesh and Cactus Toolkits.

Restricted parameters

The name of the implementation which defined the parameter, followed by two colons, then the name of the parameter--e.g. driver::global_nx.

Private parameters

The name of the thorn which defined the parameter, two colons, and the name of the parameter--e.g. wavetoyF77::amplitude.

This notation is not currently strictly enforced in the code. It is sufficient to specify the first part of the parameter name using either the implementation name, or the thorn name. However, we recommend that the above convention be followed.

The Cactus flesh performs checks for consistency and range of parameters. The severity of these checks is controlled by the command line argument -parameter-level, which can take the following values

relaxed

Cactus will issue a level 0 warning (that is, the default behaviour will be to terminate) if

• The specified parameter value is outside of the allowed range.

normal

This is the default, and provides the same warnings as the relaxed level, with the addition of a level 0 warning issued for

• An implementation and/or thorn foo is active, but the parameter foo::bar was not defined.
• The parameter foo::bar was successfully set for both an active implementation foo not implemented by a thorn foo, and to a thorn foo.

strict

This provides the same warnings as the normal level, with the addition of a level 0 warning issued for

• The parameter foo::bar is specified in the parameter file, but no implementation or thorn with the name bar is active.

Notes:

• You can obtain lists of the parameters associated with each thorn using the command-line options -o and -O (Section A3.1).

• The parameter file is read sequentially from top to bottom, this means that if you set the value of a parameter twice in the parameter file, the second value will be used. (This is why the ActiveThorns parameter is always first in the file).

• String parameter values can be specified either as unquoted tokens (not containing any whitespace), or as quoted values. If a quoted string parameter value spans multiple lines, all whitespaces, including newline characters, are preserved.

• Some parameters are steerable, and can be changed during the execution of a Cactus program by using parameter steering interfaces, for example, thorn CactusConnect/HTTPD, or by using a parameter file when recovering from a checkpoint file.

• For examples of parameter files, look in the par directory, which can be found in most thorns.