Getting Going

Download

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 Installation in the Developer Guide.

PSyclone is available on the Python Package Index (PyPI) and is hosted on GitHub:

https://github.com/stfc/PSyclone

The latest release is 2.5.0 and the latest stable version is on the master branch.

There are two ways to install PSyclone. The first one is directly from PyPI using pip install, see Installation from PyPI for more detailed information.

Alternatively, PSyclone can be downloaded from GitHub - either see 2.5.0 in the Tags tab on the PSyclone page or download and extract the latest release of PSyclone directly, e.g.

> wget https://github.com/stfc/PSyclone/archive/2.5.0.tar.gz
> tar zxf 2.5.0.tar.gz
> ls
PSyclone-2.5.0

After the source package is downloaded and unpacked, it can be installed using pip install, albeit in a slightly different way to the PyPI installation, see Installation from source for more detailed information.

Hereon the location where you download or clone PSyclone (including the PSyclone directory itself) will be referred to as <PSYCLONEHOME>.

Environment

In order to use PSyclone (including running the test suite and building documentation) you will need to install it. Before starting the installation process, please refer to the Dependencies section below.

Installation from PyPI

The simplest, and recommended, installation process is from PyPI using pip:

> pip install psyclone

for the latest available release, or:

> pip install psyclone==X.Y.Z

where X.Y.Z is the specific PSyclone release version (e.g. 2.5.0).

By default, pip will attempt a system-wide install. If you wish to do a user-local install instead then supply the --user flag:

> pip install --user psyclone

PSyclone can also be installed to a specific location using --install-option (see pip documentation for more detailed information):

> pip install --install-option="--prefix=/my/install/path" psyclone==X.Y.Z

Depending on the installation option (e.g. system-wide, user), PSyclone will be installed in different locations.

Installation from source

PSyclone can also be installed from a downloaded release or repository clone. The simplest way to do this is to use pip with the supplied setup.py:

> cd <PSYCLONEHOME>
> pip install .

As above, this attempts a system-wide install. For a user-local install use:

> pip install --user .

and for a specific location use:

> pip install --install-option="--prefix=/my/install/path" .

If for some reason you would rather not use pip then you can run the setup manually:

> python setup.py install

or, if you do not have root access:

> python setup.py install --user

or:

> python setup.py install --install-option="--prefix=/my/install/path"

As for the PyPI installation, different installation options lead to different locations of PSyclone installation.

Location and structure of PSyclone installation

Location of installed Pyclone scripts, modules and other accompanying resources is similar to other Python packages:

The psyclone script is located in <python-base-prefix>/bin directory (depending on your Linux distribution, you may need to add this location to your $PATH).
The PSyclone Python modules are located in <python-base-prefix>/lib/pythonX.Y/site-packages directory (where X.Y is the version of Python that you are using).
The configuration file, examples, tutorial and libraries are installed in <python-base-prefix>/share/psyclone directory.

For a system-wide installation on Linux, <python-base-prefix> will likely be /usr and if a user-local installation is performed it will likely be ~/.local.

For an installation to a specific location, <python-base-prefix> is simply the path given to the --install-option="--prefix=/my/install/path". Note that if using this method, it will be necessary to take further action to ensure PSyclone can find the configuration file installed as a part of this process.

Windows environment

PSyclone can also be installed in Python Windows environment using pip as described above. There are some differences in directory structure from Linux, for instance the script directory is usually called Scripts instead of bin and the modules directory Lib instead of lib.

Installation in an Anaconda Python environment on Windows also needs to be done using pip as conda install for PSyclone is currently not supported.

Dependencies

PSyclone is written in Python so needs Python 3 to be installed on the target machine. PSyclone is regularly tested with Python 3.7, 3.8 and 3.12 but should work with any version >= 3.6. (The last PSyclone release to support Python 2.7 was version 2.1.0.)

PSyclone immediately relies on four external Python packages; configparser, fparser, sympy, and pyparsing. The easiest way to satisfy the Python dependencies is to use the PyPI installation and pip.

If everything is working correctly then using pip to install PSyclone:

> pip install psyclone

will automatically install the Python dependencies.

Warning

Starting with the release 1.6.1, PSyclone will install a specific release of fparser (version specified in the setup.py script).

In addition to the mandatory dependencies just described, PSyclone also has optional dependencies on both graphviz and termcolor. PSyclone can use graphviz to produce a visualisation of a schedule’s dependency graph. If this is desired then the Python package graphviz (for the Python bindings) as well as the graphviz package itself must be installed. If the graphviz package is not available then the associated PSyclone routines will return silently and no visualisations will be produced. The Python package termcolor is used for pretty-printing a schedule in terminals that support coloured text. If the package is not available then the schedule is simply printed in plain text without colour highlighting.

System-specific set-up

System-specific Set-up for Users instructions are available for Ubuntu 14.04.2 and OpenSUSE 42.2.

fparser

The fparser package (https://github.com/stfc/fparser) is a Fortran parser originally developed as a part of the f2py project.

fparser is available from the Python Package Index and thus may be installed using pip (https://packaging.python.org/tutorials/installing-packages/#requirements-for-installing-packages):

> pip install fparser

If you do not have sufficient permissions to perform a system-wide install then you can instruct pip to do a user-local install:

> pip install --user fparser

Should you wish to remove fparser then simply do:

> pip uninstall fparser

If you have already installed fparser and want to upgrade to the latest version simply do:

> pip install fparser --upgrade

Warning

Due to the above-mentioned reliance of PSyclone on a specific fparser release, it is not advisable to install fparser independently unless it is not to be used with PSyclone. An exception is installation of PSyclone from source for development purposes, see Installation in the Developer Guide.

pyparsing

PSyclone requires pyparsing, a library designed to allow parsers to be built in Python. PSyclone uses pyparsing to parse Fortran regular expressions as fparser does not fully parse these (see here for more information).

PSyclone has been tested with pyparsing versions 1.5.2, 2.0.1 and 2.2.0.

You can test whether pyparsing is already installed on your machine by typing import pyparsing from the Python command line. If pyparsing is installed, this command will complete successfully. If pyparsing is installed you can check its version by typing pyparsing.__version__ after successfully importing it.

If pyparsing is not installed on your system then it may be installed from the Python Package Index using pip:

> pip install pyparsing

Should you wish to, uninstalling is simply performed by doing:

> pip uninstall pyparsing

If you do not have sufficient privileges for a system-wide install then you can instruct pip to do a user-local install:

> pip install --user pyparsing

Alternatively, you could follow these instructions.

SymPy

PSyclone requires sympy, a library for symbolic mathematics. PSyclone uses sympy to reason about expression being equal or not, e.g. i+j and j+i. PSyclone has been tested with sympy versions 1.7.1.

You can test whether sympy is already installed on your machine by typing import sympy from the Python command line. If sympy is installed, this command will complete successfully. If sympy is installed you can check its version by typing sympy.__version__ after successfully importing it.

If sympy is not installed on your system then it may be installed from the Python Package Index using pip:

> pip install sympy

Should you wish to, uninstalling is simply performed by doing:

> pip uninstall sympy

If you do not have sufficient privileges for a system-wide install then you can instruct pip to do a user-local install:

> pip install --user sympy

Alternatively, you could follow the instructions on the SymPy web page.

Graphviz

The data dependencies of a PSyIR schedule determine the validity of changes to this schedule. PSyclone supports the visualisation of these dependencies as a graph using graphviz. This visualisation is not needed to use PSyclone.

If the Python bindings to graphviz are not installed on your system then it may be installed from the Python Package Index using pip:

> sudo pip install graphviz

Should you wish to, uninstalling is simply performed by doing:

> sudo pip uninstall graphviz

If you do not have sufficient privileges for a system-wide install then you can instruct pip to do a user-local install:

> pip install --user graphviz

If graphviz itself is not installed on your system and your system supports the apt package manager then see below, otherwise please refer to the download and install instructions which are available here.

If your system supports the apt package manager then it can be installed and removed in the following way:

> sudo apt install graphviz
> sudo apt remove graphviz

termcolor

By default, the view() method available on any PSyIR (PSyclone Internal Representation) object prints a plain-text representation to standard-out. However, if the termcolor package is available then PSyclone uses this to add colour highlighting to the output text.

Installation (and uninstallation) of this package can be done via pip in exactly the same way as for graphviz, as described above.

Configuration

Various aspects of PSyclone are configured through a configuration file, psyclone.cfg. The default version of this file is installed to <python-base-prefix>/shared/psyclone/ during the installation process. Similar to what is described above, if a system-wide installation is being performed then this will likely be /usr/share/psyclone/. If a user-local installation is performed (--user flag to pip install) then the location will be something like ~/.local/share/psyclone/.

Warning

If PSyclone is installed to a non-standard location (e.g. by specifying the --install-option="--prefix=... option to pip install) then PSyclone will not be able to find the configuration file at execution time. There are two solutions to this: 1. copy the configuration file to a location where PSyclone will find it (see Configuration) or 2. set the PSYCLONE_CONFIG environment variable to the full-path to the configuration file, e.g.:

> export PSYCLONE_CONFIG=/some/path/PSyclone/config/psyclone.cfg

Warning

When installing in ‘editable’ mode (-e flag to pip), pip does not install the configuration file. You will have to take one of the two actions described above.

See Configuration for details of the settings contained within the config file.

Test

PSyclone contains an extensive test suite, but this test suite is not part of a standard installation. If you want to run the full test suite, you need to install PSyclone from source, see above or Installation in the Developer Guide.

Run

You are now ready to try running PSyclone on the examples. One way of doing this is to use the psyclone driver script. Assuming it is on your PATH:

> psyclone
usage: psyclone [-h] [-oalg OALG] [-opsy OPSY] [-okern OKERN] [-api API]
                [-s SCRIPT] [-d DIRECTORY] [-I INCLUDE] [-l {off,all,output}]
                [-dm] [-nodm] [--kernel-renaming {multiple,single}]
                [--profile {invokes,kernels}] [--config CONFIG] [--version]
                filename
psyclone: error: the following arguments are required: filename

As indicated above, the psyclone script takes the name of the Fortran source file containing the algorithm specification (in terms of calls to invoke()). It parses this, finds the necessary kernel source files and produces two Fortran files. The first contains the PSy, middle layer and the second a re-write of the algorithm code to use that layer. These files are named according to the user-supplied arguments (options -oalg and -opsy). If those arguments are not supplied then the script writes the generated/re-written Fortran to the terminal. For details of the other command-line arguments please see the The psyclone command Section.

Examples are provided in the examples directory of the PSyclone Git repository - if you have cloned the repository then EGS_HOME in what follows is the root PSyclone directory. Alternatively, if you have installed PSyclone using pip then they may be found in the share/psyclone directory under your Python installation (see above for location of PSyclone installation. In this case you should copy the whole examples directory to some convenient location (hereafter called EGS_HOME) before attempting to carry out the following instructions. Depending on your precise setup, you may also need to set PSYCLONE_CONFIG to the full-path to the PSyclone configuration file (see Configuration).

There are seven subdirectories, three of which (lfric, gocean and nemo) correspond to the different APIs/domains that are supported by PSyclone. (Note, that we are currently in the process of renaming the dynamo0.3 API to lfric.) In this case we are going to use one of the LFRic examples:

> cd <EGS_HOME>/examples/lfric/eg1
> psyclone -api dynamo0.3 -d ../code -nodm -oalg alg.f90 \
    -opsy psy.f90 ./single_invoke.x90

You should see two new files created, called alg.f90 (containing the re-written algorithm layer) and psy.f90 (containing the generated PSy- or middle-layer). Since this is an LFRic example the Fortran source code has dependencies on the LFRic system and therefore cannot be compiled stand-alone.

The PSy-layer that PSyclone creates is constructed using the PSyclone Internal Representation (PSyIR). Accessing this is demonstrated by the print_psyir_trans.py script in the second LFRic example:

> cd <EGS_HOME>/examples/lfric/eg2
> psyclone -api dynamo0.3 -d ../code -s ./print_psyir_trans.py \
    -opsy psy.f90 -oalg alg.f90 ./multi_invoke_mod.x90

Take a look at the print_psyir_trans.py script for more information. Hint; you can insert a single line in that script in order to break into the Python interpreter during execution: import pdb; pdb.set_trace(). This then enables interactive exploration of the PSyIR if you are interested. Alternatively, you can play with some interactive examples on Binder.