doc/fr/advanced.rst

   1 ..
   2    Copyright (C) 2008-2015 EDF R&D
   3
   4    This file is part of SALOME ADAO module.
   5
   6    This library is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Lesser General Public
   8    License as published by the Free Software Foundation; either
   9    version 2.1 of the License, or (at your option) any later version.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with this library; if not, write to the Free Software
  18    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  19
  20    See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21
  22    Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
  23
  24 .. _section_advanced:
  25
  26 ================================================================================
  27 **[DocU]** Usages avancés du module ADAO
  28 ================================================================================
  29
  30 Cette section présente des méthodes avancées d'usage du module ADAO, comment
  31 obtenir plus d'information lors d'un calcul, ou comment l'utiliser sans
  32 l'interface graphique (GUI). Cela nécessite de savoir comment trouver les
  33 fichiers ou les commandes incluses dans l'installation complète de SALOME. Tous
  34 les noms à remplacer par l'utilisateur sont indiqués par la syntaxe ``<...>``.
  35
  36 Convertir et exécuter un fichier de commandes ADAO (JDC) par l'intermédiaire d'un script shell
  37 ----------------------------------------------------------------------------------------------
  38
  39 Il est possible de convertir et exécuter une fichier de commandes ADAO (JDC, ou
  40 paire de fichiers ".comm/.py", qui se trouvent dans le répertoire ``<Répertoire
  41 du fichier JDC ADAO>``) automatiquement en utilisant un script de commandes
  42 shell "type" contenant toutes les étapes requises. L'utilisateur doit savoir où
  43 se trouvent les principaux fichiers de lancement de SALOME, et en particulier le
  44 fichier ``salome``. Le répertoire dans lequel ce fichier réside est
  45 symboliquement nommé ``<Répertoire principal d'installation de SALOME>`` et doit
  46 être remplacé par le bon dans le modèle "type" de fichier shell.
  47
  48 Lorsqu'un fichier de commande ADAO est construit par l'interface d'édition
  49 graphique d'ADAO et est enregistré, s'il est nommé par exemple
  50 "EtudeAdao1.comm", alors un fichier compagnon nommé "EtudeAdao1.py" est
  51 automatiquement créé dans la même répertoire. Il est nommé ``<Fichier Python
  52 ADAO>`` dans le modèle "type", et il est converti vers YACS comme un ``<Schéma
  53 xml YACS ADAO>``. Ensuite, il peut être exécuté en mode console en utilisant la
  54 commande standard en mode console de YACS (voir la documentation YACS pour de
  55 plus amples informations).
  56
  57 Dans l'exemple, on choisit de démarrer et arrêter le serveur d'application
  58 SALOME dans le même script, ce qui n'est pas nécessaire, mais utile pour éviter
  59 des sessions SALOME en attente. On choisit aussi de supprimer le fichier de
  60 ``<Schéma xml YACS ADAO>`` car c'est un fichier généré. L'utilisateur de ce
  61 script a seulement besoin de remplacer le texte contenu entre les symboles
  62 ``<...>``
  63
  64 Le modèle "type" de ce script de commandes shell est le suivant::
  65
  66     #!/bin/bash
  67     export USERDIR=<Répertoire du fichier JDC ADAO>
  68     export SALOMEDIR=<Répertoire principal d'installation de SALOME>
  69     $SALOMEDIR/salome start -k -t
  70     $SALOMEDIR/salome shell python \
  71         $SALOMEDIR/bin/salome/AdaoYacsSchemaCreator.py \
  72         $USERDIR/<Fichier Python ADAO> $USERDIR/<Schéma xml YACS ADAO>
  73     $SALOMEDIR/salome shell driver $USERDIR/<Schéma xml YACS ADAO>
  74     $SALOMEDIR/salome shell killSalome.py
  75     rm -f $USERDIR/<Schéma xml YACS ADAO>
  76
  77 Les sorties standard et d'erreur se font à la console.
  78
  79 Exécuter un schéma de calcul ADAO dans YACS en utilisant le mode "texte" (TUI)
  80 ------------------------------------------------------------------------------
  81
  82 Cette section décrit comment exécuter en mode TUI (Text User Interface) un
  83 schéma de calcul YACS, obtenu par la fonction "*Exporter vers YACS*" d'ADAO.
  84 Cela utilise le mode texte standard de YACS, qui est rapidement rappelé ici
  85 (voir la documentation YACS pour de plus amples informations) à travers un
  86 exemple simple. Comme décrit dans la documentation, un schéma XML peut être
  87 chargé en python. On donne ici une séquence complète de commandes pour tester la
  88 validité du schéma avant de l'exécuter, ajoutant des lignes supplémentaires
  89 initiales pour charger de manière explicite le catalogue de types pour éviter
  90 d'obscures difficultés::
  91
  92     #-*-coding:iso-8859-1-*-
  93     import pilot
  94     import SALOMERuntime
  95     import loader
  96     SALOMERuntime.RuntimeSALOME_setRuntime()
  97
  98     r = pilot.getRuntime()
  99     xmlLoader = loader.YACSLoader()
 100     xmlLoader.registerProcCataLoader()
 101     try:
 102      catalogAd = r.loadCatalog("proc", "<Schéma xml YACS ADAO>")
 103     except:
 104       pass
 105     r.addCatalog(catalogAd)
 106
 107     try:
 108         p = xmlLoader.load("<Schéma xml YACS ADAO>")
 109     except IOError,ex:
 110         print "IO exception:",ex
 111
 112     logger = p.getLogger("parser")
 113     if not logger.isEmpty():
 114         print "The imported file has errors :"
 115         print logger.getStr()
 116
 117     if not p.isValid():
 118         print "Le schéma n'est pas valide et ne peut pas être exécuté"
 119         print p.getErrorReport()
 120
 121     info=pilot.LinkInfo(pilot.LinkInfo.ALL_DONT_STOP)
 122     p.checkConsistency(info)
 123     if info.areWarningsOrErrors():
 124         print "Le schéma n'est pas cohérent et ne peut pas être exécuté"
 125         print info.getGlobalRepr()
 126
 127     e = pilot.ExecutorSwig()
 128     e.RunW(p)
 129     if p.getEffectiveState() != pilot.DONE:
 130         print p.getErrorReport()
 131
 132 Cette démarche permet par exemple d'éditer le schéma YACS XML en mode texte TUI,
 133 ou de rassembler les résultats pour un usage ultérieur.
 134
 135 .. _section_advanced_observer:
 136
 137 Obtenir des informations sur des variables spéciales au cours d'un calcul ADAO en YACS
 138 --------------------------------------------------------------------------------------
 139
 140 .. index:: single: Observer
 141 .. index:: single: Observers
 142 .. index:: single: Observer Template
 143
 144 Certaines variables spéciales internes à l'optimisation, utilisées au cours des
 145 calculs, peuvent être surveillées durant un calcul ADAO en YACS. Ces variables
 146 peuvent être affichées, tracées, enregistrées, etc. C'est réalisable en
 147 utilisant des "*observers*", qui sont des scripts, chacun associé à une
 148 variable. Pour pouvoir utiliser cette capacité, l'utilisateur doit construire
 149 des scripts disposant en entrée standard (i.e. disponible dans l'espace de
 150 nommage) des variables ``var`` et ``info``. La variable ``var`` est à utiliser
 151 de la même manière que l'objet final ADD, c'est-à-dire comme un objet de type
 152 liste/tuple.
 153
 154 Des modèles ("templates") sont disponibles lors de l'édition le cas ADAO dans
 155 l'éditeur graphique. Ces scripts simples peuvent être adaptés par l'utilisateur,
 156 soit dans l'étape d'édition EFICAS, ou dans l'étape d'édition YACS, pour
 157 améliorer l'adaptation du calcul ADAO dans YACS.
 158
 159 A titre d'exemple, voici un script trés simple (similaire au modèle
 160 "*ValuePrinter*") utilisable pour afficher la valeur d'une variable surveillée::
 161
 162     print "    --->",info," Value =",var[-1]
 163
 164 Stocké comme un fichier Python, ce script peut être associé à chaque variable
 165 présente dans le mot-clé "*SELECTION*" de la commande "*Observers*":
 166 "*Analysis*", "*CurrentState*", "*CostFunction*"... La valeur courante de la
 167 variable sera affichée à chaque étape de l'algorithme d'optimisation ou
 168 d'assimilation. Les "*observers*" peuvent inclure des capacités d'affichage
 169 graphique, de stockage, d'affichage complexe, de traitement statistique, etc.
 170
 171 Obtenir plus d'information lors du déroulement d'un calcul
 172 ----------------------------------------------------------
 173
 174 .. index:: single: Logging
 175
 176 Lors du déroulement d'un calcul, des données et messages utiles sont
 177 disponibles. Il y a deux manières d'obtenir ces informations.
 178
 179 La première, et la manière préférentielle, est d'utiliser la variable interne
 180 "*Debug*" disponible dans chaque cas ADAO. Elle est atteignable dans l'interface
 181 graphique d'édition du module. La mettre à "*1*" permet d'envoyer des messages
 182 dans la fenêtre de sortie de l'exécution dans YACS ("*YACS Container Log*").
 183
 184 La seconde consiste à utiliser le module Python natif "*logging*" (voir la
 185 documentation Python http://docs.python.org/library/logging.html pour de plus
 186 amples informations sur ce module). Dans l'ensemble du schéma YACS,
 187 principalement à travers les entrées sous forme de scripts, l'utilisateur peut
 188 fixer le niveau de logging en accord avec les besoins d'informations détaillées.
 189 Les différents niveaux de logging sont : "*DEBUG*", "*INFO*", "*WARNING*",
 190 "*ERROR*", "*CRITICAL*". Toutes les informations associées à un niveau sont
 191 affichées à tous les niveaux au-dessus de celui-ci (inclut). La méthode la plus
 192 facile consiste à changer le niveau de surveillance en utilisant les lignes
 193 Python suivantes::
 194
 195     import logging
 196     logging.getLogger().setLevel(logging.DEBUG)
 197
 198 Le niveau par défaut standard de surveillance par logging est "*WARNING*", le
 199 niveau par défaut dans le module ADAO est "*INFO*".
 200
 201 Il est aussi recommandé d'inclure de la surveillance par logging ou des
 202 mécanismes de débogage dans le code de simulation, et de les utiliser en
 203 conjonction avec les deux méthodes précédentes. Néanmoins, il convient d'être
 204 prudent dans le stockage de "grosses" variables car cela coûte du temps,
 205 quel que soit le niveau de surveillance choisi (c'est-à-dire même si ces
 206 variables ne sont pas affichées).
 207
 208 .. _subsection_ref_parallel_df:
 209
 210 Accélérer les calculs de dérivées numériques en utilisant un mode parallèle
 211 ---------------------------------------------------------------------------
 212
 213 .. index:: single: EnableMultiProcessing
 214
 215 Lors de la définition d'un opérateur, comme décrit dans le chapitre des
 216 :ref:`section_ref_operator_requirements`, l'utilisateur peut choisir la forme
 217 fonctionnelle "*ScriptWithOneFunction*". Cette forme conduit explicitement à
 218 approximer les opérateurs tangent et adjoint par un calcul par différences
 219 finies. Il requiert de nombreux appels à l'opérateur direct (fonction définie
 220 par l'utilisateur), au moins autant de fois que la dimension du vecteur d'état.
 221 Ce sont ces appels qui peuvent être potentiellement exécutés en parallèle.
 222
 223 Sous certaines conditions, il est alors possible d'accélérer les calculs de
 224 dérivées numériques en utilisant un mode parallèle pour l'approximation par
 225 différences finies. Lors de la définition d'un cas ADAO, c'est effectué en
 226 ajoutant le mot-clé optionnel "*EnableMultiProcessing*", mis à "1", de la
 227 commande "*SCRIPTWITHONEFUNCTION*" dans la définition de l'opérateur. Le mode
 228 parallèle utilise uniquement des ressources locales (à la fois multi-coeurs ou
 229 multi-processeurs) de l'ordinateur sur lequel SALOME est en train de tourner,
 230 demandant autant de ressources que disponible. Par défaut, ce mode parallèle est
 231 désactivé ("*EnableMultiProcessing=0*").
 232
 233 Les principales conditions pour réaliser ces calculs parallèles viennent de la
 234 fonction définie par l'utilisateur, qui représente l'opérateur direct. Cette
 235 fonction doit au moins être "thread safe" pour être exécutée dans un
 236 environnement Python parallèle (notions au-delà du cadre de ce paragraphe). Il
 237 n'est pas évident de donner des règles générales, donc il est recommandé, à
 238 l'utilisateur qui active ce parallélisme interne, de vérifier soigneusement sa
 239 fonction et les résultats obtenus.
 240
 241 D'un point de vue utilisateur, certaines conditions, qui doivent être réunies
 242 pour mettre en place des calculs parallèles pour les approximations des
 243 opérateurs tangent et adjoint, sont les suivantes :
 244
 245 #. La dimension du vecteur d'état est supérieure à 2 ou 3.
 246 #. Le calcul unitaire de la fonction utilisateur directe "dure un certain temps", c'est-à-dire plus que quelques minutes.
 247 #. La fonction utilisateur directe n'utilise pas déjà du parallélisme (ou l'exécution parallèle est désactivée dans le calcul de l'utilisateur).
 248 #. La fonction utilisateur directe n'effectue pas d'accès en lecture/écriture à des ressources communes, principalement des données stockées, des fichiers de sortie ou des espaces mémoire.
 249 #. Les observers ajoutés par l'utilisateur n'effectuent pas d'accès en lecture/écriture à des ressources communes, comme des fichiers ou des espaces mémoire.
 250
 251 Si ces conditions sont satisfaites, l'utilisateur peut choisir d'activer le
 252 parallélisme interne pour le calcul des dérivées numériques. Malgré la
 253 simplicité d'activation, obtenue en définissant une variable seulement,
 254 l'utilisateur est fortement invité à vérifier les résultats de ses calculs. Il
 255 faut au moins les effectuer une fois avec le parallélisme activé, et une autre
 256 fois avec le parallélisme désactivé, pour comparer les résultats. Si cette mise
 257 en oeuvre échoue à un moment ou à un autre, il faut savoir que ce schéma de
 258 parallélisme fonctionne pour des codes complexes, comme *Code_Aster* dans
 259 *SalomeMeca* [SalomeMeca]_ par exemple. Donc, si cela ne marche pas dans votre
 260 cas, vérifiez bien votre fonction d'opérateur avant et pendant l'activation du
 261 parallélisme...
 262
 263 .. warning::
 264
 265   en cas de doute, il est recommandé de NE PAS ACTIVER ce parallélisme.
 266
 267 Passer d'une version d'ADAO à une nouvelle
 268 ------------------------------------------
 269
 270 .. index:: single: Version
 271
 272 Le module ADAO et ses fichiers de cas ".comm" sont identifiés par des versions,
 273 avec des caractéristiques "Major", "Minor" et "Revision". Une version
 274 particulière est numérotée "Major.Minor.Revision", avec un lien fort avec la
 275 numérotation de la plateforme SALOME.
 276
 277 Chaque version "Major.Minor.Revision" du module ADAO peut lire les fichiers de
 278 cas ADAO de la précédente version mineure "Major.Minor-1.*". En général, elle
 279 peut aussi lire les fichiers de cas de toutes les versions mineures "Major.*.*"
 280 d'une branche majeure, mais ce n'est pas obligatoirement vrai pour toutes les
 281 commandes ou tous les mots-clés. En général aussi, un fichier de cas ADAO d'une
 282 version ne peut pas être lu par une précédente version mineure ou majeure du
 283 module ADAO.
 284
 285 Passer de la version 7.5 à la 7.6
 286 +++++++++++++++++++++++++++++++++
 287
 288 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 289 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 290 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom. Cette
 291 procédure effectue automatiquement les modifications requises dans
 292 l'arborescence de stockage du fichier de cas ADAO.
 293
 294 Passer de la version 7.4 à la 7.5
 295 +++++++++++++++++++++++++++++++++
 296
 297 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 298 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 299 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 300
 301 Passer de la version 7.3 à la 7.4
 302 +++++++++++++++++++++++++++++++++
 303
 304 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 305 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 306 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 307
 308 Passer de la version 7.2 à la 7.3
 309 +++++++++++++++++++++++++++++++++
 310
 311 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 312 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 313 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 314
 315 Passer de la version 6.6 à la 7.2
 316 +++++++++++++++++++++++++++++++++
 317
 318 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 319 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 320 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 321
 322 Il y a une incompatibilité introduite dans les fichiers de script de
 323 post-processing ou d'observers. L'ancienne syntaxe pour interroger un objet
 324 résultat, comme celui d'analyse "*Analysis*" (fourni dans un script à travers le
 325 mot-clé "*UserPostAnalysis*"), était par exemple::
 326
 327     Analysis = ADD.get("Analysis").valueserie(-1)
 328     Analysis = ADD.get("Analysis").valueserie()
 329
 330 La nouvelle syntaxe est entièrement compatible avec celle (classique) pour les
 331 objets de type liste ou tuple::
 332
 333     Analysis = ADD.get("Analysis")[-1]
 334     Analysis = ADD.get("Analysis")[:]
 335
 336 Les scripts de post-processing doivent être modifiés.
 337
 338 Passer de la version 6.5 à la 6.6
 339 +++++++++++++++++++++++++++++++++
 340
 341 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 342 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 343 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 344
 345 Il y a une incompatibilité introduite dans la dénomination des opérateurs
 346 élémentaires utilisés pour l'opérateur d'observation par script. Les nouveaux
 347 noms requis sont "*DirectOperator*", "*TangentOperator*" et "*AdjointOperator*",
 348 comme décrit dans la quatrième partie du chapitre :ref:`section_reference`. Les
 349 scripts d'opérateur doivent être modifiés.
 350
 351 Passer de la version 6.4 à la 6.5
 352 +++++++++++++++++++++++++++++++++
 353
 354 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 355 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 356 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 357
 358 Passer de la version 6.3 à la 6.4
 359 +++++++++++++++++++++++++++++++++
 360
 361 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 362 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 363 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.