psyclone.configuration

PSyclone configuration management module.

Deals with reading the config file and storing default settings.

Classes

• APISpecificConfig: A base class for functions that each API-specific class must provide.

• Config: Handles all configuration management. It is implemented as a singleton

• LFRicConfig: LFRic-specific (Dynamo 0.3) Config sub-class. Holds configuration options

• GOceanConfig: Gocean1.0-specific Config sub-class. Holds configuration options

• NemoConfig: Nemo-specific Config sub-class. Holds configuration options

class psyclone.configuration.APISpecificConfig(section)

A base class for functions that each API-specific class must provide. At the moment this is just the function ‘access_mapping’ that maps between API-specific access-descriptor strings and the PSyclone internal AccessType. :param section: configparser.SectionProxy :raises ConfigurationError: if an access-mapping is provided that assigns an invalid value (i.e. not one of ‘read’, ‘write’, ‘readwrite’), ‘inc’ or ‘sum’) to a string.

Inheritance

static create_dict_from_list(input_list)

Takes a list of strings each with the format: key:value and creates a dictionary with the key,value pairs. Any leading or trailing white space is removed.

Parameters:

input_list (list of str) – the input list.

Returns:

a dictionary with the key,value pairs from the input list.

Return type:

dict[str, Any]

Raises:

ConfigurationError – if any entry in the input list does not contain a “:”.

get_access_mapping()

Returns the mapping of API-specific access strings (e.g. gh_write) to the AccessType (e.g. AccessType.WRITE). :returns: The access mapping to be used by this API. :rtype: Dictionary of strings

abstract get_constants()

Returns:

an object containing all constants for the API.

Return type:

either psyclone.domain.lfric.LFRicConstants, psyclone.domain.gocean.GOceanConstants, or psyclone.domain.nemo.NemoConstants

static get_precision_map_dict(section)

Extracts the precision map values from the psyclone.cfg file and converts them to a dictionary with integer values.

Returns:

The precision maps to be used by this API.

Return type:

dict[str, int]

get_reverse_access_mapping()

Returns the reverse mapping of a PSyclone internal access type to the API specific string, e.g.: AccessType.READ to ‘gh_read’. This is used to provide the user with API specific error messages. :returns: The mapping of access types to API-specific strings. :rtype: Dictionary of strings

get_valid_accesses_api()

Returns the sorted, API-specific names of all valid access names. :returns: Sorted list of API-specific valid strings. :rtype: List of strings

class psyclone.configuration.Config

Handles all configuration management. It is implemented as a singleton using a class _instance variable and a get() function.

Inheritance

property api

Getter for the API selected by the user.

Returns:

The name of the selected API.

Return type:

str

api_conf(api=None)

Getter for the object holding API-specific configuration options.

Parameters:

api (str) – Optional, the API for which configuration details are required. If none is specified, returns the config for the default API.

Returns:

object containing API-specific configuration

Return type:

One of psyclone.configuration.LFRicConfig, psyclone.configuration.GOceanConfig or None.

Raises:

• ConfigurationError – if api is not in the list of supported APIs.

• ConfigurationError – if the config file did not contain a section for the requested API.

property backend_checks_enabled

Returns:

whether the validity checks in the PSyIR backend should be disabled.

Return type:

bool

property default_api

Getter for the default API used by PSyclone.

Returns:

default PSyclone API

Return type:

str

property default_stub_api

Getter for the default API used by the stub generator.

Returns:

default API for the stub generator

Return type:

str

property distributed_memory

Getter for whether or not distributed memory is enabled

Returns:

True if DM is enabled, False otherwise

Return type:

bool

property filename

Getter for the full path and name of the configuration file used to initialise this configuration object.

Returns:

full path and name of configuration file

Return type:

str

static find_file()

Static method that searches various locations for a configuration file. If the full path to an existing file has been provided in the PSYCLONE_CONFIG environment variable then that is returned. Otherwise, we search the following locations, in order:

• ${PWD}/.psyclone/

• if inside-a-virtual-environment:

  <base-dir-of-virtual-env>/share/psyclone/

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

• <system-install-prefix>/share/psyclone/

• <psyclone-installation-base>/share/psyclone/

Returns:

the fully-qualified path to the configuration file

Return type:

str

Raises:

ConfigurationError – if no config file is found

static get(do_not_load_file=False)

Static function that if necessary creates and returns the singleton config instance.

Parameters:

do_not_load_file (bool) – If set it will not load the default config file. This is used when handling the command line so that the user can specify the file to load.

get_constants()

Returns:

the constants instance of the current API.

Return type:

either psyclone.domain.lfric.LFRicConstants, psyclone.domain.gocean.GOceanConstants, or psyclone.domain.nemo.NemoConstants

get_default_keys()

Returns all keys from the default section. :returns list: List of all keys of the default section as strings.

static get_repository_config_file()

This function returns the absolute path to the config file included in the PSyclone repository. It is used by the testing framework to make sure all tests get the same config file (see tests/config_tests for the only exception). :return str: Absolute path to the config file included in the PSyclone repository.

static has_config_been_initialised()

Returns:

if the config class has loaded a (potential custom) config file.

property include_paths

Returns:

the list of paths to search for Fortran include files.

Return type:

list of str.

property kernel_naming

Returns:

what naming scheme to use when writing transformed kernels to file.

Return type:

str

property kernel_output_dir

Returns:

the directory to which to write transformed kernels.

Return type:

str

load(config_file=None)

Loads a configuration file.

Parameters:

config_file (str) – Override default configuration file to read.

Raises:

ConfigurationError – if there are errors or inconsistencies in the specified config file.

property ocl_devices_per_node

Returns:

The number of OpenCL devices per node.

Return type:

int

property psyir_root_name

Getter for the root name to use when creating PSyIR names.

Returns:

the PSyIR root name.

Return type:

str

property reprod_pad_size

Getter for the amount of padding to use for the array required for reproducible OpenMP reductions

Returns:

padding size (no. of array elements)

Return type:

int

property reproducible_reductions

Getter for whether reproducible reductions are enabled.

Returns:

True if reproducible reductions are enabled, False otherwise.

Return type:

bool

property supported_apis

Getter for the list of APIs supported by PSyclone.

Returns:

list of supported APIs

Return type:

list of str

property supported_stub_apis

Getter for the list of APIs supported by the stub generator.

Returns:

list of supported APIs.

Return type:

list of str

property valid_psy_data_prefixes

Returns:

The list of all valid class prefixes.

Return type:

list of str

class psyclone.configuration.LFRicConfig(config, section)

LFRic-specific (Dynamo 0.3) Config sub-class. Holds configuration options specific to the LFRic (Dynamo 0.3) API.

Parameters:

• config (psyclone.configuration.Config) – the ‘parent’ Config object.

• section (configparser.SectionProxy) – the entry for the ‘[dynamo0.3]’ section of the configuration file, as produced by ConfigParser.

Raises:

• ConfigurationError – for a missing mandatory configuration option.

• ConfigurationError – for an invalid option for the redundant computation over annexed dofs.

• ConfigurationError – for an invalid run_time_checks flag.

• ConfigurationError – if argument datatypes in the ‘default_kind’ mapping do not match the supported datatypes.

• ConfigurationError – for an invalid argument kind.

• ConfigurationError – for an invalid value type of NUM_ANY_SPACE.

• ConfigurationError – if the supplied number of ANY_SPACE function spaces is less than or equal to 0.

• ConfigurationError – for an invalid value type of NUM_ANY_DISCONTINUOUS_SPACE.

• ConfigurationError – if the supplied number of ANY_DISCONTINUOUS_SPACE function spaces is less than or equal to 0.

Inheritance

property compute_annexed_dofs

Getter for whether or not we perform redundant computation over annexed dofs.

Returns:

true if we are to do redundant computation.

Return type:

bool

property default_kind

Getter for default kind (precision) for real, integer and logical datatypes in LFRic.

Returns:

the default kinds for main datatypes in LFRic.

Return type:

dict of str

get_constants()

Returns:

an object containing all constants for the API.

Return type:

psyclone.domain.lfric.LFRicConstants

property num_any_discontinuous_space

Returns:

the number of ANY_DISCONTINUOUS_SPACE function spaces in LFRic.

Return type:

int

property num_any_space

Returns:

the number of ANY_SPACE function spaces in LFRic.

Return type:

int

property precision_map

Getter for precision map values for supported fortran datatypes in LFRic. (Precision in bytes indexed by the name of the LFRic kind parameter).

Returns:

the precision map values for main datatypes in LFRic.

Return type:

dict[str, int]

property run_time_checks

Getter for whether or not we generate run-time checks in the code.

Returns:

true if we are generating run-time checks

Return type:

bool

property supported_fortran_datatypes

Getter for the supported Fortran argument datatypes in LFRic.

Returns:

supported Fortran datatypes for LFRic arguments.

Return type:

list of str

class psyclone.configuration.GOceanConfig(config, section)

Gocean1.0-specific Config sub-class. Holds configuration options specific to the GOcean 1.0 API.

Parameters:

• config (psyclone.configuration.Config) – The ‘parent’ Config object.

• section (configparser.SectionProxy) – The entry for the gocean1.0 section of the configuration file, as produced by ConfigParser.

Inheritance

property debug_mode

Returns:

whether we are generating additional debug code.

Return type:

bool

get_constants()

Returns:

an object containing all constants for GOcean.

Return type:

psyclone.domain.gocean.GOceanConstants

property grid_properties

Returns:

the dict containing the grid properties.

Return type:

a dict with values of namedtuple(“Property”,”fortran type intrinsic_type”) instances.

static make_property(dereference_format, type_name, intrinsic_type)

Creates a property (based on namedtuple) for a given Fortran code to access a grid property, and the type.

Parameters:

• dereference_format (str) – The Fortran code to access a property given a field name (which will be used to replace a {0} in the string. E.g. “{0}%whole%xstop”).

• type_name (str) – The type of the grid property, must be ‘scalar’ or ‘array’.

• intrinsic_type (str) – The intrinsic type of the grid property, must be ‘integer’ or ‘real’.

Returns:

a namedtuple for a grid property given the Fortran statement to access it and the type.

Raises:

• InternalError – if type_name is not ‘scalar’ or ‘array’

• InternalError – if intrinsic_type is not ‘integer’ or ‘real’

class psyclone.configuration.NemoConfig(config, section)

Nemo-specific Config sub-class. Holds configuration options specific to the Nemo API.

Parameters:

• config (psyclone.configuration.Config) – The ‘parent’ Config object.

• section (configparser.SectionProxy) – The entry for the NEMO section of the configuration file, as produced by ConfigParser.

Inheritance

get_constants()

Returns:

an object containing all constants for Nemo.

Return type:

psyclone.domain.nemo.NemoConstants

get_index_order()

Returns:

the order in which loops should be created in NemoExplicitLoopTrans.

Return type:

list of str.

get_loop_type_data()

Returns:

the mapping of a loop type (lon, …) to a dictionary containing the corresponding variable name and start/stop values. Example: = {“lon”: {“var”: “ji”, “start”: “1”, “stop”: “jpi”}, - “lat”: {“var”: “jj”, “start”: “1”, “stop”: “jpj”} }

Return type:

dictionary with str keys, with each value being a dictionary mapping ‘var’, ‘start’, and ‘stop’ to str.

get_loop_type_mapping()

Returns:

the mapping of variable names to loop type.

Return type:

Dictionary of strings.

get_valid_loop_types()

The list is sorted to have reproducible results for testing. :returns: a sorted list of valid loop types. :rtype: list of str.

Exceptions

• ConfigurationError: Class for all configuration-related errors.

exception psyclone.configuration.ConfigurationError(value, config=None)

Class for all configuration-related errors.

Parameters:

• value (str) – error message.

• config (psyclone.configuration.Config.) – the Config object associated with the error.

Inheritance