loki.batch.item_factory

Classes

ItemFactory()

Utility class to instantiate instances of Item
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_item_from_item(name, item, config=None)

Helper method to instantiate an Item as a clone of a given item with the given new name.

This helper method checks for the presence of name in the item_cache and returns that instance. If none is in the cache, it tries a lookup via the scope, if applicable. Otherwise, a new item is created as a duplicate.

This duplication is performed by replicating the corresponding FileItem and any enclosing scope items, applying name changes for scopes as implied by name.

Parameters:

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

  • item (Item) – The item to duplicate to create the new item

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

Returns:

The new item object

Return type:

Item

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