.. # -------------------------------------------------------------------------
.. # CWIPI.CGNS - a CGNS/Python module for CWIPI
.. # See license.txt file in the root directory of this Python module source  
.. # -------------------------------------------------------------------------

Using CWIPI.CGNS
++++++++++++++++

Overview
--------

The CWIPI.CGNS module is an interface on a middleware set of services for
code-coupling based on meshes.

The CWIPI.CGNS module uses CGNS/Python trees to detect and create corresponding
parameters for CWIPI. A CGNS/Python tree contains, for each partner code of
the coupled simulation, a surface and a set of physical data to be exchanged
to/from other simulation partners.

The interface can read both structured and unstructured meshes.

CGNS/Python requirements
------------------------

Each partner code has to have a compliant CGNS/Python tree defining at least its
support grid. The surfaces are detected as boundary conditions (BC) and these
should be associated to a family. The CWIPI.CGNS module looks for an
additional family (AdditionalFamily_t) in the BCs (BC_t). The name of this
node can be user defined, its default value is `SurfaceExchange`. 

Data definition
===============

The actual family should have at least the three children nodes: `Mode`,
`DataInput`, `DataOuput`.
The `Mode` node value is 'CWIPI', the children of this node defines CWIPI 
parameters such as:

The `DataInput` and `DataOutput` have one child per value to be declared as
input/output during the simulation.

The user first has to define a family, it would be used as the support for
the coupling data exchange. The family node declares the required output values
and the expected input values. There is no declaration of exchange time step or
prediod or state at this place, the time dependent definitions are associated
with the `Trigger`.

The example below shows a `Family_t` node with its `DataInput` and `DataOutput`
children nodes. Each of these is, more or less, a list of expected values.

.. image:: images/basefam.png
   :width: 22cm

Surface definition
==================

The surface for the coupling exchange is defined by means of `BC_t` having
the required `AdditionalFamilyName_t`. The exact name of the family can be
set by the user, the default is **SurfaceExchange**. The value of the familyname 
itself is not significant, it is used to find the base family. In the case
of a same surface being used for several different exchange, you have to add
as many `AdditionalFamilyName_t` as needed, and set the corresponding base
family with their `DataInput` and `DataOutput`.

.. image:: images/addfam.png
   :width: 22cm

Protocol definition
===================

The trigger is the support for the exchange protocol.

