PSyKAl and PSyclone#

LFRic is designed so scientists and software engineers can work on different parts of the code independently. To support this, LFRic uses the PSyKAl software architecture and the PSyclone source-to-source Fortran compiler.

Note

This page is aimed at LFRic users who need to understand how PSyclone fits into the model build and where to make routine source-code changes. It is not intended to teach PSyclone development, optimisation-script writing, or the internal PSyclone representation of code. Those topics are covered in the official PSyclone User Guide and PSyclone Developer Guide.

Why LFRic uses PSyclone#

LFRic Atmosphere contains scientific code that describes atmospheric processes, but it must also run efficiently on large parallel computers. Without a separation between these concerns, scientific changes and performance-porting changes would be tightly coupled, making the model harder to maintain and optimise.

PSyclone helps provide this separation. In LFRic, users write code that follows the LFRic PSyKAl application programming interface (API). PSyclone reads that source code during the build and generates Fortran that connects the scientific operations to the LFRic infrastructure, including parallel loops, data access, and communication patterns.

This means that most LFRic users do not run PSyclone directly. It is normally invoked for you by the LFRic build system.

See also

See the PSyclone project overview, Introduction to PSyKAl, and The LFRic DSL documentation.

The PSyKAl layers#

PSyKAl is named after the PSy, Kernel, and Algorithm layers. It separates model code into three layers:

Layer

What it contains

What a user needs to know

Algorithm layer

High-level scientific control flow. It says which operations should be applied to which fields, usually through invoke calls.

This is where field-level operations are assembled into a larger model calculation.

Kernel layer

The scientific calculation performed locally, for example over a vertical column of cells in the LFRic mesh. Kernel metadata describes what the kernel reads, writes, and where it operates.

This is the layer you are most likely to inspect or edit when changing a specific piece of model science.

PSy layer, short for Parallel System layer

The generated layer between the algorithm and kernels. It handles the infrastructure details needed to run the kernels correctly and efficiently.

This layer is generated by PSyclone. You normally inspect it only when debugging, and you should not make persistent edits to generated files.

See also

See the PSyclone documentation for the Algorithm layer, Kernel layer, and PSy layer.

PSyKAl architecture separating natural science code from computational science code

Fig. 17 Separation of Natural and Computational Science in the PSyKAl architecture.#

Algorithms and invokes#

In the algorithm layer, the model describes the sequence of scientific operations to perform. The important idea for users is that an invoke call groups one or more kernel or built-in operations that act on LFRic objects such as fields, scalars, operators, quadrature objects, and stencil extents.

PSyclone uses these invoke calls to work out what generated PSy-layer code is required. For user-defined kernels, the algorithm must also make the kernel available with a Fortran use statement so that PSyclone can find the corresponding kernel module when it parses the code.

See also

See the PSyclone Algorithm layer documentation and the LFRic-specific The LFRic DSL documentation.

Kernels and metadata#

A kernel contains the local scientific calculation. In LFRic, kernels are written using an API that describes both the executable code and metadata about the operation. The metadata is essential because it tells PSyclone:

  • what arguments the kernel expects, such as fields, scalars, operators, or field vectors;

  • whether each argument is read, written, or updated;

  • which function spaces are involved;

  • what part of the mesh the kernel operates on, such as a cell column;

  • whether additional information such as basis functions, quadrature, stencils, or halo depth is needed.

PSyclone relies on this metadata to generate correct PSy-layer code. For example, it can use the metadata to insert the infrastructure calls needed for distributed-memory execution, including halo exchanges where required.

See also

See the PSyclone Kernel layer documentation, the LFRic-specific The LFRic DSL documentation, and the Metadata section for examples of LFRic metadata.

Built-ins#

Not every operation needs a user-written kernel. Some common operations are provided as LFRic built-ins. Built-ins are requested from the algorithm layer in a similar way to kernels, but their implementation is supplied by the infrastructure rather than by a separate kernel module.

Built-ins reduce the amount of scientific code that has to be maintained and allow common operations to be implemented efficiently for different computer architectures.

See also

See the general PSyKAl Built-ins documentation and the LFRic-specific Built-ins documentation.

What happens during an LFRic build#

When you build LFRic Atmosphere, the build system processes source files, invokes PSyclone, compiles the generated Fortran, and links the final executable.

For normal LFRic development, the practical consequence is:

  • edit the source files in the repository, including PSyclone source files with the .x90 extension;

  • do not make persistent edits in working/build_* directories;

  • do not rely on changes made directly to generated .f90 files, because they are build artefacts and will be regenerated.

This is why the command-line practical asks you to modify science/gungho/source/driver/gungho_step_mod.x90 rather than the generated gungho_step_mod.f90 file in a build directory.

See also

See the PSyclone command documentation, especially the section on using PSyclone for PSyKAl DSLs.

What users should take away#

For this course, you do not need to write PSyclone transformation scripts or understand PSyclone’s internal representation of Fortran code. You should be able to:

  • recognise why LFRic separates algorithm, kernel, and generated PSy-layer code;

  • understand that PSyclone is part of the build process, not a separate tool most users run manually;

  • identify source files that should be edited rather than generated build artefacts;

  • understand that kernel metadata is part of the contract between scientific code and the LFRic infrastructure;

  • know where to look for more technical information when you need it.

See also

For deeper user-level material, start with the PSyclone User Guide. For PSyclone internals, use the PSyclone Developer Guide.

Further reading#

The official PSyclone documentation has more detail: