diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index 4faf6ab39d..2979d39d1f 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -66,7 +66,7 @@ jobs: - run: sudo apt-get install -y graphviz doxygen - run: python -m pip install --upgrade pip - run: pip install .[doc] - # First we need a first build and launching a server, otherwise the + # 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 @@ -76,7 +76,7 @@ jobs: # 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 + # 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 diff --git a/doc/user_guide/getting_going.rst b/doc/user_guide/getting_going.rst index 90e250e8ad..2627dbf43d 100644 --- a/doc/user_guide/getting_going.rst +++ b/doc/user_guide/getting_going.rst @@ -47,11 +47,12 @@ Installation The following instructions are intended for a PSyclone user who wants to work with a released version of the code. If you are a developer or wish to test a specific branch of PSyclone from the GitHub repository -please see :ref:`Installation section in the Developer Guide `. +please see the +:ref:`Installation section in the Developer Guide `. .. tabs:: - .. tab:: from PyPI + .. tab:: From PyPI: For a system-wide installation use: @@ -73,10 +74,10 @@ please see :ref:`Installation section in the Developer Guide ` For more information about using ``pip`` or encapsulating the installation - in its own ``virtual environment`` we recomment reading the + in its own ``virtual environment`` we recommend reading the `Python Packaging User Guide `_. - .. tab:: from Spack + .. tab:: From Spack: To install psyclone to your loaded Spack installation use: @@ -85,10 +86,10 @@ please see :ref:`Installation section in the Developer Guide ` spack install psyclone - For more information about how to use Spack we recommend readign the + For more information about how to use Spack we recommend reading the `Spack documentation `_. - .. tab:: from Source + .. tab:: From Source: To download and install a specific PSyclone release (where ``X.Y.Z`` is the release version) from source, use: @@ -106,8 +107,8 @@ please see :ref:`Installation section in the Developer Guide ` Installation location ^^^^^^^^^^^^^^^^^^^^^ -PSyclone installation location will vary depending on the specific installation -method and options used. The ``pyclone`` command will typically already be +The PSyclone installation location will vary depending on the specific installation +method and options used. The ``psyclone`` command will typically already be prepended to your ``PATH`` after following the instructions above, but sometimes you will need to source the virtual environment or load the Spack module again after restarting your terminal. @@ -125,20 +126,20 @@ directory relative to the psyclone installation. You can replace Configuration ------------- -Various aspects of PSyclone are configured through a configuration +Various aspects of PSyclone are controlled through a configuration file, ``psyclone.cfg``. The default version of this file is located in the ``share/psyclone/psyclone.cfg`` file in the :ref:`getting-going-install-loc`. .. warning:: - If PSyclone is installed in 'editable' mode (``-e`` flag to ``pip``), ``pip`` + If PSyclone is installed in 'editable' mode (``-e`` flag to ``pip``), or in a non-standard location, then PSyclone will not be able to find the default configuration file. There are two solutions to this: 1. copy a configuration file to the location specified above. - 2. set the ``PSYCLONE_CONFIG`` environment variable to the full-path to - the configuration file, e.g.: + 2. set the ``PSYCLONE_CONFIG`` environment variable (or the ``--config`` + flag) to the full-path to the configuration file, e.g.: .. code-block:: bash @@ -212,7 +213,7 @@ There is more detailed information about each flag in :ref:`psyclone_command` se but the main parameters are the input source file that we aim to transform, and a transformation recipe that is provided with the ``-s`` flag. In addition to these, note that psyclone can be used in two distinct modes: -the code-transformation mode (when no ``-api``/``--psykal-dsl`` flags is provided) or the +the code-transformation mode (when no ``-api``/``--psykal-dsl`` flags are provided) or the PSyKAl DSL mode (when a ``-api``/``--psykal-dsl`` flag is provided). The following sections provide a brief introduction to each mode. diff --git a/doc/user_guide/transformations.rst b/doc/user_guide/transformations.rst index 18ccf5f86b..e810925c4e 100644 --- a/doc/user_guide/transformations.rst +++ b/doc/user_guide/transformations.rst @@ -134,8 +134,9 @@ can be found in the API-specific sections). .. note:: PSyclone currently only supports OpenCL and KernelImportsToArguments transformations for the GOcean 1.0 API, the OpenACC Data transformation is limited to - the NEMO and GOcean 1.0 APIs and the OpenACC Kernels - transformation is limited to the NEMO and LFRic (Dynamo0.3) APIs. + the generic code transformation and the GOcean 1.0 API and the + OpenACC Kernels transformation is limited to the generic code + transformation and the LFRic API. .. note:: The directory layout of PSyclone is currently being restructured. As a result of this some transformations are already in the new @@ -1049,9 +1050,9 @@ As well as ensuring the correct data is copied to and from the remote device, OpenACC directives must also be added to a code in order to tell the compiler how it should be parallelised. PSyclone provides the ``ACCKernelsTrans``, ``ACCParallelTrans`` and ``ACCLoopTrans`` -transformations for this purpose. The simplest of these is -``ACCKernelsTrans`` (currently only supported for the NEMO and -Dynamo0.3 APIs) which encloses the code represented by a sub-tree of +transformations for this purpose. The simplest of these is ``ACCKernelsTrans`` +(currently only supported for the generic code transformation +and LFRic API) which encloses the code represented by a sub-tree of the PSyIR within an OpenACC ``kernels`` region. This essentially gives free-reign to the compiler to automatically parallelise any suitable loops within the specified region. An example of the use of @@ -1085,8 +1086,8 @@ SIR It is currently not possible for PSyclone to output SIR code without using a script. Three examples of such scripts are given in example 4 -for the NEMO API. The first `sir_trans.py` simply outputs SIR. This -will raise an exception if used with the `tracer advection` example as +for the NEMO examples directory. The first `sir_trans.py` simply outputs SIR. +This will raise an exception if used with the `tracer advection` example as the example contains array-index notation which is not supported by the SIR backend, but will generate code for the other examples. The second, `sir_trans_loop.py` includes transformations to hoist code out diff --git a/doc/user_guide/tutorials_and_examples.rst b/doc/user_guide/tutorials_and_examples.rst index 3b3ff8fe56..e29c13383d 100644 --- a/doc/user_guide/tutorials_and_examples.rst +++ b/doc/user_guide/tutorials_and_examples.rst @@ -46,16 +46,16 @@ Tutorial PSyclone provides a hands-on tutorial. The easiest way to follow it is reading the `Readme files in github `_. -The tutorial is divided in two sections, a first section that introduces +The tutorial is divided into two sections, a first section that introduces PSyclone and how to `use it to transform generic Fortran code `_ (this is the recommended starting point for everybody). -And a second sections about +And a second section about `the LFRic DSL `_ -(this is only recommended for people interested in PSKAL DSLs and LFRic in particular). +(this is only recommended for people interested in PSyKAL DSLs and LFRic in particular). To do the proposed hands-on you will need a linux shell with Python installed and to -download the hand-on directory with: +download the hands-on directory with: .. code-block:: bash @@ -765,9 +765,8 @@ Demonstrates the introduction of simple OpenACC parallelisation (using the Example 4: Transforming Fortran code to the SIR ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Demonstrates that simple Fortran code examples which conform to the -NEMO API can be transformed to the Stencil Intermediate Representation -(SIR). The SIR is the front-end language to DAWN +Demonstrates that simple Fortran code can be transformed to the Stencil +Intermediate Representation (SIR). The SIR is the front-end language to DAWN (https://github.com/MeteoSwiss-APN/dawn), a tool which generates optimised cuda, or gridtools code. Thus various simple Fortran examples and the computational part of the tracer-advection benchmark @@ -778,7 +777,7 @@ Example 5: Kernel Data Extraction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This example shows the use of kernel data extraction in PSyclone for -the NEMO API. It instruments each kernel in the NEMO tracer-advection +generic Fortran code. It instruments each kernel in the NEMO tracer-advection benchmark with the PSyData-based kernel extraction code. Detailed compilation instructions are in the ``README.md`` file, including how to switch from using the stand-alone extraction library to the NetCDF-based @@ -797,6 +796,6 @@ adds the largest possible OpenACC Kernels regions to the code being processed. For more details see the ``examples/nemo/README.md`` file. -Note that these scripts are here to support the ongoing development of the -NEMO API in PSyclone. They are *not* intended as 'turn-key' solutions but -as a starting point. +Note that these scripts are here to support the ongoing development of PSyclone +to transform the NEMO source. They are *not* intended as 'turn-key' solutions +but as a starting point. diff --git a/src/psyclone/tests/conftest.py b/src/psyclone/tests/conftest.py index 02f3300cbc..84d5cf44b7 100644 --- a/src/psyclone/tests/conftest.py +++ b/src/psyclone/tests/conftest.py @@ -78,9 +78,9 @@ def pytest_addoption(parser): @pytest.fixture def have_graphviz(): - ''' Whether or not the system has graphviz installed. Note that this - only checks for the Python bindings. The underlying library must - also have been installed for dag generation to work correctly. ''' + ''' Whether or not the system has graphviz installed. This refers to + the underlying system library, not the python bindings that are provided + by 'import graphviz'. ''' # pylint: disable=import-outside-toplevel import graphviz try: diff --git a/tutorial/practicals/generic/Makefile b/tutorial/practicals/generic/Makefile index 54f6a0baf9..649b4dc689 100644 --- a/tutorial/practicals/generic/Makefile +++ b/tutorial/practicals/generic/Makefile @@ -32,8 +32,10 @@ # POSSIBILITY OF SUCH DAMAGE. # ------------------------------------------------------------------------------ # Author: A. R. Porter, STFC Daresbury Lab +# Modified: S. Siso, STFC Daresbury Lab -# Top-level Makefile to test all of the NEMO hands-on tutorials. +# Top-level Makefile to test all the hands-on tutorials for transforming +# generic code. TUTORIALS = $(sort $(dir $(wildcard */)))