loki.batch.item

Classes

ExternalItem(name, source[, config, origin_cls])	Item class representing an external dependency that cannot be resolved
FileItem(name, source[, config])	Item class representing a Sourcefile
InterfaceItem(name, source[, config])	Item class representing a Interface declared in a module
Item(name, source[, config])	Base class of a work item in the Scheduler graph, to which a Transformation can be applied.
ItemFactory()	Utility class to instantiate instances of Item
ModuleItem(name, source[, config])	Item class representing a Module
ProcedureBindingItem(name, source[, config])	Item class representing a Fortran procedure binding
ProcedureItem(name, source[, config])	Item class representing a Subroutine
TypeDefItem(name, source[, config])	Item class representing a TypeDef

class Item(name, source, config=None)

Bases: ItemConfig

Base class of a work item in the Scheduler graph, to which a Transformation can be applied.

The Scheduler builds a dependency graph consisting of Item instances as nodes.

The name of a Item refers to the corresponding routine’s, interface’s or type’s name using a fully-qualified name in the format <scope_name>#<local_name>. The <scope_name> corresponds to a Fortran module that, e.g., a subroutine is declared in, or can be empty if the subroutine is not enclosed in a module (i.e. exists in the global scope). This is to enable use of routines with the same name that are declared in different modules. The corresponding parts of the name can be accessed via scope_name and local_name.

For type-bound procedures, the local_name should take the format <type_name>%<binding_name>. This may also span across multiple derived types, e.g., to allow calls to type bound procedures of a derived type variable that in turn is a member of another derived type, e.g., <type_name>%<member_name>%<binding_name>. See ProcedureBindingItem` for more details.

Relation to Loki IR

Every Item corresponds to a specific node in Loki’s internal representation.

For most cases these IR nodes are scopes:

• FileItem: corresponding to Sourcefile

• ModuleItem: corresponding to Module

• ProcedureItem: corresponding to Subroutine

The remaining cases are items corresponding to IR nodes that constitute some form of intermediate dependency, which are required to resolve the indirection to the scope node:

• InterfaceItem: corresponding to Interface

• TypeDefItem: corresponding to TypeDef

• ProcedureBindingItem: corresponding to the ProcedureSymbol that is declared in a ProcedureDeclaration in a derived type.

The IR node corresponding to an item can be obtain via the ir property.

Definitions and dependencies of items

Each item exhibits two key properties:

• definitions: A list of all IR nodes that constitute symbols/names

that are made available by an item. For a FileItem, this typically consists of all modules and procedures in that sourcefile, and for a ModuleItem it comprises of procedures, interfaces, global variables and derived type definitions. * dependencies: A list of all IR nodes that introduce a dependency on other items, e.g., CallStatement or Import.

Item config

Every item has a bespoke configuration derived from the default values in SchedulerConfig. The schema and accessible attributes are defined in the base class ItemConfig.

_parser_class

The parser classes that need to be active during a parse with the REGEX frontend to create the IR nodes corresponding to the item type. This class attribute is specified by every class implementing a specific item type.

Type:

tuple of RegexParserClass or None

_defines_items

The types of items that definitions of the item may create. This class attribute is specified by every class implementing a specific item type.

Type:

tuple of subclasses of Item

_depends_class

The parser classes that need to be active during a parse with the REGEX frontend to create the IR nodes that constitute dependencies in this item type. This class attribute is specified by every class implementing a specific item type.

Type:

tuple of RegexParserClass or None

source

The sourcefile object in which the IR node corresponding to this item is defined. The ir property will look-up and yield the IR node in this source file.

Type:

Sourcefile

trafo_data

Container object for analysis passes to store analysis data. This can be used in subsequent transformation passes.

Type:

any:dict

param name:

Name to identify items in the schedulers graph

type name:

str

param source:

The underlying source file that contains the associated item

type source:

Sourcefile

param config:

Dict of item-specific config options, see ItemConfig

type config:

dict

property definitions

Return a tuple of the IR nodes this item defines

By default, this returns an empty tuple and is overwritten by derived classes.

property dependencies

Return a tuple of IR nodes that constitute dependencies for this item

This calls concretize_dependencies() to trigger a further parse with the REGEX frontend, including the _depends_class of the item. The list of actual dependencies is defined via _dependencies(), which is overwritten by derived classes.

property ir

Return the IR Node that the item represents

property scope_ir

Return the nearest Scope IR node that this item either defines or is embedded into.

concretize_definitions()

Trigger a re-parse of the source file corresponding to the current item’s scope

This uses _parser_classes_from_item_type_names() to determine all RegexParserClass that the item’s definitions require to be parsed. An item’s definition classes are listed in _defines_items.

concretize_dependencies()

Trigger a re-parse of the source file corresponding to the current item’s scope

This uses _depends_class to determine all RegexParserClass that the are require to be parsed to find the item’s dependencies.

create_definition_items(item_factory, config=None, only=None)

Create the Item nodes corresponding to the definitions in the current item

Parameters:

• item_factory (ItemFactory) – The ItemFactory to use when creating the items

• config (SchedulerConfig, optional) – The scheduler config to use when instantiating new items

• only (list of Item classes) – Filter the generated items to include only those provided in the list

Returns:

The list of Item nodes

Return type:

tuple

create_dependency_items(item_factory, config=None, only=None)

Create the Item nodes corresponding to the dependencies of the current item

Parameters:

• item_factory (ItemFactory) – The ItemFactory to use when creating the items

• config (SchedulerConfig, optional) – The scheduler config to use when instantiating new items

• only (list of Item classes) – Filter the generated items to include only those provided in the list

Returns:

The list of Item nodes

Return type:

tuple

property scope_name

The name of this item’s scope

property local_name

The item name without the scope

property scope

IR object that is the enclosing scope of this Item

Note that this property is cached, so that updating the name of an associated Module (eg. via the DependencyTransformation) may not break the association with this Item.

Return type:

Module or NoneType

property calls

Return a tuple of local names of subroutines that are called

This will replace the object name by the type name for calls to typebound procedures, but not resolve potential renaming via imports.

property targets

Set of “active” child dependencies that are part of the transformation traversal.

This includes all child dependencies of an item that will be traversed when applying a Transformation, after tree pruning rules are applied but without taking item filters into account.

This means, all items excluded via block or disable lists in the SchedulerConfig are not listed here. However, this will include items in the ignore list, which are not processed but are treated as if they were.

Return type:

list of str

property targets_and_blocked_targets

Set of all child dependencies, including those that are not part of the traversal, but ignoring disabled dependencies.

This includes all child dependencies that are returned by Item.targets as well as any that are excluded via the ItemConfig.block list.

This means, only items excluded via disable lists in the SchedulerConfig are not listed here. However, it will include items in the ignore and block list.

Return type:

list of str

property path

The filepath of the associated source file

class FileItem(name, source, config=None)

Bases: Item

Item class representing a Sourcefile

The name of this item is typically the file path.

A FileItem does not have any direct dependencies. A dependency filegraph can be generated by the SGraph class using dependencies of items defined by nodes inside the file.

A FileItem defines ModuleItem and ProcedureItem nodes.

property definitions

Return the list of definitions in this source file

property ir

Return the Sourcefile associated with this item

create_definition_items(item_factory, config=None, only=None)

Create the Item nodes corresponding to the definitions in the file

This overwrites the corresponding method in the base class to enable instantiating the top-level scopes in the file item without them being available in the ItemFactory.item_cache, yet.

Parameters:

• item_factory (ItemFactory) – The ItemFactory to use when creating the items

• config (SchedulerConfig, optional) – The scheduler config to use when instantiating new items

• only (list of Item classes) – Filter the generated items to include only those provided in the list

Returns:

The list of Item nodes

Return type:

tuple

class ModuleItem(name, source, config=None)

Bases: Item

Item class representing a Module

The name of this item is the module’s name, meaning scope name, local name and name are all equivalent.

A ModuleItem defines ProcedureItem, InterfaceItem and TypeDefItem. Note that global variable imports, which are the fourth kind of symbols that can be imported from a module into other scopes are not represented by bespoke items.

A ModuleItem can only have a dependency on another ModuleItem via a Import statement.

property definitions

Return the list of definitions in this module, filtering out global variables.

property local_name

Return the module’s name

class ProcedureItem(name, source, config=None)

Bases: Item

Item class representing a Subroutine

The name of this item is comprised of the scope’s name in which the procedure is declared, i.e., the enclosing module, and the procedure name: <scope_name>#<procedure_name>. For procedures that are not declared inside a module, the <scope_name> is an empty string, i.e., the item name becomes #<procedure_name>.

A ProcedureItem does not define any child items.

Dependencies of a ProcedureItem can be introduced by

• imports, i.e., a dependency on ModuleItem,

• the use of derived types, i.e., a dependency on TypeDefItem,

• calls to other procedures, i.e., a dependency on ProcedureItem or, as an indirection, on InterfaceItem or ProcedureBindingItem.

class TypeDefItem(name, source, config=None)

Bases: Item

Item class representing a TypeDef

The name of this item is comprised of the scope’s name in which the derived type is declared, i.e., the enclosing module, and the type name: <scope_name>#<type_name>.

A TypeDefItem defines ProcedureBindingItem.

Dependencies of a TypeDefItem are introduced via

• the use of derived types in declarations of members, i.e., a dependency on TypeDefItem,

• imports of derived types, i.e., a dependency on ModuleItem.

property definitions

Return the list of ProcedureDeclaration nodes that define procedure bindings in this item.

class InterfaceItem(name, source, config=None)

Bases: Item

Item class representing a Interface declared in a module

The name of this item is comprised of the scope’s name in which the interface is declared, i.e., the enclosing module, and the interface name: <scope_name>#<intf_name>.

A InterfaceItem does not define any child items.

The dependency of an InterfaceItem is the procedure it declares, i.e., a ProcedureItem or another InterfaceItem.

This does not constitute a work item when applying transformations across the call tree in the Scheduler and is skipped by most transformations during the processing phase. However, it is necessary to provide the dependency link from calls to procedures declared via an interface to their implementation in a Fortran routine.

property scope_ir

Return the Module in which the interface is declared.

class ProcedureBindingItem(name, source, config=None)

Bases: Item

Item class representing a Fortran procedure binding

The name of this item is comprised of three parts: the scope’s name in which the derived type with this procedure binding is declared, the name of the derived type, and the name of the procedure binding: <scope_name>#<type_name>%<bind_name>.

For nested derived types, the <bind_name> may consist of multiple parts, e.g., <scope_name>#<type1_name>%<type1_var>%<type2_var>%<bind_name>.

A ProcedureBindingItem does not define any child items.

The dependency of a ProcedureBindingItem is the procedure it binds to, i.e., a ProcedureItem, an InterfaceItem, or another ProcedureBindingItem to resolve generic bindings or calls to bindings in nested derived types.

A ProcedureBindingItem does not constitute a work item when applying transformations across the dependency tree in the Scheduler and is skipped during the processing phase by most transformations. However, it is necessary to provide the dependency link from calls to type bound procedures to their implementation in a Fortran routine.

property ir

Return the ProcedureSymbol this binding corresponds to.

property scope_ir

Return the TypeDef in which this procedure binding appears.

class ExternalItem(name, source, config=None, origin_cls=None)

Bases: Item

Item class representing an external dependency that cannot be resolved

The name of this item may be a fully qualified name containing scope and local name, or only a local name.

It does not define any child items or depend on other items.

It does not constitute a work item when applying transformations across the call tree in the Scheduler.

Parameters:

origin_cls – The subclass of Item this item represents.

property ir

This raises a RuntimeError

property scope

This raises a RuntimeError

property path

This raises a RuntimeError

class ItemFactory

Bases: object

Utility class to instantiate instances of Item

It maintains a item_cache for all created items. Most important factory method is create_from_ir() to create (or return from the cache) a Item object corresponding to an IR node. Other factory methods exist for more bespoke use cases.

item_cache

This maps item names to corresponding Item objects

Type:

CaseInsensitiveDict

create_from_ir(node, scope_ir, config=None, ignore=None)

Helper method to create items for definitions or dependency

This is a helper method to determine the fully-qualified item names and item type for a given IR Node, e.g., when creating the items for definitions (see Item.create_definition_items) or dependencies (see Item.create_dependency_items).

This routine’s responsibility is to determine the item name, and then call get_or_create_item() to look-up an existing item or create it.

Parameters:

• node (Node or pymbolic.primitives.Expression) – The Loki IR node for which to create a corresponding Item

• scope_ir (Scope) – The scope node in which the IR node is declared or used. Note that this is not necessarily the same as the scope of the created Item but serves as the entry point for the lookup mechanism that underpins the creation procedure.

• config (any:SchedulerConfiguration, optional) – The config object from which a bespoke item configuration will be derived.

• ignore (list of str, optional) – A list of item names that should be ignored, i.e., not be created as an item.

get_or_create_item(item_cls, item_name, scope_name, config=None)

Helper method to instantiate an Item of class item_cls with name item_name.

This helper method checks for the presence of item_name in the item_cache and returns that instance. If none is found, an instance of item_cls is created and stored in the item cache.

The scope_name denotes the name of the parent scope, under which a parent Item has to exist in self.item_cache to find the source object to use.

Item names matching one of the entries in the config disable list are skipped. If strict mode is enabled, this raises a RuntimeError if no matching parent item can be found in the item cache.

Parameters:

• item_cls (subclass of Item) – The class of the item to create

• item_name (str) – The name of the item to create

• scope_name (str) – The name under which a parent item can be found in the item_cache to find the corresponding source

• config (SchedulerConfig, optional) – The config object to use to determine disabled items, and to use when instantiating the new item

Returns:

The item object or None if disabled or impossible to create

Return type:

Item or None

get_or_create_file_item_from_path(path, config, frontend_args=None)

Utility method to create a FileItem for a given path

This is used to instantiate items for the first time during the scheduler’s discovery phase. It will use a cached item if it exists, or parse the source file using the given frontend_args.

Parameters:

• path (str or pathlib.Path) – The file path of the source file

• config (SchedulerConfig) – The config object from which the item configuration will be derived

• frontend_args (dict, optional) – Frontend arguments that are given to Sourcefile.from_file when parsing the file

get_or_create_file_item_from_source(source, config)

Utility method to create a FileItem corresponding to a given source object

This can be used to create a FileItem for an already parsed Sourcefile, or when looking up the file item corresponding to a Item by providing the item’s source object.

Lookup is not performed via the path property in source but by searching for an existing FileItem in the cache that has the same source object. This allows creating clones of source files during transformations without having to ensure their path property is always updated. Only if no item is found in the cache, a new one is created.

Parameters:

• source (Sourcefile) – The existing sourcefile object for which to create the file item

• config (SchedulerConfig) – The config object from which the item configuration will be derived

get_or_create_module_definitions_from_candidates(name, config, module_names=None, only=None)

Utility routine to get definition items matching name from a given list of module candidates

This can be used to find a dependency that has been introduced via an unqualified import statement, where the local name of the dependency is known and a set of candidate modules thanks to the unqualified imports on the use side.

Parameters:

• name (str) – Local name of the item(s) in the candidate modules

• config (SchedulerConfig) – The config object from which the item configuration will be derived

• module_names (list of str, optional) – List of module candidates in which to create the definition items. If not provided, all ModuleItem in the cache will be considered.

• only (list of Item classes, optional) – Filter the generated items to include only those of the type provided in the list

Returns:

The items matching name in the modules given in module_names. Ideally, only a single item will be found (or there would be a name conflict).

Return type:

tuple of Item