Merge remote-tracking branch 'origin/master' into 2727_conditional_ac…

…cesses

.github/workflows/compilation.yml

@@ -130,5 +130,5 @@ jobs:
         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/nemo run
-        make -C tutorial/practicals/nemo/4_nemo_openacc acc_test
+        F90=nvfortran F90FLAGS="-acc -Minfo=all -Mnofma -O2" make -C tutorial/practicals/generic run
+        make -C tutorial/practicals/generic/4_openacc acc_test

.github/workflows/python-package.yml

@@ -52,7 +52,7 @@ on:
   workflow_dispatch:
 
 jobs:
-  sphinx-link-check:
+  build-documentation:
     if: ${{ github.repository != 'stfc/PSyclone-mirror' }}
     # Check all Sphinx documentation for dead links.
     runs-on: ubuntu-latest
@@ -66,11 +66,18 @@ jobs:
     - run: sudo apt-get install -y graphviz doxygen
     - run: python -m pip install --upgrade pip
     - run: pip install .[doc]
+    # First we need to build the docs and launch a server, otherwise the
+    # intershpinx links would be broken
     - run: cd doc/user_guide; make html
     - run: cd doc/developer_guide; make html
     - run: cd doc/reference_guide; make html
     - run: cd doc/psyad/user_guide; make html
     - run: cd doc; python -m http.server &
+    # Now we can check for warnings and broken links
+    - run: cd doc/user_guide; make html SPHINXOPTS="-W --keep-going"
+    - run: cd doc/developer_guide; make html SPHINXOPTS="-W --keep-going"
+    - run: cd doc/reference_guide; make html SPHINXOPTS="-W --keep-going"
+    - run: cd doc/psyad/user_guide; make html SPHINXOPTS="-W --keep-going"
     - run: cd doc/user_guide; make linkcheck
     - run: cd doc/developer_guide; make linkcheck
     - run: cd doc/reference_guide; make linkcheck

changelog

@@ -250,6 +250,37 @@
 
 	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.
+
+	103) PR #2734 towards #2704. Implements the forward_dependency part of
+	the new DefinitionUseChain PSyIR tool.
+
+	104) PR #2761 for #2739. Updates the signature of the PSyKAl
+	transformation script to accept a PSyIR node.
+
+	105) PR #2745 for #2661. Add support for kernels that operate on halos.
+
+	106) PR #2770 towards #2543. Improve UG introduction.
+
+	107) PR #2776 for #1280. Fixes ref_guide warnings.
+
 release 2.5.0 14th of February 2024
 
 	1) PR #2199 for #2189. Fix bugs with missing maps in enter data

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
@@ -235,7 +235,9 @@ An example for a depth-1 halo implementation with the earlier mesh
 split into 2 partitions is given below, with the halo cells being
 coloured red. An example local indexing scheme is also provided below
 the cells. Notice the local indexing scheme is set up such that owned
-cells have lower indices than halo cells.
+cells have lower indices than halo cells, the first halo cell starts
+immediately after the last owned cell, and the cell indices are
+contiguous.
 
 .. image:: cells_distributed.png
 	   :width: 200
@@ -333,7 +335,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 +405,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 +996,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 +1022,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 +1208,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 +1224,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 +1235,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/dependency.rst

@@ -662,3 +662,29 @@ can be parallelised:
     :hide:
 
     Error: The write access to 'a(i,i)' and the read access to 'a(i + 1,i + 1)' are dependent and cannot be parallelised. Variable: 'a'.
+
+DefinitionUseChain
+==================
+PSyclone also provides a DefinitionUseChain class, which can search for forward
+dependencies (backward NYI) for a given Reference inside a region of code. This
+implementation differs from the DependencyTools as it is control-flow aware, so
+can find many dependencies for a single Reference in a given Routine or scope.
+
+This is primarily used to implement the `References.next_accesses` function, but can be
+used directly as follows:
+
+.. code::
+
+    chain = DefinitionUseChain(reference)
+    accesses = chain.find_forward_accesses()
+    # accesses contains Nodes that are dependent on reference
+    accesses[0].....
+
+By default the dependencies will be searched for in the containing Routine.
+
+Limitations
+-----------
+At the moment the DefinitionUseChain assumes that any control flow could not be taken, i.e.
+any code inside a Loop or If statement is not guaranteed to occur. These dependencies
+will be found, but will not limit further searching into the tree.
+Additionally, GOTO statements are not supported and if found, will throw an Exception.