Merge branch 'master' into 1280_ref_guide_warnings

.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"
+    # TODO #1280: - 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

@@ -275,6 +275,10 @@
 	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.
+
 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

@@ -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

doc/user_guide/conf.py

@@ -39,7 +39,9 @@
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
               'sphinx.ext.intersphinx', 'sphinx.ext.coverage',
               'sphinx.ext.imgmath', 'sphinx.ext.viewcode',
-              'sphinxcontrib.bibtex', 'apilinks']
+              'sphinxcontrib.bibtex', 'sphinx_tabs.tabs',
+              'apilinks',
+              ]
 bibtex_bibfiles = ['../bibliography/references.bib']
 
 # GITHUB_PR_NUMBER is set in .github/workflows/python-package.yml when

doc/user_guide/dynamo0p3.rst

@@ -73,19 +73,21 @@ The general requirements for the structure of an Algorithm are explained
 in the :ref:`algorithm-layer` section. This section explains the
 LFRic-API-specific specialisations and extensions.
 
-.. _lfric-example:
-
-Example
-+++++++
-
-An example LFRic API invoke call is given below with various
-different types of objects supported by the API. These different
-objects and their use are discussed in the following sections.
+The LFRic API defines a set of objects, with specific meanings and
+data-structures, that can be provided as arguments to Kernels within
+invoke calls. These are: :ref:`scalar <lfric-scalar>`,
+:ref:`field <lfric-field>`, :ref:`field vector <lfric-field-vector>`,
+:ref:`operator <lfric-operator>`,
+:ref:`column-wise operator <lfric-cma-operator>`,
+:ref:`Quadrature <lfric-quadrature>`,
+:ref:`Halo Depth <lfric-halo-depth>` and
+:ref:`Stencil Extents <lfric-alg-stencil>`. The example below showcases the
+use of each of these arguments:
 
 ::
 
   real(kind=r_def)           :: rscalar
-  integer(kind=i_def)        :: iscalar
+  integer(kind=i_def)        :: iscalar, halo_depth
   logical(kind=l_def)        :: lscalar
   integer(kind=i_def)        :: stencil_extent
   type(field_type)           :: field1, field2, field3
@@ -99,26 +101,25 @@ objects and their use are discussed in the following sections.
                builtin1(rscalar, field2, field3),                &
                int_builtin2(iscalar, field7),                    &
                kernel2(field1, stencil_extent, field3, lscalar), &
+	       kernel3(field1, halo_depth),                      &
                assembly_kernel(cma_op1, operator1),              &
-               name="some_calculation"                           &
-             )
-  call invoke( prolong_kernel_type(field1, field4),              &
-               restrict_kernel_type(field5, field6)
-             )
+               name="some_calculation")
 
-Please see the :ref:`algorithm-layer` section for a description of the
-``name`` argument.
+Each of these argument types is described in more detail in
+the next :ref:`section <lfric-alg-arg-types>`.
 
-Objects in the LFRic API can be categorised by their functionality
-as data structures and information that specifies supported operations on
-a particular data structure. These data structures are represented by the
-five LFRic API argument types: :ref:`scalar <lfric-scalar>`,
-:ref:`field <lfric-field>`, :ref:`field vector <lfric-field-vector>`,
-:ref:`operator <lfric-operator>` and :ref:`column-wise operator
-<lfric-cma-operator>`. All of them except the field vector are
-represented in the above example. ``qr`` represents a quadrature object
-which provides information required by a kernel to operate on fields
-(see section :ref:`lfric-quadrature` for more details).
+The LFRic API has support for inter-grid kernels (those that
+map fields between grids of different resolution). At the Algorithm
+layer, an ``invoke`` of such kernels looks much like an
+``invoke`` containing general-purpose kernels. The only restrictions to be
+aware of are that inter-grid kernels accept only field or field-vectors
+as arguments and that an ``invoke`` may not mix inter-grid kernels with
+any other kernel type.
+
+.. _lfric-alg-arg-types:
+
+Algorithm Argument Types
+------------------------
 
 .. _lfric-scalar:
 
@@ -250,7 +251,9 @@ information (specified using e.g. ``gh_shape = gh_quadrature_XYoZ`` in
 the kernel metadata - see Section :ref:`lfric-gh-shape`). This
 information must be passed to the kernel from the Algorithm layer in
 the form of one or more ``quadrature_type`` objects. These must be the
-last arguments passed to the kernel and must be provided in the same
+last arguments passed to the kernel (with the exception of ``halo_depth``
+- :ref:`lfric-halo-depth` - if the kernel requires it) and must be
+provided in the same
 order that they are specified in the kernel metadata, e.g. if the
 metadata for kernel ``pressure_gradient_kernel_type`` specified
 ``gh_shape = gh_quadrature_XYoZ`` and that for kernel
@@ -268,10 +271,19 @@ invoke would look something like::
 These quadrature objects specify the set(s) of points at which the
 basis/differential-basis functions required by the kernel are to be evaluated.
 
+.. _lfric-halo-depth:
+
+Halo Depth
+++++++++++
+
+If a Kernel is written to iterate into the halo (has an ``OPERATES_ON`` of
+``HALO_CELL_COLUMN`` or ``OWNED_AND_HALO_CELL_COLUMN``) then the halo depth
+must be passed as a final, ``integer`` argument to the Kernel.
+
 .. _lfric-alg-stencil:
 
-Stencils
-++++++++
+Stencil Extent
+++++++++++++++
 
 The metadata for a Kernel which operates on a cell-column may specify
 that a Kernel performs a stencil operation on a field. Any such
@@ -280,8 +292,8 @@ metadata must provide a stencil type. See the
 stencil types are ``X1D``, ``Y1D``, ``XORY1D``, ``CROSS``, ``CROSS2D`` or
 ``REGION``.
 
-If a stencil operation is specified by the Kernel metadata the
-algorithm layer must provide the ``extent`` of the stencil (the
+If a stencil operation is specified by the Kernel metadata, the
+Algorithm layer must provide the ``extent`` of the stencil (the
 maximum distance from the central cell that the stencil extends). The
 LFRic API expects this information to be added as an additional
 ``integer`` argument immediately after the relevant field when specifying
@@ -374,17 +386,6 @@ For example, running test 19.2 from the LFRic API test suite gives:
   "Generation Error: error: expected '5' arguments in the algorithm layer but found '4'.
   Expected '4' standard arguments, '1' stencil arguments and '0' qr_arguments'"
 
-Inter-grid
-++++++++++
-
-From the Algorithm layer, an Invoke for inter-grid kernels (those that
-map fields between grids of different resolution) looks much like an
-Invoke containing general-purpose kernels. The only restrictions to be
-aware of are that inter-grid kernels accept only field or field-vectors
-as arguments and that an Invoke may not mix inter-grid kernels with
-any other kernel type. (Hence the second, separate Invoke in the
-example Algorithm code given at the beginning of this Section.)
-
 .. _lfric-mixed-precision:
 
 Mixed Precision
@@ -1887,13 +1888,21 @@ is supplied with the specified data for each field/operator argument.
 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
-domain       All columns of cells
-===========  =========================================================
+============================== =======================================================
+operates_on                    Data passed for each field/operator argument
+============================== =======================================================
+``cell_column``                Single column of cells from the owned region (except
+                               when performing an INC operation on continuous fields
+			       when it will include one level of halo cells).
+``halo_cell_column``           Single column of cells exclusively from halo region.
+``owned_and_halo_cell_column`` Single column of cells but iteration space will include
+                               both owned and halo regions.
+``dof``                        Single DoF .
+``domain``                     All columns of cells in the (sub-)domain.
+============================== =======================================================
+
+(For a description of the concepts of 'owned' and 'halo' cells please see the
+:ref:`dev_guide:lfric-developers`.)
 
 procedure
 #########