9.3.2. Making parameters via bundles

Let us start from a bundle that simply initializes some parameters from the list. It is fairly simple:

parameters_ex01.py

from gna.bundle.bundle import TransformationBundle

class parameters_ex01(TransformationBundle):
    def __init__(self, *args, **kwargs):
        TransformationBundle.__init__(self, *args, **kwargs)
        self.check_nidx_dim(0,0)

    def define_variables(self):
        for parname, parcfg in self.cfg.pars.items(nested=True):
            self.reqparameter(parname, None, cfg=parcfg)

The parameters_ex01 bundle class contains two methods __init__() and define_variables(). The constructor

    def __init__(self, *args, **kwargs):
        TransformationBundle.__init__(self, *args, **kwargs)
        self.check_nidx_dim(0,0)

passes all the arguments to the common bundle costructor, which initializes configuration, multidimensional index, etc. As this particular bundle can not handle indexing, it checks that the number of dimensions is within limits \([0,0]\).

The second method is called to initialize parameters. For each name, par pair from the configuration it initializes a parameter.

    def define_variables(self):
        for parname, parcfg in self.cfg.pars.items(nested=True):
            self.reqparameter(parname, None, cfg=parcfg)

Again parameters_ex01 in a sense a function, which reads its argument from configuration dictionary.

In order to use the bundle one needs to execute its configuration. See the following example:

03_bundle_parameters.py

from gna.bundle import execute_bundle
from gna.configurator import NestedDict, uncertaindict, uncertain
from gna.env import env

#
# Bundle configuration
#
cfg = NestedDict(
    bundle = dict(
        name='parameters',
        version='ex01',
        ),
    pars = uncertaindict(
        [
            ( 'par_a',   (1.0, 1.0,  'percent') ),
            ( 'par_b',   (2.0, 0.01, 'relative') ),
            ( 'par_c',   (3.0, 0.5,  'absolute') ),
            ( 'group.a', (1.0, 'free' ) ),
            ( 'group.b', (1.0, 'fixed', 'Labeled fixed parameter' ) )
            ],
        ),
)

#
# Execute bundle configuration
#
b1 = execute_bundle(cfg)

#
# Print the parameters
#
env.globalns.printparameters(labels=True)

We start from making a dictionary with configuration:

cfg = NestedDict(
    bundle = dict(
        name='parameters',
        version='ex01',
        ),
    pars = uncertaindict(
        [
            ( 'par_a',   (1.0, 1.0,  'percent') ),
            ( 'par_b',   (2.0, 0.01, 'relative') ),
            ( 'par_c',   (3.0, 0.5,  'absolute') ),
            ( 'group.a', (1.0, 'free' ) ),
            ( 'group.b', (1.0, 'fixed', 'Labeled fixed parameter' ) )
            ],
        ),
)

The bundle specifies the bundle that should read the configuration and make parameters. The only other field is a dictionary with parameter specifications. We use uncertaindict() for this. Its signature is similar to the python dict() signature: first argument is a list with (key, value) pairs, other arguments are named and represent key=value pairs as well.

The possible variants of parameter definitions should be readable. First line

            ( 'par_a',   (1.0, 1.0,  'percent') ),

defines parameter par_a with central value of 1 and relative uncertainty of 1%, expressed in percents.

            ( 'par_b',   (2.0, 0.01, 'relative') ),

defines parameter par_b with central value of 2 and relative uncertainty of 1%, expressed in relative units.

            ( 'par_c',   (3.0, 0.5,  'absolute') ),

defines parameter par_c with central value of 3 and absolute uncertainty of 0.5.

            ( 'group.a', (1.0, 'free' ) ),

defines parameter a in a nested namespace group with default value of 1. The parameter is free.

            ( 'group.b', (1.0, 'fixed', 'Labeled fixed parameter' ) )

defines parameter b in a nested namespace group with value of 1. The parameter is fixed.

Extra argument may be added to each line defining the parameters label as it is done in the last example.

Finally we execute the bundle configuration as follows:

b1 = execute_bundle(cfg)

The function returns parameters_ex01 class instance. After execution the global namespace contains all the parameters defined:

env.globalns.printparameters(labels=True)

Variables in namespace '':
  par_a                =          1 │           1±        0.01 [          1%] │
  par_b                =          2 │           2±        0.02 [          1%] │
  par_c                =          3 │           3±         0.5 [    16.6667%] │
Variables in namespace 'group':
  a                    =          1 │           1±         inf [free]         │
  b                    =          1 │                 [fixed]                 │ Labeled fixed parameter

Such an approach enables the user to detach the configuration from the actual code. In the same time the piece of configuration indicates which code should handle it. The code of the parameters_ex01 is meant to be immutable for backwards compatibility. Alternative behaviour should be achieved by introducing other versions of the bundle or other bundles.