src/MEDOP/doc/sphinx/xmed-develguide.rst

   1 .. meta::
   2    :keywords: maillage, champ, manipulation, med, développement
   3    :author: Guillaume Boulant
   4
   5 .. include:: xmed-definitions.rst
   6
   7 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   8 Module XMED: Guide de développement
   9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  10
  11 (|XMED_DEVELGUIDE_PDF|_)
  12
  13 Ce document est la documentation technique du module XMED. Il fournit
  14 les instructions à suivre pour installer le module en vue d'un travail
  15 de développement, puis décrit les éléments de conception qui
  16 structurent le module.
  17
  18 .. contents:: Sommaire
  19    :local:
  20    :backlinks: none
  21
  22 .. warning:: Ce document est en travaux. Tant que cet avis n'aura pas
  23    disparu, veuillez en considérer le plan et le contenu encore
  24    incomplets, temporaires et sujets à caution.
  25
  26 Mise en place d'un espace de développement
  27 ==========================================
  28
  29 Gestion de configuration du module XMED
  30 ---------------------------------------
  31
  32 Les sources du module (répertoire ``xmed``) sont archivés en dépôt de
  33 configuration dans une base git du projet NEPAL. Ils peuvent être
  34 récupérés au moyen de la commande::
  35
  36  $ git clone git@cli70rw.der.edf.fr:xom/xmed.git
  37
  38 Cette commande installe un répertoire ``xmed`` contenant l'ensemble
  39 des sources du module XMED.
  40
  41 Le module XMED a pour pré-requis logiciel la plateforme SALOME:
  42
  43 * SALOME version 6.1.3 (au moins) à télécharger à l'URL
  44   http://pal.der.edf.fr/pal/projets/pal/releases/V6_1_3
  45 * On peut également utiliser une version dérivée comme SALOME-MECA 2010.1
  46 * Installer la plate-forme choisie selon les instructions fournies.
  47
  48 Le module XMED utilise également une bibliothèque interne au projet
  49 NEPAL, appelée XSALOME, et qui fournit une extension aux fonctions de
  50 SALOME pour un usage de développement (XSALOME signifie eXtension
  51 SALOME). Les sources de cette bibliothèque doivent être récupérés au
  52 moyen de la commande::
  53
  54  $ git clone git@cli70rw.der.edf.fr:xom/xsalome.git
  55
  56 Cette commande installe un répertoire ``xsalome`` contenant l'ensemble
  57 des sources de la bibliothèque XSALOME.
  58
  59 .. note:: La bibliothèque XSALOME n'est pas un module SALOME mais une
  60    simple bibliothèque de fonctions qui complète ou rend plus facile
  61    d'utilisation les fonctions de SALOME. Elle NE DOIT EN AUCUN CAS
  62    être intégrée à d'autres projets que les projets internes NEPAL ou
  63    MAILLAGE. Il s'agit en effet d'une bibliothèque de transition qui
  64    héberge des développements destinés à être reversés dans la
  65    plate-forme SALOME. Le contenu et les interfaces de XSALOME ne peut
  66    donc être garanti sur le long terme.
  67
  68 Installation et lancement de l'application
  69 ------------------------------------------
  70
  71 L'installation suppose qu'une version 6.1.3 de SALOME (ou plus) est
  72 disponible et que le shell de travail est étendu avec l'environnement
  73 de SALOME. En général, par des commandes de la forme::
  74
  75  $ . /where/is/salome/prerequis.sh
  76  $ . /where/is/salome/envSalome.sh
  77
  78 La compilation des modules xsalome et xmed suit le standard SALOME. La
  79 bibliothèque xsalome est un prérequis à la compilation de xmed. Pour
  80 cela, la variable d'environnement XSALOME_DIR doit être spécifiée pour
  81 la configuration de la procédure de reconstruction de xmed::
  82
  83  $ export XSALOME_DIR=<xsalome_installdir>
  84
  85 Aprés l'installation de xmed, il est possible de générer
  86 automatiquement une application SALOME prête à l'emploi pour la
  87 manipulation de champs::
  88
  89  $ <xmed_installdir>/bin/salome/xmed/appligen/appligen.sh
  90
  91 Cette commande génére un répertoire ``appli`` à l'emplacement où elle
  92 est exécutée. Il reste à lancer l'application SALOME au moyen de la
  93 commande::
  94
  95  $ ./appli/runAppli -k
  96
  97 Exécution des tests unitaires
  98 -----------------------------
  99
 100 Les tests unitaires peuvent être exécutés au moyen de scripts python
 101 lancés depuis une session shell SALOME. Dans un nouveau shell, taper::
 102
 103  $ ./appli/runSession
 104  [NS=mars:2810]$ python appli/lib/python2.6/site-packages/salome/xmed/test_medoperation.py
 105
 106 L'exécution imprime un rapport détaillant le résultat pour chaque
 107 fonction de test::
 108
 109  test_addition (__main__.MyTestSuite) ... ok
 110  test_arithmetics (__main__.MyTestSuite) ... ok
 111  test_composition (__main__.MyTestSuite) ... FAIL
 112  test_litteral_equation (__main__.MyTestSuite) ... ok
 113  test_modification_of_attributes (__main__.MyTestSuite) ... ok
 114  test_unary_operations (__main__.MyTestSuite) ... ok
 115  test_update_metadata (__main__.MyTestSuite) ... ok
 116
 117 Les scripts de test sont:
 118
 119 * ``test_medoperation.py``: tests des operations de champs telles
 120   qu'elles sont mises en oeuvre depuis l'interface textuelle.
 121 * ``test_xmed.py``: tests des composants CORBA mis en oeuvre
 122   (``MEDDataManager`` et ``MEDCalculator``)
 123
 124 Architecture du module XMED
 125 ===========================
 126
 127 Le module MED pour la manipulation de champs est composé de:
 128
 129 * une bibliothèque de fonctions pour le traitement de données sur des
 130   maillages et des champs conformes au modèle MED (package
 131   MEDCoupling, MEDLoader et REMAPPER);
 132 * une interface graphique pour la mise en oeuvre des cas standard de
 133   manipulation de champs;
 134 * une ensemble d'outils pour intervenir sur des fichiers au format
 135   MED.
 136
 137 Une bibliothèque de fonctions pour le traitement de données
 138 -----------------------------------------------------------
 139
 140 La figure ci-dessous montre la structure des paquets logiciels qui
 141 constituent la bibliothèque:
 142
 143 .. image:: images/medlayers.png
 144    :align: center
 145
 146 Elle comprend en particulier les paquets suivants:
 147
 148 * MEDCoupling: qui décrit les structures de données pour porter les
 149   maillages et les champs
 150 * MEDLoader: qui fournit les fonctions de persistence sous forme de
 151   fichiers au format MED (lecture et écriture).
 152 * REMAPPER:
 153
 154 Il est important de noter que MEDCoupling n'a aucune dépendance
 155 logicielle autre que la bibliothèque C++ standard. Ceci permet
 156 d'envisager son implantation dans un code de calcul ou un outil de
 157 traitement sans tirer l'ensemble pré-requis de SALOME.
 158
 159 Une interface graphique pour l'exécution des cas standard
 160 ---------------------------------------------------------
 161
 162
 163 Un ensemble d'outils pour le traitement de fichiers
 164 ---------------------------------------------------
 165
 166
 167 Description des composants
 168 ==========================
 169
 170 MEDDataManager - Le gestionnaire des données de session
 171 -------------------------------------------------------
 172
 173 Le composant MEDDataManager s'occupe de fournir les données MED sur
 174 demande des interfaces clientes, en particulier pour module de
 175 pilotage fieldproxy.py. Ces données peuvent avoir plusieurs sources,
 176 en général elle proviennent d'un fichier au format med contenant des
 177 champs définis sur des maillages. Les données sont identifiées à la
 178 lecture des métadonnées de description dans le fichiers med, puis les
 179 valeurs des champs et les maillages support sont chargés au besoin.
 180
 181 Le chargement des métadonnées de description se fait par la méthode::
 182
 183   addDatasource(const char \*filepath)
 184
 185
 186
 187 Eléments d'implémentation
 188 =========================
 189
 190 Ecrire un service CORBA qui retourne une sequence de FieldHandler:
 191
 192 .. code-block:: cpp
 193
 194   MEDOP::FieldHandlerList * MyFunction(...) {
 195     vector<MEDOP::FieldHandler*> fieldHandlerList;
 196     ...
 197
 198     fieldHandlerList.push_back(fieldHandler);
 199
 200     // Map the resulting list to a CORBA sequence for return:
 201     MEDOP::FieldHandlerList_var fieldHandlerSeq = new MEDOP::FieldHandlerList();
 202     int nbFieldHandler = fieldHandlerList.size();
 203     fieldHandlerSeq->length(nbFieldHandler);
 204     for (int i=0; i<nbFieldHandler; i++) {
 205       fieldHandlerSeq[i] = *fieldHandlerList[i];
 206     }
 207     return fieldHandlerSeq._retn();
 208   }
 209
 210 Ecrire un service CORBA qui retourne une structure CORBA:
 211
 212 .. code-block:: cpp
 213
 214     MEDOP::FieldHandler * fieldHandler = new ...
 215     _fieldHandlerMap[fieldHandler->id] = fieldHandler;
 216
 217     // >>> WARNING: CORBA struct specification indicates that the
 218     // assignement acts as a desctructor for the structure that is
 219     // pointed to. The values of the fields are copy first in the new
 220     // structure that receives the assignement and finally the initial
 221     // structure is destroyed. In the present case, WE WANT to keep
 222     // the initial fieldHandler in the map. We must then make a deep
 223     // copy of the structure found in the map and return the copy. The
 224     // CORBA struct specification indicates that a deep copy can be
 225     // done using the copy constructor.  <<<
 226     return new MEDOP::FieldHandler(*fieldHandler);
 227
 228
 229
 230 ANNEXE: Bug en cours
 231 ====================
 232
 233 TO FIX:
 234
 235 * la composition d'opérations n'est pas possible (ex: 2*f1+f2) car
 236   2*f1 est indiqué comme non compatible (il semble qu'il n'ai pas la
 237   reference correcte vers le maillage).
 238 * le script de test test_medoperation.py plante si le module xmed n'a
 239   pas été chargé avec des données chargées.