3. The Amelet HDF file

Before anything else, an Amelet HDF file is an HDF5 file. To know the file is precisely an Amelet HDF 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 Amelet HDF 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

4. Predefined categories

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

4.1. The first rule

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

4.2. Categories

Amelet HDF 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 Amelet HDF 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 Amelet HDF 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 Amelet HDF 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

4.3. The entry point

The general shape of a Amelet HDF 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 Amelet HDF instance stores some arraySets, the @entryPoint gives the nature of the file.

4.4. Physical quantity and unit

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

4.4.2. Angular quantities

Angular quantities are stored in degree instead of radian, it is the scientists preferred unit.

Warning

Angular quantities are stored in degree.

4.5. The simulation object

The purpose of the Amelet HDF Specification is to provide a standard for recording and recovering computer data of electromagnetic simulations, but what about the simulation itself ? Amelet HDF 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 :

1. parameter : parameter contains the module’s specific parameters of the simulation like global key words, global options.

2. inputs : inputs contains all informations used in the simulation, it is an HDF5 string dataset

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

4.5.1. 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 Amelet HDF but Amelet HDF 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 Amelet HDF 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 Amelet HDF. One could think it would be necessary to add physical nature of parameters to the Amelet HDF instance, but the Amelet HDF 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.

4.5.2. The simulation’s inputs

The simulation’s inputs element is a one dimensional HDF5 string dataset.

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.

4.5.3. 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 string dataset.

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

4.5.4. 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 Amelet HDF, simulation parametric elements are described in the optional /simulation/$simulation/parametricElements object. /simulation/$simulation/parametricElements is a three column array :

• The first column is a string column which contains the name of the element that takes multiple values

• The second column is a string column which contains the name of an Amelet-HDF group. The group gives the possible values for the preceding element

• The third column is a string column which contains the name of a floatingType. This floatingType gives a reprensentation of the possible values which could become absissa labels in a plot.

data.h5/
|-- extensionType/
|   `-- dataSet
|       `-- $data1
|           `-- linksDefinition
|-- globalEnvironment/
|   `-- $ge
|       `-- frequency[@floatingType=singleReal
|                     @value=1e3
|                     @physicalNature=frequency
|                     @unit=hertz]
|-- floatingType/
|   |-- $frequency1e3[@floatingType=singleReal
|   |                 @value=1e3
|   |                 @physicalNature=frequency
|   |                 @unit=hertz]
|   |-- $frequency1e4[@floatingType=singleReal
|   |                 @value=1e3
|   |                 @physicalNature=frequency
|   |                 @unit=hertz]
|   |-- $frequency1e5[@floatingType=singleReal
|   |                 @value=1e3
|   |                 @physicalNature=frequency
|   |                 @unit=hertz]
|   |-- $frequency1e6[@floatingType=singleReal
|   |                 @value=1e3
|   |                 @physicalNature=frequency
|   |                 @unit=hertz]
|   |-- $axis_values[@floatingType=vector
|   |                @physicalNature=frequency
|   |                @unit=hertz]
|   |-- $e_field
|   |-- $h_field
|   |-- $current
|   `-- $tension
|-- group/
|   `-- $all_frequencies
`-- simulation/
    `-- $sim1[@module=my-module
        |     @version=1.2]
        |-- parametricElements
        |-- parameter
        |-- inputs
        `-- outputs

With /group/$all_frequencies :

/floatingType/$frequency1e3

/floatingType/$frequency1e4

/floatingType/$frequency1e5

/floatingType/$frequency1e6

With /simulation/$sim1/parametricElements :

/globalEnvironment/$ge/frequency

/group/$all_frequencies

/floatingType/$axis_values

In the example, the process will create a number of simulations equals the number of elements of /group/$all_frequencies` simulations.

4.5.5. Batch submission system

4.6. 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 Output requests for output request definition) :

data.h5/
|-- label/
|   `-- outputRequests
|-- mesh/
|   `-- $gmesh1
|       `-- $sphere
|           `-- group
|               |-- $inside[@type=element
|               |           @entityType=volume]
|               `-- $skin[@type=element
|                         @entityType=: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