Configuration

PSyclone reads various run-time configuration options from the psyclone.cfg file. As described in Configuration, the default psyclone.cfg configuration file is installed in <python-base-prefix>/share/psyclone/ during the installation process. The original version of this file is in the PSyclone/config directory of the PSyclone distribution.

At execution-time, the user can specify a custom configuration file to be used. This can either be done with the --config command-line option, or by specifying the (full path to the) configuration file to use via the PSYCLONE_CONFIG environment variable. If the specified configuration file is not found then PSyclone will fall back to searching in a list of default locations.

The ordering of these locations depends upon whether PSyclone is being run within a Python virtual environment (such as venv). If no virtual environment is detected then the locations searched, in order, are:

1. ${PWD}/.psyclone/

2. ${HOME}/.local/share/psyclone/

3. <python-base-dir>/share/psyclone/

where <python-base-dir> is the path stored in Python’s sys.prefix.

If a virtual environment is detected then it is assumed that the share directory will be a part of that environment. In order to maintain isolation of distinct virtual environments this directory is then checked before the user’s home directory. i.e. the list of locations searched is now:

1. ${PWD}/.psyclone/

2. <python-base-dir>/share/psyclone/

3. ${HOME}/.local/share/psyclone/

As a last resort, the location <psyclone-src-base>/config/ is searched in case PSyclone was installed in editable mode.

Options

The configuration file is read by the Python ConfigParser class (https://docs.python.org/3/library/configparser.html) and must be formatted accordingly. It currently consists of a DEFAULT section e.g.:

[DEFAULT]
DISTRIBUTED_MEMORY = true
REPRODUCIBLE_REDUCTIONS = false
REPROD_PAD_SIZE = 8
PSYIR_ROOT_NAME = psyir_tmp
VALID_PSY_DATA_PREFIXES = profile, extract
FORTRAN_STANDARD = f2008

and an optional API specific section, for example for the lfric section:

[lfric]
COMPUTE_ANNEXED_DOFS = false
supported_fortran_datatypes = real, integer, logical
default_kind = real: r_def, integer: i_def, logical: l_def
precision_map = i_def: 4,
                l_def: 1,
                r_def: 8,
                r_double: 8,
                r_ncdf: 8,
                r_quad: 16,
                r_second: 8,
                r_single: 4,
                r_solver: 4,
                r_tran: 8,
                r_bl: 8,
                r_um: 8
RUN_TIME_CHECKS = none
NUM_ANY_SPACE = 10
NUM_ANY_DISCONTINUOUS_SPACE = 10

or for gocean:

[gocean]
grid-properties = go_grid_xstop: {0}%%grid%%subdomain%%internal%%xstop: scalar,
               go_grid_ystop: {0}%%grid%%subdomain%%internal%%ystop: scalar,
               go_grid_data: {0}%%data: array,
               ...

The meaning of the various entries is described in the following sub-sections.

Note that ConfigParser supports various forms of boolean entry including “true/false”, “yes/no” and “1/0”. See https://docs.python.org/3/library/configparser.html#supported-datatypes for more details.

DEFAULT Section

This section contains entries that are, in principle, applicable to all APIs supported by PSyclone.

Entry	Description	Type
DISTRIBUTED_MEMORY	Whether or not to generate code for distributed-memory parallelism by default. Note that this is currently only supported for the LFRic API.	bool
REPRODUCIBLE_REDUCTIONS	Whether or not to generate code for reproducible OpenMP reductions (see Reductions) by default.	bool
REPROD_PAD_SIZE	If generating code for reproducible OpenMP reductions, this setting controls the amount of padding used between elements of the array in which each thread accumulates its local reduction. (This prevents false sharing of cache lines by different threads.)	int
PSYIR_ROOT_NAME	The root for generated PSyIR symbol names if one is not supplied when creating a symbol. Defaults to “psyir_tmp”.	str
VALID_PSY_DATA_PREFIXES	Which class prefixes are permitted in any PSyData-related transformations. See The PSyData Transformations for details.	list of str
BACKEND_CHECKS_ENABLED	Optional (defaults to True). Whether or not the PSyIR backend should validate the tree that it is passed. Can be overridden by the --backend command-line flag (see Backend Options).	bool
BACKEND_INDENTATION_DISABLED	Optional (defaults to False). Whether or not the PSyIR backend should output nested code structures using indentation. Can be overridden by the --backend command-line flag (see Backend Options).	bool
FORTRAN_STANDARD	Optional (defaults to f2008). The Fortran standard that should be used by fparser. Valid values are f2003 and f2008.	str

lfric Section

This section contains configuration options that are only applicable when using the LFRic API.

Entry	Description
COMPUTE_ANNEXED_DOFS	Whether or not to perform redundant computation over annexed dofs in order to reduce the number of halo exchanges, see Annexed DoFs.
supported_fortran_datatypes	Captures the supported Fortran data types of LFRic arguments, see Supported Data Types and Default Kind.
default_kind	Captures the default kinds (precisions) for the supported Fortran data types in LFRic, see Supported Data Types and Default Kind.
precision_map	Captures the value of the actual precisions in bytes, see Precision Map
RUN_TIME_CHECKS	Specifies whether to generate run-time validation checks, see Run-time Checks. Must be one of none, warn or error.
NUM_ANY_SPACE	Sets the number of ANY_SPACE function spaces in LFRic, see Number of Generalised ANY_*_SPACE Function Spaces.
NUM_ANY_DISCONTINUOUS_SPACE	Sets the number of ANY_DISCONTINUOUS_SPACE function spaces in LFRic, see Number of Generalised ANY_*_SPACE Function Spaces.

gocean Section

This section contains configuration options that are only applicable when using the Gocean 1.0 API.

Entry	Description
iteration-spaces	This contains definitions of additional iteration spaces used by PSyclone. A detailed description can be found in the Iteration-spaces section of the GOcean1.0 chapter.
grid-properties	This key contains definitions to access various grid properties. A detailed description can be found in the Grid Properties section of the GOcean1.0 chapter.

Overwriting Config Settings on the Command Line

PSyclone provides the command line option --config-opts to overwrite settings in the configuration file. This can be convenient to test different scenarios without having to maintain a config files for each of them.

The option takes a space-separated list of key=value pairs, for example:

psyclone --config-opts="run_time_checks=warn reprod_pad_size=27" ...

This will overwrite the settings for run_time_checks and reprod_pad_size in the configuration file. You can overwrite any setting in any section (without having to specify the section). Capitalisation of the keys is ignored. If an invalid key is specified, an exception will be raised and execution will be aborted.