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/

Note that for developers a slightly different configuration handling is implemented, see Module: configuration for details.

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

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

[lfric]
access_mapping = gh_read: read, gh_write: write, gh_readwrite: readwrite,
                 gh_inc: inc, gh_readinc: readinc, gh_sum: sum
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_phys: 8,
                r_um: 8
RUN_TIME_CHECKS = false
NUM_ANY_SPACE = 10
NUM_ANY_DISCONTINUOUS_SPACE = 10

or for gocean:

[gocean]
access_mapping = go_read:read, go_write:write, go_readwrite:readwrite
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 (Dynamo 0.3) 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 PSyData API 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

Common Sections

The following entries must be defined for each API in order for PSyclone to work as expected:

Entry

Description

access_mapping

This field defines the strings that are used by a particular API to indicate write, read, … access. Its value is a comma separated list of access-string:access pairs, e.g.: gh_read: read, gh_write: write, gh_readwrite: readwrite, gh_inc: inc, gh_readinc: gh_sum: sum At this stage these 6 types are defined for read, write, read+write, increment, read+increment and summation access by PSyclone. Sum is a form of reduction. The GOcean API does not support increment or sum, so it only defines three mappings for read, write, and readwrite.

lfric Section

This section contains configuration options that are only applicable when using the LFRic (Dynamo 0.3) 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.
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.