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

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. 

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.