PSyclone 3.2.0__tar.gz → 3.2.2__tar.gz

{psyclone-3.2.0/src/PSyclone.egg-info → psyclone-3.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PSyclone
-Version: 3.2.0
+Version: 3.2.2
 Summary: PSyclone - a source-to-source and DSL Fortran compiler for HPC applications
 Home-page: https://github.com/stfc/psyclone
 Author: Rupert Ford, Andrew Porter <andrew.porter@stfc.ac.uk>, Sergi Siso <sergi.siso@stfc.ac.uk>, Joerg Henrichs <joerg.henrichs@bom.gov.au>
@@ -21,7 +21,7 @@ Classifier: Operating System :: Unix
 Classifier: Operating System :: MacOS
 License-File: LICENSE
 Requires-Dist: pyparsing
-Requires-Dist: fparser>=0.2.1
+Requires-Dist: fparser==0.2.1
 Requires-Dist: configparser
 Requires-Dist: sympy
 Requires-Dist: Jinja2

{psyclone-3.2.0 → psyclone-3.2.2}/doc/developer_guide/module_manager.rst

@@ -172,7 +172,7 @@ of `ModuleManager`.
 
 .. testcode ::
 
-    mod_manager = ModuleManager.get(cache_active=True)
+    ModuleManager.get().cache_active = True
 
 
 Most of the time in the PSyIR generation is currently spent in the
@@ -200,8 +200,9 @@ a path can be provided to the module manager.
 
 .. testcode ::
 
-    mod_manager = ModuleManager.get(cache_active=True,
-                     cache_path="/tmp/my_cache_path")
+    mod_manager = ModuleManager.get()
+    mod_manager.cache_active = True
+    mod_manager.cache_path = "/tmp/my_cache_path"
 
 A cache file name will then be created based on the hashsum of each
 source code file. The combination of the provided `cache_path` and

{psyclone-3.2.0 → psyclone-3.2.2}/doc/developer_guide/psy_data.rst

@@ -1066,8 +1066,9 @@ the wrapper depends on (e.g. NetCDF).
     and link time for now, since the kernel contains metadata. Issue
     #2049 tracks a solution for this.
 
-The following changes are applied by the ``ExtractionDriverCreator``
-in order to generate stand-alone code for GOcean:
+The following changes are applied by the ``GOceanDriverCreator`` and
+the base class ``DriverCreator`` in order to generate stand-alone
+code for GOcean:
 
 1. The `dl_esm_inf` field type is replaced with 2d Fortran arrays.
    The structure name used is 'flattened', i.e. each ``%`` is replaced
@@ -1175,7 +1176,7 @@ the wrapper depends on (e.g. NetCDF).
 
 The driver creation process is explained in the Python sources:
 
-.. autoclass:: psyclone.domain.lfric.LFRicExtractDriverCreator
+.. autoclass:: psyclone.domain.lfric.LFRicDriverCreator
     :no-index:
     :members:
 

{psyclone-3.2.0 → psyclone-3.2.2}/doc/developer_guide/working_practises.rst

@@ -493,13 +493,13 @@ computational cost (so that we 'fail fast'):
  3. All links within the Sphinx documentation (rst files) are checked (see
     note below);
 
- 4. All of the examples are tested (for Python versions 3.10 and 3.13)
+ 4. All of the examples are tested (for Python versions 3.9 and 3.14)
     using the ``Makefile`` in the ``examples`` directory. No compilation is
     performed; only the ``transform`` (performs the PSyclone transformations)
     and ``notebook`` (runs the various Jupyter notebooks) targets are used.
     The ``transform`` target is run 2-way parallel (``-j 2``).
 
- 5. The full test suite is run for Python versions 3.10 and 3.13 but
+ 5. The full test suite is run for Python versions 3.9 and 3.14 but
     without the compilation checks. ``pytest`` is passed the ``-n auto`` flag
     so that it will run the tests in parallel on as many cores as are
     available (currently 2 on GHA instances).

{psyclone-3.2.0 → psyclone-3.2.2}/doc/user_guide/getting_going.rst

@@ -171,70 +171,77 @@ Running PSyclone
 You are now ready to run PSyclone. One way of doing this is to use the ``psyclone``
 command. To list the available options run: ``psyclone -h``, it should output::
 
-   usage: psyclone [-h] [--version] [--config CONFIG] [-s SCRIPT] [-I INCLUDE]
-                   [-l {off,all,output}] [--profile {invokes,routines,kernels}]
-		   [--backend {disable-validation,disable-indentation}]
-		   [-o OUTPUT_FILE] [-api DSL] [-oalg OUTPUT_ALGORITHM_FILE]
-		   [-opsy OUTPUT_PSY_FILE] [-okern OUTPUT_KERNEL_PATH]
-		   [-d DIRECTORY] [-dm] [-nodm]
-                   [--kernel-renaming {multiple,single}]
-		   [--log-level {OFF,DEBUG,INFO,WARNING,ERROR,CRITICAL}]
-		   [--log-file LOG_FILE] [--keep-comments] [--keep-directives]
-                   filename
-
-   Transform a file using the PSyclone source-to-source Fortran compiler
-
-   positional arguments:
-     filename              input source code
-
-   options:
-     -h, --help            show this help message and exit
-     --version, -v         display version information
-     -c CONFIG, --config CONFIG
-                           config file with PSyclone specific options
-     -s SCRIPT, --script SCRIPT
-                           filename of a PSyclone optimisation recipe
-     -I INCLUDE, --include INCLUDE
-                           path to Fortran INCLUDE or module files
-     --enable-cache        whether to enable caching of imported module dependencies (if
-                           enabled, it will generate a .psycache file of each imported
-			   module in the same location as the imported source file).
-     -l {off,all,output}, --limit {off,all,output}
-                           limit the Fortran line length to 132 characters (default 'off').
-                           Use 'all' to apply limit to both input and output Fortran. Use
-                           'output' to apply line-length limit to output Fortran only.
-     -p {invokes,routines,kernels}, --profile {invokes,routines,kernels}
-                           add profiling hooks for 'kernels', 'invokes' or 'routines'
-     --backend {disable-validation,disable-indentation}
-                           options to control the PSyIR backend used for code generation.
-                           Use 'disable-validation' to disable the validation checks that
-                           are performed by default. Use 'disable-indentation' to turn off
-			   all indentation in the generated code.
-     -o OUTPUT_FILE        (code-transformation mode) output file
-     -api DSL, --psykal-dsl DSL
-                           whether to use a PSyKAl DSL (one of ['lfric', 'gocean'])
-     -oalg OUTPUT_ALGORITHM_FILE
-                           (psykal mode) filename of transformed algorithm code
-     -opsy OUTPUT_PSY_FILE
-                           (psykal mode) filename of generated PSy-layer code
-     -okern OUTPUT_KERNEL_PATH
-                           (psykal mode) directory in which to put transformed kernels, default
-                           is the current working directory
-     -d DIRECTORY, --directory DIRECTORY
-                           (psykal mode) path to a root directory structure containing kernel
-                           source code. Multiple roots can be specified by using multiple -d
-                           arguments.
-     -dm, --dist_mem       (psykal mode) generate distributed memory code
-     -nodm, --no_dist_mem  (psykal mode) do not generate distributed memory code
-     --kernel-renaming {multiple,single}
-                           (psykal mode) naming scheme to use when re-naming transformed kernels
-     --log-level {OFF,DEBUG,INFO,WARNING,ERROR,CRITICAL}
-                           sets the level of the logging (defaults to OFF).
-     --log-file LOG_FILE   sets the output file to use for logging (defaults to stderr).
-     --keep-comments       keeps comments from the original code (defaults to False).
-                           Directives are not kept with this option (use
-			   --keep-directives).
-     --keep-directives     keeps directives from the original code (defaults to False).
+    usage: psyclone [-h] [-v] [-c CONFIG] [-s SCRIPT] [--enable-cache] [-l {off,all,output}]
+                    [-p {invokes,routines,kernels}]
+                    [--backend {disable-validation,disable-indentation}] [-o OUTPUT_FILE]
+                    [-api DSL] [-oalg OUTPUT_ALGORITHM_FILE] [-opsy OUTPUT_PSY_FILE]
+                    [-okern OUTPUT_KERNEL_PATH] [-dm] [-nodm]
+                    [--kernel-renaming {multiple,single}]
+                    [--log-level {OFF,DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--log-file LOG_FILE]
+                    [--keep-comments] [--keep-directives] [-I INCLUDE] [-d DIRECTORY]
+                    [--modman-file-ignore IGNORE_PATTERN] [--free-form | --fixed-form]
+                    filename
+
+    Transform a file using the PSyclone source-to-source Fortran compiler
+
+    positional arguments:
+      filename              input source code
+
+    options:
+      -h, --help            show this help message and exit
+      -v, --version         display version information
+      -c CONFIG, --config CONFIG
+                            config file with PSyclone specific options
+      -s SCRIPT, --script SCRIPT
+                            filename of a PSyclone optimisation recipe
+      --enable-cache        whether to enable caching of imported module dependencies (if
+                            enabled, it will generate a .psycache file of each imported module in
+                            the same location as the imported source file).
+      -l {off,all,output}, --limit {off,all,output}
+                            limit the Fortran line length to 132 characters (default 'off'). Use
+                            'all' to apply limit to both input and output Fortran. Use 'output'
+                            to apply line-length limit to output Fortran only.
+      -p {invokes,routines,kernels}, --profile {invokes,routines,kernels}
+                            add profiling hooks for 'kernels', 'invokes' or 'routines'
+      --backend {disable-validation,disable-indentation}
+                            options to control the PSyIR backend used for code generation. Use
+                            'disable-validation' to disable the validation checks that are
+                            performed by default. Use 'disable-indentation' to turn off all
+                            indentation in the generated code.
+      -o OUTPUT_FILE        (code-transformation mode) output file
+      -api DSL, --psykal-dsl DSL
+                            whether to use a PSyKAl DSL (one of ['lfric', 'gocean'])
+      -oalg OUTPUT_ALGORITHM_FILE
+                            (psykal mode) filename of transformed algorithm code
+      -opsy OUTPUT_PSY_FILE
+                            (psykal mode) filename of generated PSy-layer code
+      -okern OUTPUT_KERNEL_PATH
+                            (psykal mode) directory in which to put transformed kernels, default
+                            is the current working directory
+      -dm, --dist_mem       (psykal mode) generate distributed memory code
+      -nodm, --no_dist_mem  (psykal mode) do not generate distributed memory code
+      --kernel-renaming {multiple,single}
+                            (psykal mode) naming scheme to use when re-naming transformed kernels
+      --log-level {OFF,DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                            sets the level of the logging (defaults to OFF).
+      --log-file LOG_FILE   sets the output file to use for logging (defaults to stderr).
+      --keep-comments       keeps comments from the original code (defaults to False). Directives
+                            are not kept with this option (use --keep-directives).
+      --keep-directives     keeps directives from the original code (defaults to False).
+      --free-form           forces PSyclone to parse this file as free format (default is to look
+                            at the input file extension).
+      --fixed-form          forces PSyclone to parse this file as fixed format (default is to
+                            look at the input file extension).
+
+    Directory management:
+      -I INCLUDE, --include INCLUDE
+                            path to Fortran INCLUDE or module files
+      -d DIRECTORY, --directory DIRECTORY
+                            (psykal mode) path to a root directory structure containing kernel
+                            source code. Multiple roots can be specified by using multiple -d
+                            arguments. These directories will be searchedrecursively.
+      --modman-file-ignore IGNORE_PATTERN
+                            Ignore files that contain the specified pattern.
 
 There is more detailed information about each flag in :ref:`psyclone_command` section,
 but the main parameters are the input source file that we aim to transform, and a transformation

{psyclone-3.2.0 → psyclone-3.2.2}/doc/user_guide/lfric.rst

@@ -51,7 +51,7 @@ allow PSyclone to generate the PSy layer. These algorithm and kernel
 APIs are discussed separately in the following sections.
 
 The LFRic API supports the Met Office's finite element (hereafter FEM)
-based GungHo dynamical core.
+based 'GungHo' dynamical core.
 This dynamical core with atmospheric physics parameterisation
 schemes is a part of the Met Office LFRic modelling system :footcite:t:`lfric-2019`,
 currently being developed in preparation for exascale computing in the 2020s.
@@ -64,6 +64,13 @@ requires login access to MOSRS. For more technical details on the
 implementation of LFRic, please see the `LFRic documentation
 <https://code.metoffice.gov.uk/trac/lfric/attachment/wiki/LFRicDocumentationPapers/lfric_documentation.pdf>`_.
 
+.. note::
+   The following sections assume that the reader is familiar
+   with various concepts relating to the LFRic mesh and how it is decomposed
+   for distributed-memory parallel computing. For a detailed description of
+   these things, please see the :ref:`LFRic <lfric-developers>` section of the
+   Developer Guide.
+
 .. _lfric-api-algorithm:
 
 Algorithm
@@ -308,9 +315,9 @@ Halo Depth
 ++++++++++
 
 If a Kernel is written such that it *must* 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.
+:ref:`OPERATES_ON <lfric-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:
 
@@ -879,9 +886,11 @@ types.
 Rules specific to General-Purpose Kernels without CMA Operators
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-1) General-purpose kernels with ``operates_on = CELL_COLUMN`` accept
-   arguments of any of the following types: field, field vector, LMA
-   operator, scalar (``real``, ``integer`` or ``logical``).
+1) General-purpose kernels that :ref:`operate on <lfric-operates-on>`
+   any kind of ``CELL_COLUMN``
+   accept arguments of any of the following types: field,
+   field vector, LMA operator, scalar (``real``, ``integer`` or
+   ``logical``).
 
 2) A Kernel is permitted to write to more than one
    quantity (field or operator) and these quantities may be on the
@@ -1005,12 +1014,13 @@ on a ``CELL_COLUMN`` without CMA Operators. Specifically:
 Rules for all User-Supplied Kernels that Operate on DoFs (DoF Kernels)
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-Kernels that have ``operates_on = DOF`` and
-:ref:`LFRic Built-ins<lfric-built-ins>` overlap significantly in their
-scope, and the conventions that DoF Kernels must follow are influenced
-by those for built-ins as a result. This includes :ref:`metadata arguments
-<lfric-api-built-ins-metadata>` and :ref:`valid data types
-and access modes<lfric-built-ins-dtype-access>`. Naming conventions for DoF
+Kernels that have an :ref:`operates_on <lfric-operates-on>` of ``DOF``
+(or ``OWNED_DOF``) and :ref:`LFRic Built-ins<lfric-built-ins>` overlap
+significantly in their scope, and the conventions that DoF Kernels
+must follow are influenced by those for built-ins as a result. This
+includes :ref:`metadata arguments <lfric-api-built-ins-metadata>` and
+:ref:`valid data types and access
+modes<lfric-built-ins-dtype-access>`. Naming conventions for DoF
 Kernels should follow those for General-Purpose Kernels.
 
 The list of rules for DoF Kernels is as follows:
@@ -1336,9 +1346,8 @@ user-defined Kernels are summarised here. All argument types
 ``GH_COLUMNWISE_OPERATOR``) may be read within a Kernel and this
 is specified in metadata using ``GH_READ``. At least one kernel
 argument must be listed as being modified. When data is *modified*
-in a user-supplied Kernel (i.e. a Kernel that operates on a
-``CELL_COLUMN``, see :ref:`iteration space metadata
-<lfric-operates-on>`) then the permitted access
+in a user-supplied Kernel that operates on cell columns (see
+:ref:`iteration space metadata <lfric-operates-on>`) then the permitted access
 modes depend upon the argument type and the function space it is on:
 
 .. tabularcolumns:: |l|l|l|
@@ -1365,9 +1374,9 @@ modes depend upon the argument type and the function space it is on:
 
 Note that scalar arguments to user-defined Kernels must be read-only.
 Only :ref:`Built-ins <lfric-built-ins>` are permitted to modify scalar
-arguments. In practice this means that the only allowed access for the scalars
-in user-defined Kernels is ``GH_READ`` (see the allowed accesses for arguments
-in Built-ins in the :ref:`section below <lfric-built-ins-dtype-access>`).
+arguments. In practice this means that the only allowed access for scalar
+arguments in user-defined Kernels is ``GH_READ`` (see the allowed accesses for
+arguments in Built-ins in the :ref:`section below <lfric-built-ins-dtype-access>`).
 
 Note also that a ``GH_FIELD`` argument that has ``GH_WRITE`` or
 ``GH_READWRITE`` as its access pattern must typically (see below) be
@@ -1955,21 +1964,49 @@ 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 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:`lfric-developers`.)
+.. tabularcolumns:: |p{4.5cm}|p{3.0cm}|p{6.5cm}|
+
++--------------------------------+--------------------------------------+--------------------------------------------+
+| operates_on                    | Data passed for each field/operator  | Iteration space                            |
+|                                | argument                             |                                            |
++================================+======================================+============================================+
+| ``cell_column``                | Single column of cells.              | Conceptually, all columns in the global    |
+|                                |                                      | mesh. For each MPI                         |
+|                                |                                      | process this will operate on all owned     |
+|                                |                                      | columns and may be extended into the halo  |
+|                                |                                      | to perform redundant computation.          |
++--------------------------------+--------------------------------------+--------------------------------------------+
+| ``owned_cell_column``          | Single column of cells.              | Restricted to owned columns. Prevents      |
+|                                |                                      | extending into the halos to perform        |
+|                                |                                      | redundant computation.                     |
++--------------------------------+--------------------------------------+--------------------------------------------+
+| ``halo_cell_column``           | Single column of cells.              | Restricted to columns from the halo region |
+|                                |                                      | (to a specified depth).                    |
++--------------------------------+--------------------------------------+--------------------------------------------+
+| ``owned_and_halo_cell_column`` | Single column of cells.              | Iteration space must include both owned    |
+|                                |                                      | and halo columns (to a specified depth).   |
++--------------------------------+--------------------------------------+--------------------------------------------+
+| ``dof``                        | Single DoF.                          | Defaults to owned DoFs but may be extended |
+|                                |                                      | to annexed and halo DoFs.                  |
++--------------------------------+--------------------------------------+--------------------------------------------+
+| ``owned_dof``                  | Single DoF.                          | Restricted to owned DoFs only. Prevents    |
+|                                |                                      | extending into the halos to perform        |
+|                                |                                      | redundant computation.                     |
++--------------------------------+--------------------------------------+--------------------------------------------+
+| ``domain``                     | All columns of cells in the (sub-)   | None.                                      |
+|                                | domain.                              |                                            |
++--------------------------------+--------------------------------------+--------------------------------------------+
+
+(For a description of the concepts of 'owned' and 'halo' cells and 'annexed' DoFs
+please see the :ref:`LFRic section <lfric-developers>` of the Developer Guide.)
+
+The ``owned_cell_column`` and ``owned_dof`` values of ``OPERATES_ON`` are intended for
+use only with special cases where the kernel concerned cannot be used to perform
+redundant computation (e.g. when filling a field with pseudo-random numbers without
+regard to cell location). Processing an application that makes use of such a kernel
+requires that the ``COMPUTE_ANNEXED_DOFS`` configuration option (see
+:ref:`lfric-annexed_dofs`) be set to ``False`` as PSyclone can no longer guarantee that
+annexed DoFs are always clean between different ``invoke`` calls.
 
 procedure
 #########
@@ -3242,6 +3279,12 @@ pseudo-random numbers in the interval ``0 <= x < 1``::
 where ``RAND()`` is some function that returns a new pseudo-random number
 each time it is called.
 
+Due to different parallel elements using independent random-number generator
+streams, this built-in has ``OPERATES_ON=owned_dof``. This will prevent
+optimisations such as redundant computation (including the global
+``COMPUTE_ANNEXED_DOFS`` option).
+
+
 .. warning:: This Built-in is implemented using the Fortran ``random_number``
 	     intrinsic. Therefore no guarantee is made as to the quality of
 	     the sequence of pseudo-random numbers, especially when running

{psyclone-3.2.0 → psyclone-3.2.2}/doc/user_guide/psyclone_command.rst

@@ -51,63 +51,77 @@ by the command:
 .. parsed-literal::
 
   > psyclone -h
-    usage: psyclone [-h] [-v] [-c CONFIG] [-s SCRIPT] [-I INCLUDE] [-l {off,all,output}] [-p {invokes,routines,kernels}]
-                    [--backend {disable-validation,disable-indentation}]
-                    [-o OUTPUT_FILE] [-api DSL] [-oalg OUTPUT_ALGORITHM_FILE] [-opsy OUTPUT_PSY_FILE] [-okern OUTPUT_KERNEL_PATH] [-d DIRECTORY] [-dm] [-nodm]
-                    [--kernel-renaming {multiple,single}] [--log-level {OFF,DEBUG,INFO,WARNING,ERROR,CRITICAL}]
-                    [--log-file LOG_FILE] [--keep-comments] [--keep-directives]
+    usage: psyclone [-h] [-v] [-c CONFIG] [-s SCRIPT] [--enable-cache] [-l {off,all,output}]
+                    [-p {invokes,routines,kernels}]
+                    [--backend {disable-validation,disable-indentation}] [-o OUTPUT_FILE]
+                    [-api DSL] [-oalg OUTPUT_ALGORITHM_FILE] [-opsy OUTPUT_PSY_FILE]
+                    [-okern OUTPUT_KERNEL_PATH] [-dm] [-nodm]
+                    [--kernel-renaming {multiple,single}]
+                    [--log-level {OFF,DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--log-file LOG_FILE]
+                    [--keep-comments] [--keep-directives] [-I INCLUDE] [-d DIRECTORY]
+                    [--modman-file-ignore IGNORE_PATTERN] [--free-form | --fixed-form]
                     filename
 
     Transform a file using the PSyclone source-to-source Fortran compiler
-    
+
     positional arguments:
       filename              input source code
-    
+
     options:
-     -h, --help            show this help message and exit
-     -v, --version         display version information
-     -c CONFIG, --config CONFIG
-                           config file with PSyclone specific options
-     -s SCRIPT, --script SCRIPT
-                           filename of a PSyclone optimisation recipe
-     -I INCLUDE, --include INCLUDE
-                           path to Fortran INCLUDE or module files
-     --enable-cache        whether to enable caching of imported module dependencies (if
-                           enabled, it will generate a .psycache file of each imported
-                           module in the same location as the imported source file).
-     -l {off,all,output}, --limit {off,all,output}
-                           limit the Fortran line length to 132 characters (default 'off').
-                           Use 'all' to apply limit to both input and output Fortran. Use
-     -p {invokes,routines,kernels}, --profile {invokes,routines,kernels}
-                           add profiling hooks for 'kernels', 'invokes' or 'routines'
-     --backend {disable-validation,disable-indentation}
-                           options to control the PSyIR backend used for code generation.
-                           Use 'disable-validation' to disable the validation checks that
-                           are performed by default. Use 'disable-indentation' to turn
-			   off all indentation in the generated code.
-     -o OUTPUT_FILE        (code-transformation mode) output file
-     -api DSL, --psykal-dsl DSL
-                           whether to use a PSyKAl DSL (one of ['lfric', 'gocean'])
-     -oalg OUTPUT_ALGORITHM_FILE
-                           (psykal mode) filename of transformed algorithm code
-     -opsy OUTPUT_PSY_FILE
-                           (psykal mode) filename of generated PSy-layer code
-     -okern OUTPUT_KERNEL_PATH
-                           (psykal mode) directory in which to put transformed kernels, default is the current working directory
-     -d DIRECTORY, --directory DIRECTORY
-                           (psykal mode) path to a root directory structure containing kernel
-                           source code. Multiple roots can be specified by using multiple -d
-                           arguments.
-     -dm, --dist_mem       (psykal mode) generate distributed memory code
-     -nodm, --no_dist_mem  (psykal mode) do not generate distributed memory code
-     --kernel-renaming {multiple,single}
-                           (psykal mode) naming scheme to use when re-naming transformed kernels
-     --log-level {OFF,DEBUG,INFO,WARNING,ERROR,CRITICAL}
-                           sets the level of the logging (defaults to OFF).
-     --log-file LOG_FILE   sets the output file to use for logging (defaults to stderr).
-     --keep-comments       keeps comments from the original code (defaults to False).
-                           Directives are not kept with this option (use --keep-directives).
-     --keep-directives     keeps directives from the original code (defaults to False).
+      -h, --help            show this help message and exit
+      -v, --version         display version information
+      -c CONFIG, --config CONFIG
+                            config file with PSyclone specific options
+      -s SCRIPT, --script SCRIPT
+                            filename of a PSyclone optimisation recipe
+      --enable-cache        whether to enable caching of imported module dependencies (if
+                            enabled, it will generate a .psycache file of each imported module in
+                            the same location as the imported source file).
+      -l {off,all,output}, --limit {off,all,output}
+                            limit the Fortran line length to 132 characters (default 'off'). Use
+                            'all' to apply limit to both input and output Fortran. Use 'output'
+                            to apply line-length limit to output Fortran only.
+      -p {invokes,routines,kernels}, --profile {invokes,routines,kernels}
+                            add profiling hooks for 'kernels', 'invokes' or 'routines'
+      --backend {disable-validation,disable-indentation}
+                            options to control the PSyIR backend used for code generation. Use
+                            'disable-validation' to disable the validation checks that are
+                            performed by default. Use 'disable-indentation' to turn off all
+                            indentation in the generated code.
+      -o OUTPUT_FILE        (code-transformation mode) output file
+      -api DSL, --psykal-dsl DSL
+                            whether to use a PSyKAl DSL (one of ['lfric', 'gocean'])
+      -oalg OUTPUT_ALGORITHM_FILE
+                            (psykal mode) filename of transformed algorithm code
+      -opsy OUTPUT_PSY_FILE
+                            (psykal mode) filename of generated PSy-layer code
+      -okern OUTPUT_KERNEL_PATH
+                            (psykal mode) directory in which to put transformed kernels, default
+                            is the current working directory
+      -dm, --dist_mem       (psykal mode) generate distributed memory code
+      -nodm, --no_dist_mem  (psykal mode) do not generate distributed memory code
+      --kernel-renaming {multiple,single}
+                            (psykal mode) naming scheme to use when re-naming transformed kernels
+      --log-level {OFF,DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                            sets the level of the logging (defaults to OFF).
+      --log-file LOG_FILE   sets the output file to use for logging (defaults to stderr).
+      --keep-comments       keeps comments from the original code (defaults to False). Directives
+                            are not kept with this option (use --keep-directives).
+      --keep-directives     keeps directives from the original code (defaults to False).
+      --free-form           forces PSyclone to parse this file as free format (default is to look
+                            at the input file extension).
+      --fixed-form          forces PSyclone to parse this file as fixed format (default is to
+                            look at the input file extension).
+
+    Directory management:
+      -I INCLUDE, --include INCLUDE
+                            path to Fortran INCLUDE or module files
+      -d DIRECTORY, --directory DIRECTORY
+                            (psykal mode) path to a root directory structure containing kernel
+                            source code. Multiple roots can be specified by using multiple -d
+                            arguments. These directories will be searchedrecursively.
+      --modman-file-ignore IGNORE_PATTERN
+                            Ignore files that contain the specified pattern.
 
 Basic Use
 ---------
@@ -238,6 +252,29 @@ Finally, if all else fails, the code-generation part of PSyclone (the
 "backend") can be instructed not to use any indentation at all. See the
 :ref:`backend-options` section.
 
+
+.. _fortran_source_format:
+
+Fortran Format Option
+---------------------
+
+PSyclone supports both free and fixed format source input. By default,
+PSyclone follows the gfortran specification for file extensions:
+
+    - Free format extensions: .f90, .f95, .f03, .f08, .F90, .F95, .F03, .F08
+    - Fixed format extensions: .f, .for, .fpp, .ftn, .F, .FOR, .FPP, .FTN
+
+PSyclone also recognises the following extensions as free format to support
+current uses cases: .x90, .xu90
+
+PSyclone also provides the ``--free-form`` and ``-fixed-form`` to override the
+default behaviour, and will use the specified option over the file extension.
+
+If the file extension is not one of the ones listed above, and neither of the
+``--free-form`` or ``--fixed-form`` flags is used then PSyclone defaults to
+assuming the input source is free form Fortran.
+
+
 .. _backend-options:
 
 Backend Options