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:
${PWD}/.psyclone/
${HOME}/.local/share/psyclone/
<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:
${PWD}/.psyclone/
<python-base-dir>/share/psyclone/
${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]
DEFAULTAPI = dynamo0.3
DEFAULTSTUBAPI = dynamo0.3
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
dynamo0.3
section:
[dynamo0.3]
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 gocean1.0
:
[gocean1.0]
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 |
---|---|---|
DEFAULTAPI |
The API that PSyclone assumes an Algorithm/Kernel conforms to if no API is specified. Must be one of the APIs supported by PSyclone (“dynamo0.3”, “gocean1.0” and “nemo”). If there is no API specified and there is only one API-specific section in the config file loaded, this API will be used. This value can be overwritten by the command line option ‘-api’. If there is no API entry in the config file, and ‘-api’ is not specified on the command line, “dynamo0.3” is used as default. |
str |
DEFAULTSTUBAPI |
The API that the kernel-stub generator assumes by default. Must be one of the stub-APIs supported by PSyclone (“dynamo0.3” only at this stage). |
str |
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 |
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.:
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. |
dynamo0.3
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 |
NUM_ANY_DISCONTINUOUS_SPACE |
Sets the number of |
gocean1.0
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. |
NEMO
Section
This section contains configuration options that are only applicable when using the NEMO API.
Entry |
Description |
---|---|
mapping-TYPE |
This declares a mapping for a certain loop level, specified as TYPE. Each value must have three key:value pairs. A value can be empty if it is not required or not known, but the key must still be specified. The required keys are:
Each loop detected by the NEMO API will be given one of the TYPE values specified in the configuration file. See the example below for more details. |
index-order |
Specifies the order in which loops are created when
converting an implicit loop to an explicit loop.
All values in this comma-separated list must have a
corresponding |
Below we show an example of the NEMO section of a PSyclone configuration file.
Note how the values in index-order
have corresponding mapping entries, e.g.
mapping-lon
, mapping-lat
etc.:
mapping-lon = var: ji, start: 1, stop: jpi
mapping-lat = var: jj, start: 1, stop: jpj
mapping-levels = var: jk, start: 1, stop: jpk
mapping-tracers = var: jt, start: 1, stop:
mapping-unknown = var: , start: 1, stop:
index-order = lon, lat, levels, tracers
If a NEMO loop then uses Do jj=...
, PSyclone will give this loop the type
‘lat’, because the loop uses the variable name specified in the configuration file
for a loop of type ‘lat’.
The loop type can be accessed using loop.loop_type
, i.e. in this example
it will be loop.loop_type == 'lat'
.
The entry mapping-unknown
has an empty value for the key ‘var’. This means
that the type ‘unknown’ will be used for any loop that can not be mapped
using any of the other variable names in the configuration file.