loki.batch.item

Functions

get_all_import_map(scope)

Map of imported symbol names to objects in scope and any parent scopes

Classes

ExternalItem(name, source[, config, ...])	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.
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

get_all_import_map(scope)

Map of imported symbol names to objects in scope and any parent scopes

For imports that shadow imports in a parent scope, the innermost import takes precedence.

Parameters:

scope (Scope) – The scope for which the import map is built

Returns:

Mapping of symbol name to symbol object

Return type:

CaseInsensitiveDict

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

plan_data

Container object for plan dry-run passes to store information about additional and removed dependencies.

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.

property transformation_ir

Return the nearest Scope IR node that corresponds to a suitable transformation entry point, i.e., is a ProgramUnit or Sourcefile.

For most but not all item types this is equivalent to scope_ir.

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.

property transformation_ir

The transformation entry point for TypeDefItem is the scope in which the typedef is declared.

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.

property transformation_ir

The transformation entry point is the scope in which the typedef is declared to which this procedure binding is attached.

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

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.

• is_generated (bool) – A flag that indicates whether this item is expected to be generated by the build.

property ir

This raises a RuntimeError

property scope

This raises a RuntimeError

property path

This raises a RuntimeError