doc/dev/sphinx/fr/medcalc-develguide.rst

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