MetOffice · MetBenjaminWent · Feb 12, 2026 · Feb 12, 2026 · Feb 13, 2026 · Mar 2, 2026
diff --git a/documentation/source/developer_guide/psyclone/psyclone_makefiles.rst b/documentation/source/developer_guide/psyclone/psyclone_makefiles.rst
@@ -101,4 +101,29 @@ 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.
+    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.
+To affect all transformations for a given site, it is recommended that the PSyclone extras environment variables are set in the ``[[BUILD]]`` section of the corresponding ``suite_config_<SITE>.conf`` file, e.g.:
+
+[[EX1A_BUILD]]
+        [[[environment]]]
+            PSYCLONE_TRANSMUTE_EXTRAS = '-l all'
+
+To target the PSyclone arguments for a single file, such as in the case of preserving compiler directives, it is recommended to set the environment variables via a per-file system such as the GNUMake system shipped with LFRic.
diff --git 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/
     └── <platform>/
@@ -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**::
 
     <lfric_atm working directory>/
@@ -102,25 +102,50 @@ 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_PHYSICS_FILES``
+* ``PSYCLONE_PASS_NO_SCRIPT``
+* ``TRANSMUTE_INCLUDE_METHOD``
+* ``PSYCLONE_DIRECTORIES``
+* ``PSYCLONE_PHYSICS_EXCEPTION``
+
+
+``PSYCLONE_PHYSICS_FILES`` is used with ``TRANSMUTE_INCLUDE_METHOD`` ``specify_include``.
+File names (without file extensions), which are to be affected by PSyclone, are
+added to this list. Any files not included in this list will not be processed by
+PSyclone.
+A PSyclone transformation script is applied to each respective file.
+The ``global.py`` script is used as the default transformation script, overridden by file- or directory-specific alternatives as detailed above.
+This is currently the default method for enabling PSyclone transformation scripts for
+source files.
+
+``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.
-``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.
+``PSYCLONE_PASS_NO_SCRIPT`` specifies files to be passed to PSyclone without any associated transformation scripts.
+The primary use case is to remove existing clauses from a file without modifying the Fortran source.
+Any files included in ``PSYCLONE_PASS_NO_SCRIPT`` are filtered out of the ``PSYCLONE_PHYSICS_FILES`` list.
+No transformation scripts will be applied to files in this list regardless of the ``TRANSMUTE_INCLUDE_METHOD``.
-``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.
+``PSYCLONE_PASS_NO_SCRIPT`` has been implemented for the ``TRANSMUTE_INCLUDE_METHOD``
+``specify_include``. Use of this variable for the ``specify_exclude`` method is not mature,
+though work is planned (see [GitHub issue number here]).
+This variable specifies files to be passed to PSyclone without applying any transformations.
+This can be useful to remove existing clauses from a file without modifying the Fortran source.
+Any files included in ``PSYCLONE_PASS_NO_SCRIPT`` are filtered out of the ``PSYCLONE_PHYSICS_FILES`` list.
-``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.
+``PSYCLONE_PASS_NO_SCRIPT`` specifies files to be passed to PSyclone without any associated transformation scripts.
+The primary use case is to remove existing clauses from a file without modifying the Fortran source.
+Any files included in ``PSYCLONE_PASS_NO_SCRIPT`` are filtered out of the ``PSYCLONE_PHYSICS_FILES`` list.
+No transformation scripts will be applied to files in this list regardless of the ``TRANSMUTE_INCLUDE_METHOD``.
-``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.
+``PSYCLONE_PASS_NO_SCRIPT`` has been implemented for the ``TRANSMUTE_INCLUDE_METHOD``
+``specify_include``. Use of this variable for the ``specify_exclude`` method is not mature,
+though work is planned (see [GitHub issue number here]).
+This variable specifies files to be passed to PSyclone without applying any transformations.
+This can be useful to remove existing clauses from a file without modifying the Fortran source.
+Any files included in ``PSYCLONE_PASS_NO_SCRIPT`` are filtered out of the ``PSYCLONE_PHYSICS_FILES`` list.
+
+``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 only these files will be
+passed. All other Fortran source files will not be passed to PSyclone.
+
+When using ``specify_exclude``, a list of target directories is passed via
+``PSYCLONE_DIRECTORIES``. For all directories in this list, every Fortran source file
+found in these directories will be passed to PSyclone. To omit a file from being passed
+to PSyclone, the filename (including extension) can be added to
+``PSYCLONE_PHYSICS_EXCEPTION``. This can often be used with .h files currently.
 
-    PSYCLONE_PHSYICS_FILES_IMPORT
-    PSYCLONE_PHSYICS_FILES_FCM
-
-* 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.
 
 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