TransformationBundle

Overview

TransformationBundle is a base class to implement a concept of bundles. Bundle is needed to simplify the following tasks:

  • Construction and configuration a single transformation.

  • Construction, configuration and connection of several transformations. In this sense Bundle is a transformation of a higher level.

  • Based on the given configuration initialize necessary environments and variables, set uncertainties, etc.

Design principle

Bundles define the way configuration files are processed and variables are created, therefore bundles are meant to be persistent during GNA development cycle.

Bundle name usually contains a version mark. It is guaranteed that the bundle with given name and version will not be modified in a way that breaks the backwards compatibility.

If significant modification is required another bundle is created with different version.

Initialization

There are two ways to initialize a bundle:

  1. By using method execute_bundle (preferred). One can find example of creating bundle instance of detector_iav_db_root_v01:

    from gna.bundle import execute_bundle
bundle = execute_bundle( name='detector_iav_db_root_v01', cfg=cfg, namespaces=namespaces, common_namespace=common_namespace )
bundle = execute_bundle( cfg=cfg, namespaces=namespaces, common_namespace=common_namespace )

    if name is not passed, it’s read from cfg.bundle. The specified class <name> is searched in the module gna.bundles.<name>.

  2. By direct class instantiation:

    from gna.bundles.detector_iav_db_root_v01 import detector_iav_db_root_v01
bundle = detector_iav_db_root_v01( cfg=cfg, namespaces=namespaces, common_namespace=common_namespace )

If a bundle name contains ‘:’ like 'bundlename:arg1' or 'bundlename:arg1:arg2' all the strings split by ‘:’ will be treated as string arguments and passed to the bundle constructor. See bundlesum_v01 or bundlechain_v01 bundles for the example.

Arguments

The arguments to the bundle initialization are the following:

  1. cfg — the configuration of type NestedDict. The configuration items may be found in the documentation of specific bundle.

  2. common_namespace — namespace, where the common variables will be initialized. By default is set to env.globalns.

  3. namespaces — a list of namespaces or namespace names (from common_namespace), where uncorrelated variables will be stored. The bundle is expected to create an output transformation for each namespace. By default set to [common_namespace]. In principle, the bundle may decide to create namespaces on it’s own.

Execution and output

The transformation is defined by two methods define_variables and build, defined in individual bundles. First method reads the configuration and uncertain parameters within common_namespace and namespaces. Second method creates a single transformation or a graph of the transformations. The graph has an output transformation for each namespace in namespaces. After the execution the following tuples are populated:

  1. self.objects - NestedDict with all the GNAObjects created within bundle.

  2. self.transformations_in - NestedDict with individual transformations, that require inputs to be connected.

  3. self.transformations_out - NestedDict with individual transformations, with open outputs to passed further.

  4. self.outputs - NestedDict with inputs to be connected (should be consistent with transformations_out).

  5. self.inputs - NestedDict with open outputs (should be consistent with transformations_in).