16. Extension types

16.1. Introduction

Amelet HDF is closely related the Quercy, it is a software platform aiming at :

  • Integrating scientific softwares;
  • Providing knowledge management capabilities;
  • Managing computation execution;
  • Providing pre and post processing tools;
  • and lot of other cool stuff

Quercy expresses data in the form of objects called “infotype” (defined by meta-data). Infotypes are classes, informations are infotype instances. Informations are stored in a relational database.

Infotypes instances can be involved in the simulation process, as input and output, so each infotype have to be converted into equivalent concepts into Amelet HDF. Therefore, it exists a sort of bijection between infotypes and Amelet HDF for predefined concepts.

For unknown infotypes or infotypes added by users, Amelet HDF must be sufficiently flexible to express unknown data coming from this new infotypes.

For example, imagine a module taken a car instance made of four wheel instances. The infotypes “car” and “wheel” are user infotypes so there is no equivalent concept in Amelet HDF. Each wheel can be composed of a known material and a pressure array (pressure / speed), Amelet HDF must expose this structure of a kind in a consistent manner.

The next sections show the definition of Quercy infotypes and the machinery to serialize them into Amelet HDF vocabulary.

16.2. Infotype’s definition

An infotype is like a class in object oriented programming, it is defined by a name and some properties. Properties are called meta-data.

16.2.1. The meta-data

16.2.1.1. Simple types

A meta-data is named attribute with some other characteristics.

  • Type : boolean, integer, real, string
  • Physical nature : for instance resistance, length
  • Unit : ohm, meter
  • Possible values : if the meta-data is a string, the possible values can be a list of words, if the meta-data is an integer, the possible values can be an interval...
  • Default value : the value taken by the meta-data at the creation.

Example, below is the definition of a 3d cartesian grid :

  • nx is the number of cells along the x axis
  • ny is the number of cells along the y axis
  • nz is the number of cells along the z axis
  • dx is the step cell along the x axis
  • dy is the step cell along the y axis
  • dz is the step cell along the z axis

Infotype characteristics :

Specification name User interface name Aggregate
CartesianGrid Cartesian grid False

Meta-data characteristics :

Name Type Physical Nature Unit Possible Values Default Value
nx integer Null Null N 1
ny integer Null Null N 1
nz integer Null Null N 1
dx real length meter R+ 1
dy real length meter R+ 1
dz real length meter R+ 1

Note

  • N represents all Integers
  • R represents all Reals
  • R+ represents all positive Reals

16.2.1.2. Nested Lists

Sometimes, the meta-data is a named list. A list can be compared to an HDF5 table. A list is defined by columns of the same nature than simple types meta-data.

For instance, the children of a family can be a list of (string, integer) couple for (name, age), each child is defined in a row :

Infotype characteristics :

Specification name User interface name Aggregate
Familly Familly False

The word “Aggregate” will be explained in the next section.

Meta-data characteristics :

Name Type Physical Nature Unit Possible Values Default Value
father string Null Null S dad
mother string Null Null S mum
children listOfChildren Null Null N 1

Note

S represents all Strings

listOfChildren characteristics :

Name Type Physical Nature Unit Possible Values Default Value
name string Null Null S son
age integer time year N 10

And finally, a family instance “Simpsons” could be defined by

  • the meta-data are :
meta-data value
father Brian
mother Julia
  • and the children are :
name age
john 10
charly 13

The “Simpsons” family is composed of Brian, Julia and two children :

  • john, 10 years old
  • charly, 13 years old

16.2.2. Quantum and aggregate

The simplest form of infotype is the quantum. A quantum is composed of simple meta-data.

However, a meta-data can be an infotype instance. An infotype that contains infotypes is an aggregate.

In Quercy, the structure of an aggregate can be visualized by a tree view, think of a car and its four wheels

$my-car[@infotype=car]
|-- $my-wheel1[@infotype=wheel,
|   |          @radius=12]
|   |-- $pressure[@infotype=arraySet]
|   `-- $material[@infotype=classicalMaterial]
|-- $my-wheel2[@infotype=wheel,
|   |          @radius=12]
|   |-- $pressure[@infotype=arraySet]
|   `-- $material[@infotype=classicalMaterial]
|-- $my-wheel3[@infotype=wheel,
|   |          @radius=12]
|   |-- $pressure[@infotype=arraySet]
|   `-- $material[@infotype=classicalMaterial]
`-- $my-wheel4[@infotype=wheel,
    |          @radius=12]
    |-- $pressure[@infotype=arraySet]
    `-- $material[@infotype=classicalMaterial]

$my-car is an instance of car and have four aggregated informations instances of wheel. Each wheel have two aggregated informations and one simple real meta-data :

  • pressure, it is an instance of arraySet
  • material, it is an instance of classicalMaterial.
  • radius is a meta-data for the wheel infotype, it is a real and its value is 12.

This hierarchy of object can be rewritten with an XML syntax

<car name="$my-car">
    <wheel
        name="$my-wheel1"
        radius="12">
        <arraySet name="pressure"/>
        <classicalMaterial name="material">
    </wheel>
    <wheel
        name="$my-wheel2"
        radius="12">
        <arraySet name="pressure"/>
        <classicalMaterial name="material"
    </wheel>
    <wheel
        name="$my-wheel3"
        radius="12">
        <arraySet name="pressure"/>
        <classicalMaterial name="material">
    </wheel>
    <wheel
        name="$my-wheel4"
        radius="12">
        <arraySet name="pressure"/>
        <classicalMaterial name="material">
    </wheel>
</car>

Consequently, a hiereachy data structure that can be mapped in XML can be adapted to the infotype point of view.

16.3. The serialization

Users infotypes are serialized in the Amelet HDF extensionTypes category.

The hierarchy level of an infotype’s definition can be highly deep (an aggregate can contain aggregates that can contain aggregates ...). This hierarchy level can not be reproduced in Amelet HDF without danger : absolute name can become very long. In addition, the “category” formalism can not be respected.

The manner users infotypes are serialized is described now. Each Quercy infotype (and not information) (for example car and wheel) are stored in extensionTypes/car and extensionTypes/wheel categories.

Each infotype instance become an HDF5 group children of their infotype category. For example, all informations “car” are stored in /extensionTypes/car and all informations “wheel” are stored in /extensionTypes/wheel.

16.3.1. Simple type meta-data

The simple types Quercy meta-data becomes HDF5 attributes :

  • Boolean meta-data : the boolean meta-data are converted into HDF5 integer attributes. The name of the attribute is the specification name name of the meta-data (ASCII name).
    • False becomes 0
    • True becomes 1
  • Integer meta-data : the integer meta-data are converted into HDF5 integer attributes. The name of the attribute is the specification name of the meta-data (ASCII name).
  • Real meta-data : the real meta-data are converted into HDF5 float attributes. The name of the attribute is the specification name of the meta-data (ASCII name).
  • String meta-data : the string meta-data are converted into HDF5 string attributes. The name of the attribute is the specification name of the meta-data (ASCII name).

16.3.2. Nested lists

The nested lists definition is very closed to HDF5 tables, the conversion is straightforward.

a nested list becomes an HDF5 table. The name of the table is the specification name of the list (ASCII name). Each list’s field become a columns in the table and the type of the column follow the rules of simple type meta-data.

For example, a nested list children defined by :

name age
john 10
charly 13

is converted into a table, child of /extensionType/family, named children of two columns

/extensionType/
`-- family/
    `-- $Simpsons[@father=Brian,
        |         @mother=Julia]/
        `-- children

The first column is called name and contains strings, the second columns is called age and contains integer.

16.3.2.1. Aggregation

For aggregate instances, a linksDefinition dataset reproduces the hierarchy schema. The linksDefinition dataset is a (n x 2) HDF5 string dataset :

  • the first column contains name of the element in the Amelet HDF instance.
  • the second column contains the optional name/role of the element in the parent.
data.h5
`-- extensionType/
    |-- car/
    |   `-- $my-car/
    |       `-- linksDefinitions
    `-- wheel/
        |-- $my-wheel1[@radius=12]
        |   `-- linksDefinition
        |-- $my-wheel2[@radius=12]
        |   `-- linksDefinition
        |-- $my-wheel3[@radius=12]
        |   `-- linksDefinition
        `-- $my-wheel4[@radius=12]
            `-- linksDefinition

with /extensionTypes/car/$my-car/linksDefinition :

/extensionType/wheel/$my-wheel1 ” “
/extensionType/wheel/$my-wheel2 ” “
/extensionType/wheel/$my-wheel3 ” “
/extensionType/wheel/$my-wheel4 ” “

Sometimes, aggregated informations are named. For instance, the car’s wheels must be identified separately and can be picked by their name :

  • nose_right_wheel
  • nose_left_wheel
  • rear_right_wheel
  • rear_left_wheel

The Amelet HDF conversion gives in this case a new linksDefinition /extensionTypes/car/$my-car/linksDefinition:

/extensionType/wheel/$my-wheel1 nose_right_wheel
/extensionType/wheel/$my-wheel2 nose_left_wheel
/extensionType/wheel/$my-wheel3 rear_right_wheel
/extensionType/wheel/$my-wheel4 rear_left_wheel

Finally, /extensionTypes/wheel/my-wheel1/linksDefinition looks like :

/physicalModel/volume/$wood material
/floatingType/$pressure pressure

16.4. Predefined extension types

16.4.1. floatingType

Scalar real or complex numbers can be produced by computations. Amelet-HDF proposes the floatingType category to store genuine floating floatingType.

Example :

data.h5
`-- extensionType/
    `-- floatingType/
        |-- $time[@floatingType=singleReal
        |         @physicalNature=time
        |         @unit=second
        |         @value=10]
        `-- $probability[@floatingType=singleReal
                         @value=0.05]

16.4.2. unstructuredEdge

16.4.2.1. Introduction

Amelet HDF describe unstructured meshes with the nodes approach. A convention could provide a way to edges of a mesh, but all edges consumer should implements the algorithm. An another means is to store the edges.

Once the edges are computed, the element definition by edge is also interesting for some kind of softwares and stored in elementEdges.

The referenced mesh is given by the attribute mesh.

An edge is defined by two nodes (node 1, node 2), so edges is an integer dateset of number_of_edges X 2 elements. The referenced mesh elementTypes dataset gives the number of edges for each element. So for an element in elementTypes, there are n rows in elementEdges for its description by edges.

elementEdges is an HDF5 integer dataset of one column, each row is the number of an edge.

data.h5
|-- mesh
|   `-- $gmesh1
|       `-- $mesh1
|           |-- nodes
|           |-- elementTypes
|           `-- elementNodes
`-- extensionType/
    `-- unstructuredEdge/
        `-- $edge-mesh1[@mesh=/mesh/$gmesh1/$mesh1]
            |-- edges
            `-- elementEdges

with data.h5:/extensionType/unstructuredEdge/$edge-mesh1/edges :

implicit index node1 node2
0 0 1
1 1 2
2 3 4

and with data.h5:/extensionType/unstructuredEdge/$edge-mesh1/elementEdges :

implicit index edge
0 0
1 1
2 2

Headers are implicit in this case.