# loki.batch.configure

Classes

`ItemConfig`(config) | `Item`-specific configuration settings.
`PipelineConfig`(name[, transformations]) | Configuration object for custom `Pipeline` instances that can be used to create pipelines from other transformations stored in the config.
`SchedulerConfig`(default, routines[, ...]) | Configuration object for the `Scheduler`
`TransformationConfig`(name, module[, ...]) | Configuration object for `Transformation` instances that can be used to create `Transformation` objects from dictionaries or a config file.

class SchedulerConfig(default, routines, disable=None, dimensions=None, transformation_configs=None, pipeline_configs=None, enable_imports=False, frontend_args=None)

  Bases: `object`

  > Configuration object for the `Scheduler`

  > It encapsulates config options for scheduler behaviour, with default options and item-specific overrides, as well as transformation-specific parameterisations.

  > The `SchedulerConfig` can be created either from a raw dictionary or configuration file.

  > defaultdict

  >   Default options for each item

  > routinesdict of dicts or list of dicts

  >   Dicts with routine-specific options.

  > dimensionsdict of dicts or list of dicts

  >   Dicts with options to define `Dimension` objects.

  > disablelist of str

  >   Subroutine names that are entirely disabled and will not be added to either the callgraph that we traverse, nor the visualisation. These are intended for utility routines that pop up in many routines but can be ignored in terms of program control flow, like `flush` or `abort`.

  > enable_imports : bool

  ￼ Disable the inclusion of module imports as scheduler dependencies.
    transformation_configsdict

      Dicts with transformation-specific options

    frontend_argsdict

      Dicts with file-specific frontend options

  classmethod from_dict(config)
  classmethod from_file(path)
  static match_item_keys(item_name, keys, use_pattern_matching=False, match_item_parents=False)

    Helper routine to match an item name against config keys.

    The `item_name` may be a fully-qualified name of an `Item`, which may include a scope, or only a partial, e.g., local name part. This is then compared against a provided list of keys as they may appear in a config property (for example an `ignore` or `disable` list).

    By default, the fully qualified name and the local name are matched. Optionally, the matching can be be extended to parent scopes in the item name, which is particularly useful if, e.g., the item name of a module member is checked against an exclusion list, which lists the module name. This is enabled via `match_item_parents`.

    The matching can take patterns in the `keys` into account, allowing for the pattern syntax supported by `fnmatch`. This requires enabling `use_pattern_matching`.

    Parameters:

      - item_name (str) – The item name to check for matches

      - keys (list of str) – The config key values to check for matches

      - use_pattern_matching (bool, optional) – Allow patterns in `keys` when matching (default `False`)

      - match_item_parents (bool, optional) – Match also name parts of parent scopes in `item_name`

    Returns:

      The entries in `keys` that `item_name` matched

    Return type:

      tuple of str

  create_item_config(name)

    Create the bespoke config dict for an `Item`

    The resulting config object contains the `default` values and any item-specific overwrites and additions.

  create_frontend_args(path, default_args)

    Create bespoke `frontend_args` to pass to the constructor or `make_complete` method for a file

    The resulting dict contains overwrites that have been provided in the `frontend_args` of the config.

    Parameters:

      - path (str or pathlib.Path) – The file path for which to create the frontend arguments. This can be a fully-qualified path or include `fnmatch`-compatible patterns.

      - default_args (dict) – The default options to use. Only keys that are explicitly overriden for the file in the scheduler config are updated.

    Returns:

      The frontend arguments, with file-specific overrides of `default_args` if specified in the Scheduler config.

    Return type:

      dict

  is_disabled(name)

    Check if the item with the given `name` is marked as disabled

class TransformationConfig(name, module, classname=None, path=None, options=None)

  Bases: `object`

  Configuration object for `Transformation` instances that can be used to create `Transformation` objects from dictionaries or a config file.

  Parameters:

    - name (str) – Name of the transformation object

    - module (str) – Python module from which to load the transformation class

    - classname (str, optional) – Name of the class to look for when instantiating the transformation. If not provided, `name` will be used instead.

    - path (str or Path, optional) – Path to add to the sys.path before attempting to load the `module`

    - options (dict) – Dicts of options that define the transformation behaviour. These options will be passed as constructor arguments using keyword-argument notation.

  resolve_dimensions(dimensions)

    Substitute `Dimension` objects for placeholder strings.

    The format of the string replacement matches the TOML configuration. It will attempt to replace `%dimensions.dim_name%` with a `Dimension` found in `dimensions`:

    Parameters:

      dimensions (dict) – Dict matching string to pre-configured `Dimension` objects.

  instantiate()

    Creates instantiated `Transformation` object from stored config options.

class PipelineConfig(name, transformations=None)

  Bases: `object`

  Configuration object for custom `Pipeline` instances that can be used to create pipelines from other transformations stored in the config.

  Parameters:

    - name (str) – Name of the transformation object

    - transformations (list of str) – List of transformation names for which to look when instnatiating thie pipeline.

  instantiate(transformation_map=None)

    Creates a custom `Pipeline` object from instantiated `Transformation` or `Pipeline` objects in the given map.

class ItemConfig(config)

  Bases: `object`

  `Item`-specific configuration settings.

  This is filled by inheriting values from `SchedulerConfig.default` and applying explicit specialisations provided for an item in the config file or dictionary.

  role

    Role in the transformation chain, typically `'driver'` or `'kernel'`

    Type:

      str or None

  mode

    Transformation “mode” to pass to transformations applied to the item

    Type:

      str or None

  expand

    Flag to enable/disable expansion of children under this node

    Type:

      bool (default: False)

  strict

    Flag controlling whether to fail if dependency items cannot be found

    Type:

      bool (default: True)

  replicate

    Flag indicating whether to mark item as “replicated” in call graphs

    Type:

      bool (default: False)

  disable

    List of dependency names that are completely ignored and not reported as dependencies by the item. Useful to exclude entire call trees or utility routines.

    Type:

      tuple

  block

    List of dependency names that should not be added to the scheduler graph as dependencies and are not processed as targets. Note that these might still be shown in the graph visualisation.

    Type:

      tuple

  ignore

    List of dependency names that should not be added to the scheduler graph as dependencies (and are therefore not processed by transformations) but are treated in the current item as targets. This facilitates processing across build targets, where, e.g., caller and callee-side are transformed in separate Loki passes.

    Type:

      tuple

  enrich

    List of program units that should still be looked up and used to “enrich” IR nodes (e.g., `ProcedureSymbol` in `CallStatement`) in this item for inter-procedural transformation passes.

    Type:

      tuple

  Parameters:

    config (dict) – The config values for the `Item`. Typically generated by `SchedulerConfig.create_item_config`.

  property role

    Role in the transformation chain, for example `'driver'` or `'kernel'`

  property mode

    Transformation “mode” to pass to the transformation

  property expand

    Flag to trigger expansion of children under this node

  property lib

    Compile unit/library this item belongs to

  property strict

    Flag controlling whether to strictly fail if source file cannot be parsed

  property replicate

    Flag indicating whether to mark item as “replicated” in call graphs

  property disable

    List of sources to completely exclude from expansion and the source tree.

  property block

    List of sources to block from processing, but add to the source tree for visualisation.

  property ignore

    List of sources to expand but ignore during processing

  property enrich

    List of sources to to use for IPA enrichment

  property is_ignored

    Flag controlling whether the item is ignored during processing

  classmethod match_symbol_or_name(symbol_or_name, keys, scope=None)

    Match a `TypedSymbol`, `MetaSymbol` or name against a list of config values given as `keys`

    This checks whether `symbol_or_name` matches any of the given entries, which would typically be something like the `disable`, `ignore`, or `block` config entries.

    Optionally, `scope` provides the name of the scope in which `symbol_or_name` is defined. For derived type members, this takes care of resolving to the type name and matching that. This will also match successfully, if only parent components match, e.g., the scope name or the type name of the symbol. The use of simple patterns is allowed, see `SchedulerConfig.match_item_keys` for more information.

    Parameters:

      - symbol_or_name (`TypedSymbol` or `MetaSymbol` or str) – The symbol or name to match

      - keys (list of str) – The list of candidate names to match against. This can be fully qualified names (e.g., `'my_scope#my_routine'`), plain scope or routine names (e.g., `'my_scope'` or `'my_routine'`), or use simple patterns (e.g., `'my_*'`).

      - scope (str, optional) – The name of the scope, in which `symbol_or_name` is defined, if available. Providing this allows to match a larger range of name combinations

    Returns:

      `True` if matched successfully, otherwise `False`

    Return type:

      bool