`psyclone.core`#

This module provides access to various classes used in determining variable access information.

Classes #

AccessInfo: This class stores information about an access to a variable (the node
AccessSequence: This class stores a list with all accesses to one variable.
AccessType: A simple enum-class for the various valid access types.
ComponentIndices: This class stores index information for variable accesses. It stores
Signature: Given a variable access of the form a(i,j)%b(k,l)%c, the signature
SymbolicMaths: A wrapper around the symbolic maths package ‘sympy’. It
VariablesAccessMap: This dictionary stores AccessSequence instances indexed by

class psyclone.core.AccessInfo(access_type, node, component_indices=None)[source]#

This class stores information about an access to a variable (the node where it happens and the type of access, and the index accessed if available).

Parameters:

access – the access type.
node (Node) – Node in PSyIR in which the access happens.
component_indices (Union[list[list[Node]], ComponentIndices, None]) – indices used in the access, defaults to None.

Inheritance

property access_type: AccessType#

Returns:: the access type.

change_read_to_write()[source]#

This changes the access mode from READ to WRITE. This is used for processing assignment statements, where the LHS is first considered to be READ, and which is then changed to be WRITE.

Raises:: InternalError – if the variable originally does not have READ access.

property component_indices#

This function returns the list of accesses used for each component as an instance of ComponentIndices. For example, a(i)%b(j,k)%c will return an instance of ComponentIndices representing [ [i], [j, k], [] ]. In the case of a simple scalar variable such as a, the component_indices will represent [ [] ].

Returns:: the indices used in this access for each component.
Return type:: psyclone.core.component_indices.ComponentIndices

property description: str#

Returns:: a textual description of this access for use in error messages.

has_indices()[source]#

Return type:: bool
Returns:: whether any of the access components uses an index.

is_any_read()[source]#

Return type:: bool
Returns:: whether this access represents a write of any kind.

is_any_write()[source]#

Return type:: bool
Returns:: whether this access represents a write of any kind.

property is_data_access: bool#

Returns:: whether or not this access is to the data associated with a signature (i.e. is not just an inquiry-type access).

property node#

Returns:: the PSyIR node at which this access happens.
Return type:: psyclone.psyir.nodes.Node

class psyclone.core.AccessSequence(signature)[source]#

This class stores a list with all accesses to one variable.

Parameters:: signature (psyclone.core.Signature) – signature of the variable.

Inheritance

add_access(access_type, node, component_indices=None)[source]#

Adds access information to this variable.

Parameters:

access_type (AccessType) – the type of access (READ, WRITE, ….)
node (Node) – Node in PSyIR in which the access happens.
component_indices (Union[list[list[Node]], ComponentIndices, None]) – indices used for each component of the access.

property all_read_accesses#

Returns:: a list with all AccessInfo data for this variable that involve reading this variable.
Return type:: List[psyclone.core.AccessInfo]

property all_write_accesses#

Returns:: a list with all AccessInfo data for this variable that involve writing this variable.
Return type:: List[psyclone.core.AccessInfo]

change_read_to_write()[source]#

This function is only used when analysing an assignment statement. The LHS has first all variables identified, which will be READ. This function is then called to change the assigned-to variable on the LHS to from READ to WRITE. Since the LHS is stored in a separate AccessSequence class, it is guaranteed that there is only one READ entry for the variable (although there maybe INQUIRY accesses for array bounds).

Raises:: InternalError – if there is an access that is not READ or INQUIRY or there is > 1 READ access.

has_data_access()[source]#

Return type:: bool
Returns:: True if there is an access of the data associated with this signature (as opposed to a call or an inquiry), False otherwise.

has_indices(index_variable=None)[source]#

Checks whether this variable accesses has any index. If the optional index_variable is provided, only indices involving the given variable are considered.

Parameters:: index_variable (str) – only consider index expressions that involve this variable.
Return type:: bool
Returns:: true if any of the accesses has an index.

has_read_write()[source]#

Checks if this variable has at least one READWRITE access.

Returns:: True if this variable is read (at least once).
Return type:: bool

is_called()[source]#

Return type:: bool
Returns:: whether or not any accesses of this variable represent a call.

is_read()[source]#

Return type:: bool
Returns:: True if this variable is read (at least once).

is_read_only()[source]#

Checks if this variable is always read, and never written.

Return type:: bool
Returns:: True if this variable is read only.

is_written()[source]#

Return type:: bool
Returns:: True if this variable is written (at least once).

is_written_first()[source]#

Return type:: bool
Returns:: True if this variable is written in the first data access (which indicates that this variable is not an input variable for a kernel).

property signature#

Returns:: the signature for which the accesses are stored.
Return type:: psyclone.core.Signature

str_access_summary()[source]#

Return type:: str
Returns:: a string of the accesstypes but removing duplicates.

property var_name#

Returns:: the name of the variable whose access info is managed.
Return type:: str

class psyclone.core.AccessType(*values)[source]#

A simple enum-class for the various valid access types.

Inheritance

CALL = 8#: A symbol representing a routine is called.

CONSTANT = 10#: Access data that cannot be redefined during execution, therefore, it is available at compile-time and can be used for type properties such as kinds or dimensions.

INC = 4#: Incremented from more than one cell column (see the LFRic API section of the User Guide).

INQUIRY = 9#: The property/ies of a symbol is/are queried but the data it represents is not accessed (e.g. ‘var’ in SIZE(var, dim=1)).

READ = 1#: Data associated with the symbol is read.

READINC = 5#: Read before incrementing. Requires that the outermost halo be clean (see the LFRic API section of the User Guide).

READWRITE = 3#: Data associated with the symbol is both read and written (e.g. is passed to a routine with intent(inout)).

SUM = 6#: Is the output of a SUM reduction.

UNKNOWN = 7#: This is used internally to indicate unknown access type of a variable, e.g. when a variable is passed to a subroutine and the access type of this variable in the subroutine is unknown. TODO #2863 - VariablesAccessMap does not currently consider UNKNOWN accesses and it should!

WRITE = 2#: Data associated with the symbols is written.

static all_read_accesses()[source]#

Returns:: A list of all access types that involve reading an argument in some form.
Return type:: List of py:class:psyclone.core.access_type.AccessType.

static all_write_accesses()[source]#

Returns:: A list of all access types that involve writing to an argument in some form.
Return type:: List of py:class:psyclone.core.access_type.AccessType.

api_specific_name()[source]#

This convenience function returns the name of the type in the current API. E.g. in the lfric API, WRITE –> “gh_write”. If no mapping is available then the generic name is returned.

Return type:: str
Returns:: The API specific name.

static from_string(access_string)[source]#

Convert a string (e.g. “read”) into the corresponding AccessType enum value (AccessType.READ).

Parameters:: access_string (str) – Access type as a string.
Returns:: Corresponding AccessType enum.
Return type:: psyclone.core.access_type.AccessType
Raises:: ValueError – if access_string is not a valid access type.

static get_valid_reduction_modes()[source]#

Returns:: A list of valid reduction access modes.
Return type:: List of py:class:psyclone.core.access_type.AccessType.

static get_valid_reduction_names()[source]#

Returns:: A list of valid reduction access names.
Return type:: List of strings.

static non_data_accesses()[source]#

Returns:: all access types that do not touch any data associated with a symbol.
Return type:: list[psyclone.core.AccessType]

class psyclone.core.ComponentIndices(indices=None)[source]#

This class stores index information for variable accesses. It stores one index list for each component of a variable, e.g. for a(i)%b(j) it would store [ [i], [j] ]. Even for scalar accesses an empty list is stored, so a would have the component indices [ [] ], and a%b would have [ [], [] ]. Each member of this list of lists is the PSyIR node describing the array expression used.

As a shortcut, the indices parameter can be None or an empty list (which then creates the component indices as [[]], i.e. indicating a scalar access), a list l (which will then create the component indices as [l], i.e. a single component variable, which uses all the indices in the list l as array indices).

TODO #845 - the constructor should check that the things it is passed are PSyIR nodes. Currently it is sometimes given strings.

Parameters:

indices (None, [], a list or a list of lists of psyclone.psyir.nodes.Node) – the indices from which to create this object.

Raises:

InternalError – if the indices parameter is not None, a list or a list of lists.
InternalError – if the indices parameter is a list, and some but not all members are a list.

Inheritance

get_subscripts_of(set_of_vars)[source]#

This function returns a flat list of which variable from the given set of variables is used in each subscript. For example, the access a(i+i2)%b(j*j+k,k)%c(l,5) would have the component_indices [[i+i2], [j*j+k,k], [l,5]]. If the set of variables is (i,j,k), then get_subscripts_of would return [{i},{j,k},{k},{l},{}].

Parameters:: set_of_vars (Set[str]) – set with name of all variables.
Returns:: a list of sets with all variables used in the corresponding array subscripts as strings.
Return type:: List[Set[str]]

has_indices()[source]#

Return type:: bool
Returns:: whether any of the access components uses an index

property indices_lists#

Returns:: the component indices list of lists.
Return type:: list of list of psyclone.psyir.nodes.Node

iterate()[source]#

Allows iterating over all component indices. It returns a tuple with two elements, the first one indicating the component, the second the dimension for which the index is. The return tuple can be used in a dictionary access (see __getitem__) of this object.

Returns:: a tuple of the component index and index.
Return type:: tuple(int, int)

class psyclone.core.Signature(variable, sub_sig=None)[source]#

Given a variable access of the form a(i,j)%b(k,l)%c, the signature of this access is the tuple (a,b,c). For a simple scalar variable a the signature would just be (a,). The signature is the key used in VariablesAccessMap. In order to make sure two different signature objects containing the same variable can be used as a key, this class implements __hash__ and other special functions. The constructor also supports appending an existing signature to this new signature using the sub_sig argument. This is used in StructureReference to assemble the overall signature of a structure access.

Parameters:

variable (str or tuple of str or list of str) – the variable that is accessed.
sub_sig (psyclone.core.Signature) – a signature that is to be added to this new signature.

Inheritance

property is_structure#

Returns:: True if this signature represents a structure.
Return type:: bool

to_language(component_indices=None, language_writer=None)[source]#

Converts this signature with the provided indices to a string in the selected language.

TODO 1320 This subroutine can be removed when we stop supporting strings - then we can use a PSyIR writer for the ReferenceNode to provide the right string.

Parameters:

component_indices (None (default is scalar access), or psyclone.core.component_indices.ComponentIndices) – the indices for each component of the signature.
language_writer (None (default is Fortran), or an instance of psyclone.psyir.backend.language_writer.LanguageWriter) – a backend visitor to convert PSyIR expressions to a representation in the selected language. This is used when creating error and warning messages.

Raises:

InternalError – if the number of components in this signature is different from the number of indices in component_indices.

property var_name#

Returns:: the actual variable name, i.e. the first component of the signature.
Return type:: str

class psyclone.core.SymbolicMaths[source]#

A wrapper around the symbolic maths package ‘sympy’. It provides convenience functions for PSyclone. It has a Singleton access, e.g.:

>>> from psyclone.psyir.backend.fortran import FortranWriter
>>> from psyclone.core import SymbolicMaths
>>> sympy = SymbolicMaths.get()
>>> # Assume lhs is the PSyIR of 'i+j', and rhs is 'j+i'
>>> if sympy.equal(lhs, rhs):
...     writer = FortranWriter()
...     print(f"'{writer(lhs)}' and '{writer(rhs)}' are equal.")
'i + j' and 'j + i' are equal.

Inheritance

class Fuzzy(*values)[source]#: Enumeration used as a return value for situations where we need to support ‘true’, ‘false’ and ‘maybe’.

static equal(exp1, exp2, identical_variables=None)[source]#

Test if the two PSyIR expressions are symbolically equivalent. The optional identical_variables dictionary can contain information about variables which are known to be the same. For example, if identical_variables={‘i’: ‘j’}, then ‘i+1’ and ‘j+1’ will be considered equal.

Parameters:

exp1 (psyclone.psyir.nodes.Node) – the first expression to be compared.
exp2 (psyclone.psyir.nodes.Node) – the second expression to be compared.
identical_variables (Optional[dict[str, str]]) – which variable names are known to be identical

Returns:

whether the two expressions are mathematically identical.

Return type:

bool

static expand(expr)[source]#

Expand a PSyIR expression. This is done by converting the PSyIR expression to a sympy expression, applying the expansion operation (or simplify_logic in the case of a Boolean expression) and then converting the resultant output back into PSyIR.

Currently does not work if the PSyIR expression contains Range nodes, see issue #1655.

Parameters:: expr (psyclone.psyir.nodes.Node) – the expression to be expanded.

static get()[source]#

Static function that creates (if necessary) and returns the singleton SymbolicMaths instance.

Returns:: the instance of the symbolic maths class.
Return type:: psyclone.core.SymbolicMaths

static greater_than(exp1, exp2, all_variables_positive=None)[source]#

Determines whether exp1 is, or might be, numerically greater than exp2.

Parameters:

exp1 (psyclone.psyir.nodes.Node) – the first expression for the comparison.
exp1 – the second expression for the comparison.
all_variables_positive (Optional[bool]) – whether or not to assume that all variables appearing in either expression are positive definite. Default is not to make this assumption.

Returns:

whether exp1 is, or might be, numerically greater than exp2.

Return type:

psyclone.core.symbolic_maths.Fuzzy

static less_than(exp1, exp2, all_variables_positive=None)[source]#

Determines whether exp1 is, or might be, numerically less than exp2.

Parameters:

exp1 (psyclone.psyir.nodes.Node) – the first expression for the comparison.
exp1 – the second expression for the comparison.
all_variables_positive (Optional[bool]) – whether or not to assume that all variables appearing in either expression are positive definite. Default is not to make this assumption.

Returns:

whether exp1 is, or might be, numerically less than exp2.

Return type:

psyclone.core.symbolic_maths.Fuzzy

static never_equal(exp1, exp2)[source]#

Returns if the given SymPy expressions are guaranteed to be different regardless of the values of symbolic variables. E.g. n-1 and n are always different, but 5 and n are not always different.

Parameters:

exp1 (psyclone.psyir.nodes.Node) – the first expression to be compared.
exp2 (psyclone.psyir.nodes.Node) – the second expression to be compared.

Returns:

whether or not the expressions are never equal.

Return type:

bool

static solve_equal_for(exp1, exp2, symbol)[source]#

Returns all solutions of exp1==exp2, solved for the specified symbol. It restricts the solution domain to integer values. If there is an infinite number of solutions, it returns the string ‘independent’, indicating that the solution of exp1==exp2 does not depend on the specified symbol. This is done to avoid that the SymPy instance representing an infinite set is used elsewhere in PSyclone (i.e. creating a dependency in other modules to SymPy). Otherwise a standard Python set is returned that stores the solutions.

Parameters:

exp1 (sympy.core.basic.Basic) – the first expression.
exp2 (sympy.core.basic.Basic) – the second expression.
symbol (sympy.core.symbol.Symbol) – the symbol for which to solve.

Returns:

a set of solutions, or the string “independent”.

Return type:

Union[set, str]

class psyclone.core.VariablesAccessMap[source]#

This dictionary stores AccessSequence instances indexed by their signature.

Inheritance

add_access(signature, access_type, node, component_indices=None)[source]#

Adds access information for the variable with the given signature. If the component_indices parameter is not an instance of ComponentIndices, it is used to construct an instance. Therefore it can be None, a list or a list of lists of PSyIR nodes. In the case of a list of lists, this will be used unmodified to construct the ComponentIndices structures. If it is a simple list, it is assumed that it contains the indices used in accessing the last component of the signature. For example, for a%b with component_indices=[i,j], it will create [[], [i,j] as component indices, indicating that no index is used in the first component a. If the access is supposed to be for a(i)%b(j), then the component_indices argument must be specified as a list of lists, i.e. [[i], [j]].

Parameters:

signature (psyclone.core.Signature) – the signature of the variable.
access_type (psyclone.core.access_type.AccessType) – the type of access (READ, WRITE, …)
node (psyclone.psyir.nodes.Node instance) – Node in PSyIR in which the access happens.
component_indices (psyclone.core.component_indices.ComponentIndices, or any other type that can be used to construct a ComponentIndices instance (None, List[psyclone.psyir.nodes.Node] or List[List[psyclone.psyir.nodes.Node]])) – index information for the access.

property all_data_accesses: List[Signature]#

Returns:: all Signatures in this instance that have a data access (i.e. the data associated with them is read or written).

property all_signatures#

Returns:: all signatures contained in this instance, sorted (in order to make test results reproducible).
Return type:: List[psyclone.core.Signature]

has_read_write(signature)[source]#

Checks if the specified variable signature has at least one READWRITE access (which is typically only used in a function call).

Parameters:: signature (psyclone.core.Signature) – signature of the variable
Returns:: True if the specified variable name has (at least one) READWRITE access.
Return type:: bool
Raises:: KeyError if the signature cannot be found.

is_called(signature)[source]#

Parameters:: signature (Signature) – signature of the variable.
Return type:: bool
Returns:: True if the specified variable is called at least once.

is_read(signature)[source]#

Checks if the specified variable signature is at least read once.

Parameters:: signature (psyclone.core.Signature) – signature of the variable
Return type:: bool
Returns:: True if the specified variable name is read (at least once).
Raises:: KeyError if the signature cannot be found.

is_written(signature)[source]#

Checks if the specified variable signature is at least written once.

Parameters:: signature (psyclone.core.Signature) – signature of the variable.
Returns:: True if the specified variable is written (at least once).
Return type:: bool
Raises:: KeyError if the signature name cannot be found.

update(other_access_map)[source]#

Updates this dictionary with the entries in the provided VariablesAccessMap. If there are repeated signatures, the provided values are appended to the existing sequence of accesses.

Parameters:: other_access_map (psyclone.core.VariablesAccessMap) – the other VariablesAccessMap instance.

psyclone.core#

Submodules#

Classes#

`psyclone.core`#

Submodules #

Classes #