.. # -------------------------------------------------------------------------
.. # C3PO - Coupling Capsule using CGNS/Python for OpenPalm
.. # See license.txt file in the root directory of this Python module source  
.. # -------------------------------------------------------------------------

Using C3PO
++++++++++

Overview
--------

The C3PO module is an interface on the OpenPalm middleware, it provides
OpenPalm users with CGNS/Python data input and output. OpenPalm already
has a python API with a mapping on the numpy arrays. C3PO uses this API
and adds some CGNS/Python related features in order to make CGNS/Python
tools connexion easier.

You can either connect two CGNS/Python applications, not having any OpenPalm
interface or one CGNS/Python to another application already defining an
OpenPalm interface.

CGNS/Python to OpenPalm
-----------------------

You have a CGNS/Python application and you want to connect it to another
already using OpenPalm. This OpenPalm application, say ``A1``, defines
an ID card with all possible input and output OpenPalm can manage for you.
It actual connection to the global simulation system is achieved in a
black-box way, that means you do not need to know how the data is managed,
at the end you use it on your side.

The CGNS/Python application, say ``A2`` has no relationship at all with
OpenPalm. But it can produce and consume CGNS/Python trees. You have to
map actual data you want to send/receive in the CGNS/Tree.

For example, you want to retrieve the mean ``temperature`` on a surface, the
computation is performed by ``A1`` which provides an ID card more or less 
like:

.. code-block:: c

  OBJECT\
   -name Temperature
   -space one_double

``A1`` produces this real value, OpenPalm manages the transfer to your Python
script and you have now to set this value in the CGNS/Python tree used as 
input to ``A2``:

.. code-block:: python

   path='/CGNSTree/Cylindre/ReferenceState/Reynolds'
   C3PO.capsule.nodeRetrieveAsDouble("node",T,path)

Tests
+++++

The first test suite is a ``Left`` to ``Right`` simple exchange,
it shows how to use the ``capsule`` interface together with the ``ppl``
files and associated scripts.

+----+----------------------------+------------------------------+--------+
+    + export/publish/send/put    + import/retrieve/receive/get  + Remarks+
+====+============================+==============================+========+
+ t1 + full CGNS/python tree      + full CGNS/python             +   1    +
+----+----------------------------+------------------------------+--------+
+ t2 + CGNS/python path           + one_integer                  +   1    +
+----+----------------------------+------------------------------+--------+
+ t3 + CGNS/python path           + one_double                   +   1    +
+----+----------------------------+------------------------------+--------+
+ t4 + CGNS/Python path           + double array                 +   1    +
+----+----------------------------+------------------------------+--------+
+ t5 + double array               + CGNS/Python path             +   1    +
+----+----------------------------+------------------------------+--------+

**Remarks:**

**1** Test is run as a ``palm_main`` exec

**2** Test is run as a python script

Detailled examples
------------------

.. toctree::

   t1
   t4

Other specific tests
++++++++++++++++++++

The second test suite requires ``elsA``, it shows code-coupling
with a set of remote scripts. 

+----+----------------------------+------------------------------+
+    + export/publish/send/put    + import/retrieve/receive/get  +
+====+============================+==============================+
+ e1 + full CGNS/python tree      + full CGNS/python             +
+----+----------------------------+------------------------------+
+ e2 +                            +                              +
+----+----------------------------+------------------------------+
+ e3 +                            +                              +
+----+----------------------------+------------------------------+


