`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.
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)[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 (Union[Node, Symbol]) – Node in PSyIR in which the access happens, can also be a DataSymbol.

Inheritance

property access_type: AccessType#

Returns:: the access type.

component_indices()[source]#

Returns:: a tuple of tuples of index expressions; one for every component in the accessor. For example, for a scalar it returns (()), for a%b it returns ((),()) - two components with 0 indices in each, and for a(i)%b(j,k+1) it returns ((i,),(j,k+1)).

property description: str#

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

has_indices()[source]#

Check if the expression is a reference that has indices in any of its components.

Return type:: bool

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: Node | Symbol#

Returns:: the PSyIR node at which this access happens.

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)[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.

Return type:

None

property all_read_accesses: list[AccessInfo]#

Returns:: a list with all AccessInfo data for this variable that involve reading this variable.

property all_write_accesses: list[AccessInfo]#

Returns:: a list with all AccessInfo data for this variable that involve writing this variable.

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 (Optional[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: Signature#

Returns:: the signature for which the accesses are stored.

str_access_summary()[source]#

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

update(access_seq)[source]#

This function adds all accesses from the given access sequence to this access sequence.

Parameters:: access_seq (AccessSequence) – the accesses to add to this object.
Raises:: ValueError – if the given access sequence is for a different signature.
Return type:: None

property var_name: str#

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

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)).

REDUCTION = 6#: Is the output of a (min/max/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]#

Return type:: list[AccessType]
Returns:: A list of all access types that involve reading an argument in some form.

static all_write_accesses()[source]#

Return type:: list[AccessType]
Returns:: A list of all access types that involve writing to an argument in some form.

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.
Return type:: AccessType
Returns:: Corresponding AccessType enum.
Raises:: ValueError – if access_string is not a valid access type.

static non_data_accesses()[source]#

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

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

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)[source]#

Adds access information for the variable with the given signature.

Parameters:

signature (Signature) – the signature of the variable.
access_type (AccessType) – the type of access (READ, WRITE, …)
node (Node) – Node in PSyIR in which the access happens.

Return type:

None

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 (Signature) – signature of the variable.
Return type:: bool
Returns:: True if the specified variable is written (at least once).
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 (VariablesAccessMap) – the other VariablesAccessMap instance.
Return type:: None

psyclone.core#

Submodules#

Classes#

`psyclone.core`#

Submodules #

Classes #