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 (whereX.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.