diff --git a/documentation/source/developer_guide/psyclone/psyclone_makefiles.rst b/documentation/source/developer_guide/psyclone/psyclone_makefiles.rst index df3481972..0e703f74d 100644 --- a/documentation/source/developer_guide/psyclone/psyclone_makefiles.rst +++ b/documentation/source/developer_guide/psyclone/psyclone_makefiles.rst @@ -101,4 +101,26 @@ application at:: This is only required for modules with transformation scripts held in the ``transmute/`` directory (non-LFRic source or modules that are not targeted by the LFRic Core ``psyclone.mk`` file). Some applications will - not have this .mk file. \ No newline at end of file + not have this .mk file. + + +Modifying the PSyclone command(s) +--------------------------------- + +To assist with more flexible use of the PSyclone command(s) for the two DSL methods, +PSyKAl and Transmute, a flag has been added to allow users to adjust the flags used +with the command. +The main options are still required by default, but options that could be adjustable +per site, or potentially per file are being allowed, like compiler options. +An example is the use of ``-l all``, which has caused issues with some compilers, +such as Intel or Nvidia. + +* ``PSYCLONE_TRANSMUTE_EXTRAS`` - used by Transmute +* ``PSYCLONE_PSYKAL_EXTRAS`` - used by PSyKAl + +This has not been expanded further, however a user should be able to override them at +a site level, and a file level. +For just a site level, this could be set in the build option in the site cylc file. +Per file, which may be needed to preserve compiler clauses, and add optimisations in, a +makefile will need to export privatised versions of these per file and imported into +the application. \ No newline at end of file diff --git a/documentation/source/developer_guide/psyclone/psyclone_scripts.rst b/documentation/source/developer_guide/psyclone/psyclone_scripts.rst index 0d9305762..375e09185 100644 --- a/documentation/source/developer_guide/psyclone/psyclone_scripts.rst +++ b/documentation/source/developer_guide/psyclone/psyclone_scripts.rst @@ -47,8 +47,8 @@ filename. :: Storing a local transformation script, ``local.py`` +++++++++++++++++++++++++++++++++++++++++++++++++++ All files to be optimised by transmute (see ``psyclone_transmute_file_list.mk``) -in ``large_scale_precipitation`` will use this script unless overwritten with -a matching filename.:: +in the ``large_scale_precipitation`` directory will use this script unless overwritten +with a matching source filename.:: optimisation/ └── / @@ -71,7 +71,7 @@ For a script with matching source filename └── ls_ppn.F90 -* In the **built** ``lfric_atm`` application, ``ls_ppn.F90`` is found here - +* To understand the required path for storing a matching source filename, the build directory of a built application should be consulted. In the **built** ``lfric_atm`` application, ``ls_ppn.F90`` is found here - **use this path**:: / @@ -102,25 +102,47 @@ apply module-specific PSyclone transformations. This can be found at:: └── build/ └── psyclone_transmute_file_list.mk -Within this makefile there are environment variables that hold the names of -Fortran modules/transformation scripts that the science interface PSyclone -makefile should target. These are:: +Within this makefile there are several environment variables which control the +how files are passed to PSyclone Transmute. +These are: - PSYCLONE_PHSYICS_FILES_IMPORT - PSYCLONE_PHSYICS_FILES_FCM +* ``PSYCLONE_PHYSICS_FILES`` +* ``PSYCLONE_PASS_NO_SCRIPT`` +* ``TRANSMUTE_INCLUDE_METHOD`` +* ``PSYCLONE_DIRECTORIES`` +* ``PSYCLONE_PHYSICS_EXCEPTION`` -* If the module for which you are adding a transformation script lives in the - LFRic Apps directory, please use ``PSYCLONE_PHSYICS_FILES_IMPORT``. This - includes any non-LFRic source stored in the ``interfaces/`` directory. -* If the module is being imported from UKCA, JULES, CASIM, UM, SOCRATES, or any - other code base and does not have a copy in the LFRic Apps repository, please - use the ``PSYCLONE_PHSYICS_FILES_FCM`` variable. +``PSYCLONE_PHYSICS_FILES`` is used with ``TRANSMUTE_INCLUDE_METHOD`` ``specify_include``. +File names (without the type), which are to be affected by PSyclone, are added to this list. +A PSyclone transformation script is applied to each respective file. +The global.py script with be used as default, overwritten with alternatives as advised above. +This is also currently the default method as we slowly transformation additional science files +across to using PSyclone. + +``PSYCLONE_PASS_NO_SCRIPT`` has been implemented primarily for the ``TRANSMUTE_INCLUDE_METHOD`` +``specify_include``, however can be expanded to either. +It controls whether files are to be passed to PSyclone, but not to have a script applied to them. +This can be useful to remove existing clauses from a file, but not add anything back. +files to be affected this way should only be added to this list, as they will be filtered out of +``PSYCLONE_PHYSICS_FILES`` anyway. + +``TRANSMUTE_INCLUDE_METHOD`` can be set to either ``specify_include`` or ``specify_exclude``. +With ``specify_include``, ``PSYCLONE_PHYSICS_FILES`` will be used to define the list of files +to be passed to the PSyclone Transmute command, and with ``specify_exclude``, +``PSYCLONE_DIRECTORIES`` and ``PSYCLONE_PHYSICS_EXCEPTION`` will be used. + +``PSYCLONE_DIRECTORIES`` is used with ``TRANSMUTE_INCLUDE_METHOD`` ``specify_exclude``. +It provides a list of directories instead, where the build system populates the list of files to +be passed to PSyclone with all of the files in the directory. +``PSYCLONE_PHYSICS_EXCEPTION`` is used to filter the list of files found in each respective +``PSYCLONE_DIRECTORIES`` and remove them. This can often be used with .h files currently. + Module/transformation script names should be added in the following style (in accordance with GNUMake):: - PSYCLONE_PHSYICS_FILES_IMPORT = \ + PSYCLONE_PHYSICS_FILES = \ ls_ppn \ lsp_taper_ndrop \ mphys_air_density_mod