`psyclone.parse.algorithm`

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

Functions 

parse(): Takes a PSyclone conformant algorithm file as input and outputs a
get_builtin_defs(): Get the names of the supported built-in operations and the file
get_invoke_label(): Takes an invoke argument contained in the parse_tree argument and
get_kernel(): Takes the parse tree of an invoke kernel argument and returns the
create_var_name(): Creates a valid variable name from an argument that optionally

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

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)

psyclone.parse.algorithm.get_builtin_defs(api)

Get the names of the supported built-in operations and the file containing the associated meta-data for the supplied API

Parameters:: api (str) – the specified PSyclone API.
Returns:: a 2-tuple containing a dictionary of the supported built-ins and the filename where these built-ins are specified.
Return type:: (dict, str)

psyclone.parse.algorithm.get_invoke_label(parse_tree, alg_filename, identifier='name')

Takes an invoke argument contained in the parse_tree argument and returns the label specified within it.

Parameters:

parse_tree (fparser.two.Actual_Arg_Spec) – Parse tree of an invoke argument. This should contain a “name=xxx” argument.
alg_filename (str) – The file containing the algorithm code.
identifier (str) – An optional name used to specify a named argument. Defaults to ‘name’.

Returns:

the label as a lower-cased string.

Return type:

str

Raises:

InternalError – if the form of the argument is not what was expected.
InternalError – if the number of items contained in the argument is not what was expected.
ParseError – if the name used for the named argument does not match what was expected.
ParseError – if the label is not specified as a string.
ParseError – if the label is not a valid Fortran name.

psyclone.parse.algorithm.get_kernel(parse_tree, alg_filename, arg_type_defns)

Takes the parse tree of an invoke kernel argument and returns the name of the kernel and a list of Arg instances which capture the relevant information about the arguments associated with the kernel.

Parameters:

parse_tree (fparser.two.Fortran2003.Part_Ref or fparser.two.Fortran2003.Structure_Constructor) – parse tree of an invoke argument. This should contain a kernel name and associated arguments.
alg_filename (str) – The file containing the algorithm code.
arg_type_defns (dict[str] = (str, str or NoneType)) – dictionary holding a 2-tuple consisting of type and precision information for each variable declared in the algorithm layer, indexed by variable name.

Returns:

a 2-tuple with the name of the kernel being called and a list of ‘Arg’ instances containing the required information for the arguments being passed from the algorithm layer. The list order is the same as the argument order.

Return type:

(str, list of psyclone.parse.algorithm.Arg)

Raises:

InternalError – if the parse tree is of the wrong type.
InternalError – if Part_Ref or Structure_Constructor do not have two children.
InternalError – if Proc_Component_Ref has a child with an unexpected type.
InternalError – if Data_Ref has a child with an unexpected type.
NotImplementedError – if an expression contains a variable.
InternalError – if an unsupported argument format is found.

psyclone.parse.algorithm.create_var_name(arg_parse_tree)

Creates a valid variable name from an argument that optionally includes brackets and potentially dereferences using ‘%’.

Parameters:: arg_parse_tree (fparser.two.Fortran2003.Name or fparser.two.Fortran2003.Data_Ref or fparser.two.Fortran2003.Part_Ref or fparser.two.Fortran2003.Proc_Component_Ref) – the input argument. Contains braces and potentially dereferencing. e.g. a%b(c).
Returns:: a valid variable name.
Return type:: str
Raises:: InternalError – if unrecognised fparser content is found.

Classes 

Parser: Supports the parsing of PSyclone conformant algorithm code within a
FileInfo: Captures information about the algorithm file and the invoke calls
InvokeCall: Keeps information about an individual invoke call.
ParsedCall: Base class for information about a user-supplied or built-in
KernelCall: Store information about a user-supplied (coded) kernel. Specialises
BuiltInCall: Store information about a system-supplied (builtin)
Arg: Description of an argument as obtained from parsing kernel or

class psyclone.parse.algorithm.Parser(api='', invoke_name='invoke', kernel_paths=None, line_length=False)

Supports the parsing of PSyclone conformant algorithm code within a file and extraction of relevant information for any ‘invoke’ calls contained within the code.

Parameters:

api (str) – the PSyclone API to use when parsing the code.
invoke_name (str) – the expected name of the invocation calls in the algorithm code.
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.

For example:

>>> from psyclone.parse.algorithm import Parser
>>> parser = Parser(api="gocean1.0")
>>> ast, info = parser.parse(SOURCE_FILE)

Inheritance

check_invoke_label(argument)

Takes the parse tree of an invoke argument containing an invoke label. Raises an exception if this label has already been used by another invoke in the same algorithm code. If all is well it returns the label as a string.

Parameters:: argument (fparser.two.Actual_Arg_Spec) – Parse tree of an invoke argument. This should contain a “name=xxx” argument.
Returns:: the label as a string.
Return type:: str
Raises:: ParseError – if this label has already been used by another invoke in this algorithm code.

create_builtin_kernel_call(kernel_name, args)

Takes the builtin kernel name and a list of Arg objects which capture information about the builtin call arguments and returns a BuiltinCall instance with content specific to the particular API (as specified in self._api).

Parameters:

kernel_name (str) – the name of the builtin kernel being called
args – a list of ‘Arg’ instances containing the required information for the arguments being passed from the algorithm layer. The list order is the same as the argument order.

Returns:

a BuiltInCall instance with information specific to the API.

Return type:

psyclone.parse.algorithm.BuiltInCall

Raises:

ParseError – if the builtin is specified in a use statement in the algorithm layer

create_coded_kernel_call(kernel_name, args)

Takes a coded kernel name and a list of Arg objects which capture information about the coded call arguments and returns a KernelCall instance with content specific to the particular API (as specified in self._api).

Parameters:

kernel_name (str) – the name of the coded kernel being called
args – a list of ‘Arg’ instances containing the required information for the arguments being passed from the algorithm layer. The list order is the same as the argument order.

Returns:

a KernelCall instance with information specific to the API.

Return type:

psyclone.parse.algorithm.KernelCall

Raises:

ParseError – if the kernel is not specified in a use statement in the algorithm layer

create_invoke_call(statement)

Takes the part of a parse tree containing an invoke call and returns an InvokeCall object which captures the required information about the invoke.

Parameters:

statement (fparser.two.Fortran2003.Call_Stmt) – Parse tree of the invoke call.

Returns:

An InvokeCall object which contains relevant information about the invoke call.

Return type:

psyclone.parse.algorithm.InvokeCall

Raises:

ParseError – if more than one invoke argument contains ‘name=xxx’.
ParseError – if an unknown or unsupported invoke argument is found.

create_kernel_call(argument)

Takes the parse tree of an invoke argument containing a reference to a kernel or a builtin and returns the kernel or builtin object respectively which contains the required information.

Parameters:: argument (fparser.two.Fortran2003.Part_Ref or fparser.two.Fortran2003.Structure_Constructor) – Parse tree of an invoke argument. This should contain a kernel name and associated arguments.
Returns:: A builtin or coded kernel call object which contains relevant information about the Kernel.
Return type:: psyclone.parse.algorithm.KernelCall or psyclone.parse.algorithm.BuiltInCall

invoke_info(alg_parse_tree)

Takes an fparser2 representation of a PSyclone-conformant algorithm code as input and returns an object containing information about the ‘invoke’ calls in the algorithm file and any associated kernels within the invoke calls. Also captures the type and precision of every variable declaration within the parse tree.

Parameters:

alg_parse_tree – the fparser2 representation of the algorithm code.

Type:

fparser.two.Fortran2003.Program

Returns:

an object holding details of the algorithm code and the invokes found within it.

Return type:

psyclone.parse.FileInfo

Raises:

ParseError – if a program, module, subroutine or function is not found in the fparser2 tree.
InternalError – if the fparser2 tree representing the type declaration statements is not in the expected form.
NotImplementedError – if the algorithm code contains two different datatypes with the same name.

parse(alg_filename)

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. If the NEMO API is being used then the parsed code is returned without any additional information about the code.

Parameters:: alg_filename (str) – The file containing the algorithm code.
Returns:: 2-tuple consisting of the fparser2 parse tree of the algorithm code and an object holding details of the algorithm code and the invokes found within it, unless it is the NEMO API, where the first entry of the tuple is None and the second is the fparser2 parse tree of the code.
Return type:: (fparser.two.Fortran2003.Program, psyclone.parse.FileInfo) or (NoneType, fparser.two.Fortran2003.Program)

update_arg_to_module_map(statement)

Takes a use statement and adds its contents to the internal arg_name_to_module_name map. This map associates names specified in the ‘only’ list with the corresponding use name.

Parameters:: statement (fparser.two.Fortran2003.Use_Stmt) – A use statement
Raises:: InternalError – if the statement being passed is not an fparser use statement.

class psyclone.parse.algorithm.FileInfo(name, calls)

Captures information about the algorithm file and the invoke calls found within the contents of the file.

Parameters:

name (str) – the name of the algorithm program unit (program, module, subroutine or function)
calls (list of psyclone.parse.algorithm.InvokeCall) – information about the invoke calls in the algorithm code.

Inheritance

property calls

Returns:: information about invoke calls
Return type:: list of psyclone.parse.algorithm.InvokeCall

property name

Returns:: the name of the algorithm program unit
Return type:: str

class psyclone.parse.algorithm.InvokeCall(kcalls, name=None, invoke_name='invoke')

Keeps information about an individual invoke call.

Parameters:

kcalls (list of psyclone.parse.algorithm.KernelCall or psyclone.parse.algorithm.BuiltInCall) – Information about the kernels specified in the invoke.
name (str) – An optional name to call the transformed invoke call. This defaults to None.
invoke_name (str) – the name that is used to indicate an invoke call. This defaults to ‘invoke’.

Inheritance

property kcalls

Returns:: the list of kernel calls in this invoke call
Return type:: list of psyclone.parse.algorithm.KernelCall or psyclone.parse.algorithm.BuiltInCall

property name

Returns:: the name of this invoke call
Return type:: str

class psyclone.parse.algorithm.ParsedCall(ktype, args)

Base class for information about a user-supplied or built-in kernel.

Parameters:

ktype (API-specific specialisation of psyclone.parse.kernel.KernelType) – information about a kernel or builtin. Provides access to the PSyclone description metadata and the code if it exists.
args (list of psyclone.parse.algorithm.Arg) – a list of Arg instances which capture the relevant information about the arguments associated with the call to the kernel or builtin.

Inheritance

property args

Returns:: a list of Arg instances which capture the relevant information about the arguments associated with the call to the kernel or builtin
Return type:: list of psyclone.parse.algorithm.Arg

property ktype

Returns:: information about a kernel or builtin. Provides access to the PSyclone description metadata and the code if it exists.
Return type:: API-specific specialisation of psyclone.parse.kernel.KernelType

property module_name

This name is assumed to be set by the subclasses.

Returns:: the name of the module containing the kernel code.
Return type:: str

class psyclone.parse.algorithm.KernelCall(module_name, ktype, args)

Store information about a user-supplied (coded) kernel. Specialises the generic ParsedCall class adding a module name value and a type for distinguishing this class.

Parameters:

module_name (str) – the name of the kernel module.
ktype (API-specific specialisation of psyclone.parse.kernel.KernelType) – information about the kernel. Provides access to the PSyclone description metadata and the code.
args – a list of Arg instances which capture the relevant information about the arguments associated with the call to the kernel.

Inheritance

property type

Specifies that this is a kernel call.

Returns:: the type of call as a string.
Return type:: str

class psyclone.parse.algorithm.BuiltInCall(ktype, args)

Store information about a system-supplied (builtin) kernel. Specialises the generic ParsedCall class adding a function name method (the name of the builtin) and a type for distinguishing this class.

Parameters:

ktype (API-specific specialisation of psyclone.parse.kernel.KernelType) – information about this builtin. Provides access to the PSyclone description metadata.
args (list of psyclone.parse.algorithm.Arg) – a list of Arg instances which capture the relevant information about the arguments associated with the call to the kernel or builtin

Inheritance

property func_name

Returns:: the name of this builtin.
Return type:: str

property type

Specifies that this is a builtin call.

Returns:: the type of call as a string.
Return type:: str

class psyclone.parse.algorithm.Arg(form, text, varname=None, datatype=None)

Description of an argument as obtained from parsing kernel or builtin arguments within invokes in a PSyclone algorithm code.

Parameters:

form (str) – describes whether the argument is a literal value, standard variable or indexed variable. Supported options are specified in the local form_options list.
text (str) – the original Fortran text of the argument.
varname – the extracted variable name from the text if the form is not literal otherwise it is set to None. This is optional and defaults to None.
datatype ((str, str or NoneType) or NoneType) – a tuple containing information about the datatype and precision of the argument, or None if no information is available. Defaults to None.

Value varname:

str or NoneType

Raises:

InternalError – if the form argument is not one one of the supported types as specified in the local form_options list.

Inheritance

property form

Returns:: a string indicating what type of variable this is. Supported options are specified in the local form_options list.
Return type:: str

is_literal()

Indicates whether this argument is a literal or not.

Returns:: True if this argument is a literal and False otherwise.
Return type:: bool

property text

Returns:: the original Fortran text of the argument.
Return type:: str

property varname

Returns:: the extracted variable name from the text if the form is not literal and None otherwise
Return type:: str or NoneType

psyclone.parse.algorithm

Functions

Classes

`psyclone.parse.algorithm`

Functions 

Classes 