Multiple files capabilities
===========================

There are a lot of use cases for which an |namespec| instance could be
split up into several files :

* The mesh are in an another file because it has been generated and stored
  separately. It is also better for the re-usability of objects.
* A large arraySet has been generated by a simulation.

|namespec| offers a flexible means to handle multiple files.


The externalElement category
----------------------------

The ``/externalElement`` category is an HDF5 group, its children are
HDF5 string (n x 3) datasets :

* The first column contains elements names used
  in the |namespec| instance but defined in another (external) 
  |namespec| instance.
* The second column contains the file's name the element is defined in.
* The third column contains the name of the elements in the external file.


.. note:: 
    
    The name of the children of ``/externalElement`` 
    is not specified by |namespec|.

Example, consider the following |namespec| instances data.h5 and mesh.h5 :

::

    data.h5/
    |-- externalElement/
    |   `-- $external_element
    |-- simulation/
    |-- link/
    |   `-- $link_group[@type=dataOnMesh]
    |       `-- link_instance[@subject=/physicalModel/volume/$diel1
    |                         @object=/mesh/$gmesh1/$plane/group/$right-wing]
    `-- physicalModel/
        `-- volume
            `-- $diel1

where ``data.h5:/externalElement/$external_element`` is :

========================= =================== ========================
 /mesh/$gmesh1/$plane         mesh.h5          /mesh/$gmesh1/$mesh1
 /mesh/$gmesh1/$wing          mesh.h5          /mesh/$gmesh1/$mesh2
========================= =================== ========================

and :

::

    mesh.h5/
    `-- mesh
        `-- $gmesh1
            |-- $mesh2
            `-- $mesh1
                |-- elementNodes
                |-- elementTypes
                |-- nodes
                |-- group
                |   |-- $field-location[@type=node]
                |   |-- $right-wing[@type=element]
                |   `-- $left-wing[@type=element]
                |-- groupGroup
                |   `-- $wings
                `-- selectorOnMesh
                    |-- nodes
                    `-- elements


The mesh ``data.h5:/mesh/$gmesh1/$mesh1`` declared (and used) in the instance 
data.h5 is really defined in the instance ``mesh.h5:/mesh/$gmesh1/$mesh1``.

From this point, elements which appear in ``data.h5`` with a 
name beginning with ``/mesh/$gmesh1/$plane`` must be read from 
``data.h5:/mesh/$gmesh1/$mesh1``.

.. note::

    With ``externalElement``, it is possible to know all elements defined 
    externally in one glance.



the linkDefinition attribute
----------------------------

A named element can have one optional attribute which drives toward 
the genuine location of its definition :

This attribute is ``linkDefinition`` : It is the absolute name of 
the element definition. It is an HDF5 |pathlen| character string attribute.

Example, consider the following |namespec| instances data.h5 containing
two arraySet ``data.h5:/floatingType/e_field`` and ``data.h5:/floatingType/h_field`` :

::

    data.h5/
    `-- floatingType
        |-- e_field
        |   |-- data
        |   `-- ds
        |       |-- dim1
        |       `-- dim2
        `-- h_field
            |-- data
            `-- ds
                |-- dim1[@linkDefinition=/floatingType/e_field/ds/dim1]
                `-- dim2[@linkDefinition=/floatingType/e_field/ds/dim2]
      
In this example, the dimension of ``data.h5:/floatingType/h_field`` are defined
from the dimension of ``data.h5:/floatingType/e_field``.