# loki.batch.item module

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

  property orig_path

    The original filepath of the associated source file necessary for planning when duplicating/renaming items

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

  property ir

    Return the IR `Node` that the item represents

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`