The psyclone command

The psyclone command is an executable script designed to be run from the command line, e.g.:

> psyclone <args>

The optional -h argument gives a description of the options provided by the command:

> psyclone -h
 usage: psyclone [-h] [--version] [--config CONFIG] [-s SCRIPT] [-I INCLUDE]
                 [-l {off,all,output}] [--profile {invokes,routines,kernels}]
                                 [--backend {enable-validation,disable-validation}] [-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}]
                 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
   --config CONFIG, -c 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
   -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.
   --profile {invokes,routines,kernels}, -p {invokes,routines,kernels}
                         add profiling hooks for 'kernels', 'invokes' or 'routines'
   --backend {enable-validation,disable-validation}
                         options to control the PSyIR backend used for code generation.
                         Use 'disable-validation' to disable the validation checks that
                         are performed by default.
   -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

Basic Use

The simplest way to use psyclone is to provide a Fortran input source file:

psyclone input.f90

If the input file is valid Fortran, PSyclone will print the output Fortran (in this case the same unmodified code but with normalised syntax) to stdout. Otherwise it will print the errors detected while parsing the Fortran file.

Usually we want to redirect the output to a file that we can later compile. We can do this with the -o flag:

psyclone input.f90 -o output.f90

Transformation script

By default, the psyclone command will not apply any transformation (other than canonicalising the code and generating a normalised syntax). To apply transformations to the code, a recipe needs to be specified with the -s flag. This option is discussed in more detail in the PSyclone User Scripts section. With a transformation recipe the command looks like:

psyclone input.f90 -s transformation_recipe.py

Fortran INCLUDE Files and Modules

If the source code to be processed by PSyclone contains INCLUDE statements then the location of any INCLUDE’d files must be supplied to PSyclone via the -I or --include option. (This is necessary because INCLUDE lines are a part of the Fortran language and must therefore be parsed - they are not handled by any pre-processing step.) Multiple locations may be specified by using multiple -I flags, e.g.:

psyclone -I /some/path -I /some/other/path input.f90

If no include paths are specified then the directory containing the source file currently being parsed is searched by default. If the specified INCLUDE file is not found then PSyclone will abort with an appropriate error. For example:

psyclone -I nonexisting test.f90
PSyclone configuration error: Include path 'nonexisting' does not exist

Currently, the PSyKAl-based APIs (LFRic and GOcean - see below) will ignore (but preserve) INCLUDE statements in algorithm-layer code. However, INCLUDE statements in kernels will, in general, cause the kernel parsing to fail unless the file(s) referenced in such statements are in the same directory as the kernel file. Once kernel parsing has been re-implemented to use fparser2 (issue #239) and the PSyclone Intermediate Representation then the behaviour will be the same as for generic code-transformations.

Since PSyclone does not attempt to be a full compiler, it does not require that the code be available for any Fortran modules referred to by use statements. However, certain transformations do require that e.g. type information be determined for all variables in the code being transformed. In this case PSyclone will need to be able to find and process any referenced modules. To do this it searches in the directories specified by the -I/--include flags.

C Pre-processor #include Files

PSyclone currently only supports Fortran input. As such, if a file to be processed contains CPP #include statements then it must first be processed by a suitable pre-processor before being passed to PSyclone. PSyclone will abort with an appropriate error if it encounters a #include in any code being processed (whether or not a PSykAL DSL is in use).

Fortran line length

By default the psyclone command will generate Fortran code with no consideration of Fortran line-length limits. As the line-length limit for free-format Fortran is 132 characters, the code that is output may be non-conformant.

Line length is not an issue for many compilers as they provide flags to increase or disable Fortran standard line lengths limits. However this is not the case for all compilers.

When either the -l all or -l output option is specified to the psyclone command, the output will be line wrapped so that the output lines are always within the 132 character limit.

The -l all additionally checks the input Fortran files for conformance and raises an error if they do not conform.

Line wrapping is not performed by default. There are two reasons for this. This first reason is that most compilers are able to cope with long lines. The second reason is that the line wrapping implementation could fail in certain pathological cases. The implementation and limitations of line wrapping are discussed in the Limitations section.

Backend Options

The final code generated by PSyclone is created by passing the PSyIR tree to one of the ‘backends’ (see PSyIR Back-ends in the Developer Guide for more details). The --backend flag permits a user to tune the behaviour of this code generation. Currently, the only option is {en,dis}able-validation which turns on/off the validation checks performed when doing code generation. By default, such validation is enabled as it is only at code-generation time that certain constraints can be checked (since PSyclone does not mandate the order in which code transformations are applied). Occasionally, these validation checks may raise false positives (due to incomplete implementations), at which point it is useful to be able to disable them. The default behaviour may be changed by adding the BACKEND_CHECKS_ENABLED entry to the configuration file. Any command-line setting always takes precendence though. It is recommended that validation only be disabled as a last resort and for as few input source files as possible.

Automatic Profiling Instrumentation

The --profile option allows the user to instruct PSyclone to automatically insert profiling calls in addition to the code transformations specified in the recipe. This flag accepts the options: routines, invokes and kernels. PSyclone will insert profiling-start and -stop calls at the beginning and end of each routine, PSy-layer invoke or PSy-layer kernel call, respectively. The generated code must be linked against the PSyclone profiling interface and the profiling tool itself. The application that calls the PSyclone-generated code is responsible for initialising and finalising the profiling library that is being used (if necessary). For more details on the use of this profiling functionality please see the Profiling section.

Using PSyclone for PSyKAL DSLs

In addition to the default code-transformation mode, psyclone can also be used to process Fortran files that implement PSyKAL DSLs (see Introduction to PSyKAl). To do this you can choose a DSL API with the -api or --psykal-dsl flag.

The main difference is that, instead of providing a single file to process, for PSyKAl DSLs PSyclone expects an algorithm-layer file that describes the high-level view of an algorithm. PSyclone will use this algorithm file and the metadata of the kernels that it calls to generate a PSy(Parallel System)-layer code that connects the Algorithm layer to the Kernels. In this mode of operation, any supplied transformation recipe is applied to the PSy-layer.

By default, the psyclone command for PSyKAl APIs will generate distributed memory (DM) code (unless otherwise specified in the Configuration file). Alternatively, whether or not to generate DM code can be specified as an argument to the psyclone command using the -dm/--dist_mem or -nodm/--no_dist_mem flags, respectively. For exampe the following command will generate GOcean PSyKAl code with DM:

psyclone -api gocean -dm algorithm.f90

See psyclone usage for PSyKAl section for more information about how to use PSyKAl DSLs.

PSyKAl file output

By default the modified algorithm code and the generated PSy code are output to the terminal. These can instead be output to files by using the -oalg <file> and -opsy <file> options, respectively. For example, the following will output the generated PSy code to the file ‘psy.f90’ but the algorithm code will be output to the terminal:

psyclone -opsy psy.f90 algorithm.f90

If PSyclone is being used to transform Kernels then the location to write these to is specified using the -okern <directory> option. If this is not supplied then they are written to the current working directory. By default, PSyclone will overwrite any kernel of the same name in that directory. To change this behaviour, the user can use the --no_kernel_clobber option. This causes PSyclone to re-name any transformed kernel that would clash with any of those already present in the output directory.

Algorithm files with no invokes

If psyclone is provided with a file that contains no invoke calls then the command outputs a warning to stdout and copies the input file to stdout, or to the specified algorithm file (if the -oalg <file> option is used). No PSy code will be output. If a file is specified using the -opsy <file> option this file will not be created.

> psyclone -opsy psy.f90 -oalg alg_new.f90 empty_alg.f90
Warning: 'Algorithm Error: Algorithm file contains no invoke() calls: refusing to
generate empty PSy code'

Kernel search directory

When an algorithm file is parsed, the parser looks for the associated kernel files. The way in which this is done requires that any user-defined kernel routine (as opposed to Built-ins) called within an invoke must have an explicit use statement. For example, the following code gives an error:

> cat no_use.f90
program no_use
  call invoke(testkern_type(a,b,c,d,e))
end program no_use
> psyclone -api gocean no_use.f90
"Parse Error: kernel call 'testkern_type' must either be named in a use statement or be a recognised built-in (one of '[]' for this API)"

(If the chosen API has any Built-ins defined then these will be listed within the [] in the above error message.) If the name of the kernel is provided in a use statement then the parser will look for a file with the same name as the module in the use statement. In the example below, the parser will look for a file called “testkern.f90” or “testkern.F90”:

> cat use.f90
program use
  use testkern, only : testkern_type
  call invoke(testkern_type(a,b,c,d,e))
end program use

Therefore, for PSyclone to find kernel files, the module name of a kernel file must be the same as its filename. By default the parser looks for the kernel file in the same directory as the algorithm file. If this file is not found then an error is reported.

> psyclone use.f90
Kernel file 'testkern.[fF]90' not found in <location>

The -d option can be used to tell psyclone where to look for kernel files by supplying it with a directory. The execution will recurse from the specified directory path to look for the required file. There must be only one instance of the specified file within (or below) the specified directory:

> cd <PSYCLONEHOME>/src/psyclone
> psyclone -d . use.f90
More than one match for kernel file 'testkern.[fF]90' found!
> psyclone -d tests/test_files/dynamo0p3 -api lfric use.f90
[code output]

Note

The -d option can be repeated to add as many search directories as is required, with the constraint that there must be only one instance of the specified file within (or below) the specified directories.

Transforming PSyKAl Kernels

When transforming kernels there are two use-cases to consider:

a given kernel will be transformed only once and that version then used from multiple, different Invokes and Algorithms;

a given kernel is used from multiple, different Invokes and Algorithms and is transformed differently, depending on the Invoke.

Whenever PSyclone is used to transform a kernel, the new kernel must be re-named in order to avoid clashing with other possible calls to the original. By default (--kernel-renaming multiple), PSyclone generates a new, unique name for each kernel that is transformed. Since PSyclone is run on one Algorithm file at a time, it uses the chosen kernel output directory (-okern) to ensure that names created by different invocations do not clash. Therefore, when building a single application, the same kernel output directory must be used for each separate invocation of PSyclone.

Alternatively, in order to support use case 1, a user may specify --kernel-renaming single: now, before transforming a kernel, PSyclone will check the kernel output directory and if a transformed version of that kernel is already present then that will be used. Note, if the kernel file on disk does not match with what would be generated then PSyclone will raise an exception.