psyclone.psyir.symbols

Symbols package module

Submodules

Classes

  • ArgumentInterface: Captures the interface to a Symbol that is accessed as a routine

  • ArrayType: Describes an array datatype. Can be an array of intrinsic types (e.g.

  • CommonBlockInterface: A symbol declared in the local scope but acts as a global that

  • ContainerSymbol: Symbol that represents a reference to a Container. The reference

  • DataSymbol: Symbol identifying a data element. It contains information about:

  • DataType: Abstract base class from which all types are derived.

  • DataTypeSymbol: Symbol identifying a user-defined type (e.g. a derived type in Fortran).

  • DefaultModuleInterface: The symbol contains data declared in a module scope without additional

  • UnresolvedType: Indicates that the type declaration has not been found yet.

  • ImportInterface: Describes the interface to a Symbol that is imported from an

  • AutomaticInterface: The symbol is declared without attributes. Its data will live

  • NoType: Indicates that the associated symbol has an empty type (equivalent

  • RoutineSymbol: Symbol identifying a callable routine.

  • ScalarType: Describes a scalar datatype (and its precision).

  • StaticInterface: The symbol contains data that is kept alive through the execution

  • StructureType: Describes a ‘structure’ or ‘derived’ datatype that is itself composed

  • Symbol: Generic Symbol item for the Symbol Table and PSyIR References.

  • SymbolTable: Encapsulates the symbol table and provides methods to add new

  • TypedSymbol: Abstract base class for those Symbols that have an associated datatype.

  • UnsupportedFortranType: Indicates that a Fortran declaration is not supported by the PSyIR.

  • UnknownInterface: We have a symbol with a declaration but PSyclone does not support its

  • UnsupportedType: Indicates that a variable declaration is not supported by the PSyIR.

  • UnresolvedInterface: We have a symbol but we don’t know where it is declared.

class psyclone.psyir.symbols.ArgumentInterface(access=None)

Captures the interface to a Symbol that is accessed as a routine argument.

Parameters:

access (psyclone.psyir.symbols.ArgumentInterface.Access) – specifies how the argument is used in the Schedule

Inheritance

Inheritance diagram of ArgumentInterface
class Access(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enumeration for the different types of access that an Argument Symbol is permitted to have.

property access
Returns:

the access-type for this argument.

Return type:

psyclone.psyir.symbols.ArgumentInterface.Access

copy()
Returns:

a copy of this object.

Return type:

psyclone.psyir.symbol.SymbolInterface

class psyclone.psyir.symbols.ArrayType(datatype, shape)

Describes an array datatype. Can be an array of intrinsic types (e.g. integer) or of structure types. For the latter, the type must currently be specified as a DataTypeSymbol (see #1031).

Parameters:
  • datatype (psyclone.psyir.datatypes.DataType or psyclone.psyir.symbols.DataTypeSymbol) – the datatype of the array elements.

  • shape (list) – shape of the symbol in column-major order (leftmost index is contiguous in memory). Each entry represents an array dimension. If it is ArrayType.Extent.ATTRIBUTE the extent of that dimension is unknown but can be obtained by querying the run-time system (e.g. using the SIZE intrinsic in Fortran). If it is ArrayType.Extent.DEFERRED then the extent is also unknown and may or may not be defined at run-time (e.g. the array is ALLOCATABLE in Fortran). Otherwise it can be an int or a DataNode (that returns an int) or a 2-tuple of such quantities. If only a single value is provided then that is taken to be the upper bound and the lower bound defaults to 1. If a 2-tuple is provided then the two members specify the lower and upper bounds, respectively, of the current dimension. Note that providing an int is supported as a convenience, the provided value will be stored internally as a Literal node.

Raises:
  • TypeError – if the arguments are of the wrong type.

  • NotImplementedError – if a structure type does not have a DataTypeSymbol as its type.

Inheritance

Inheritance diagram of ArrayType
class ArrayBounds(lower, upper)

namedtuple used to store lower and upper limits of an array dimension

lower

Alias for field number 0

upper

Alias for field number 1

class Extent(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enumeration of array shape extents that are unspecified at compile time. When the extent must exist and is accessible via the run-time system it is an ‘ATTRIBUTE’. When it may or may not be defined in the current scope (e.g. the array may need to be allocated/malloc’d) it is ‘DEFERRED’.

property datatype
Returns:

the datatype of each element in the array.

Return type:

psyclone.psyir.symbols.DataSymbol

property intrinsic
Returns:

the intrinsic type of each element in the array.

Return type:

pyclone.psyir.datatypes.ScalarType.Intrinsic or psyclone.psyir.symbols.DataSymbol

property precision
Returns:

the precision of each element in the array.

Return type:

psyclone.psyir.symbols.ScalarType.Precision, int or psyclone.psyir.symbols.DataSymbol

property shape
Returns:

the (validated) shape of the symbol in column-major order (leftmost index is contiguous in memory) with each entry representing an array dimension.

Return type:

a list of ArrayType.Extent.ATTRIBUTE, ArrayType.Extent.DEFERRED, or psyclone.psyir.nodes.ArrayType.ArrayBounds. If an entry is ArrayType.Extent.ATTRIBUTE the extent of that dimension is unknown but can be obtained by querying the run-time system (e.g. using the SIZE intrinsic in Fortran). If it is ArrayType.Extent.DEFERRED then the extent is also unknown and may or may not be defined at run-time (e.g. the array is ALLOCATABLE in Fortran). Otherwise an entry is a DataNode that returns an int.

class psyclone.psyir.symbols.CommonBlockInterface

A symbol declared in the local scope but acts as a global that can be accessed by any scope referencing the same CommonBlock name.

Inheritance

Inheritance diagram of CommonBlockInterface
class psyclone.psyir.symbols.ContainerSymbol(name, wildcard_import=False, **kwargs)

Symbol that represents a reference to a Container. The reference is lazy evaluated, this means that the Symbol will be created without parsing and importing the referenced container, but this can be imported when needed.

Parameters:
  • name (str) – name of the symbol.

  • wildcard_import (bool) – if all public Symbols of the Container are imported into the current scope. Defaults to False.

  • kwargs (unwrapped dict.) – additional keyword arguments provided by psyclone.psyir.symbols.Symbol.

Inheritance

Inheritance diagram of ContainerSymbol
property container

Returns the referenced container. If it is not available, use the interface to import the container

Returns:

referenced container.

Return type:

psyclone.psyir.nodes.Container

copy()

Create and return a copy of this object. Any references to the original will not be affected so the copy will not be referred to by any other object.

Returns:

A symbol object with the same properties as this symbol object.

Return type:

psyclone.psyir.symbols.Symbol

property wildcard_import
Returns:

whether or not there is a wildcard import of all public symbols from this Container.

Return type:

bool

class psyclone.psyir.symbols.DataSymbol(name, datatype, is_constant=False, initial_value=None, **kwargs)

Symbol identifying a data element. It contains information about: the datatype, the shape (in column-major order) and the interface to that symbol (i.e. Local, Global, Argument).

Parameters:
  • name (str) – name of the symbol.

  • datatype (psyclone.psyir.symbols.DataType) – data type of the symbol.

  • is_constant (bool) – whether this DataSymbol is a compile-time constant (default is False). If True then an initial_value must also be provided.

  • initial_value (Optional[item of TYPE_MAP_TO_PYTHON | psyclone.psyir.nodes.Node]) – sets a fixed known expression as an initial value for this DataSymbol. If is_constant is True then this Symbol will always have this value. If the value is None then this symbol does not have an initial value (and cannot be a constant). Otherwise it can receive PSyIR expressions or Python intrinsic types available in the TYPE_MAP_TO_PYTHON map. By default it is None.

  • kwargs (unwrapped dict.) – additional keyword arguments provided by psyclone.psyir.symbols.TypedSymbol

Inheritance

Inheritance diagram of DataSymbol
copy()

Create and return a copy of this object. Any references to the original will not be affected so the copy will not be referred to by any other object.

Returns:

An object with the same properties as this symbol object.

Return type:

psyclone.psyir.symbols.DataSymbol

copy_properties(symbol_in)

Replace all properties in this object with the properties from symbol_in, apart from the name (which is immutable) and visibility.

Parameters:

symbol_in (psyclone.psyir.symbols.DataSymbol) – the symbol from which the properties are copied.

Raises:

TypeError – if the argument is not the expected type.

property initial_value
Returns:

the initial value associated with this symbol (if any).

Return type:

psyclone.psyir.nodes.Node

property is_constant
Returns:

Whether the symbol is a compile-time constant (True) or not (False).

Return type:

bool

class psyclone.psyir.symbols.DataType

Abstract base class from which all types are derived.

Inheritance

Inheritance diagram of DataType
class psyclone.psyir.symbols.DataTypeSymbol(name, datatype, visibility=Visibility.PUBLIC, interface=None)

Symbol identifying a user-defined type (e.g. a derived type in Fortran).

Parameters:

Inheritance

Inheritance diagram of DataTypeSymbol
copy()

Create and return a copy of this object. Any references to the original will not be affected so the copy will not be referred to by any other object.

Returns:

A symbol object with the same properties as this symbol object.

Return type:

psyclone.psyir.symbols.TypeSymbol

copy_properties(symbol_in)

Replace all properties in this object with the properties from symbol_in, apart from the name (which is immutable) and visibility.

Parameters:

symbol_in (psyclone.psyir.symbols.DataSymbol) – the symbol from which the properties are copied.

Raises:

TypeError – if the argument is not the expected type.

property datatype
Returns:

datatype that this DataTypeSymbol represents.

Return type:

psyclone.psyir.symbols.DataType

class psyclone.psyir.symbols.DefaultModuleInterface

The symbol contains data declared in a module scope without additional attributes.

Inheritance

Inheritance diagram of DefaultModuleInterface
class psyclone.psyir.symbols.UnresolvedType

Indicates that the type declaration has not been found yet.

Inheritance

Inheritance diagram of UnresolvedType
class psyclone.psyir.symbols.ImportInterface(container_symbol, orig_name=None)

Describes the interface to a Symbol that is imported from an external PSyIR container. The symbol can be renamed on import and, if so, its original name in the Container is specified using the optional ‘orig_name’ argument.

Parameters:
  • container_symbol (psyclone.psyir.symbols.ContainerSymbol) – symbol representing the external container from which the symbol is imported.

  • orig_name (Optional[str]) – the name of the symbol in the external container before it is renamed, or None (the default) if it is not renamed.

Raises:

TypeError – if the orig_name argument is an unexpected type.

Inheritance

Inheritance diagram of ImportInterface
property container_symbol
Returns:

symbol representing the container containing this Symbol.

Return type:

psyclone.psyir.symbols.ContainerSymbol

copy()
Returns:

a copy of this object.

Return type:

psyclone.psyir.symbol.SymbolInterface

property orig_name
Returns:

the symbol’s original name if it is renamed on import, or None otherwise.

Return type:

Optional[str]

class psyclone.psyir.symbols.AutomaticInterface

The symbol is declared without attributes. Its data will live during the local context.

Inheritance

Inheritance diagram of AutomaticInterface
class psyclone.psyir.symbols.NoType

Indicates that the associated symbol has an empty type (equivalent to void in C).

Inheritance

Inheritance diagram of NoType
class psyclone.psyir.symbols.RoutineSymbol(name, datatype=None, **kwargs)

Symbol identifying a callable routine.

Parameters:

Inheritance

Inheritance diagram of RoutineSymbol
property is_elemental
Returns:

whether the routine represented by this Symbol is elemental (acts element-by-element on supplied array arguments) or None if this is not known.

Return type:

bool | NoneType

property is_pure
Returns:

whether the routine represented by this Symbol has no side effects (guarantees that the routine always returns the same result for a given set of inputs).

Return type:

bool | NoneType

class psyclone.psyir.symbols.ScalarType(intrinsic, precision)

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

Inheritance

Inheritance diagram of ScalarType
class Intrinsic(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enumeration of the different intrinsic scalar datatypes that are supported by the PSyIR.

class Precision(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enumeration of the different types of ‘default’ precision that may be specified for a scalar datatype.

property intrinsic
Returns:

the intrinsic used by this scalar type.

Return type:

pyclone.psyir.datatypes.ScalarType.Intrinsic

property precision
Returns:

the precision of this scalar type.

Return type:

psyclone.psyir.symbols.ScalarType.Precision, int or psyclone.psyir.symbols.DataSymbol

class psyclone.psyir.symbols.StaticInterface

The symbol contains data that is kept alive through the execution of the program.

Inheritance

Inheritance diagram of StaticInterface
class psyclone.psyir.symbols.StructureType

Describes a ‘structure’ or ‘derived’ datatype that is itself composed of a list of other datatypes. Those datatypes are stored as an OrderedDict of namedtuples.

Note, we could have chosen to use a SymbolTable to store the properties of the constituents of the type. (Since they too have a name, a type, and visibility.) If this class ends up duplicating a lot of the SymbolTable functionality then this decision could be revisited.

Inheritance

Inheritance diagram of StructureType
class ComponentType(name, datatype, visibility, initial_value)
datatype

Alias for field number 1

initial_value

Alias for field number 3

name

Alias for field number 0

visibility

Alias for field number 2

add(name, datatype, visibility, initial_value)

Create a component with the supplied attributes and add it to this StructureType.

Parameters:
Raises:

TypeError – if any of the supplied values are of the wrong type.

property components
Returns:

Ordered dictionary of the components of this type.

Return type:

collections.OrderedDict

static create(components)

Creates a StructureType from the supplied list of properties.

Parameters:

components (List[tuple[ str, psyclone.psyir.symbols.DataType | psyclone.psyir.symbols.DataTypeSymbol, psyclone.psyir.symbols.Symbol.Visibility, Optional[psyclone.psyir.symbols.DataNode] ]]) – the name, type, visibility (whether public or private) and initial value (if any) of each component.

Returns:

the new type object.

Return type:

psyclone.psyir.symbols.StructureType

lookup(name)
Returns:

the ComponentType tuple describing the named member of this StructureType.

Return type:

psyclone.psyir.symbols.StructureType.ComponentType

class psyclone.psyir.symbols.Symbol(name, visibility=Visibility.PUBLIC, interface=None)

Generic Symbol item for the Symbol Table and PSyIR References. It has an immutable name label because it must always match with the key in the SymbolTable. If the symbol is private then it is only visible to those nodes that are descendants of the Node to which its containing Symbol Table belongs.

Parameters:
Raises:

TypeError – if the name is not a str.

Inheritance

Inheritance diagram of Symbol
class Visibility(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enumeration of the different visibility attributes supported in the PSyIR. If no visibility information is supplied for a Symbol then it is given the DEFAULT_VISIBILITY value.

PUBLIC: the symbol is visible in any scoping region that has access to

the SymbolTable containing it.

PRIVATE: the symbol is only visibile inside the scoping region that

contains the SymbolTable to which it belongs.

copy()

Create and return a copy of this object. Any references to the original will not be affected so the copy will not be referred to by any other object.

Returns:

A symbol object with the same properties as this symbol object.

Return type:

psyclone.psyir.symbols.Symbol

copy_properties(symbol_in)

Replace all properties in this object with the properties from symbol_in, apart from the name (which is immutable) and visibility.

Parameters:

symbol_in (psyclone.psyir.symbols.Symbol) – the symbol from which the properties are copied.

Raises:

TypeError – if the argument is not the expected type.

find_symbol_table(node)

Searches back up the PSyIR tree for the SymbolTable that contains this Symbol.

Parameters:

node (psyclone.psyir.nodes.Node) – the PSyIR node from which to search.

Returns:

the SymbolTable containing this Symbol or None.

Return type:

psyclone.psyir.symbols.SymbolTable or NoneType

Raises:

TypeError – if the supplied node argument is not a PSyIR Node.

get_external_symbol()

Looks-up and returns the Symbol referred to by this Symbol’s Import Interface.

Raises:
  • SymbolError – if the module pointed to by the symbol interface does not contain the symbol (or the symbol is not public).

  • NotImplementedError – if this symbol does not have an ImportInterface.

property interface
Returns:

the an object describing the interface to this Symbol.

Return type:

Sub-class of psyclone.psyir.symbols.symbol.SymbolInterface

property is_argument
Returns:

whether the Symbol has an ArgumentInterface.

Return type:

bool

property is_array
Returns:

True if this symbol is an array and False if it is not or there is not enough symbol information to determine it.

Return type:

bool

is_array_access(index_variable=None, access_info=None)

This method detects if a variable is used as an array or not. If available, it will use the access information, i.e. how the variable is used (e.g. if it has indices somewhere, like a(i)%b). This can be incorrect in case of implicit loops (e.g. a=b+1, where a and b are arrays) where the variable usage information will not have information about indices. In this case this function will fallback to querying the symbol itself.

This can cause significant slowdown if this symbol is imported from a module, since then these modules need to be parsed. # TODO #1213: Parsing modules is not yet supported.

If a loop_variable is specified, a variable access will only be considered an array access if the specified variable is used in at least one of the indices. For example: >>> do i=1, n >>> a(j) = 2

the access to a is not considered an array if loop_variable is set to i. If loop_variable is specified, access_information must be specified.

Parameters:
  • index_variable (str) – optional loop variable that is used to to determine if an access is an array access using this variable.

  • access_info (psyclone.core.SingleVariableAccessInfo) – variable access information, optional.

Returns:

if the variable is an array.

Rtype bool:

Raises:

InternalError – if a loop_variable is specified, but no access information is given.

property is_automatic
Returns:

whether the Symbol has an AutomaticInterface.

Return type:

bool

property is_commonblock
Returns:

whether the Symbol has a CommonBlockInterface.

Return type:

bool

property is_import
Returns:

whether the Symbol has an ImportInterface.

Return type:

bool

property is_modulevar
Returns:

whether the Symbol has a DefaultModuleInterface.

Return type:

bool

property is_static
Returns:

whether the Symbol has a StaticInterface.

Return type:

bool

property is_unknown_interface
Returns:

whether the Symbol has an UnknownInterface.

Return type:

bool

property is_unresolved
Returns:

whether the Symbol has an UnresolvedInterface.

Return type:

bool

property name
Returns:

name of the Symbol.

Return type:

str

resolve_type()

Update the properties of this Symbol by using the definition imported from the external Container. If this symbol does not have an ImportInterface then there is no lookup needed and we just return this symbol.

Returns:

a symbol object with the class and type determined by examining the Container from which it is imported.

Return type:

subclass of psyclone.psyir.symbols.Symbol

specialise(subclass, **kwargs)

Specialise this symbol so that it becomes an instance of the class provided in the subclass argument. This allows this instance to become a subclass without any references to it becoming invalid.

Parameters:

subclass (type of sub-class of psyclone.psyir.symbols.Symbol) – the class that this symbol will become.

Raises:

TypeError – if subclass is not a sub-class of Symbol.

property visibility
Returns:

the visibility of this Symbol.

Return type:

psyclone.psyir.symbol.Symbol.Visibility

class psyclone.psyir.symbols.SymbolTable(node=None, default_visibility=Visibility.PUBLIC)

Encapsulates the symbol table and provides methods to add new symbols and look up existing symbols. Nested scopes are supported and, by default, the add and lookup methods take any ancestor symbol tables into consideration (ones attached to nodes that are ancestors of the node that this symbol table is attached to). If the default visibility is not specified then it defaults to Symbol.Visbility.PUBLIC.

Parameters:
Raises:

TypeError – if node argument is not a Schedule or a Container.

Inheritance

Inheritance diagram of SymbolTable
add(new_symbol, tag=None)

Add a new symbol to the symbol table if the symbol name is not already in use.

Parameters:
  • new_symbol (psyclone.psyir.symbols.Symbol) – the symbol to add to the symbol table.

  • tag (str) – a tag identifier for the new symbol, by default no tag is given.

Raises:
  • InternalError – if the new_symbol argument is not a symbol.

  • KeyError – if the symbol name is already in use.

  • KeyError – if a tag is supplied and it is already in use.

property argument_datasymbols
Returns:

list of symbols representing arguments.

Return type:

List[psyclone.psyir.symbols.DataSymbol]

property argument_list

Checks that the contents of the SymbolTable are self-consistent and then returns the list of kernel arguments.

Returns:

ordered list of arguments.

Return type:

list of psyclone.psyir.symbols.DataSymbol

Raises:

InternalError – if the entries of the SymbolTable are not self-consistent.

attach(node)

Attach this symbol table to the provided scope.

Parameters:

node (py:class:psyclone.psyir.nodes.ScopingNode) – the scoped node this symbol table will attach to.

property automatic_datasymbols
Returns:

list of symbols representing automatic variables.

Return type:

List[psyclone.psyir.symbols.DataSymbol]

check_for_clashes(other_table)

Checks the symbols in the supplied table against those in this table. If there is a name clash that cannot be resolved by renaming then a SymbolError is raised.

Parameters:

other_table (psyclone.psyir.symbols.SymbolTable) – the table for which to check for clashes.

Raises:

SymbolError – if there would be an unresolvable name clash when importing symbols from other_table into this table.

property containersymbols
Returns:

a list of the ContainerSymbols present in the Symbol Table.

Return type:

List[psyclone.psyir.symbols.ContainerSymbol]

copy_external_import(imported_var, tag=None)

Copy the given imported variable (and its referenced ContainerSymbol if needed) into the SymbolTable.

Parameters:
Raises:
  • TypeError – if the given variable is not an imported variable.

  • KeyError – if the given variable name already exists in the symbol table.

property data_arguments
Returns:

list of symbols representing kernel data arguments.

Return type:

List[psyclone.psyir.symbols.DataSymbol]

Raises:

NotImplementedError – this method is abstract.

property datasymbols
Returns:

list of symbols representing data variables.

Return type:

List[psyclone.psyir.symbols.DataSymbol]

property datatypesymbols
Returns:

the DataTypeSymbols present in the Symbol Table.

Return type:

List[psyclone.psyir.symbols.DataTypeSymbol]

deep_copy()

Create a copy of the symbol table with new instances of the top-level data structures and also new instances of the symbols contained in these data structures. Modifying a symbol attribute will not affect the equivalent named symbol in the original symbol table.

The only attribute not copied is the _node reference to the scope, since that scope can only have one symbol table associated to it.

Returns:

a deep copy of this symbol table.

Return type:

psyclone.psyir.symbols.SymbolTable

property default_visibility
Returns:

the default visibility of symbols in this table.

Return type:

psyclone.psyir.symbols.Symbol.Visibility

detach()

Detach this symbol table from the associated scope and return self.

Returns:

this symbol table.

Return type:

py:class:psyclone.psyir.symbols.SymbolTable

find_or_create(name, **new_symbol_args)

Lookup a symbol by its name, if it doesn’t exist create a new symbol with the given properties.

Parameters:
  • name (str) – name of the symbol to lookup or create.

  • new_symbol_args (unwrapped Dict[str, object]) – arguments to create a new symbol.

Raises:

SymbolError – if the symbol already exists but the type_symbol argument does not match the type of the symbol found.

find_or_create_tag(tag, root_name=None, **new_symbol_args)

Lookup a tag, if it doesn’t exist create a new symbol with the given tag. By default it creates a generic Symbol with the tag as the root of the symbol name. Optionally, a different root_name or any of the arguments available in the new_symbol() method can be given to refine the name and the type of the created Symbol.

Parameters:
  • tag (str) – tag identifier.

  • root_name (str) – optional name of the new symbol if it needs to be created. Otherwise it is ignored.

  • new_symbol_args (unwrapped Dict[str, object]) – arguments to create a new symbol.

Returns:

symbol associated with the given tag.

Return type:

psyclone.psyir.symbols.Symbol

Raises:

SymbolError – if the symbol already exists but the type_symbol argument does not match the type of the symbol found.

get_reverse_tags_dict()

Constructs and returns a reverse of the map returned by tags_dict method.

Returns:

ordered dictionary of tags indexed by symbol.

Return type:

OrderedDict[psyclone.psyir.symbols.Symbol, str]

get_symbols(scope_limit=None)

Return symbols from this symbol table and all symbol tables associated with ancestors of the node that this symbol table is attached to. If there are name duplicates we only return the one from the closest ancestor including self. It accepts an optional scope_limit argument.

Parameters:

scope_limit (Optional[psyclone.psyir.nodes.Node]) – optional Node which limits the symbol search space to the symbol tables of the nodes within the given scope. If it is None (the default), the whole scope (all symbol tables in ancestor nodes) is searched otherwise ancestors of the scope_limit node are not searched.

Returns:

ordered dictionary of symbols indexed by symbol name.

Return type:

OrderedDict[str] = psyclone.psyir.symbols.Symbol

get_tags(scope_limit=None)

Return tags from this symbol table and all symbol tables associated with ancestors of the node that this symbol table is attached to. If there are tag duplicates we only return the one from the closest ancestor including self. It accepts an optional scope_limit argument.

Parameters:

scope_limit (psyclone.psyir.nodes.Node or NoneType) – optional Node which limits the symbol search space to the symbol tables of the nodes within the given scope. If it is None (the default), the whole scope (all symbol tables in ancestor nodes) is searched otherwise ancestors of the scope_limit node are not searched.

Returns:

ordered dictionary of symbols indexed by tag.

Return type:

OrderedDict[str] = psyclone.psyir.symbols.Symbol

has_wildcard_imports()

Searches this symbol table and then up through any parent symbol tables for a ContainerSymbol that has a wildcard import.

Returns:

True if a wildcard import is found, False otherwise.

Return type:

bool

property imported_symbols
Returns:

list of symbols that have an imported interface (are associated with data that exists outside the current scope).

Return type:

List[psyclone.psyir.symbols.Symbol]

is_empty()
Returns:

True if the symbol table is empty, and False otherwise.

Return type:

bool

property iteration_indices
Returns:

list of symbols representing kernel iteration indices.

Return type:

List[psyclone.psyir.symbols.DataSymbol]

Raises:

NotImplementedError – this method is abstract.

lookup(name, visibility=None, scope_limit=None)

Look up a symbol in the symbol table. The lookup can be limited by visibility (e.g. just show public methods) or by scope_limit (e.g. just show symbols up to a certain scope).

Parameters:
  • name (str) – name of the symbol.

  • visibilty – the visibility or list of visibilities that the symbol must have.

  • scope_limit (psyclone.psyir.nodes.Node or NoneType) – optional Node which limits the symbol search space to the symbol tables of the nodes within the given scope. If it is None (the default), the whole scope (all symbol tables in ancestor nodes) is searched otherwise ancestors of the scope_limit node are not searched.

Returns:

the symbol with the given name and, if specified, visibility.

Return type:

psyclone.psyir.symbols.Symbol

Raises:
  • TypeError – if the name argument is not a string.

  • SymbolError – if the name exists in the Symbol Table but does not have the specified visibility.

  • TypeError – if the visibility argument has the wrong type.

  • KeyError – if the given name is not in the Symbol Table.

lookup_with_tag(tag, scope_limit=None)

Look up a symbol by its tag. The lookup can be limited by scope_limit (e.g. just show symbols up to a certain scope).

Parameters:
  • tag (str) – tag identifier.

  • scope_limit – optional Node which limits the symbol search space to the symbol tables of the nodes within the given scope. If it is None (the default), the whole scope (all symbol tables in ancestor nodes) is searched otherwise ancestors of the scope_limit node are not searched.

Returns:

symbol with the given tag.

Return type:

psyclone.psyir.symbols.Symbol

Raises:
  • TypeError – if the tag argument is not a string.

  • KeyError – if the given tag is not in the Symbol Table.

merge(other_table, include_arguments=True)

Merges all of the symbols found in other_table into this table. Symbol objects in either table may be renamed in the event of clashes.

If other_table belongs to a Routine and contains a symbol with the same name as the Routine (i.e. a function in Fortran) then that symbol is not added to this symbol table. Also, if include_arguments is False then any Symbols representing formal routine arguments are excluded.

Parameters:
  • other_table (psyclone.psyir.symbols.SymbolTable) – the symbol table from which to add symbols.

  • include_arguments (bool) – whether to include Symbols that represent routine arguments.

Raises:
  • TypeError – if other_table is not a SymbolTable.

  • SymbolError – if name clashes prevent the merge.

new_symbol(root_name=None, tag=None, shadowing=False, symbol_type=None, **symbol_init_args)

Create a new symbol. Optional root_name and shadowing arguments can be given to choose the name following the rules of next_available_name(). An optional tag can also be given. By default it creates a generic symbol but a symbol_type argument and any additional initialization keyword arguments of this symbol_type can be provided to refine the created Symbol.

Parameters:
  • root_name (str or NoneType) – optional name to use when creating a new symbol name. This will be appended with an integer if the name clashes with an existing symbol name.

  • tag (str) – optional tag identifier for the new symbol.

  • shadowing (bool) – optional logical flag indicating whether the name can be overlapping with a symbol in any of the ancestors symbol tables. Defaults to False.

  • symbol_type (type object of class (or subclasses) of psyclone.psyir.symbols.Symbol) – class type of the new symbol.

  • symbol_init_args (unwrapped Dict[str] = object) – arguments to create a new symbol.

Raises:

TypeError – if the type_symbol argument is not the type of a Symbol object class or one of its subclasses.

next_available_name(root_name=None, shadowing=False, other_table=None)

Return a name that is not in the symbol table and therefore can be used to declare a new symbol. If the root_name argument is not supplied or if it is an empty string then the name is generated internally, otherwise the root_name is used. If required, an additional integer is appended to avoid clashes. If the shadowing argument is True (is False by default), the names in parent symbol tables will not be considered. If other_table is supplied, the new name is constructed so as not to clash with any entries in that table.

Parameters:
  • root_name (str) – optional name to use when creating a new symbol name. This will be appended with an integer if the name clashes with an existing symbol name.

  • shadowing (bool) – optional logical flag indicating whether the name can be overlapping with a symbol in any of the ancestors symbol tables. Defaults to False.

  • other_table (:py:class`psyclone.psyir.symbols.SymbolTable`) – an optional, second symbol table to take into account when constructing a new name.

Returns:

the new unique symbol name.

Return type:

str

Raises:

TypeError – if any of the arguments are of the wrong type.

property node
Returns:

the Schedule or Container to which this symbol table belongs.

Return type:

psyclone.psyir.nodes.Schedule, psyclone.psyir.nodes.Container or NoneType

parent_symbol_table(scope_limit=None)

If this symbol table is enclosed in another scope, return the symbol table of the next outer scope. Otherwise return None.

Parameters:

scope_limit (psyclone.psyir.nodes.Node or NoneType) – optional Node which limits the symbol search space to the symbol tables of the nodes within the given scope. If it is None (the default), the whole scope (all symbol tables in ancestor nodes) is searched otherwise ancestors of the scope_limit node are not searched.

Returns:

the ‘parent’ SymbolTable of the current SymbolTable (i.e. the one that encloses this one in the PSyIR hierarchy).

Return type:

psyclone.psyir.symbols.SymbolTable or NoneType

property precision_datasymbols
Returns:

list of all symbols used to define the precision of other symbols within the table.

Return type:

List[psyclone.psyir.symbols.DataSymbol]

remove(symbol)

Remove the supplied symbol from the Symbol Table. This has a high potential to leave broken links, so this method checks for some references to the removed symbol depending on the symbol type.

Currently, generic Symbols, ContainerSymbols and RoutineSymbols are supported. Support for removing other types of Symbol will be added as required.

TODO #898. This method should check for any references/uses of the target symbol.

Parameters:

symbol (psyclone.psyir.symbols.ContainerSymbol) – the container symbol to remove.

Raises:
  • TypeError – if the supplied symbol is not of type Symbol.

  • NotImplementedError – the removal of this symbol type is not supported yet.

  • KeyError – if the supplied symbol is not in the symbol table.

  • ValueError – if the supplied container symbol is referenced by one or more DataSymbols.

  • InternalError – if the supplied symbol is not the same as the entry with that name in this SymbolTable.

rename_symbol(symbol, name, dry_run=False)

Rename the given symbol which should belong to this symbol table with the new name provided.

Parameters:
  • symbol (psyclone.psyir.symbols.Symbol) – the symbol to be renamed.

  • name (str) – the new name.

  • dry_run (bool) – if True then only the validation checks are performed.

Raises:
  • TypeError – if the symbol is not a Symbol.

  • TypeError – if the name is not a str.

  • ValueError – if the given symbol does not belong to this symbol table.

  • KeyError – if the given variable name already exists in the symbol table.

  • SymbolError – if the specified Symbol is a ContainerSymbol, is imported or is a formal routine argument.

  • SymbolError – if the specified Symbol is accessed within a CodeBlock in the scope of this table.

  • SymbolError – if the symbol has a common block interface.

resolve_imports(container_symbols=None, symbol_target=None)

Try to resolve deferred and unknown information from imported symbols in this symbol table by searching for their definitions in referred external container. A single symbol to resolve can be specified for a more targeted import.

Parameters:
  • container_symbols (list of psyclone.psyir.symbols.ContainerSymbol) – list of container symbols to search in order to resolve imported symbols. Defaults to all container symbols in the symbol table.

  • symbol_target (psyclone.psyir.symbols.Symbol or NoneType) – If a symbol is given, this method will just resolve information for the given symbol. Otherwise it will resolve all possible symbols information. Defaults to None.

Raises:
  • SymbolError – if a symbol name clash is found between multiple imports or an import and a local symbol.

  • TypeError – if the provided container_symbols is not a list of ContainerSymbols.

  • TypeError – if the provided symbol_target is not a Symbol.

  • KeyError – if a symbol_target has been specified but this has not been found in any of the searched containers.

property scope
Returns:

the scope associated to this symbol table.

Return type:

psyclone.psyir.nodes.ScopingNode

shallow_copy()

Create a copy of the symbol table with new instances of the top-level data structures but keeping the same existing symbol objects. Symbols added to the new symbol table will not be added in the original but the existing objects are still the same.

Returns:

a shallow copy of this symbol table.

Return type:

psyclone.psyir.symbols.SymbolTable

specify_argument_list(argument_symbols)

Sets-up the internal list storing the order of the arguments to this kernel.

Parameters:

argument_symbols (list) – ordered list of the DataSymbols representing the kernel arguments.

Raises:

ValueError – if the new argument_list is not consistent with the existing entries in the SymbolTable.

swap(old_symbol, new_symbol)

Remove the old_symbol from the table and replace it with the new_symbol.

Parameters:
Raises:
  • TypeError – if either old/new_symbol are not Symbols.

  • SymbolError – if old_symbol and new_symbol don’t have the same name (after normalising).

swap_symbol_properties(symbol1, symbol2)

Swaps the properties of symbol1 and symbol2 apart from the symbol name. Argument list positions are also updated appropriately.

Parameters:
Raises:
  • KeyError – if either of the supplied symbols are not in the symbol table.

  • TypeError – if the supplied arguments are not symbols, or the names of the symbols are the same in the SymbolTable instance.

property symbols
Returns:

list of symbols.

Return type:

List[psyclone.psyir.symbols.Symbol]

property symbols_dict
Returns:

ordered dictionary of symbols indexed by symbol name.

Return type:

OrderedDict[str] = psyclone.psyir.symbols.Symbol

symbols_imported_from(csymbol)

Examines the contents of this symbol table to see which DataSymbols (if any) are imported from the supplied ContainerSymbol (which must be present in the SymbolTable).

Parameters:

csymbol (psyclone.psyir.symbols.ContainerSymbol) – the ContainerSymbol to search for imports from.

Returns:

list of DataSymbols that are imported from the supplied ContainerSymbol. If none are found then the list is empty.

Return type:

list of psyclone.psyir.symbols.DataSymbol

Raises:
  • TypeError – if the supplied object is not a ContainerSymbol.

  • KeyError – if the supplied object is not in this SymbolTable.

property tags_dict
Returns:

ordered dictionary of symbols indexed by tag.

Return type:

OrderedDict[str] = psyclone.psyir.symbols.Symbol

property unresolved_datasymbols
Returns:

list of symbols representing unresolved variables.

Return type:

List[psyclone.psyir.symbols.DataSymbol]

view()
Returns:

a representation of this Symbol Table.

Return type:

str

class psyclone.psyir.symbols.TypedSymbol(name, datatype, **kwargs)

Abstract base class for those Symbols that have an associated datatype.

Parameters:

Inheritance

Inheritance diagram of TypedSymbol
copy()

Create and return a copy of this object. Any references to the original will not be affected so the copy will not be referred to by any other object.

Returns:

A symbol object with the same properties as this symbol object.

Return type:

psyclone.psyir.symbols.TypedSymbol

copy_properties(symbol_in)

Replace all properties in this object with the properties from symbol_in, apart from the name (which is immutable) and visibility.

Parameters:

symbol_in (psyclone.psyir.symbols.DataSymbol) – the symbol from which the properties are copied.

Raises:

TypeError – if the argument is not the expected type.

property datatype
Returns:

datatype of the TypedSymbol.

Return type:

psyclone.psyir.symbols.DataType or psyclone.psyir.symbols.DataTypeSymbol

property is_array
Returns:

True if this symbol is an array and False if it is not or there is not enough symbol information to determine it.

Return type:

bool

property is_scalar
Returns:

True if this symbol is a scalar and False otherwise.

Return type:

bool

resolve_type()

If the symbol has an Unresolved datatype, find where it is defined (i.e. an external container) and obtain the properties of the symbol.

Returns:

this TypedSymbol with its properties updated. This is for consistency with the equivalent method in the Symbol class which returns a new Symbol object.

Return type:

psyclone.psyir.symbols.TypedSymbol

property shape
Returns:

shape of the symbol in column-major order (leftmost index is contiguous in memory). Each entry represents an array dimension. If it is ‘None’ the extent of that dimension is unknown, otherwise it holds an integer literal or a reference to an integer symbol with the extent. If it is an empty list then the symbol represents a scalar.

Return type:

List[Optional[psyclone.psyir.nodes.Literal | psyclone.psyir.nodes.Reference]]

class psyclone.psyir.symbols.UnsupportedFortranType(declaration_txt, partial_datatype=None)

Indicates that a Fortran declaration is not supported by the PSyIR.

Parameters:

Inheritance

Inheritance diagram of UnsupportedFortranType
property partial_datatype
Returns:

partial datatype information if it can be determined, else None.

Return type:

Optional[psyclone.symbols.DataType]

property type_text

Parses the original Fortran declaration and uses the resulting parse tree to extract the type information. This is returned in text form and also cached.

TODO #2137 - alter Unsupported(Fortran)Type so that it is only the type information that is stored as a string. i.e. remove the name of the variable being declared. Once that is done this method won’t be required.

Note that UnsupportedFortranType is also used to hold things like ‘SAVE :: /my_common/’ and thus it is not always possible/appropriate to extract a type expression.

Returns:

the Fortran code specifying the type.

Return type:

str

Raises:

NotImplementedError – if declaration text cannot be extracted from the original Fortran declaration.

class psyclone.psyir.symbols.UnknownInterface

We have a symbol with a declaration but PSyclone does not support its attributes.

Inheritance

Inheritance diagram of UnknownInterface
class psyclone.psyir.symbols.UnsupportedType(declaration_txt)

Indicates that a variable declaration is not supported by the PSyIR. This class is abstract and must be subclassed for each language supported by the PSyIR frontends.

Parameters:

declaration_txt (str) – the original textual declaration of the symbol.

Raises:

TypeError – if the supplied declaration_txt is not a str.

Inheritance

Inheritance diagram of UnsupportedType
property declaration
Returns:

the original declaration of the symbol. This is obviously language specific and hence this class must be subclassed.

Return type:

str

class psyclone.psyir.symbols.UnresolvedInterface

We have a symbol but we don’t know where it is declared.

Inheritance

Inheritance diagram of UnresolvedInterface

Exceptions

  • SymbolError: PSyclone-specific exception for use with errors relating to the Symbol and

exception psyclone.psyir.symbols.SymbolError(value)

PSyclone-specific exception for use with errors relating to the Symbol and SymbolTable in the PSyIR.

Parameters:

value (str) – the message associated with the error.

Inheritance

Inheritance diagram of SymbolError

Variables

psyclone.psyir.symbols.BOOLEAN_TYPE

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

<psyclone.psyir.symbols.datatypes.ScalarType object at 0x7f31db3eef00>
psyclone.psyir.symbols.CHARACTER_TYPE

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

<psyclone.psyir.symbols.datatypes.ScalarType object at 0x7f31db3eef30>
psyclone.psyir.symbols.INTEGER_TYPE

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

<psyclone.psyir.symbols.datatypes.ScalarType object at 0x7f31db3eede0>
psyclone.psyir.symbols.INTEGER_SINGLE_TYPE

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

<psyclone.psyir.symbols.datatypes.ScalarType object at 0x7f31db3eecf0>
psyclone.psyir.symbols.INTEGER_DOUBLE_TYPE

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

<psyclone.psyir.symbols.datatypes.ScalarType object at 0x7f31db3eee70>
psyclone.psyir.symbols.INTEGER4_TYPE

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

<psyclone.psyir.symbols.datatypes.ScalarType object at 0x7f31db3eeea0>
psyclone.psyir.symbols.INTEGER8_TYPE

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

<psyclone.psyir.symbols.datatypes.ScalarType object at 0x7f31db3eeed0>
psyclone.psyir.symbols.REAL_TYPE

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

<psyclone.psyir.symbols.datatypes.ScalarType object at 0x7f31db3eec00>
psyclone.psyir.symbols.REAL_SINGLE_TYPE

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

<psyclone.psyir.symbols.datatypes.ScalarType object at 0x7f31db3eec60>
psyclone.psyir.symbols.REAL_DOUBLE_TYPE

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

<psyclone.psyir.symbols.datatypes.ScalarType object at 0x7f31db3eec90>
psyclone.psyir.symbols.REAL4_TYPE

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

<psyclone.psyir.symbols.datatypes.ScalarType object at 0x7f31db3eecc0>
psyclone.psyir.symbols.REAL8_TYPE

Describes a scalar datatype (and its precision).

Parameters:
Raises:
  • TypeError – if any of the arguments are of the wrong type.

  • ValueError – if any of the argument have unexpected values.

<psyclone.psyir.symbols.datatypes.ScalarType object at 0x7f31db3eed20>
psyclone.psyir.symbols.TYPE_MAP_TO_PYTHON

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:

d = {} for k, v in iterable:

d[k] = v

dict(**kwargs) -> new dictionary initialized with the name=value pairs

in the keyword argument list. For example: dict(one=1, two=2)

{<Intrinsic.INTEGER: 1>: <class 'int'>,
 <Intrinsic.REAL: 2>: <class 'float'>,
 <Intrinsic.BOOLEAN: 3>: <class 'bool'>,
 <Intrinsic.CHARACTER: 4>: <class 'str'>}