Merge branch 'master' into 2779_split_element_order

.github/workflows/linkcheck.yml

@@ -4,7 +4,8 @@ jobs:
   check-links:
     if: ${{ github.repository != 'stfc/PSyclone-mirror' }}
     name: Run linkspector
-    runs-on: ubuntu-latest
+    # TODO 2838: linkspector doesn't support ubuntu-latest at the moment.
+    runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
       - name: Run linkspector

.github/workflows/python-package.yml

@@ -1,7 +1,7 @@
 # -----------------------------------------------------------------------------
 # BSD 3-Clause License
 #
-# Copyright (c) 2020-2024, Science and Technology Facilities Council.
+# Copyright (c) 2020-2025, Science and Technology Facilities Council.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -36,6 +36,7 @@
 # Modified by A. J. Voysey, Met Office
 # Modified by J. Henrichs, Bureau of Meteorology
 # Modified by N. Nobre, STFC Daresbury Lab
+# Modified by A. B. G. Chalk, STFC Daresbury Lab
 
 # This workflow will install Python dependencies, run tests and lint with a
 # variety of Python versions.
@@ -103,7 +104,8 @@ jobs:
     - run: cd doc/developer_guide; make html; make doctest
   build:
     if: ${{ github.repository != 'stfc/PSyclone-mirror' }}
-    runs-on: ubuntu-latest
+    # TODO 2837: Switch to ubuntu-latest once Python 3.7 support is removed.
+    runs-on: ubuntu-22.04
     strategy:
       matrix:
         python-version: [3.7, 3.8, 3.13]

changelog

@@ -13,6 +13,17 @@
 	AST tree. There are two new FortranReader arguments to select the behaviour
 	for comments and directives (by default they are not parsed).
 
+	5) PR #2836 for #2835. Reverts GHA to use Ubuntu 22.04 as python-3.7
+	not available in ubuntu-latest and linkspector is also broken.
+
+	6) PR #2820 for #2773. Adds support for the Vernier timing library.
+
+	7) PR #2840 for #2839. Raise error in FortranReader if ignore_directives
+	is True but ignore_comments is True.
+
+	8) PR #2832 for #2831. Reorders the arguments to the parser to meet best
+	practices.
+
 release 3.0.0 6th of December 2024
 
 	1) PR #2477 for #2463. Add support for Fortran Namelist statements.

doc/developer_guide/psy_data.rst

@@ -72,8 +72,8 @@ the same time as checking that read-only values are indeed not modified,
 different module names and data types must be used.
 
 PSyData divides its application into different classes. For example,
-the class "profile" is used for all profiling tools (e.g. TAU, DrHook or the
-NVIDIA profiling tools). This class name is used as a prefix for
+the class "profile" is used for all profiling tools (e.g. TAU, Vernier,
+DrHook, or the NVIDIA profiling tools). This class name is used as a prefix for
 the module name, the ``PSyDataType`` and functions. So if a profiling application
 is linked the above code will actually look like this::
 
@@ -101,7 +101,7 @@ The class prefixes supported at the moment are:
 Class Prefix            Description
 ======================= =======================================================
 profile                 All libraries related to profiling tools like TAU,
-                        DrHook, NVIDIA's profiling tools etc. See
+                        DrHook, NVIDIA's profiling tools, Vernier etc. See
                         :ref:`user_guide:profiling` for details.
 extract                 For libraries used for kernel data extraction. See
                         :ref:`user_guide:psyke` for details.
@@ -970,7 +970,7 @@ by storing pointers to the profiling data to be able to
 print all results in a ProfileFinalise() subroutine.
 Some of the wrapper libraries use the PSyData base class (e.g. dl_timer,
 simple_timing, template), others do not (e.g. NVIDIA profiling, TAU,
-DrHook wrapper).
+Vernier, DrHook wrapper).
 
 .. _psyke:
 

doc/user_guide/profiling.rst

@@ -51,9 +51,9 @@ transformation within a transformation script.
 
 
 PSyclone can be used with a variety of existing profiling tools.
-It currently supports dl_timer, TAU, Dr Hook, the NVIDIA GPU profiling
-tools and it comes with a simple stand-alone timer library. The
-:ref:`PSyData API <psy_data>` (see also the
+It currently supports dl_timer, TAU, Vernier, Dr Hook, the NVIDIA GPU
+profiling tools and it comes with a simple stand-alone timer library.
+The :ref:`PSyData API <psy_data>` (see also the
 :ref:`Developer Guide <dev_guide:psy_data>`)
 is utilised to implement wrapper libraries that connect the PSyclone
 application to the profiling libraries. Certain adjustments to
@@ -77,8 +77,8 @@ Interface to Third Party Profiling Tools
 ----------------------------------------
 
 PSyclone comes with :ref:`wrapper libraries <libraries>` to support
-usage of TAU, Dr Hook, dl_timer, NVTX (NVIDIA Tools Extension library),
-and a simple non-thread-safe timing library. Support for further
+usage of TAU, Vernier, Dr Hook, dl_timer, NVTX (NVIDIA Tools Extension
+library), and a simple non-thread-safe timing library. Support for further
 profiling libraries will be added in the future. To compile the
 wrapper libraries, change into the directory ``lib/profiling``
 of PSyclone and type ``make`` to compile all wrappers. If only
@@ -107,23 +107,29 @@ libraries that come with PSyclone:
 ``lib/profiling/dl_timer``
     This wrapper uses the apeg-dl_timer library. In order to use
     this wrapper, you must download and install the dl_timer library
-    from ``https://bitbucket.org/apeg/dl_timer``. This library has
+    from https://bitbucket.org/apeg/dl_timer. This library has
     various compile-time options and may be built with MPI or OpenMP
     support. Additional link options might therefore be required
     (e.g. enabling OpenMP, or linking with MPI).
 
 ``lib/profiling/tau``
     This wrapper uses TAU profiling and tracing toolkit. It can be
-    downloaded from ``https://www.cs.uoregon.edu/research/tau``.
+    downloaded from https://www.cs.uoregon.edu/research/tau.
 
 ``lib/profiling/drhook``
     This wrapper uses the Dr Hook library. You need to contact
     ECMWF to obtain a copy of Dr Hook.
 
+``lib/profiling/vernier``
+    This wrapper uses the UK Met Office's Vernier library. It can be
+    downloaded from https://github.com/MetOffice/Vernier. This
+    library writes its output to files ``vernier-out-<RANK>``, and
+    will overwrite existing output files.
+
 ``lib/profiling/nvidia``
     This is a wrapper library that maps the PSyclone profiling API
     to the NVIDIA Tools Extension library (NVTX). This library is
-    available from ``https://developer.nvidia.com/cuda-toolkit``.
+    available from https://developer.nvidia.com/cuda-toolkit.
 
 ``lib/profiling/lfric_timer``
     This profile wrapper uses the timer functionality provided by

doc/user_guide/tutorials_and_examples.rst

@@ -317,7 +317,7 @@ Example 5.2: Profiling
 This example shows how to use the profiling support in PSyclone.
 It instruments two invoke statements and can link in with any
 of the following profiling wrapper libraries: template,
-simple_timer, dl_timer, TAU, and DrHook (see
+simple_timer, dl_timer, TAU, Vernier, and DrHook (see
 :ref:`profiling_third_party_tools`). The ``README.md``
 file contains detailed instructions on how to build the
 different executables. By default (i.e. just using ``make``

examples/gocean/eg5/profile/.gitignore

@@ -2,3 +2,4 @@ alg.f90
 psy.f90
 profile_test*
 timer.txt
+vernier-output-*

examples/gocean/eg5/profile/Makefile

@@ -87,6 +87,16 @@ drhook:
 			PROFILE_LINK="-L $(DRHOOK_DIR)/build/lib -ldrhook" \
 	        drhook_lib $(NAME).drhook
 
+# Needs to additionally link with the Vernier library
+# As default assume Vernier is installed 'next' to PSyclone
+VERNIER_DIR?=$(ROOT_DIR)/../Vernier
+vernier:
+	$(MAKE) WRAPPER_DIR="$(PROFILE_DIR)/vernier"                \
+	        WRAPPER_NAME="vernier_psy"                          \
+			PROFILE_LINK="-L $(VERNIER_DIR)/local/lib           \
+			-lvernier_f -lvernier_c -lvernier"                  \
+	        $(NAME).vernier
+
 TAU_DIR?=$(ROOT_DIR)/../tau
 # By adding the dependency to INF_LIB here, we will be invoking the original
 # compiler, not tau_f90.sh (since we don't want to instrument the whole
@@ -146,6 +156,9 @@ $(INF_LIB):
 drhook_lib :
 	$(MAKE) DRHOOK_ROOT=$(DRHOOK_DIR) -C $(WRAPPER_DIR)
 
+vernier_lib :
+	$(MAKE) VERNIER_ROOT=$(VERNIER_DIR) -C $(WRAPPER_DIR)
+
 tau_lib :
 	$(MAKE) F90=tau_f90.sh TAU_ROOT=$(TAU_DIR) -C $(WRAPPER_DIR)
 

examples/gocean/eg5/profile/README.md

@@ -17,6 +17,7 @@ profile wrapper libraries:
 - drhook
 - lfric
 - tau
+- vernier
 
 By default (``make`` without an argument) the ``template`` library will 
 be used, which just prints the name of the regions called.
@@ -43,9 +44,9 @@ it yourself, and make sure that the ``tau_f90.sh`` compiler wrapper
 is in your path. The Makefile will automatically call ``tau_f90.sh``, there
 is no need to set ``$F90`` in this case.
 
-If you are using ``dl_timer`` or ``drhook``, you need to compile these
-libraries yourself first, and modify the ``Makefile`` in this directory
-to specify the required linking parameters. The ``Makefile``
+If you are using ``dl_timer``, ``vernier`` or ``drhook``, you need to
+compile these libraries yourself first, and modify the ``Makefile`` in
+this directory to specify the required linking parameters. The ``Makefile``
 supports the following environment variables that can be defined
 to find the various software packages:
 
@@ -70,6 +71,10 @@ The location of the LFRic infrastructure library. It defaults to
 which is the small, stand-alone LFRic infrastructure library that
 is included in PSyclone. In spite of the dependence on LFRic, this
 profiling wrapper library can be used with with any application.
+### VERNIER_DIR
+The location of the Vernier library. It defaults to
+``../../../../../Vernier``, i.e. it is assumed that Vernier is
+installed next to PSyclone.
 
 The makefile here will invoke psyclone with the ``--profile invokes``
 flag, which will add profiling around the two invokes used in the example.

lib/profiling/Makefile

@@ -41,19 +41,20 @@ F90 ?= gfortran
 F90FLAGS ?= -g
 # -----------------------------------------------------------------------------
 
-# We don't build dl_timer, drhook, nvidia, and tau since they require
-# external libraries to be available.
+# We don't build dl_timer, drhook, nvidia, Vernier, and tau by default
+# since they require external libraries to be available.
 ALL_LIBS = lfric_timer simple_timing template
 
-.PHONY: default all $(ALL_LIBS) clean allclean
+.PHONY: default all $(ALL_LIBS) clean allclean \
+	dl_timer drhook nvidia tau vernier
 
 default: all
 
 all: $(ALL_LIBS)
 
 # Invoke make in the corresponding subdirectory, and also support
 # the wrapper that need additional software to be installed
-$(ALL_LIBS) dl_timer drhook nvidia tau:
+$(ALL_LIBS) dl_timer drhook nvidia tau vernier:
 		$(MAKE) -C $@
 
 clean:
@@ -62,7 +63,8 @@ clean:
 allclean: clean
 	# These libs are not cleaned by 'clean' (since they
 	# depend on external libraries)
-	$(MAKE) -C nvidia clean
-	$(MAKE) -C drhook clean
 	$(MAKE) -C dl_timer clean
+	$(MAKE) -C drhook clean
+	$(MAKE) -C nvidia clean
 	$(MAKE) -C tau clean
+	$(MAKE) -C vernier clean

lib/profiling/README.md

@@ -86,6 +86,32 @@ Example output:
     =============================================================================
 ```
 
+### [Vernier](./vernier)
+
+This wrapper library interfaces with UK Met Office's [Vernier library](
+https://github.com/MetOffice/Vernier). Detailed building and linking
+instructions are in [``vernier/README.md``](
+./vernier/README.md).
+
+Note that Vernier writes the output to one file per MPI rank, called
+e.g. `vernier-output-0`. Example profiling output:
+
+```
+$ less vernier-output-0
+Profiling on 8 thread(s).
+
+    #  % Time         Cumul         Self        Total     # of calls        Self   Total    Routine@
+                                                                             (Size; Size/sec; Size/call; MinSize; MaxSize)
+        (self)        (sec)        (sec)        (sec)                    ms/call   ms/call
+
+    1  100.000        1.496        1.496        1.496              1    1496.066    1496.066    skeleton_constants_mod_psy:invoke_create_de_rham_matrices-compute_derham_matrices_code-r0@0
+    2    0.425        1.502        0.006        0.006              5       1.271       1.271    lfric_xios_setup_mod_psy:invoke_1_nodal_coordinates_kernel_type-nodal_coordinates_code-r1@0
+    3    0.368        1.508        0.006        0.006             10       0.550       0.550    skeleton_alg_mod_psy:invoke_compute_divergence-matrix_vector_code-r2@0
+    4    0.318        1.513        0.005        0.005              1       4.754       4.754    lfric_xios_setup_mod_psy:invoke_0_nodal_xyz_coordinates_kernel_type-nodal_xyz_coordinates_code-r0@0
+...
+
+```
+
 ### [Dr Hook](./drhook)
 
 This wrapper library interfaces with the ECMWF Dr Hook library. This

lib/profiling/drhook/README.md

@@ -64,10 +64,6 @@ The compilation process will create the wrapper library ``libdrhook_psy.a``.
 
 ### Linking the wrapper library
 
-In order to use the wrapper with your application, you must provide the
-location of the wrapper as an ``include`` path (so that the module file is found),
-and link first with the wrapper library, then the DrHook library:
-
 In order to use the wrapper with your application, the location of this
 library must be provided as an ``include`` path (so that the module file
 is found), and linked first with the wrapper library, ``drhook_psy``,

lib/profiling/vernier/.gitignore

@@ -0,0 +1 @@
+libdrhook_psy.a

lib/profiling/vernier/Makefile

@@ -0,0 +1,69 @@
+# -----------------------------------------------------------------------------
+# BSD 3-Clause License
+#
+# Copyright (c) 2019-2024, 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
+# Modified I. Kavcic, Met Office
+
+# ----------- Default "make" values, can be overwritten by the user -----------
+# Compiler and compiler flags
+F90 ?= gfortran
+F90FLAGS ?=
+# Path to the Vernier installation. It defaults to the assumed location
+# of the Vernier directory next to a clone of PSyclone repository.
+# Overwrite for a custom location.
+VERNIER_ROOT ?= ./../../../../Vernier
+# Path to the Vernier "include" files. Overwrite for a custom location.
+VERNIER_MODULES ?= $(VERNIER_ROOT)/local/include
+# -----------------------------------------------------------------------------
+
+F90FLAGS += -I$(VERNIER_MODULES)
+
+PSYDATA_LIB_NAME = vernier_psy
+PSYDATA_LIB = lib$(PSYDATA_LIB_NAME).a
+
+OBJS = vernier_psy.o
+
+default: $(PSYDATA_LIB)
+
+.PHONY: default clean allclean
+
+$(PSYDATA_LIB): $(OBJS)
+	ar rs $(PSYDATA_LIB) $(OBJS)
+
+%.o: %.f90
+	$(F90) $(F90FLAGS) -c $<
+
+clean:
+	rm -f *.o *.mod $(PSYDATA_LIB)
+
+allclean: clean