Parameterized attributes
========================

Introduction
------------

To get the point of parameterized attributes begin with an example :
the ``/electromagneticSource/planeWave`` definition.

We have seen that a plane wave is defined by some attributes and a
``magnitude`` arraySet :

::

    data.h5
    `-- electromagneticSource
        `-- planeWave
            `-- $a-plane-wave[@xo=0.0
                |             @yo=0.0
                |             @zo=0.0
                |             @theta=0.0
                |             @phi=0.0
                |             @linearPolarization=0.0]
                `-- magnitude[@floatingType=arraySet]

All attributes are simple :

* the physical nature is given by |namespec|
* the unit is fixed
* the value is a scalar 

However, it could happen someone would like to define a plane wave with
varying parameters :

* ``theta`` and/or ``phi`` could take their values in an interval [0, PI]
  because a module can take into account several directions of
  propagation in a single simulation
* Make the origin point move during a simulation

For these reasons, |namespec| offers a flexible way to override attributes
definition without blurring the simplicity of the format.

The _param group
----------------

Given a simple attribute of the above example, ``@xo`` for example,
we want it to take many values.
The solution is to create a ``_param`` group in
``electromagneticSource/planeWave/a-plane-wave`` element and
add an ``xo`` floating type arrayset to ``_param`` ::

    data.h5
    `-- electromagneticSource
        `-- planeWave
            `-- a-plane-wave[@yo=0.0
                |            @zo=0.0
                |            @theta=0.0
                |            @phi=0.0
                |            @linearPolarization=0.0]
                |-- magnitude[@floatingType=arraySet]
                `-- _param
                    `-- xo[@floatingType=arraySet]
                        |-- data[@physicalNature=length
                        |        @unit=meter]
                        `-- ds
                            `-- dim1[@physicalNature=time
                                     @unit=second]

The element ``a-plane-wave/_param/xo`` simply overrides
the definition ``a-plane-wave/@xo``.

The general rule is that
    *a container's attribute can be overridden by adding an
    element with the same name to the ``_param`` group child
    of the container.*