11. 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, Amelet HDF introduces the Link concept. In a few words, a Link couples two objects and gives the relation a sense.

11.1. Link category

The /link category contains all associations between elements of an Amelet HDF 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.

11.2. 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 Amelet HDF file

• object. object is an HDF5 string attribute representing the name of an element in the Amelet HDF 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.

11.2.1. 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.

11.2.2. 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, Amelet HDF introduces the /label category which aims at converting a string label into an Amelet HDF 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 contains 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.

11.2.3. 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.

11.3. 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).