psyclone.psyir.symbols
Symbols package module
Submodules
psyclone.psyir.symbols.containersymbol
psyclone.psyir.symbols.data_type_symbol
psyclone.psyir.symbols.datasymbol
psyclone.psyir.symbols.datatypes
psyclone.psyir.symbols.interfaces
psyclone.psyir.symbols.intrinsic_symbol
psyclone.psyir.symbols.routinesymbol
psyclone.psyir.symbols.symbol
psyclone.psyir.symbols.symbol_table
psyclone.psyir.symbols.typed_symbol
Classes
ArgumentInterface
: Captures the interface to a Symbol that is accessed as a routineArrayType
: 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 thatContainerSymbol
: Symbol that represents a reference to a Container. The referenceDataSymbol
: 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 additionalUnresolvedType
: Indicates that the type declaration has not been found yet.ImportInterface
: Describes the interface to a Symbol that is imported from anAutomaticInterface
: The symbol is declared without attributes. Its data will liveNoType
: Indicates that the associated symbol has an empty type (equivalentRoutineSymbol
: Symbol identifying a callable routine.ScalarType
: Describes a scalar datatype (and its precision).StaticInterface
: The symbol contains data that is kept alive through the executionStructureType
: Describes a ‘structure’ or ‘derived’ datatype that is itself composedSymbol
: Generic Symbol item for the Symbol Table and PSyIR References.SymbolTable
: Encapsulates the symbol table and provides methods to add newTypedSymbol
: 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 itsUnsupportedType
: 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
- 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:
- 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
orpsyclone.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
- 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:
- property intrinsic
- Returns:
the intrinsic type of each element in the array.
- Return type:
pyclone.psyir.datatypes.ScalarType.Intrinsic
orpsyclone.psyir.symbols.DataSymbol
- property precision
- Returns:
the precision of each element in the array.
- Return type:
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.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
- 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
- property container
Returns the referenced container. If it is not available, use the interface to import the container
- Returns:
referenced container.
- Return type:
- 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:
- 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
- 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:
- 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:
- 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
- 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:
name (str) – the name of this symbol.
datatype (
psyclone.psyir.symbols.DataType
) – the type represented by this symbol.visibility (
psyclone.psyir.symbols.Symbol.Visibility
) – the visibility of this symbol.interface (
psyclone.psyir.symbols.SymbolInterface
) – the interface to this symbol.
Inheritance
- 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:
- class psyclone.psyir.symbols.DefaultModuleInterface
The symbol contains data declared in a module scope without additional attributes.
Inheritance
- class psyclone.psyir.symbols.UnresolvedType
Indicates that the type declaration has not been found yet.
Inheritance
- 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
- property container_symbol
- Returns:
symbol representing the container containing this Symbol.
- Return type:
- 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
- class psyclone.psyir.symbols.NoType
Indicates that the associated symbol has an empty type (equivalent to void in C).
Inheritance
- class psyclone.psyir.symbols.RoutineSymbol(name, datatype=None, **kwargs)
Symbol identifying a callable routine.
- Parameters:
name (str) – name of the symbol.
datatype (
psyclone.psyir.symbols.DataType
) – data type of the symbol. Default to NoType().kwargs (unwrapped dict.) – additional keyword arguments provided by
psyclone.psyir.symbols.TypedSymbol
Inheritance
- 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:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- Raises:
TypeError – if any of the arguments are of the wrong type.
ValueError – if any of the argument have unexpected values.
Inheritance
- 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 orpsyclone.psyir.symbols.DataSymbol
- class psyclone.psyir.symbols.StaticInterface
The symbol contains data that is kept alive through the execution of the program.
Inheritance
- 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
- 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:
name (str) – the name of the new component.
datatype (
psyclone.psyir.symbols.DataType
|psyclone.psyir.symbols.DataTypeSymbol
) – the type of the new component.visibility (
psyclone.psyir.symbols.Symbol.Visibility
) – whether this component is public or private.initial_value (Optional[
psyclone.psyir.nodes.DataNode
]) – the initial value of the new component.
- 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:
- lookup(name)
- Returns:
the ComponentType tuple describing the named member of this StructureType.
- Return type:
- 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:
name (str) – name of the symbol.
visibility (
psyclone.psyir.symbols.Symbol.Visibility
) – the visibility of the symbol.interface (Optional[
psyclone.psyir.symbols.symbol.SymbolInterface
]) – optional object describing the interface to this symbol (i.e. whether it is passed as a routine argument or accessed in some other way). Defaults topsyclone.psyir.symbols.AutomaticInterface
- Raises:
TypeError – if the name is not a str.
Inheritance
- 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:
- 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:
node (
psyclone.psyir.nodes.Schedule
,psyclone.psyir.nodes.Container
or NoneType) – reference to the Schedule or Container to which this symbol table belongs.default_visibility – optional default visibility value for this symbol table, if not provided it defaults to PUBLIC visibility.
- Raises:
TypeError – if node argument is not a Schedule or a Container.
Inheritance
- 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:
- 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:
- 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:
- 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:
- copy_external_import(imported_var, tag=None)
Copy the given imported variable (and its referenced ContainerSymbol if needed) into the SymbolTable.
- Parameters:
imported_var (
psyclone.psyir.symbols.DataSymbol
) – the variable to be copied in.tag (str) – a tag identifier for the new copy, by default no tag is given.
- 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:
- Raises:
NotImplementedError – this method is abstract.
- property datasymbols
- Returns:
list of symbols representing data variables.
- Return type:
- property datatypesymbols
- Returns:
the DataTypeSymbols present in the Symbol Table.
- Return type:
- 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:
- property default_visibility
- Returns:
the default visibility of symbols in this table.
- Return type:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
old_symbol (
psyclone.psyir.symbols.Symbol
) – the symbol to remove from the table.new_symbol (
psyclone.psyir.symbols.Symbol
) – the symbol to add to the table.
- 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:
symbol1 (
psyclone.psyir.symbols.Symbol
) – the first symbol.symbol2 (
psyclone.psyir.symbols.Symbol
) – the second symbol.
- 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:
- 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:
- 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:
- 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:
name (str) – name of the symbol.
datatype (
psyclone.psyir.symbols.DataType
) – data type of the symbol.kwargs (unwrapped dict.) – additional keyword arguments provided by
psyclone.psyir.symbols.Symbol
Inheritance
- 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:
- 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
orpsyclone.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:
- 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:
declaration_txt (str) – string containing the original variable declaration.
partial_datatype (Optional[
psyclone.psyir.symbols.DataType
orpsyclone.psyir.symbols.DataTypeSymbol
]) – a PSyIR datatype representing the subset of type attributes that are supported.
Inheritance
- 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
- 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
- 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
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
Variables
- psyclone.psyir.symbols.BOOLEAN_TYPE
Describes a scalar datatype (and its precision).
- Parameters:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- 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:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- 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:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- 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:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- 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:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- 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:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- 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:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- 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:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- 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:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- 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:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- 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:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- 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:
intrinsic (
pyclone.psyir.datatypes.ScalarType.Intrinsic
) – the intrinsic of this scalar type.precision (
psyclone.psyir.symbols.ScalarType.Precision
, int orpsyclone.psyir.symbols.DataSymbol
) – the precision of this scalar type.
- 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'>}