Exchange surface
================

In the context of multi-method simulation or multi-scale simulation it often
happens that numerical data produced by a computation must be used as input
by another computation.

The exchange surface stores numerical ``data`` on a mesh according the 
huygens principle or the reciprocity principle.


Exchange Surface
################

An exchange surface is a named HDF5 group child of the category
``/exchangeSurface``. The name's length must have less than |elementlen|
characters.

An exchange surface has two attributes :

* ``type``. The ``type`` can take the following values :

  * ``reciprocity``
  * ``huygens``
  * ``gauss``

* ``nature``

  * ``outside`` : the energy is radiated outside the surface
  * ``inside`` : the energy is radiated inside the surface

 
Example an ``exchangeSurface`` called ``/exchangeSurface/$surf1`` : ::

    data.h5
    |-- mesh/
    |   `-- $gmesh1/
    |       `-- $mesh1[@type=unstructured]
    `-- exchangeSurface/
        `-- $surf1[@type=huygens
                   @nature=inside]

An exchange surface can have several single surfaces children, each single 
surface contains a quantity component relative to the principle surface.


Single Surface
##############

An exchange surface can have several single surfaces, a quantity per
single surface is stored. Each quantity is then stored
in an HDF5 named group child of the exchange surface. 

The name's length of the component group must have less than 
|elementlen| characters.

A single surface is a ``floatingType`` equals ``arraySet`` 
representing numerical data on mesh (see :ref:`numericaldataonmesh`).

Example of an exchange surface ``/exchangeSurface/$surf1`` made up of two
single surfaces ``/exchangeSurface/$surf1/$surf11`` and
``/exchangeSurface/$surf1/$surf12`` :

::

    data.h5
    |-- mesh/
    |   `-- $gmesh1/
    |       `-- $mesh1[@type=unstructured]
    |           |-- nodes
    |           `-- group
    |               |-- $point_cloud[@type=node]
    |               `-- $exchange_surface[@type=element
    |                                     @entityType=face]
    `-- exchangeSurface
        `-- $surf1[@type=huygens
            |      @nature=inside]
            |-- $surf11[@floatingType=arraySet           # single surface
            |    |       @physicalNature=electricField
            |    |       @unit=voltPerMeter]
            |    |-- data
            |    `-- ds
            |        |-- dim1[@physicalNature=component]
            |        `-- dim2[@physicalNature=meshEntity
            |                 @meshEntity=/mesh/$gmesh1/$mesh1/group/$exchange_surface]
            `-- $surf11[@floatingType=arraySet           # single surface
                |       @physicalNature=magneticField
                |       @unit=henryPerMeter]
                |-- data
                `-- ds
                    |-- dim1[@physicalNature=component]
                    `-- dim2[@physicalNature=meshEntity
                             @meshEntity=/mesh/$gmesh1/$mesh1/group/$exchange_surface]


In addition, consider a points cloud representing locations 
where physical quantities are
computed. The huygens principle implies physical quantities are 
balanced by the a surface and oriented. The approach is to create a mesh
with patches, the surface of a patch is the weight, a patch is also oriented, so
the single surface is properly defined.

Example :

::

    data.h5
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $mesh2[@type=unstructured]
    |           |-- nodes
    |           |-- elementTypes
    |           `-- group
    |               `-- $circular_patch[@type=element
    |                                   @entityType=face]
    `-- exchangeSurface
        `-- $surf1[@type=huygens
            |      @nature=inside]
            |-- $surf11[@floatingType=arraySet           # single surface
            |    |       @physicalNature=electricField
            |    |       @unit=voltPerMeter]
            |    |-- data
            |    `-- ds
            |        |-- dim1[@physicalNature=component]
            |        `-- dim2[@physicalNature=meshEntity
            |                 @meshEntity=/mesh/$gmesh1/$mesh2/group/$circular_patch]
            `-- $surf11[@floatingType=arraySet           # single surface
                |       @physicalNature=magneticField
                |       @unit=henryPerMeter]
                |-- data
                `-- ds
                    |-- dim1[@physicalNature=component]
                    `-- dim2[@physicalNature=meshEntity
                             @meshEntity=/mesh/$gmesh1/$mesh2/group/$circular_patch]

``data.h5:/mesh/$gmesh1/mesh2/group/$circular_patch`` is a group of circle
elements, their center are the quantities location, the surface is the weight
of each value.