1623 add training

.github/workflows/compilation.yml

@@ -138,6 +138,11 @@ jobs:
         module load gcc/${GFORTRAN_VERSION} openmpi/${OPENMPI_VERSION}
         module load hdf5/${HDF5_VERSION} netcdf-c/${NETCDF_C_VERSION} netcdf-fortran/${NETCDF_FORTRAN_VERSION}
         make -C tutorial/practicals compile
+        # Set F90 to mpif90 so the MPI example works, and it also avoids
+        # that the openacc example defaults to nvfoetran. Also, the implicitly
+        # defined F90FLAGS (in a module?) does not include -fopenmp, which
+        # then causes some examples to fail, so explicitly define this
+        USE_GPU=no F90=mpif90 F90FLAGS="-g -Wall -O0 -fopenmp" make -C tutorial/training/ test_run
     - name: Examples with compilation - nvfortran
       run: |
         . .runner_venv/bin/activate
@@ -150,10 +155,18 @@ jobs:
       run: |
         . .runner_venv/bin/activate
         make -C tutorial/practicals allclean
+        make -C tutorial/training allclean
         module load nvidia-hpcsdk/${NVFORTRAN_VERSION}
         module load hdf5/${HDF5_VERSION} netcdf-c/${NETCDF_C_VERSION} netcdf-fortran/${NETCDF_FORTRAN_VERSION}
         F90=nvfortran F90FLAGS="-acc -Minfo=all" make -C tutorial/practicals/LFRic compile
         F90=nvfortran F90FLAGS="-acc -Minfo=all -Mnofma -O2" make -C tutorial/practicals/generic run
+        # We cannot run non-GPU examples with the openacc flag, since output_field
+        # needs a openacc directive, which fails if the rest of the code is not on GPU
+        # Enable OpenMP on CPU (for some run tests)
+        USE_GPU=no F90=mpif90 F90FLAGS="-mp -Minfo=all" make -C tutorial/training test_run
+        # Delete any previous files, and compile the openacc example with openacc:
+        F90=nvfortran F90FLAGS="-acc -Minfo=all" make -C tutorial/training/gocean/2.14-GameOfLife-openacc/solution allclean
+        USE_GPU=yes F90=nvfortran F90FLAGS="-acc -Minfo=all" make -C tutorial/training/gocean/2.14-GameOfLife-openacc/solution test_run
         make -C tutorial/practicals/generic/4_openacc acc_test
     - name: Test logfile creation.
       run: |

.github/workflows/python-package.yml

@@ -122,6 +122,7 @@ jobs:
           ( make -C tutorial/practicals transform > /dev/null )
           # Jupyter notebooks are out-of-date
           # ( make -C tutorial/notebooks notebook )
+          ( make -C tutorial/training test )
       - name: Test with pytest
         if: ${{ !(matrix.python-version == '3.9') }}
         run: |

changelog

@@ -1,3 +1,6 @@
+   33) PR #3145 for #1623. Adds extensive training material using both the
+   GOcean and LFRic APIs.
+
    32) PR #3299 for #3297. Fix intermittent test failures by more consistent
    use of str and Path in the ModuleManager.
 

doc/psyad/user_guide/.gitignore

@@ -0,0 +1 @@
+_build

examples/lfric/eg17/full_example/main.x90

@@ -37,18 +37,11 @@ program main
     use global_mesh_mod,        only: global_mesh_type
     use mesh_mod,               only: mesh_type, PLANE
     use local_mesh_mod,         only: local_mesh_type
-    use local_mesh_collection_mod, only: local_mesh_collection, local_mesh_collection_type
     use mesh_collection_mod,    only: mesh_collection, mesh_collection_type
-    use halo_routing_collection_mod,   only: halo_routing_collection_type,   &
-                                           halo_routing_collection
-    use function_space_collection_mod, only: function_space_collection_type, &
-                                           function_space_collection
     use driver_collections_mod, only: init_collections
-
     use partition_mod,          only: partition_type, partitioner_planar, partitioner_interface
     use extrusion_mod,          only: extrusion_type, uniform_extrusion_type
     use function_space_mod,     only: function_space_type
-    use function_space_collection_mod, only: function_space_collection
     use fs_continuity_mod,      only: W0, W1, W2, W2V, W2H
     use field_mod,              only: field_type, field_proxy_type
     use field_real64_mod,      only : field_real64_type

examples/lfric/eg17/full_example_extract/main.X90

@@ -49,18 +49,11 @@ program main
     use global_mesh_mod,        only: global_mesh_type
     use mesh_mod,               only: mesh_type, PLANE
     use local_mesh_mod,         only: local_mesh_type
-    use local_mesh_collection_mod, only: local_mesh_collection, local_mesh_collection_type
-    use mesh_collection_mod,    only: mesh_collection, mesh_collection_type
-    use halo_routing_collection_mod,   only: halo_routing_collection_type,   &
-                                           halo_routing_collection
-    use function_space_collection_mod, only: function_space_collection_type, &
-                                           function_space_collection
+    use mesh_collection_mod,    only: mesh_collection
     use driver_collections_mod, only: init_collections
-
     use partition_mod,          only: partition_type, partitioner_planar, partitioner_interface
     use extrusion_mod,          only: extrusion_type, uniform_extrusion_type
     use function_space_mod,     only: function_space_type
-    use function_space_collection_mod, only: function_space_collection
     use fs_continuity_mod,      only: W0, W1, W2, W2V, W2H
     use field_mod,              only: field_type, field_proxy_type
     use field_real64_mod,      only : field_real64_type
@@ -93,7 +86,10 @@ program main
     type(field_type)                           :: chi(3)
     real(kind=r_def)                           :: one
     logical(kind=l_def)                        :: some_logical
-    integer                                    :: i, ierr
+    integer                                    :: i
+#ifdef _MPI
+    integer                                    :: ierr
+#endif
 
 
 

src/psyclone/tests/domain/common/driver_creator_test.py

@@ -51,6 +51,21 @@
 from psyclone.tests.utilities import Compile, get_invoke
 
 
+# ----------------------------------------------------------------------------
+def test_lfric_driver_valid_unit_name():
+    '''Tests that we create valid unit names, i.e. less than 64 characters,
+    and no ":" in name.'''
+
+    long_name = "A"*100
+    new_name = DriverCreator._make_valid_unit_name(long_name)
+    assert new_name == "A"*63
+
+    special_characters = "aaa-bbb"
+    new_name = DriverCreator._make_valid_unit_name(special_characters)
+    assert new_name == "aaabbb"
+
+
+# ----------------------------------------------------------------------------
 def test_basic_driver_add_call(fortran_writer):
     '''Tests that adding a call detects errors and adds calls
     with and without parameters as expected.

tutorial/README.md

@@ -0,0 +1,21 @@
+# PSyclone Tutorials
+
+This directory contains tutorials and trainings material for PSyclone.
+
+## Notebooks (directory `notebooks`)
+This directory contains three notebooks, that can be executed in
+a web browser. Instructions are included in the `notebooks` directory.
+
+## Practicals (directory `practicals`)
+This is a selection of hands-on trainings material covering some
+parts of LFRic, and PSyclone's generic code transformation abilities.
+
+## Advanced PSyclone Training (directory `training`)
+This directory contains the hands-on parts of a two-day PSyclone
+training course for HPC experts. It is intended for HPC experts,
+i.e. specialist who will be writing optimisations scripts.
+It covers both PSyclone's GOcean and LFRic domains, including an
+introduction to writing code using PSyclone's DSL capabilities,
+and transforming the code. It also contains a section about generic
+code transformations, and advanced topics such as data dependencies
+and using symbolic maths.

tutorial/training/Makefile

@@ -0,0 +1,53 @@
+# -----------------------------------------------------------------------------
+# BSD 3-Clause License
+#
+# Copyright (c) 2023-2026, Science and Technology Facilities Council.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+# * Neither the name of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+# COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# ------------------------------------------------------------------------------
+# Author: J. Henrichs, Bureau of Meteorology
+
+# The Makefile target `test` runs tests on the gitlab CI (i.e. without
+# compilation), `test_run` will compile all binaries (as far as possible
+# since some examples cannot be compiled), and execute the binary (and
+# if tests are available for checking the binary they will be triggered
+# as well). In case that an example cannot be compiled, `test_run` will
+# still execute all `test` targets. So, `test_run` is the most complete
+# set of tests (and is executed as part of PSyclone's integration tests).
+# The `clean` target removes all temporary files (e.g. transformed code,
+# object # and mod files). Using `allclean` will additionally clean all
+# libraries (e.g. infrastructure, psydata).
+
+.PHONY: allclean clean test test_run
+
+allclean clean test test_run:
+	$(MAKE) -C lfric_users $@
+	$(MAKE) -C gocean $@
+	$(MAKE) -C transformation $@
+	$(MAKE) -C lfric $@

tutorial/training/README.rst

@@ -0,0 +1,92 @@
+PSyclone Training
+=================
+
+This is the training material for the usage of PSyclone, a code
+transformation and generator tool. PSyclone was originally developed
+for the UK Met Office’s new LFRic numerical weather prediction system,
+but its features of modifying large codes based on scripts have found
+other use cases, for example NOAA’s Tsunami model MOST (Method of
+Splitting Tsunamis) and Nemo (Nucleus for European Modelling of the
+Ocean) are both using it.
+
+There are three different user groups that
+will be using PSyclone. Firstly, research who will be using any model
+that uses PSyclone for code transformation will see PSyclone being used
+during the build process, and in case of errors might need to be able
+to have a very high-level understanding to diagnose the reason for the
+error. Secondly, natural scientists who want to write code using the
+code generation capabilities will need to be aware of PSyclone’s rules.
+Lastly, HPC experts who are writing recipes (or scripts) to optimise
+code need to have a much deeper understanding of PSyclone’s internal
+data structure, behaviour and features.
+
+The 2-day training course is a sequence of presentations, followed
+by a hands-on session to allow the trainees to try the concepts
+introduced in a simple test case. Some of the hands-on sessions are
+more open ended, and trainees are encouraged to go back to these
+examples and implement better solutions later.
+
+The training material is split into four parts, and the files
+and documentation here are only the hands-on section. The full
+training is accompanied by presentations
+(a slightly outdated version of the slides are available on the `wiki
+<https://github.com/stfc/PSyclone/wiki/Presentations>`_,
+we are working on updating these, see ticket #3270). It
+contains the following sessions (in the order in which they are presented):
+
+
+PSyclone for LFRic Users
+------------------------
+This introductory session is “PSyclone for LFRic Users”, which
+is part of the official LFRic training. It can be used
+stand-alone to introduce anyone working with LFRic to what PSyclone
+is and what it does. But it is also a valuable
+introduction for HPC experts, and as such is included here.
+The hands-on session is in the directory
+``tutorial/training/psyclone_for_lfric_users``.
+
+PSyclone GOcean DSL
+-------------------
+The material in ``tutorial/training/gocean`` contains an
+introduction to PSyclone domain-specific-language features (DSL).
+It uses the easier ``gocean`` API to introduce the user to
+writing kernels, applying transformations, and writing
+transformation scripts. It is the longest session in this training
+material and will take one full day.
+
+Transforming existing Fortran code with PSyclone
+------------------------------------------------
+PSyclone can also be used as a transformation tool for generic
+Fortran code, i.e. not using its DSL code-creation features.
+The material in ``tutorial/training/transformation`` contains
+material related to transforming existing Fortran code.
+
+PSyclone LFRic DSL
+------------------
+This section introduces the LFRic DSL. This DSL is a lot more
+complex than the GOcean API used previously. Many of the concepts
+from the previous sections will apply without modifications, but
+due to the more complex data structures this DSL uses, it's
+harder to understand.
+
+Testing the Training Material
+=============================
+The different training sections provide makefiles for the users
+which contain convenient shortcuts to avoid that a user has
+to type long command line options and file paths. However, these targets
+are expected to fail in some cases, e.g. the "PSyclone
+for LFRic Users" section contains examples that show how PSyclone
+will detect errors. In order to facilitate consistent testing
+across the whole training material, the makefiles contain two special
+targets:
+
+- `test` This will run any tests that will only use transformations.
+  E.g. no compilation will be done here (nor running any compiled
+  binaries). If a hands-on session is supposed to show a failure,
+  the `test` target will test that the expected error message
+  is indeed shown.
+- `test_run` This target will compile binaries if possible, and run
+  the binary to validate the output. This will always include any
+  tests done by the `test` target (i.e. even if an example cannot
+  be compiled or run, the transformation process will be tested,
+  including checking for expected error messages).

tutorial/training/gocean/.gitignore

@@ -0,0 +1,5 @@
+gol
+2*/time_step_alg_mod.f90
+2*/time_step_alg_mod_psy.f90
+2*/solution/time_step_alg_mod.f90
+2*/solution/time_step_alg_mod_psy.f90

tutorial/training/gocean/2.10-GameOfLife-mpi/Makefile

@@ -0,0 +1,24 @@
+EXE = gol
+API = gocean
+
+# The MPI flag is used to indicate if a MPI enabled compiler is used.
+# If not, the transformations will still use distributed memory, but
+# compilation will be disabled.
+MPI ?= yes
+F90 ?= mpif90
+
+# Trigger the flag -dm, and linking of MPI library in common.mk:
+USE_MPI = yes
+SCRIPT ?= openmp.py
+include ../common.mk
+
+run: $(EXE)
+	mpirun -np 4 ./$(EXE) ../gol-lib/config.glider
+
+# Call the default test (which checks the output file), but do a second test to make
+# sure we get a 2x2 domain decomposition, otherwise the job was not running properly
+# with MPI
+test: test-default
+	@bash -c "if [[ $$(make run | grep -c 'go_decompose: using grid of   2x  2') != 1 ]]; then \
+		echo 'Job is not running properly with MPI'; \
+	fi"