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[@xo=0.0
                |            @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.*


The ``floatingRef`` floatingType 
--------------------------------

To go to one step further, the ``_param`` group introduces a last floating type
which can found out only within a ``_param`` group : the ``floatingRef``
floatingType.

When a floating type is a ``floatingRef``, it is followed by a ``value``
attribute which gives the name of a floating type. This floating type is used
as if it was defined inplace in the ``_param`` group::


    data.h5
    |-- floatingType/
    |   `-- x[@floatingType=arraySet]
    |       |-- data[@physicalNature=length
    |       |        @unit=meter]
    |       `-- ds
    |           `-- dim1[@physicalNature=time
    |                    @unit=second]
    `-- 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]
                `-- _param/
                   `-- xo[@floatingType=floatingRef
                          @value=/floatingType/x]


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