Extension types =============== Introduction ------------ |namespec| 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 |namespec|. Therefore, it exists a sort of bijection between infotypes and |namespec| for predefined concepts. For unknown infotypes or infotypes added by users, |namespec| 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 |namespec|. Each wheel can be composed of a known material and a pressure array (pressure / speed), |namespec| 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 |namespec| vocabulary. 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. The meta-data ^^^^^^^^^^^^^ 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 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 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 :: Consequently, a hiereachy data structure that can be mapped in XML can be adapted to the infotype point of view. The serialization ----------------- Users infotypes are serialized in the |namespec| ``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 |namespec| 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``. 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). 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. 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 |namespec| 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 |namespec| 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 ==================================== ====================== Predefined extension types -------------------------- 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] unstructuredEdge ^^^^^^^^^^^^^^^^ Introduction ############ |namespec| 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. The ``unstructredEdge/$unstructuredEdge/meshLink`` ################################################## As for the ``/mesh``, equalities between couples of entities of different meshes have to be defined, that 's why ``/extensionType/unstructured/meshLink``. This sub-category work as ``/mesh/$gmesh/meshLink``. Example of ``/extensionType/unstructured/meshLink`` : :: data.h5 |-- mesh | `-- $gmesh1 | |-- $mesh1 | | |-- nodes | | |-- elementTypes | | `-- elementNodes | |-- $mesh2 | | |-- nodes | | |-- elementTypes | | `-- elementNodes | `--meshLink `-- extensionType/ `-- unstructuredEdge/ |-- $edge-mesh1[@mesh=/mesh/$gmesh1/$mesh1] | |-- edges | `-- elementEdges |-- $edge-mesh2[@mesh=/mesh/$gmesh1/$mesh2] | |-- edges | `-- elementEdges `-- meshLink `-- $ml1[@type=edge @mesh1=/extensionType/unstructuredEdge/$edge-mesh1 @mesh2=/extensionType/unstructuredEdge/$edge-mesh2]