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

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