The |namespec| file =================== Before anything else, an |namespec| file is an HDF5 file. To know the file is precisely an |namespec| instance, the file object has two attributes : * ``FORMAT`` is an HDF5 string attribute, its value is ``AMELETHDF``. * ``AMELETHDF_FORMAT_VERSION`` is an HDF5 string attribute defining the version number of the |namespec| specification. ``AMELETHDF_FORMAT_VERSION`` attribute is composed of three integers separated by colons. The first integer is the major version, the second integer is the minor version and the third integer is a release number. The release number is rarely used. Example : :: data.h5[@FORMAT=AMELETHDF | @AMELETHDF_FORMAT_VERSION=1.0.0]/ `-- physicalModel `-- volume |--$water `--$soltWater Predefined categories ===================== |namespec| is a specialization of the HDF5 format, it can then be represented by a tree, for which all groups (branches) can contain groups or leaves (datasets, tables). Branches and leaves can have attributes to precise specific values. These groups, datasets and tables compose a hierarchical dictionary of electromagnetic data definitions like dielectric materials, impedance, mesh object or numerical data, electromagnetic sources (antenna) and so on. The first rule -------------- |namespec| relies on a first rule, each definition is contained in a predefined category (a category is an HDF5 group). For instance, three homogeneous material models will be defined in ``/physicalModel/volume`` : :: data.h5/ `-- physicalModel `-- volume |--$water `--$soltWater .. note:: In this document, where there are prefixed HDF5 names with "$", (``$water``, ``$soltWater``) the names are example names the user can modify. Categories ---------- |namespec| information hierarchies can be represented by a tree a human being can easily read :: data.h5/ |-- label |-- group |-- externalElement |-- globalEnvironment |-- electromagneticSource | |-- planeWave | |-- sphericalWave | |-- generator | |-- dipole | |-- sourceOnMesh | `-- antenna |-- physicalModel | |-- multiport | |-- multilayer | |-- slotProperties | |-- anisotropic | |-- volume | |-- aperture | |-- shield | `-- grid |-- mesh |-- floatingType |-- exchangeSurface |-- transmissionLine | `--transmissionLineElement |-- network | `-- $net1 | |-- topology | |-- tubes | |-- junctions | `-- connections |-- link |-- outputRequest |-- localizationSystem |-- extensionTypes | `-- $car `-- simulation `-- $sim1 |-- input `-- output The predefined categories are presented underneath and each one represents a concept of the electromagnetic simulation domain : * label The category contains all labels used in the |namespec| instance. * group This category contains ``group`` objects. A group contains only element names which have something in common * externalElement The category contains all elements used in the |namespec| instance but defined in another instance. * globalEnvironment Global data about simulations. If the simulation is in the time domain, "time" defines the computation duration, if the simulation is in the frequency domain, "frequency" defines the input simulation spectrum. * electromagneticSource This category contains all electromagnetic sources definition : * planeWave A plane wave is defined by a direction of propagation, a linear polarisation angle, an elliptic polarisation angle, a magnitude and a nul phase point * generator A generator is defined by a magnitude and a linear circuit element * dipole A dipole is defined by a rotation, a localization, a magnitude, a linear circuit element, a length and a radius. * sourceOnMesh A source on mesh is defined by an array of values and an exchange Surface * antenna An antenna is defined by an efficiency, a magnitude, an input impedance, a feeder impedance and a load impedance. * physicalModel In physicalModel are gathered all physical models. * volume This groups defines homogeneous volume material. A volume material is composed of a relative permittivity, an electric conductivity, a relative permeability and a magnetic conductivity Predefined volume : ``vacuum`` * multiport This category contains material models based upon linear circuit elements. All classical element can be used : impedance, admittance, resistance, inductance, capacitance, conductance, s parameters, **multiport circuit** ? Predefined multiports : ``short circuit``, ``open circuit``, ``matched multiport`` * anisotropic An anisotropic material is defined by volumes or linear multiport. One material model per matrices element * multilayer A multilayer material is a group of layers, a layer is the association of a physicalModel/material and a thickness * interface A interface defines the connection between two media * slotProperties A slot properties defined a slot with a width, a thickness and a material * mesh Electromagnetic simulation methods often consume a discretized space. The space can be discretized with unstructured elements or structured elements. In this category all meshes are gathered. * selectorOnMesh Mesh entity are not named in the mesh category (or mesh group), the three tables in this category allow to give a name to mesh entities. * link Once material models and meshes are defined, boundary conditions may have to be set. Links associate material models to mesh entities. * floatingType This category contains floatingType elements which are meaningless in the context of |namespec| neither a predefined location. ``FloatingType`` computation results are stored in this category : electric field, magnetic field, current... * exchangeSurface exchangeSurface modelize the data and the mesh to share data between electromagnetic simulations * transmissionLine This category defines a transmission line section * network This category describes all networks in the simulation * localizationSystem Coordinate system definition * simulation Definition of the simulations with input data and output data * extensionType Definition of extensions * OutputRequest The entry point --------------- The general shape of a |namespec| instance is an HDF5 file with a lot of not empty categories. The question is the following : what is the first element to be read ? The file attribute ``@entryPoint`` is the answer, ``@entryPoint`` is an HDF5 string attribute that spots the major element of the file. ``@entryPoint`` is optional. :: data.h5[@entryPoint=/simulation/$sim1] `-- simulation/ `-- $sim1[@module=my-module | @version=1.2] |-- parameter |-- inputs `-- outputs In this example, the first element the reader must open is ``data.h5:/simulation/$sim1``. In addition ``@entryPoint`` can focus a on group if there is no particular element to read : :: data.h5[@entryPoint=/floatingType] `-- floatingType/ |-- $e_field `-- $h_field Here, the |namespec| instance stores some arraySets, the ``@entryPoint`` gives the *nature* of the file. Physical quantity and unit -------------------------- International System of Units ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The value of a physical quantity Q is expressed as the product of a numerical value {Q} and a physical unit [Q]* (http://en.wikipedia.org/wiki/Physical_quantity) : Q = {Q} x [Q] All [Q] are expressed in the SI units (http://en.wikipedia.org/wiki/SI) **except for angular quantities**. Angular quantities ^^^^^^^^^^^^^^^^^^ Angular quantities are stored in ``degree`` instead of ``radian``, it is the scientists preferred unit. .. warning:: Angular quantities are stored in ``degree``. The simulation object --------------------- The purpose of the |namespec| Specification is to provide a standard for recording and recovering computer data of electromagnetic simulations, but what about the simulation itself ? |namespec| makes an attempt to describe the simulation with its inputs and outputs. A simulation is an HDF5 group and is localized in the ``simulation`` category, see for instance ``$sim1`` simulation below :: data.h5/ `-- simulation `-- $sim1[@module=my-module | @version=1.2] |-- parameter |-- inputs `-- outputs A ``simulation`` child (i.e. a simulation) has two attributes : * the ``module`` attribute : this attribute gives the name of the module or the treatment process that must interpret the file, it is an HDF5 string attribute * the ``version`` attribute : this attribute is the version number of the module, it is an HDF5 string attribute In this preceding example, a "$sim1" simulation is defined, and the module that will be used is "my-module" in version 1.2. The ``simulation`` group has three children : #. ``parameter`` : ``parameter`` contains the module's specific parameters of the simulation like global key words, global options. #. ``inputs`` : ``inputs`` contains all informations used in the simulation, it is an HDF5 string dataset #. ``outputs`` : ``outputs`` contains the informations skeleton of the output created by the simulation, it is an HDF5 string dataset .. warning:: The simulation object is the default entry point of an |namespec| file. The simulation's parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^ The simulation's parameters are module's specific parameters of a simulation like global key words, global options, all information that is not common. The module's specific parameters can not be specified by |namespec| but |namespec| allows the user to describe schema data needed by the module. Simulation parameters are named typed element, the type can be either 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) ``/simulation/$simulation/parameter`` is an HDF5 group and parameters are written as follows : * Simple type parameters 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. Example : Consider the parameters defined by : * Parameter 1 : * name : color * type : string * Parameter 2 : * name : temperature * type : real * Parameter 3 : * name : listOfCommands * type : compound * name : commandName * type : string * name : option1 * type : string * name : option2 * type : string As a consequence, an instance of |namespec| looks like : :: data.h5/ `-- simulation/ `-- $sim1[@module=my-module | @version=1.2] |-- inputs |-- outputs `-- parameter[@color=black | @temperature=300] `-- listOfCommands with the ``data.h5:/simulation/$sim1/parameter/listOfCommands`` table : ============ ============ ============ commandName option1 option2 ============ ============ ============ $command1 $option11 $option12 $command2 $option21 $option22 ============ ============ ============ .. note:: Logically, simulation parameters of a specific module are not specified by |namespec|. One could think it would be necessary to add physical nature of parameters to the |namespec| instance, but the |namespec| instance is aimed to be read by the module adapter, and this component knows the module's interface. Parameters physical nature is not mentioned in a simulation software input file. The simulation's inputs ^^^^^^^^^^^^^^^^^^^^^^^ The simulation's inputs element is a one dimensional HDF5 dataset and contains |elementlen| characters strings. The possible inputs for a module are defined by the module itself, so there is no surprise by discovering the list of inputs. The module can perform some checks. For a 3D electromagnetic module, FDTD method for instance, the first input to be read could be ``/link/$my-data-on-mesh``, this object associates all physical models to the mesh entities. For instance see the following ``inputs`` dataset: +------------------------------------------------+ |``/link/$my-data-on-mesh`` | +------------------------------------------------+ |``/mesh/$gmesh1/$my-car`` | +------------------------------------------------+ |``/physicalModel/volume/$iron`` | +------------------------------------------------+ |``/electromagneticSource/antenna/$my-antenna-1``| +------------------------------------------------+ |``/electromagneticSource/antenna/$my-antenna-2``| +------------------------------------------------+ |``/localizationSystem/$the-loc`` | +------------------------------------------------+ |``/link/$the-data-on-loc`` | +------------------------------------------------+ The simulation takes a mesh ($my-car), a data on mesh ($my-data-on-mesh), a volume material ($iron), two antennas ($my-antenna-1, $my-antenna-2) located with the localization system. The simulation's outputs ^^^^^^^^^^^^^^^^^^^^^^^^ On one hand, simulation's inputs are described in the ``inputs`` group, on the other hand, many objects will be created while the computation runs and have to be well organized in order to be read correctly by the next process. Simulation's output group describes those created objects. The simulation's outputs element is a one dimensional HDF5 dataset and contains |elementlen| characters strings. For instance see the following table : :: data.h5/ |-- extensionType/ | `-- dataSet | `-- $data1 | `-- linksDefinition |-- floatingType/ | |-- $e_field | |-- $h_field | |-- $current | `-- $tension `-- simulation/ `-- $sim1[@module=my-module | @version=1.2] |-- inputs `-- outputs with ``data.h5:/extensionType/dataSet/$data1/linksDefinition`` : ==================================== ================ name specificRole ==================================== ================ ``/floatingType/$e_field`` ``/floatingType/$h_field`` ``/floatingType/$current`` ``/floatingType/$tension`` ==================================== ================ and ``data.h5:/simulation/$sim1/outputs`` : +------------------------------------------------+ | ``/extensionTypes/dataSet/$output_data`` | +------------------------------------------------+ | ``/extensionTypes/dataSet/$output_power`` | +------------------------------------------------+ Simulation's parametric elements ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A parametric simulation is a simulation defined by a set of combinatorial input data. For instance, for a monochromatic solver the computation on a frequency spectrum (i.e. several frequencies) is a parametric simulation. In |namespec|, simulation parametric elements are described in the **optional** ``/simulation/$simulation/parametricElements`` object. ``/simulation/$simulation/parametricElements`` is a two column table : * The first column ``name`` is a string column which contains the name of the parametric element * The second column ``selected`` is an integer column which contains 1 or 0 : * 0 : the process which read the simulation object must skip the parametric element * 1 : the process which read the simulation object must take into account the parametric element and deal with the creation of as much simulations as required. :: data.h5/ |-- extensionType/ | `-- dataSet | `-- $data1 | `-- linksDefinition |-- globalEnvironment/ | `-- $ge | `-- frequency[@floatingType=vector | @physicalNature=frequency | @unit=hertz] |-- floatingType/ | |-- $e_field | |-- $h_field | |-- $current | `-- $tension `-- simulation/ `-- $sim1[@module=my-module | @version=1.2] |-- parametricElements |-- parameter |-- inputs `-- outputs With ``/simulation/$sim1/parametricElements`` : ==================================== ================ name selected ==================================== ================ ``/globalEnvironment/$ge/frequency`` 1 ==================================== ================ In the example, the process will create a number of simulations equals the number of elements of ``/globaleEnvironment/$ge/frequency`` simulations. Batch submission system ^^^^^^^^^^^^^^^^^^^^^^^ The ``group`` category ---------------------- This category contains ``group`` objects. A group contains only element names which have something in common. In the following example, ``data.h5:/group/$em_field_result`` is used to gather ``/floatingType/$e_field`` and ``/floatingType/$h_field`` for an output request for instance (see :ref:`outputRequest` for output request definition) : :: data.h5/ |-- label/ | `-- outputRequests |-- mesh/ | `-- $gmesh1 | `-- $sphere | `-- group | |-- $inside[@type=volume] | `-- $skin[@type=face] |-- group | |-- $em_field_result | `-- $group2 |-- floatingType/ | |-- $e_field | |-- $h_field | |-- $current | `-- $tension |-- simulation/ | `-- $sim1[@module=my-module | | @version=1.2] | |-- inputs | `-- outputs `-- outputRequest/ `-- $outputRequest_group/ `-- $or1[@subject=/label/predefinedOutputRequests @subject_id=0 @object=/mesh/$gmesh1/$sphere/group/$inside @output=/floatingType/$e_field] with ``data.h5:/label/outputRequests`` : +------------------------------+ | ``electromagneticField`` | +------------------------------+ and with ``data.h5:/group/$em_field_result`` : +------------------------------+ | ``/floatingType/$e_field`` | +------------------------------+ | ``/floatingType/$h_field`` | +------------------------------+