doc/accesLocal.rst

   1
   2 .. _secacceslocal:
   3
   4 Component with local access
   5 ==============================
   6 Principle
   7 -------------
   8 As mentioned in the :ref:`secetapes` chapter, the internal object built in the :ref:`seccompinterne` chapter can be manipulated
   9 from a local python interpreter according to the following scheme.
  10
  11 .. _figacceslocal2:
  12
  13
  14 .. image:: images/accesLocal.png
  15    :align: center
  16
  17 .. centered::   Access from a local python interpreter
  18
  19 In the case of a C++ internal object, a python/ C++ interface has to be written to obtain a local component.
  20 The next section describes how this interface is written.  Nothing needs to be done in the case of a python internal
  21 object:  the python internal object can be used as a local component.
  22
  23 Starting from a python internal object
  24 ------------------------------------------
  25 There is no need to introduce an additional interface if the internal object is implemented as a python object.
  26
  27 Starting from a C++ internal object
  28 ------------------------------------------
  29 A python/C++ interface has to be used before a C++ object can be used from a python interpreter.  This interface can be
  30 coded by the integrator or it can be generated (semi-) automatically using tools such as swig [SWIG]_ or boost [BOOST]_.
  31 This document describes how the interface is generated using swig, through a simple example.  Refer to the swig
  32 documentation, or even the python documentation, for processing of special cases.
  33
  34 Swig interface file
  35 ^^^^^^^^^^^^^^^^^^^^^^^^
  36 The standard procedure to use swig is to write an **interface file** (terminating with ``.i``).  This interface file
  37 is very similar to a C++ interface file (for example see ``vecteur.hxx`` or ``FreeFem.hxx``).  It contains all C++
  38 declarations (structures, functions, classes, constants, etc.) that the integrator wants to “export” to the python level.
  39 Only the public part of classes can be indicated in the interface file for C++ classes.  Examples will be given later.
  40
  41 Process for generating the C++ / python interface code
  42 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  43 **Rule**
  44   Extensions to the python language written in the C / C++ / f77 language (compiled languages other than python) must be compiled
  45   in the form of dynamic libraries (``.so`` under unix, ``.dll`` under windows).  These extensions will be loaded from the python
  46   interpreter using the import command.
  47
  48 Therefore, all components to be integrated will be compiled in the form of a dynamic library, which will mean a particular
  49 procedure for the use of debugging tools (see below).  The various operations to be carried out and the files involved in the
  50 process are shown diagrammatically on the following figure.
  51
  52 .. _processusswig:
  53
  54
  55 .. image:: images/accesLocalCpp.png
  56    :align: center
  57
  58 .. centered::   Interface through swig
  59
  60 Example 5 (first version)
  61 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  62 If it is required to access the ``alglin`` class from a local python interpreter, an interface file will be written with type:
  63
  64
  65 .. _alglin.i.v1:
  66
  67
  68 ``alglin.i``
  69
  70 .. include:: ./exemples/exemple5/v1/alglin.i
  71    :literal:
  72
  73 The different lines mean::
  74
  75    %module AlgLinModule
  76
  77 Defines the name of the python module.  We will write ``import AlgLinModule``, to import the definitions of the component
  78 from a python interpreter. ::
  79
  80    %{
  81    #include "alglin.hxx"
  82    %}
  83
  84 The C++ declarations that the C++ / python interface code will need will have to be written between the ``%{`` and ``%}``
  85 lines (otherwise the C++ file generated by swig will not compile).  Typically, the interface file of the C++ internal
  86 object constructed in the previous chapter will be included here.
  87
  88 ::
  89
  90    class alglin {
  91    public:
  92      alglin ();
  93      ~alglin ();
  94      void      addvec (vecteur *C, vecteur *A, vecteur *B);
  95      double    prdscl (vecteur *A, vecteur *B);
  96      vecteur * create_vector (long n);
  97      void      destroy_vector (vecteur *V);
  98
  99    };
 100
 101 The remainder of the ``alglin.i``. file includes an indication about the classes and definitions that are to be
 102 exported to the python interpreter.  Example use of the generated interface:
 103
 104 .. include:: ./exemples/exemple5/v1/sortie.txt
 105    :literal:
 106
 107 **Notes**
 108
 109   #. A constructor (``alglin()`` ) and a destructor (``~alglin()`` ) have been introduced that were not in the declaration of
 110      the C++ class (file ``alglin.hxx``).  This constructor and this destructor are not necessary in the C++ class of the internal
 111      object (the internal object does not need to be initialised when it is created and does not manage the C++ dynamic memory).
 112      In this case, the compiler provides a default constructor and destructor.  On the other hand, a constructor and a destructor
 113      **must be** explicitly declared for the swig interface file so that python can manage the C++ memory correctly (i.e. the internal
 114      C++ object is also created / deleted “cleanly” when a python object is created / deleted).
 115   #. Note that the definition of the ``vector`` structure/class is not explicitely described in the ``alglin.i`` interface file. ``Vector``
 116      type objects will be seen from the python interpreter as “black box” objects (their type and memory location are known, but
 117      associated methods / attributes are not known). The following error message will be produced if an attempt is made to call
 118      a method on a vector object:
 119
 120 .. include:: ./exemples/exemple5/v1/sortie2.txt
 121    :literal:
 122
 123
 124 .. epigraph::
 125
 126    The second version of this example (below) will correct this problem.
 127
 128    .. %
 129
 130
 131 Example 5 (second version)
 132 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 133 The first version of the example suffers from two defects (among others) concerning vector type objects:
 134
 135 - there is no access to methods nor to attributes of objects in the vector class (see the second comment above)
 136 - nothing is provided to initialise/modify the coefficients contained in a vector object.
 137
 138 Swig enriches the ``alglin.i`` interface file to add missing functions:
 139
 140 .. _alglin.i.v2:
 141
 142
 143 ``alglin.i (version 2)``
 144
 145 .. include:: ./exemples/exemple5/v2/alglin.i
 146    :literal:
 147
 148
 149 **Note**
 150   Unlike the previous version, there is the declaration of the vector class, which for example provides access to the size of vectors
 151   and to a “handle” to coefficients (but not to coefficients individually).  The third version will correct this defect.
 152   An example use of the component (and the limitation on access to vectors) is given below:
 153
 154 .. include:: ./exemples/exemple5/v2/sortie.txt
 155    :literal:
 156
 157 Example 5 (third version)
 158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 159 The second version of the example makes it possible to “see” vector type objects but only at the “surface”.  In particular, there is
 160 no individual access to coefficients from the python interpreter.  By adding utility functions (``__setitem__`` and ``__getitem__``)
 161 into the ``alglin.i`` interface, the third version makes it possible to (partially) simulate genuine coefficient vectors from the python layer.
 162
 163 **Note**: We have also added an ``__str__`` display function that displays the list of coefficients of v, when
 164 ``print v`` is executed from the interpreter.
 165
 166
 167 .. _alglin.i.v3:
 168
 169
 170 ``alglin.i (version 3)``
 171
 172 .. include:: ./exemples/exemple5/v3/alglin.i
 173    :literal:
 174
 175 The following contains an example use of the component (including access to vectors):
 176
 177 .. include:: ./exemples/exemple5/v3/sortie.txt
 178    :literal:
 179