Merge remote-tracking branch 'origin/master' into 2244_lfric_tiled_co…

…louring

.github/workflows/lfric_test.yml

@@ -73,7 +73,6 @@ jobs:
         # than the latest release from pypi.
         # pip install external/fparser
         pip install .[test]
-        pip install jinja2
 
     # PSyclone, compile and run MetOffice gungho_model on GPU
     - name: LFRic GungHo with OpenMP offload

changelog

@@ -247,6 +247,27 @@
 	Python used in the CI.
 
 	85) PR #2748. Revert Python used on RTD to 3.12 as 3.13 unsupported.
+
+	86) PR #2707 for #257. Fixes bugs in the loop-fusion transformation.
+
+	87) PR #2752 towards #2717. Adds Assignment.is_literal_assignment property.
+
+	88) PR #2753 towards #2717. Adds DataNode.is_character method.
+
+	89) PR #2712 for #2711. Adds support for user-supplied Kernels that
+	operate on dofs (in the LFRic API).
+
+	99) PR #2685 for #2027. Improves datatype and shape inference.
+
+	100) PR #2694 for #2690. Extends the PSyData NaN-checking tooling to
+	perform value verification.
+
+	101) PR #2749 for #2311. Alters test-harness generation for the LFRic
+	API in PSyAD to base the generated test-code filenames on the name of
+	the supplied LFRic Algorithm file.
+
+	102) PR #2763 towards #2717. Upstreams PSyACC functionality: ensures
+	that clauses on an OpenACC directive are consistent.
 
 release 2.5.0 14th of February 2024
 

config/psyclone.cfg

@@ -46,7 +46,7 @@ REPRODUCIBLE_REDUCTIONS = false
 # Amount to pad the local summation array when REPRODUCIBLE_REDUCTIONS is true
 REPROD_PAD_SIZE = 8
 PSYIR_ROOT_NAME = psyir_tmp
-VALID_PSY_DATA_PREFIXES = profile, extract, read_only_verify, nan_test
+VALID_PSY_DATA_PREFIXES = profile, extract, read_only_verify, value_range_check
 
 # Specify number of OpenCL devices per node. When combining OpenCL with MPI,
 # the mpirun/mpiexec ranks_per_node parameter must match this number.

doc/developer_guide/APIs.rst

@@ -48,29 +48,29 @@ TBD
 
 .. Generating API-specific code
 .. ============================
-.. 
+..
 .. This section explains how to create a new API in PSyclone. PSyclone
 .. currently supports the following APIs: lfric and gocean.
-.. 
+..
 .. config.py
 .. ---------
-.. 
+..
 .. The names of the supported APIs and the default API are specified in
 .. ``configuration.py``. When adding a new API you must add the name you would like
 .. to use to the ``_supported_api_list``.
-.. 
+..
 .. parse.py
 .. --------
-.. 
+..
 .. The parser reads the algorithm code and associated kernel metadata.
-.. 
+..
 .. The parser currently assumes that all APIs will use the ``invoke()``
 .. API for the algorithm-to-psy layer but that the content and structure
 .. of the metadata in the kernel code may differ. If the algorithm API
 .. differs, then the parser will need to be refactored. This is beyond
 .. the scope of this document and is currently not considered in the
 .. PSyclone software architecture.
-.. 
+..
 .. The kernel metadata however, will be different from one API to
 .. another. To parse this kernel-API-specific metadata a
 .. ``KernelTypeFactory`` is provided which should return the appropriate
@@ -79,7 +79,7 @@ TBD
 .. in the ``KernelTypeFactory`` class. If the kernel metadata happens to be
 .. the same as another existing API then the existing ``KernelType``
 .. subclass can be used for the new API.
-.. 
+..
 .. The ``KernelType`` subclass needs to specialise the class constructor
 .. and initialise the ``KernelType`` base class with the
 .. supplied arguments. The role of the ``KernelType`` subclass is to create
@@ -88,95 +88,95 @@ TBD
 .. this is appends the kernel-metadata-specific subclass instance is
 .. appended to the ``_arg_descriptors`` list provided by the ``KernelType``
 .. base class.
-.. 
+..
 .. TBC
-.. 
+..
 .. This information
-.. 
+..
 .. KernelType base class assumes kernel metadata stored as a type. Searches for that type.
 .. Checks whether the metadata is public (it should be ?)
 .. Assumes iterates_over variable.
 .. Binding to a procedure - assumes one of two styles.
 .. Assumes a meta_args type
 .. *What about our func_args type???*
-.. 
+..
 .. type x
 .. meta_args=
 .. *meta_func=*
 .. iterates_over=
 .. code => or code =
 .. end type x
-.. 
+..
 .. The descriptor class ...
-.. 
+..
 .. psyGen.py
 .. ---------
-.. 
+..
 .. factory
 .. +++++++
-.. 
+..
 .. A new file needs to be created and the following classes found in
 .. psyGen.py need to be subclassed.
-.. 
+..
 .. PSy, Invokes, Invoke, InvokeSchedule, Loop, Kern, Arguments, Argument
 .. You may also choose to subclass the Inf class if required.
-.. 
+..
 .. The subclass of the PSy class then needs to be added as an option to
 .. the create method in the PSyFactory class.
-.. 
+..
 .. Initialisation
 .. ++++++++++++++
-.. 
+..
 .. The parser information passed to the PSy layer is used to create an
 .. invokes object which in turn creates a list of invoke objects. Each
 .. invoke object contains an InvokeSchedule which consists of loops and
 .. calls. Finally, a call contains an arguments object which itself
 .. contains a list of argument objects.
-.. 
+..
 .. To make sure the subclass versions of the above objects are created
 .. the __init__ methods of the subclasses must make sure they create
 .. the appropriate objects.
-.. 
+..
 .. Some of the baseclass constructors (__init__ methods) support the
 .. classname being provided. This allow them to instantiate the
 .. appropriate objects without knowing what they are.
-.. 
+..
 .. gen_code()
 .. ++++++++++
-.. 
+..
 .. All of the above classes (with the exception of PSy which supports a
 .. gen() method) have the gen_code() method. This method passes the
 .. parent of the generation tree and expect the object to add the code
 .. associated with the object as a child of the parent. The object is
 .. then expected to call any children. This approach is powerful as it
 .. lets each object concentrate on the code that it is responsible for.
-.. 
+..
 .. Adding code in gen_code()
 .. +++++++++++++++++++++++++
-.. 
+..
 .. The f2pygen classes have been developed to help create appropriate
 .. fortran code in the gen_code() method.
-.. 
+..
 .. When writing a gen_code() method for a particular object and API it is
 .. natural to add code as a child of the parent provided by the callee of
 .. the method. However, in some cases we do not want code to appear at
 .. the current position in the hierarchy.
-.. 
+..
 .. The add() method
 .. ++++++++++++++++
-.. 
+..
 .. PSyclone supports this via the add() method
-.. 
+..
 .. explicitly place at the appropriate place in the hierarchy. For example,
 .. parent.parent.add(...)
-.. 
+..
 .. optional argument. default is auto. This attempts to place code in the
 .. expected place. For example, specify a declaration. auto finds a
 .. correct place to put this code.
-.. 
+..
 .. Specify position explicitly
 .. "before", "after", "first", "last"
-.. 
+..
 .. Sometimes don't know exactly where to place. On example that is
 .. supported is when you want to add something before or after a loop
 .. nest. start_parent_loop(). This method recurses up until the parent is
@@ -333,7 +333,7 @@ grey) then we get:
 
 .. image:: dofs_cont_halos.png
 	   :width: 230
-		   
+
 An example for a depth-1 halo implementation with the earlier mesh
 split into 2 partitions is given below, with the halo cells drawn in
 grey and halo dofs coloured red. An example local indexing scheme is
@@ -403,9 +403,9 @@ Loop iterators
 --------------
 
 In the current implementation of the LFRic API it is possible to
-iterate (loop) either over cells or dofs. At the moment all coded
-kernels are written to iterate over cells and all Built-in kernels are
-written to iterate over dofs, but that does not have to be the case.
+iterate (loop) either over cells or dofs. At the moment coded
+kernels can be written to iterate over cells or dofs and all Built-in kernels
+are written to iterate over dofs, but that does not have to be the case.
 
 The loop iteration information is specified in the kernel metadata. In
 the case of Built-ins there is kernel metadata but it is part of
@@ -994,7 +994,7 @@ If an application is being built in parallel then it is possible that
 different invocations of PSyclone will happen simultaneously and
 therefore we must take care to avoid race conditions when querying the
 filesystem. For this reason we use ``os.open``::
-  
+
     fd = os.open(<filename>, os.O_CREAT | os.O_WRONLY | os.O_EXCL)
 
 The ``os.O_CREATE`` and ``os.O_EXCL`` flags in combination mean that
@@ -1020,7 +1020,7 @@ of a given colour may be safely updated in parallel
 	   Example of the colouring of the horizontal cells used to
 	   ensure the thread-safe update of shared dofs (black
 	   circles).  (Courtesy of S. Mullerworth, Met Office.)
-	   
+
 The loop over colours must then be performed sequentially but the loop
 over cells of a given colour may be done in parallel. A loop that
 requires colouring may be transformed using the ``Dynamo0p3ColourTrans``
@@ -1206,13 +1206,13 @@ TBD
 
 .. OpenMP Support
 .. --------------
-.. 
+..
 .. Loop directives are treated as first class entities in the psyGen
 .. package. Therefore they can be added to psyGen's high level
 .. representation of the fortran code structure in the same way as calls
 .. and loops. Obviously it is only valid to add a loop directive outside
 .. of a loop.
-.. 
+..
 .. When adding a call inside a loop the placement of any additional calls
 .. or declarations must be specified correctly to ensure that they are
 .. placed at the correct location in the hierarchy. To avoid accidentally
@@ -1222,7 +1222,7 @@ TBD
 .. f2pygen*.  This method returns the location at the top of any loop
 .. hierarchy and before any comments immediately before the top level
 .. loop.
-.. 
+..
 .. The OpenMPLoopDirective object needs to know which variables are
 .. shared and which are private. In the current implementation default
 .. shared is used and private variables are listed. To determine the
@@ -1233,13 +1233,13 @@ TBD
 .. the directive and adds each calls list of private variables, returned
 .. with the local_vars() method. Therefore the OpenMPLoopDirective object
 .. relies on calls specifying which variables they require being local.
-.. 
+..
 .. Next ...
-.. 
+..
 .. Update transformation for colours
-.. 
-.. OpenMPLoop transformation in transformations.py. 
-.. 
+..
+.. OpenMPLoop transformation in transformations.py.
+..
 .. Create third transformation which goes over all loops in a schedule and
 .. applies the OpenMP loop transformation.
 

doc/developer_guide/system_specific_setup.rst

@@ -180,19 +180,3 @@ Verifying the pylint standards is done with::
 
 
 OK, you're all set up.
-
-Installing Tools for PSyData Wrapper Libraries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If you intend to compile the PSyData wrapper libraries or develop new libraries,
-you might need to install Jinja2 (most wrapper libraries require Jinja2 though
-some, like the NVIDIA GPU profiling wrapper, do not need it). You can install
-the necessary dependencies to create all PSyData wrapper libraries with::
-
-    > pip install psyclone[psydata]
-
-or when using the git version::
-
-    > pip install .[psydata]
-
-
-Check :ref:`psy_data` and especially the section :ref:`jinja` for more details.

doc/user_guide/dynamo0p3.rst

@@ -796,9 +796,6 @@ support for i-first kernels
 point the looping (and associated parallelisation) will be put
 back into the PSy layer.
 
-.. note:: Support for DoF kernels have not yet been implemented in PSyclone
-          (see PSyclone issue #1351 for progress).
-
 .. _lfric-user-kernel-rules:
 
 Rules for all User-Supplied Kernels that Operate on Cell-Columns
@@ -981,9 +978,6 @@ on a ``CELL_COLUMN`` without CMA Operators. Specifically:
 Rules for all User-Supplied Kernels that Operate on DoFs (DoF Kernels)
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-.. note:: Support for DoF kernels have not yet been implemented in PSyclone
-          (see PSyclone issue #1351 for progress).
-
 Kernels that have ``operates_on = DOF`` and
 :ref:`LFRic Built-ins<lfric-built-ins>` overlap significantly in their
 scope, and the conventions that DoF Kernels must follow are influenced
@@ -1015,8 +1009,9 @@ The list of rules for DoF Kernels is as follows:
    to do this.) Any scalar arguments must therefore be declared in the metadata
    as `GH_READ` - see :ref:`below<lfric-kernel-valid-access>`
 
-6) Kernels must be written to operate on a single DoF, such that single DoFs
-   can be provided to the Kernel within a loop over the DoFs of a field.
+6) Kernels must be written to operate on a single DoF, such that field values
+   at the same dof location/index can be provided to the Kernel within a loop
+   over the DoFs of the function space of the field that is being updated.
 
 .. _lfric-api-kernel-metadata:
 
@@ -1889,16 +1884,14 @@ operates_on
 The fourth type of metadata provided is ``OPERATES_ON``. This
 specifies that the Kernel has been written with the assumption that it
 is supplied with the specified data for each field/operator argument.
-For user-supplied kernels this is currently only permitted to be
-``CELL_COLUMN`` or ``DOMAIN``. The possible values for ``OPERATES_ON``
-and their interpretation are summarised in the following table:
+The possible values for ``OPERATES_ON`` and their interpretation are
+summarised in the following table:
 
 ===========  =========================================================
 operates_on  Data passed for each field/operator argument
 ===========  =========================================================
 cell_column  Single column of cells
-dof          Single DoF (currently :ref:`built-ins` only, but see PSyclone
-             issue #1351)
+dof          Single DoF
 domain       All columns of cells
 ===========  =========================================================
 
@@ -2477,9 +2470,6 @@ as the second argument to the kernel (after ``nlayers``).
 Rules for DoF Kernels
 #####################
 
-.. note:: Support for DoF kernels have not yet been implemented in PSyclone
-          (see PSyclone issue #1351 for progress).
-
 The rules for kernels that have ``operates_on = DOF`` are similar to those for
 general-purpose kernels but, due to the restriction that only fields and
 scalars can be passed to them, are much fewer. The full set of rules, along
@@ -2504,12 +2494,6 @@ with PSyclone's naming conventions, are:
          passed in separately. Again, the intent is determined from the
          metadata (see :ref:`meta_args <lfric-api-meta-args>`).
 
-   3) Include the unique number of degrees of freedom for the function space.
-      This is an ``integer`` of kind ``i_def`` with intent ``in``. The name of
-      this argument is simply ``undf`` without a function space suffix (as for
-      general purpose kernels) since all fields will be on the same function
-      space.
-
 .. _lfric-kernel-arg-intents:
 
 Argument Intents