API

The generator module

This module provides the PSyclone ‘main’ routine which is intended to be driven from the bin/psyclone executable script. ‘main’ takes an algorithm file as input and produces modified algorithm code and generated PSy code. A function, ‘generate’, is also provided which has the same functionality as ‘main’ but can be called from within another Python program.

psyclone.generator.generate(filename, api='', kernel_paths=None, script_name=None, line_length=False, distributed_memory=None, kern_out_path='', kern_naming='multiple')[source]

Takes a PSyclone algorithm specification as input and outputs the associated generated algorithm and psy codes suitable for compiling with the specified kernel(s) and support infrastructure. Uses the parse.algorithm.parse() function to parse the algorithm specification, the psyGen.PSy class to generate the PSy code and the alg_gen.Alg class to generate the modified algorithm code.

Parameters
  • filename (str) – the file containing the algorithm specification.

  • api (str) – the name of the API to use. Defaults to empty string.

  • kernel_paths (list of str or NoneType) – the directories from which to recursively search for the files containing the kernel source (if different from the location of the algorithm specification). Defaults to None.

  • script_name (str) – a script file that can apply optimisations to the PSy layer (can be a path to a file or a filename that relies on the PYTHONPATH to find the module). Defaults to None.

  • line_length (bool) – a logical flag specifying whether we care about line lengths being longer than 132 characters. If so, the input (algorithm and kernel) code is checked to make sure that it conforms. The default is False.

  • distributed_memory (bool) – a logical flag specifying whether to generate distributed memory code. The default is set in the ‘config.py’ file.

  • kern_out_path (str) – directory to which to write transformed kernel code. Defaults to empty string.

  • kern_naming (bool) – the scheme to use when re-naming transformed kernels. Defaults to “multiple”.

Returns

2-tuple containing the fparser1 AST for the algorithm code and the fparser1 AST or a string (for NEMO) of the psy code.

Return type

(fparser.one.block_statements.BeginSource, fparser.one.block_statements.Module) or (fparser.one.block_statements.BeginSource, str)

Raises
  • GenerationError – if an invalid API is specified.

  • GenerationError – if an invalid kernel-renaming scheme is specified.

  • IOError – if the filename or search path do not exist.

For example:

>>> from psyclone.generator import generate
>>> alg, psy = generate("algspec.f90")
>>> alg, psy = generate("algspec.f90", kernel_paths=["src/kernels"])
>>> alg, psy = generate("algspec.f90", script_name="optimise.py")
>>> alg, psy = generate("algspec.f90", line_length=True)
>>> alg, psy = generate("algspec.f90", distributed_memory=False)

The parse module

Module that uses the Fortran parser fparser2 to parse PSyclone-conformant Algorithm code.

psyclone.parse.algorithm.parse(alg_filename, api='', invoke_name='invoke', kernel_paths=None, line_length=False)[source]

Takes a PSyclone conformant algorithm file as input and outputs a parse tree of the code contained therein and an object containing information about the ‘invoke’ calls in the algorithm file and any associated kernels within the invoke calls.

Parameters
  • alg_filename (str) – the file containing the algorithm specification.

  • api (str) – the PSyclone API to use when parsing the code. Defaults to empty string.

  • invoke_name (str) – the expected name of the invocation calls in the algorithm code. Defaults to “invoke”.

  • kernel_paths (list of str or NoneType) – the paths to search for kernel source files (if different from the location of the algorithm source). Defaults to None.

  • line_length (bool) – a logical flag specifying whether we care about line lengths being longer than 132 characters. If so, the input (algorithm and kernel) code is checked to make sure that it conforms and an error raised if not. The default is False.

Returns

2-tuple consisting of the fparser2 parse tree of the Algorithm file and an object holding details of the invokes found.

Return type

(fparser.two.Fortran2003.Program, psyclone.parse.FileInfo)

For example:

>>> from psyclone.parse.algorithm import parse
>>> ast, info = parse(SOURCE_FILE)

The transformations module

The psyGen module

This module provides generic support for PSyclone’s PSy code optimisation and generation. The classes in this method need to be specialised for a particular API and implementation.

class psyclone.psyGen.PSy(invoke_info)[source]

Base class to help manage and generate PSy code for a single algorithm file. Takes the invocation information output from the function parse.algorithm.parse() as its input and stores this in a way suitable for optimisation and code generation.

Parameters

invoke_info (psyclone.parse.algorithm.FileInfo) – An object containing the required invocation information for code optimisation and generation. Produced by the function parse.algorithm.parse().

For example:

>>> from psyclone.parse.algorithm import parse
>>> ast, info = parse("argspec.F90")
>>> from psyclone.psyGen import PSyFactory
>>> api = "..."
>>> psy = PSyFactory(api).create(info)
>>> print(psy.gen)
property container
Returns

the container associated with this PSy object

Return type

psyclone.psyir.nodes.Container

abstract property gen

Abstract base class for code generation function.

Returns

root node of generated Fortran AST.

Return type

psyclone.psyir.nodes.Node

property invokes
Returns

the list of invokes.

Return type

psyclone.psyGen.Invokes or derived class

property name
Returns

the name of the PSy object.

Return type

str

The alg_gen module

This module provides the Alg class and supporting exception-handling to translate the original algorithm file into one that can be compiled and linked with the generated PSy code.

It also provides the generate() function that, given kernel metadata, will create suitable algorithm-layer code which invokes that kernel.

class psyclone.alg_gen.Alg(parse_tree, psy, invoke_name='invoke')[source]

Generate a modified algorithm code for a single algorithm specification. Takes the parse tree of the algorithm specification output from the function psyclone.parse.algorithm.parse() and an instance of the psyGen.PSy class as input. The latter allows consistent names to be generated between the algorithm (callng) and psy (callee) layers.

For example:

>>> from psyclone.algorithm.parse import parse
>>> parse_tree, info = parse("argspec.F90")
>>> from psyclone.psyGen import PSy
>>> psy = PSy(info)
>>> from psyclone.alg_gen import Alg
>>> alg = Alg(parse_tree, psy)
>>> print(alg.gen)
Parameters
  • parse_tree (fparser.two.utils.Base) – an object containing a parse tree of the algorithm specification which was produced by the function psyclone.parse.algorithm.parse(). Assumes the algorithm will be parsed by fparser2 and expects a valid program unit, program, module, subroutine or function.

  • psy (psyclone.psyGen.PSy) – an object containing information about the PSy layer.

  • invoke_name (str) – the name that the algorithm layer uses to indicate an invoke call. This is an optional argument that defaults to the name “invoke”.

property gen

Return modified algorithm code.

Returns

the modified algorithm specification as an fparser2 parse tree.

Return type

fparser.two.utils.Base

The line_length module

Provides support for breaking long fortran lines into smaller ones to allow the code to conform to the maximum line length limits (132 for f90 free format is the default)

class psyclone.line_length.FortLineLength(line_length=132)[source]

This class take a free format fortran code as a string and line wraps any lines that are larger than the specified line length

property length

returns the maximum allowed line length

long_lines(fortran_in)[source]

returns true if at least one of the lines in the input code is longer than the allowed length. Otherwise returns false

process(fortran_in)[source]

takes fortran code as a string as input and output fortran code as a string with any long lines wrapped appropriately