.. _link:

Link and Label
==============

In cases of computing methods based on the mesh concept like the
finite differences, finite elements or finite volumes, mesh entities 
have to be associated with physical models like
material models or electromagnetic sources.

Sometimes, an object plays
a specific role in a simulation, for instance an antenna is the transmitter 
and another antenna is the receiver and the module must make a difference 
between the two antennas.

Or else, two objects must be associated, for instance to express a plane
incident wave is propagated toward a network tube.

For all those issues, |namespec| introduces the ``Link`` concept. In a few
words, a ``Link`` couples two objects and gives the relation a sense.


Link category
-------------

The ``/link`` category contains all associations between elements 
of an |namespec| instance :

Examples :

* Links between physical models and meshes
* Links between physical models and networks
* Links between label and object
* Links between model instances...

::

    data.h5
    `-- link/


In the ``link`` category, links are gathered in groups. The number of
groups and the name of groups are not specified.

Link groups are named HDF5 groups.

::

    data.h5
    `-- link/
        |-- $link_group1/
        `-- $link_group2/


Link groups are described further in the text.


.. _linkinstance:

Link
----

Finally, link group children (``data.h5:/link/$link_group/$link_instance``) 
are called link instance.

A link instance is an HDF5 group with two mandatory attributes :

* ``subject``. ``subject`` is an HDF5 string attribute representing the name
  of an element in the |namespec| file
* ``object``. ``object`` is an HDF5 string attribute representing the name
  of an element in the |namespec| file

Example :

::

    data.h5
    |-- mesh/
    |   `-- $gmesh1/
    |       `-- $plane/
    |           `-- group
    |               `-- $wing
    |-- physicalModel/
    |   `-- volume/
    |       `-- $diel1
    `-- link/
        `-- $link_group/
            `-- $link_instance1[@subject=/physicalModel/volume/$diel1
                                @object=/mesh/$gmesh1/$plane/group/$wing]

This example shows a link (``data.h5:/link/$link_group/$link_instance``) 
between a volume material (``$diel1``) and the ``$wing`` mesh group.


Tables and datasets
^^^^^^^^^^^^^^^^^^^

Imagine we want to associate a label to a network's tube. We have to select
a label in a dataset (/label/$some_labels for instance) and to select
a row in a table (/network/$a_network/tubes for instance)

In the case of a table, an attribute is added : the name of this attribute
is built with a prefix (``subject_`` or ``object_``) concatenated with the name
of the column. The value of the attribute is the value of the cell.

In the case of a dataset, an attribute is added : the name of this attribute
is built with a prefix (``subject_`` or ``object_``) concatenated with "id".
The value of the attribute is the coordinates the cell :

::

    data.h5
    |-- label/
    |   `-- $some_labels
    |-- transmissionLine/
    |-- network/
    |   `-- $a_network/
    |       |-- junctions
    |       |-- tubes
    |       `-- connections
    `-- link/
        `-- $link_group/
            `-- $link_instance1[@subject=/label/$some_labels
                                @subject_id=2
                                @object=/network/$a_network/tubes
                                @object_id=$tub_1]

with the ``data.h5:/label/$some_labels`` dataset :

+---------------+
| first         |
+---------------+
| last          |
+---------------+
| ground_height |
+---------------+

with the ``data.h5:/network/$a_network`` table :

========= ========== ========== ======================
  id      extremity1 extremity2  transmissionLine      
========= ========== ========== ======================
  ...
  $tub_1     $j1        $j2     /transmissionLine/$tl1
  $tub2      $j2        $j3     /transmissionLine/$tl2
  $tub#3     $j1        $j3     /transmissionLine/$tl3
  ...
========= ========== ========== ======================

Here, the link associates the ``ground_height`` to the tube ``$tube_1``

.. warning::
    
    In @subject_id=2, _id is the cell's index and
    in @object_id=$tub_1, id is the column's name


.. note::

    If the element to be picked is in a dataset, 
    the ``object_id`` (or ``subject_id``)  attribute is used. 
    This attribute contains the coordinates of the element inside the dataset.

    For instance, if the dataset is a two dimensional dataset (N x M), 
    ``object_id`` equals ``(n, m)``. ``object_id`` is a multi value
    HDF5 integer attribute. 


Label link
^^^^^^^^^^

Links, where the subject is a label, are usually used to set 
the role of an element in the context of a simulation. For instance, a module
would need to know whether an antenna is the transmitter 
or the receptor.

For this use case, |namespec| introduces the ``/label`` category 
which aims at converting a string label into an |namespec| element.

The ``label`` category is an HDF5 group containing only HDF5 dataset :

* The name of the datasets is not specified
* The datasets have only one column.
* The dataset contain |filelen| character HDF5 strings.

Example of a label table :

::

    data.h5
    `-- label/
        `-- $label_dataset1
        
with ``data.h5:/label/$label_dataset1`` :

+---------------------+
| transmitter         |
+---------------------+
| receptor            |
+---------------------+
| useSecondOrder      |
+---------------------+

Example of a link using a label :

::

    data.h5
    |-- label/
    |  `-- $label_dataset1
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $plane
    |           `-- group
    |               `-- $wing
    |-- electromagneticSource/
    |   |-- antenna
    |   |   `-- $antenna1
    `-- link/
        `-- $link_group
            |-- $link_instance1[@subject=/label/$label_dataset1
            |                   @subject_id=0
            |                   @object=/electromagneticSource/antenna/$antenna1]
            `-- $link_instance2[@subject=/label/$label_dataset1
                                @subject_id=2
                                @object=/mesh/$gmesh1/$plane/group/$wing]

In this example, the label "transmitter" is linked to the 
``/electromagneticSource/antenna/$antenna1`` antenna thanks to the
``data.h5:/link/$link_group/$link_instance1`` link and
the label "useSecondOrder" is linked to /mesh/$gmesh1/$plane/group/$wing.

.. note::

  Labels are relative to a module and can be defined by the module's developer.


Link options
^^^^^^^^^^^^

A link instance can have many options (defined as simulation's parameters),
they can  simple (i.e. a native type) or compound (i.e. a structure) :

* The simple types are :

  * integer
  * real
  * string
  * boolean

* A compound type is a type made of a list of named simple types, example :
  (param1: integer, param2: real, param3: string)

A link is an HDF5 group, link's options are written as follows in a link :

* Simple type options become simple HDF5 named attributes 
* Compound parameters are stocked in named HDF5 tables where columns are the
  structure's fields and the table's name is the parameter's name.


For instance, to place a generator on a tube's wire of a network, an integer 
``idWire`` attribute is mandatory to select the wire :

::

    data.h5
    |-- electromagneticSource/
    |   `-- generator
    |       `-- $v1
    |-- mesh/
    |   `-- $gmesh/
    |       `-- $umesh
    |           `-- group
    |               `-- $tube1[@type=element
    |                          @entityType=edge]
    |-- physicalModel/
    |-- transmissionLine/
    |-- network/
    |   `-- $network1
    |       |-- tubes
    |       |-- junctions
    |       `-- connections
    `-- link/
        `-- $link_group
            `-- $link_instance[@subject=/electromagneticSource/generator/$v1
                               @object=/mesh/$gmesh/$umesh/group/$tube1
                               @idWire=1]

.. note::

  Options are relative to a module and can be defined by the module's developer.





Link group
----------

As seen above, in the ``link`` category links are gathered in groups. 
The number of groups and the name of groups are not specified.

Link group children are named HDF5 groups which gather genuine link instances.

Each link group has several optional attribute :

* ``rootSubject``. In a link group all link subjects can have a common root
  in their name. ``rootSubject`` is an HDF5 string attribute representing
  this common root part.
* ``rootObject``. In a link group all link objects can have a common root
  in their name. ``rootObject`` is an HDF5 string attribute representing
  this common root part.
* ``type``. ``type`` is an HDF5 string attribute. This attribute
  sets the type of all its children.


Example of ``rootObject`` usage :

::

    data.h5
    |-- mesh/
    |   `-- $gmesh1/
    |       `-- $plane/
    |           |-- nodes
    |           |-- elementTypes
    |           |-- elementNodes
    |           |-- group
    |           |   |-- $phase_origine[@type=node]
    |           |   `-- $wing[@type=element]
    |           `-- selectorOnMesh
    |               |-- $generator_v1[@type=pointInElement]
    |               `-- $generator_i1[@type=pointInElement]
    |-- electromagneticSource/
    |   |-- planeWave
    |   |   `-- $pw1
    |   `-- generator/
    |       |-- $v1
    |       `-- $i1
    `-- link/
        `-- $link_group[@rootObject=/mesh/$gmesh1/$plane/selectorOnMesh]
            |-- $link_instance1[@subject=/electromagneticSource/generator/$v1
            |                   @object=$generator_v1]
            `-- $link_instance2[@subject=/electromagneticSource/generator/$i1
                                @object=$generator_i1]


with ``data.h5:/mesh/$gmesh1/$plane/selectorOnMesh/$generator_v1`` :

======= ==== ==== ====
 index   v1   v2   v3
======= ==== ==== ====
  23     0.5  -1   -1
======= ==== ==== ====

with ``data.h5:/mesh/$gmesh1/$plane/selectorOnMesh/$generator_i1`` :

======= ==== ==== ====
 index   v1   v2   v3
======= ==== ==== ====
  26     0.5  -1   -1
======= ==== ==== ====

and with ``data.h5:/mesh/$gmesh1/$plane/group/$phase_origin`` :

+---------+
|  124    |
+---------+


.. note::
    The ``data.h5:/link/$link_group/$link instance`` shows that 
    link instance ``object`` (or ``subject``) attribute
    can still be used, in this case it 
    represents a name part to be added to ``rootObject`` (or ``rootSubject``).