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. Si la commande principale de
  43 lancement de SALOME, nommée ``salome``, n'est pas couramment accessible dans un
  44 terminal courant, l'utilisateur doit savoir où se trouvent les principaux
  45 fichiers de lancement de SALOME, et en particulier ce fichier ``salome``. Le
  46 répertoire dans lequel ce fichier réside est symboliquement nommé ``<Répertoire
  47 principal d'installation de SALOME>`` et doit être remplacé par le bon dans le
  48 modèle "type" de fichier Shell.
  49
  50 Lorsqu'un fichier de commande ADAO est construit par l'interface d'édition
  51 graphique d'ADAO et est enregistré, s'il est nommé par exemple
  52 "EtudeAdao1.comm", alors un fichier compagnon nommé "EtudeAdao1.py" est
  53 automatiquement créé dans la même répertoire. Il est nommé ``<Fichier Python
  54 ADAO>`` dans le modèle "type", et il est converti vers YACS comme un ``<Schéma
  55 xml YACS ADAO>`` sous la forme d'un fichier en ".xml" nommé "EtudeAdao1.xml".
  56 Ensuite, ce dernier peut être exécuté en mode console en utilisant l'ordre
  57 standard du mode console de YACS (voir la documentation YACS pour de plus amples
  58 informations).
  59
  60 Dans tous les exemples de fichiers de commandes Shell de lancement, on choisit
  61 de démarrer et arrêter le serveur d'application SALOME dans le même script. Ce
  62 n'est pas indispensable, mais c'est utile pour éviter des sessions SALOME en
  63 attente.
  64
  65 L'exemple le plus simple consiste uniquement à lancer l'exécution d'un schéma
  66 YACS donné, qui a préalablement été généré par l'utilisateur en interface
  67 graphique. Dans ce cas, en ayant pris soin de remplacer les textes contenus
  68 entre les symboles ``<...>``, il suffit d'enregistrer le script de commandes
  69 Shell suivant::
  70
  71     #!/bin/bash
  72     USERDIR="<Répertoire du fichier JDC ADAO>"
  73     SALOMEDIR="<Répertoire principal d'installation de SALOME>"
  74     $SALOMEDIR/salome start -k -t
  75     $SALOMEDIR/salome shell -- "driver $USERDIR/<Schéma xml YACS ADAO>"
  76     $SALOMEDIR/salome shell killSalome.py
  77
  78 Il faut ensuite le rendre exécutable pour l'exécuter.
  79
  80 Un exemple une peu plus complet consiste à lancer l'exécution d'un schéma YACS
  81 indiqué par l'utilisateur, en ayant préalablement vérifié sa disponibilité. Pour
  82 cela, en remplaçant le texte ``<Répertoire principal d'installation de
  83 SALOME>``, il suffit d'enregistrer le script de commandes Shell suivant::
  84
  85     #!/bin/bash
  86     if (test $# != 1)
  87     then
  88       echo -e "\nUsage: $0 <Schéma xml YACS ADAO>\n"
  89       exit
  90     else
  91       USERFILE="$1"
  92     fi
  93     if (test ! -e $USERFILE)
  94     then
  95       echo -e "\nErreur : le fichier XML nommé $USERFILE n'existe pas.\n"
  96       exit
  97     else
  98       SALOMEDIR="<Répertoire principal d'installation de SALOME>"
  99       $SALOMEDIR/salome start -k -t
 100       $SALOMEDIR/salome shell -- "driver $USERFILE"
 101       $SALOMEDIR/salome shell killSalome.py
 102     fi
 103
 104 Un autre exemple de script consiste à ajouter la conversion du fichier de
 105 commandes ADAO (JDC, ou paire de fichiers ".comm/.py") en un schéma YACS associé
 106 (fichier ".xml"). A la fin du script, on choisit aussi de supprimer le fichier
 107 de ``<Schéma xml YACS ADAO>`` car c'est un fichier généré. Pour cela, en ayant
 108 bien pris soin de remplacer le texte ``<Répertoire principal d'installation de
 109 SALOME>``, il suffit d'enregistrer le script de commandes Shell suivant::
 110
 111     #!/bin/bash
 112     if (test $# != 1)
 113     then
 114       echo -e "\nUsage: $0 <Cas .comm/.py ADAO>\n"
 115       exit
 116     else
 117       D=`dirname $1`
 118       F=`basename -s .comm $1`
 119       F=`basename -s .py $F`
 120       USERFILE="$D/$F"
 121     fi
 122     if (test ! -e $USERFILE.py)
 123     then
 124       echo -e "\nErreur : le fichier PY nommé $USERFILE.py n'existe pas.\n"
 125       exit
 126     else
 127       SALOMEDIR="<Répertoire principal d'installation de SALOME>"
 128       $SALOMEDIR/salome start -k -t
 129       $SALOMEDIR/salome shell -- "python $SALOMEDIR/bin/salome/AdaoYacsSchemaCreator.py $USERFILE.py $USERFILE.xml"
 130       $SALOMEDIR/salome shell -- "driver $USERFILE.xml"
 131       $SALOMEDIR/salome shell killSalome.py
 132       rm -f $USERFILE.xml
 133     fi
 134
 135 Dans tous les cas, les sorties standard et d'erreur se font dans le terminal de
 136 lancement.
 137
 138 Exécuter un schéma de calcul ADAO dans YACS en utilisant le mode "texte" (TUI)
 139 ------------------------------------------------------------------------------
 140
 141 Cette section décrit comment exécuter en mode TUI (Text User Interface) YACS un
 142 schéma de calcul YACS, obtenu dans l'interface graphique par la fonction
 143 "*Exporter vers YACS*" d'ADAO. Cela utilise le mode texte standard de YACS, qui
 144 est rapidement rappelé ici (voir la documentation YACS pour de plus amples
 145 informations) à travers un exemple simple. Comme décrit dans la documentation,
 146 un schéma XML peut être chargé en python. On donne ici une séquence complète de
 147 commandes pour tester la validité du schéma avant de l'exécuter, ajoutant des
 148 lignes supplémentaires initiales pour charger de manière explicite le catalogue
 149 de types pour éviter d'obscures difficultés::
 150
 151     #-*-coding:iso-8859-1-*-
 152     import pilot
 153     import SALOMERuntime
 154     import loader
 155     SALOMERuntime.RuntimeSALOME_setRuntime()
 156
 157     r = pilot.getRuntime()
 158     xmlLoader = loader.YACSLoader()
 159     xmlLoader.registerProcCataLoader()
 160     try:
 161      catalogAd = r.loadCatalog("proc", "<Schéma xml YACS ADAO>")
 162     except:
 163       pass
 164     r.addCatalog(catalogAd)
 165
 166     try:
 167         p = xmlLoader.load("<Schéma xml YACS ADAO>")
 168     except IOError,ex:
 169         print "IO exception:",ex
 170
 171     logger = p.getLogger("parser")
 172     if not logger.isEmpty():
 173         print "The imported file has errors :"
 174         print logger.getStr()
 175
 176     if not p.isValid():
 177         print "Le schéma n'est pas valide et ne peut pas être exécuté"
 178         print p.getErrorReport()
 179
 180     info=pilot.LinkInfo(pilot.LinkInfo.ALL_DONT_STOP)
 181     p.checkConsistency(info)
 182     if info.areWarningsOrErrors():
 183         print "Le schéma n'est pas cohérent et ne peut pas être exécuté"
 184         print info.getGlobalRepr()
 185
 186     e = pilot.ExecutorSwig()
 187     e.RunW(p)
 188     if p.getEffectiveState() != pilot.DONE:
 189         print p.getErrorReport()
 190
 191 Cette démarche permet par exemple d'éditer le schéma YACS XML en mode texte TUI,
 192 ou de rassembler les résultats pour un usage ultérieur.
 193
 194 .. _section_advanced_observer:
 195
 196 Obtenir des informations sur des variables spéciales au cours d'un calcul ADAO en YACS
 197 --------------------------------------------------------------------------------------
 198
 199 .. index:: single: Observer
 200 .. index:: single: Observer Template
 201
 202 Certaines variables spéciales internes à l'optimisation, utilisées au cours des
 203 calculs, peuvent être surveillées durant un calcul ADAO en YACS. Ces variables
 204 peuvent être affichées, tracées, enregistrées, etc. C'est réalisable en
 205 utilisant des "*observer*", qui sont des scripts, chacun associé à une
 206 variable. Pour pouvoir utiliser cette capacité, l'utilisateur doit construire
 207 des scripts disposant en entrée standard (i.e. disponible dans l'espace de
 208 nommage) des variables ``var`` et ``info``. La variable ``var`` est à utiliser
 209 de la même manière que l'objet final ADD, c'est-à-dire comme un objet de type
 210 liste/tuple.
 211
 212 Des modèles ("templates") sont disponibles lors de l'édition le cas ADAO dans
 213 l'éditeur graphique. Ces scripts simples peuvent être adaptés par l'utilisateur,
 214 soit dans l'étape d'édition intégrée, ou dans l'étape d'édition avant
 215 l'exécution, pour améliorer l'adaptation du calcul ADAO dans le superviseur
 216 d'exécution de SALOME.
 217
 218 A titre d'exemple, voici un script très simple (similaire au modèle
 219 "*ValuePrinter*") utilisable pour afficher la valeur d'une variable surveillée::
 220
 221     print "    --->",info," Value =",var[-1]
 222
 223 Stocké comme un fichier Python, ce script peut être associé à chaque variable
 224 présente dans le mot-clé "*SELECTION*" de la commande "*Observers*":
 225 "*Analysis*", "*CurrentState*", "*CostFunction*"... La valeur courante de la
 226 variable sera affichée à chaque étape de l'algorithme d'optimisation ou
 227 d'assimilation. Les "*observer*" peuvent inclure des capacités d'affichage
 228 graphique, de stockage, d'affichage complexe, de traitement statistique, etc.
 229
 230 Obtenir plus d'information lors du déroulement d'un calcul
 231 ----------------------------------------------------------
 232
 233 .. index:: single: Logging
 234
 235 Lors du déroulement d'un calcul, des données et messages utiles sont
 236 disponibles. Il y a deux manières d'obtenir ces informations.
 237
 238 La première, et la manière préférentielle, est d'utiliser la variable interne
 239 "*Debug*" disponible dans chaque cas ADAO. Elle est atteignable dans l'interface
 240 graphique d'édition du module. La mettre à "*1*" permet d'envoyer des messages
 241 dans la fenêtre de sortie de l'exécution dans YACS ("*YACS Container Log*").
 242
 243 La seconde consiste à utiliser le module Python natif "*logging*" (voir la
 244 documentation Python http://docs.python.org/library/logging.html pour de plus
 245 amples informations sur ce module). Dans l'ensemble du schéma YACS,
 246 principalement à travers les entrées sous forme de scripts, l'utilisateur peut
 247 fixer le niveau de logging en accord avec les besoins d'informations détaillées.
 248 Les différents niveaux de logging sont : "*DEBUG*", "*INFO*", "*WARNING*",
 249 "*ERROR*", "*CRITICAL*". Toutes les informations associées à un niveau sont
 250 affichées à tous les niveaux au-dessus de celui-ci (inclut). La méthode la plus
 251 facile consiste à changer le niveau de surveillance en utilisant les lignes
 252 Python suivantes::
 253
 254     import logging
 255     logging.getLogger().setLevel(logging.DEBUG)
 256
 257 Le niveau par défaut standard de surveillance par logging est "*WARNING*", le
 258 niveau par défaut dans le module ADAO est "*INFO*".
 259
 260 Il est aussi recommandé d'inclure de la surveillance par logging ou des
 261 mécanismes de débogage dans le code de simulation, et de les utiliser en
 262 conjonction avec les deux méthodes précédentes. Néanmoins, il convient d'être
 263 prudent dans le stockage de "grosses" variables car cela coûte du temps,
 264 quel que soit le niveau de surveillance choisi (c'est-à-dire même si ces
 265 variables ne sont pas affichées).
 266
 267 .. _subsection_ref_parallel_df:
 268
 269 Accélérer les calculs de dérivées numériques en utilisant un mode parallèle
 270 ---------------------------------------------------------------------------
 271
 272 .. index:: single: EnableMultiProcessing
 273
 274 Lors de la définition d'un opérateur, comme décrit dans le chapitre des
 275 :ref:`section_ref_operator_requirements`, l'utilisateur peut choisir la forme
 276 fonctionnelle "*ScriptWithOneFunction*". Cette forme conduit explicitement à
 277 approximer les opérateurs tangent et adjoint par un calcul par différences
 278 finies. Il requiert de nombreux appels à l'opérateur direct (fonction définie
 279 par l'utilisateur), au moins autant de fois que la dimension du vecteur d'état.
 280 Ce sont ces appels qui peuvent être potentiellement exécutés en parallèle.
 281
 282 Sous certaines conditions, il est alors possible d'accélérer les calculs de
 283 dérivées numériques en utilisant un mode parallèle pour l'approximation par
 284 différences finies. Lors de la définition d'un cas ADAO, c'est effectué en
 285 ajoutant le mot-clé optionnel "*EnableMultiProcessing*", mis à "1", de la
 286 commande "*SCRIPTWITHONEFUNCTION*" dans la définition de l'opérateur. Le mode
 287 parallèle utilise uniquement des ressources locales (à la fois multi-coeurs ou
 288 multi-processeurs) de l'ordinateur sur lequel SALOME est en train de tourner,
 289 demandant autant de ressources que disponible. Par défaut, ce mode parallèle est
 290 désactivé ("*EnableMultiProcessing=0*").
 291
 292 Les principales conditions pour réaliser ces calculs parallèles viennent de la
 293 fonction définie par l'utilisateur, qui représente l'opérateur direct. Cette
 294 fonction doit au moins être "thread safe" pour être exécutée dans un
 295 environnement Python parallèle (notions au-delà du cadre de ce paragraphe). Il
 296 n'est pas évident de donner des règles générales, donc il est recommandé, à
 297 l'utilisateur qui active ce parallélisme interne, de vérifier soigneusement sa
 298 fonction et les résultats obtenus.
 299
 300 D'un point de vue utilisateur, certaines conditions, qui doivent être réunies
 301 pour mettre en place des calculs parallèles pour les approximations des
 302 opérateurs tangent et adjoint, sont les suivantes :
 303
 304 #. La dimension du vecteur d'état est supérieure à 2 ou 3.
 305 #. Le calcul unitaire de la fonction utilisateur directe "dure un certain temps", c'est-à-dire plus que quelques minutes.
 306 #. 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).
 307 #. 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.
 308 #. Les "*observer*" 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.
 309
 310 Si ces conditions sont satisfaites, l'utilisateur peut choisir d'activer le
 311 parallélisme interne pour le calcul des dérivées numériques. Malgré la
 312 simplicité d'activation, obtenue en définissant une variable seulement,
 313 l'utilisateur est fortement invité à vérifier les résultats de ses calculs. Il
 314 faut au moins les effectuer une fois avec le parallélisme activé, et une autre
 315 fois avec le parallélisme désactivé, pour comparer les résultats. Si cette mise
 316 en oeuvre échoue à un moment ou à un autre, il faut savoir que ce schéma de
 317 parallélisme fonctionne pour des codes complexes, comme *Code_Aster* dans
 318 *SalomeMeca* [SalomeMeca]_ par exemple. Donc, si cela ne marche pas dans votre
 319 cas, vérifiez bien votre fonction d'opérateur avant et pendant l'activation du
 320 parallélisme...
 321
 322 .. warning::
 323
 324   en cas de doute, il est recommandé de NE PAS ACTIVER ce parallélisme.
 325
 326 On rappelle aussi qu'il faut choisir dans YACS un container par défaut de type
 327 "*multi*" pour le lancement du schéma, pour permettre une exécution
 328 véritablement parallèle.
 329
 330 Passer d'une version d'ADAO à une nouvelle
 331 ------------------------------------------
 332
 333 .. index:: single: Version
 334
 335 Le module ADAO et ses fichiers de cas ".comm" sont identifiés par des versions,
 336 avec des caractéristiques "Major", "Minor" et "Revision". Une version
 337 particulière est numérotée "Major.Minor.Revision", avec un lien fort avec la
 338 numérotation de la plateforme SALOME.
 339
 340 Chaque version "Major.Minor.Revision" du module ADAO peut lire les fichiers de
 341 cas ADAO de la précédente version mineure "Major.Minor-1.*". En général, elle
 342 peut aussi lire les fichiers de cas de toutes les versions mineures "Major.*.*"
 343 d'une branche majeure, mais ce n'est pas obligatoirement vrai pour toutes les
 344 commandes ou tous les mots-clés. En général aussi, un fichier de cas ADAO d'une
 345 version ne peut pas être lu par une précédente version mineure ou majeure du
 346 module ADAO.
 347
 348 Passer de la version 7.5 à la 7.6
 349 +++++++++++++++++++++++++++++++++
 350
 351 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 352 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 353 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom. Cette
 354 procédure effectue automatiquement les modifications requises dans
 355 l'arborescence de stockage du fichier de cas ADAO.
 356
 357 Passer de la version 7.4 à la 7.5
 358 +++++++++++++++++++++++++++++++++
 359
 360 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 361 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 362 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 363
 364 Passer de la version 7.3 à la 7.4
 365 +++++++++++++++++++++++++++++++++
 366
 367 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 368 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 369 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 370
 371 Passer de la version 7.2 à la 7.3
 372 +++++++++++++++++++++++++++++++++
 373
 374 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 375 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 376 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 377
 378 Passer de la version 6.6 à la 7.2
 379 +++++++++++++++++++++++++++++++++
 380
 381 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 382 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 383 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 384
 385 Il y a une incompatibilité introduite dans les fichiers de script de
 386 post-processing ou d'observers. L'ancienne syntaxe pour interroger un objet
 387 résultat, comme celui d'analyse "*Analysis*" (fourni dans un script à travers le
 388 mot-clé "*UserPostAnalysis*"), était par exemple::
 389
 390     Analysis = ADD.get("Analysis").valueserie(-1)
 391     Analysis = ADD.get("Analysis").valueserie()
 392
 393 La nouvelle syntaxe est entièrement compatible avec celle (classique) pour les
 394 objets de type liste ou tuple::
 395
 396     Analysis = ADD.get("Analysis")[-1]
 397     Analysis = ADD.get("Analysis")[:]
 398
 399 Les scripts de post-processing doivent être modifiés.
 400
 401 Passer de la version 6.5 à la 6.6
 402 +++++++++++++++++++++++++++++++++
 403
 404 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 405 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 406 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 407
 408 Il y a une incompatibilité introduite dans la dénomination des opérateurs
 409 élémentaires utilisés pour l'opérateur d'observation par script. Les nouveaux
 410 noms requis sont "*DirectOperator*", "*TangentOperator*" et "*AdjointOperator*",
 411 comme décrit dans la quatrième partie du chapitre :ref:`section_reference`. Les
 412 scripts d'opérateur doivent être modifiés.
 413
 414 Passer de la version 6.4 à la 6.5
 415 +++++++++++++++++++++++++++++++++
 416
 417 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 418 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 419 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 420
 421 Passer de la version 6.3 à la 6.4
 422 +++++++++++++++++++++++++++++++++
 423
 424 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 425 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 426 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.