Libraries

PSyclone provides PSyData-API-based wrappers to various external libraries. These wrapper libraries provide PSyclone transformations that insert callbacks to an external library at runtime. The callbacks then allow third-party libraries to access data structures at specified locations in the code for different purposes, such as profiling and extraction of argument values.

These wrapper libraries can be found under the lib directory in the Git repository. If you have installed PSyclone using pip then the libraries may be found in share/psyclone/lib under your Python (or PSyclone, depending on the pip install options) installation (see here for possible locations).

Note

If working with wrapper libraries from a PSyclone installation, it is advisable to copy the entire lib directory to some convenient location before building and using them. The provided Makefiles support the options to specify paths to the libraries and their dependencies, see compilation for more information.

Available libraries

An overview of the currently available functionality is below. For details of what each library does and how to build and use it please see the related sections in the User Guide and the specific README.md files in the associated directories.

Profiling

PSyclone provides wrapper libraries for some common performance profiling tools, such as dl_timer and Dr Hook. More information can be found in the Profiling section.

Profiling libraries are located in the lib/profiling directory. For detailed instructions on how to build and use them please refer to their specific README.md documentation.

Kernel Data Extraction

These libraries enable PSyclone to add callbacks that provide access to all input variables before, and output variables after a kernel invocation. More information can be found in the PSy Kernel Extractor (PSyKE) section.

Example libraries that extract input and output data into a NetCDF file for LFRic (Dynamo0.3) and GOcean1.0 APIs are included with PSyclone in the lib/extract/netcdf directory. For detailed instructions on how to build and use these libraries please refer to their specific README.md documentation.

Access Verification

Read-only libraries check that a field declared as read-only is not modified during a kernel call. More information can be found in the Read-Only Verification section.

The libraries for LFRic (Dynamo0.3) and GOcean1.0 APIs are included with PSyclone in the lib/read_only directory. For detailed instructions on how to build and use these libraries please refer to their specific README.md documentation.

NAN Test

These libraries test all input and output parameters of a kernel to make sure they are not NaN or infinite. More information can be found in the NAN Test section.

The libraries for LFRic (Dynamo0.3) and GOcean1.0 APIs are included with PSyclone in the lib/nan_test directory. For detailed instructions on how to build and use these libraries please refer to their specific README.md documentation.

Dependencies

Building and using the wrapper libraries requires that PSyclone be installed on the host system, see section Getting Going. A Fortran compiler (e.g. Gnu Fortran compiler, gfortran, is free and easily installed) and Gnu Make are also required.

The majority of wrapper libraries use Jinja templates to create PSyData-derived classes (please refer to psy_data and Jinja Support in the Base Class for full details about the PSyData API).

Compilation of extract, nan_test, read_only and some of the profiling wrapper libraries depends on infrastructure libraries relevant to the API they are used for. LFRic API uses the LFRic infrastructure and GOcean1.0 uses the dl_esm_inf library. The LFRic infrastructure can be obtained from the LFRic code repository, however this requires access to the Met Office Science Repository Service (MOSRS). A useful contact for LFRic-related questions (including access to MOSRS) is the “lfric” mailing list which gathers the Met Office and external LFRic developers and users. The dl_esm_inf library is freely available and can be downloaded from https://github.com/stfc/dl_esm_inf.

Some libraries require NetCDF for compilation. Installation of NetCDF is described in details in the hands-on practicals documentation.

Profiling wrapper libraries that depend on external tools (e.g. dl_timer) require these tools be installed and configured beforehand.

Compilation

Each library is compiled with make using the provided Makefile that has configurable options for compiler flags and locations of dependencies.

As in case of examples, F90 and F90FLAGS specify the compiler and compilation flags to use. The default value for F90 is gfortran.

Locations of the top-level lib directory and the required Jinja templates are specified with the PSYDATA_LIB_DIR and LIB_TMPLT_DIR variables. For testing purposes their default values are set to relative paths to the respective directories in the PSyclone repository.

The locations of the infrastructure libraries for LFRic and GOcean1.0 applications can be configured with the variables LFRIC_INF_DIR and GOCEAN_INF_DIR, respectively. Their default values are set to relative paths to the locations of these libraries in the PSyclone repository. The dl_esm_inf library is provided as a Git submodule of the PSyclone project (see Installation in the Developers’ Guide for details on working with submodules) and a pared-down version of LFRic infrastructure is also available in the PSyclone repository (please refer to the README.md documentation of relevant wrapper libraries). However, the infrastructure libraries are not available in a PSyclone installation and they need to be downloaded separately, see Dependencies for more information. In this case LFRIC_INF_DIR and GOCEAN_INF_DIR must be set to the exact paths to where the respective infrastructure source can be found. For instance,

GOCEAN_INF_DIR=$HOME/dl_esm_inf/finite_difference make

Profiling wrapper libraries that depend on external tools have specific variables that configure paths to where these libraries are located in a user environment.

For more information on how to build and configure a specific library please refer to its README.md documentation.

Similar to compilation of the examples, the compiled library can be removed by running make clean. There is also the allclean target that removes the compiled wrapper library as well as the compiled infrastructure library that the wrapper may depend on.

The compilation of wrapper libraries was tested with the Gnu and Intel Fortran compilers, see here for the full list. Please let the PSyclone developers know if you have problems using a compiler that has been tested or if you are working with a different compiler.