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 <Schéma xml YACS 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 EFICAS, ou dans l'étape d'édition YACS, pour
 215 améliorer l'adaptation du calcul ADAO dans YACS.
 216
 217 A titre d'exemple, voici un script très simple (similaire au modèle
 218 "*ValuePrinter*") utilisable pour afficher la valeur d'une variable surveillée::
 219
 220     print "    --->",info," Value =",var[-1]
 221
 222 Stocké comme un fichier Python, ce script peut être associé à chaque variable
 223 présente dans le mot-clé "*SELECTION*" de la commande "*Observers*":
 224 "*Analysis*", "*CurrentState*", "*CostFunction*"... La valeur courante de la
 225 variable sera affichée à chaque étape de l'algorithme d'optimisation ou
 226 d'assimilation. Les "*observer*" peuvent inclure des capacités d'affichage
 227 graphique, de stockage, d'affichage complexe, de traitement statistique, etc.
 228
 229 Obtenir plus d'information lors du déroulement d'un calcul
 230 ----------------------------------------------------------
 231
 232 .. index:: single: Logging
 233
 234 Lors du déroulement d'un calcul, des données et messages utiles sont
 235 disponibles. Il y a deux manières d'obtenir ces informations.
 236
 237 La première, et la manière préférentielle, est d'utiliser la variable interne
 238 "*Debug*" disponible dans chaque cas ADAO. Elle est atteignable dans l'interface
 239 graphique d'édition du module. La mettre à "*1*" permet d'envoyer des messages
 240 dans la fenêtre de sortie de l'exécution dans YACS ("*YACS Container Log*").
 241
 242 La seconde consiste à utiliser le module Python natif "*logging*" (voir la
 243 documentation Python http://docs.python.org/library/logging.html pour de plus
 244 amples informations sur ce module). Dans l'ensemble du schéma YACS,
 245 principalement à travers les entrées sous forme de scripts, l'utilisateur peut
 246 fixer le niveau de logging en accord avec les besoins d'informations détaillées.
 247 Les différents niveaux de logging sont : "*DEBUG*", "*INFO*", "*WARNING*",
 248 "*ERROR*", "*CRITICAL*". Toutes les informations associées à un niveau sont
 249 affichées à tous les niveaux au-dessus de celui-ci (inclut). La méthode la plus
 250 facile consiste à changer le niveau de surveillance en utilisant les lignes
 251 Python suivantes::
 252
 253     import logging
 254     logging.getLogger().setLevel(logging.DEBUG)
 255
 256 Le niveau par défaut standard de surveillance par logging est "*WARNING*", le
 257 niveau par défaut dans le module ADAO est "*INFO*".
 258
 259 Il est aussi recommandé d'inclure de la surveillance par logging ou des
 260 mécanismes de débogage dans le code de simulation, et de les utiliser en
 261 conjonction avec les deux méthodes précédentes. Néanmoins, il convient d'être
 262 prudent dans le stockage de "grosses" variables car cela coûte du temps,
 263 quel que soit le niveau de surveillance choisi (c'est-à-dire même si ces
 264 variables ne sont pas affichées).
 265
 266 .. _subsection_ref_parallel_df:
 267
 268 Accélérer les calculs de dérivées numériques en utilisant un mode parallèle
 269 ---------------------------------------------------------------------------
 270
 271 .. index:: single: EnableMultiProcessing
 272
 273 Lors de la définition d'un opérateur, comme décrit dans le chapitre des
 274 :ref:`section_ref_operator_requirements`, l'utilisateur peut choisir la forme
 275 fonctionnelle "*ScriptWithOneFunction*". Cette forme conduit explicitement à
 276 approximer les opérateurs tangent et adjoint par un calcul par différences
 277 finies. Il requiert de nombreux appels à l'opérateur direct (fonction définie
 278 par l'utilisateur), au moins autant de fois que la dimension du vecteur d'état.
 279 Ce sont ces appels qui peuvent être potentiellement exécutés en parallèle.
 280
 281 Sous certaines conditions, il est alors possible d'accélérer les calculs de
 282 dérivées numériques en utilisant un mode parallèle pour l'approximation par
 283 différences finies. Lors de la définition d'un cas ADAO, c'est effectué en
 284 ajoutant le mot-clé optionnel "*EnableMultiProcessing*", mis à "1", de la
 285 commande "*SCRIPTWITHONEFUNCTION*" dans la définition de l'opérateur. Le mode
 286 parallèle utilise uniquement des ressources locales (à la fois multi-coeurs ou
 287 multi-processeurs) de l'ordinateur sur lequel SALOME est en train de tourner,
 288 demandant autant de ressources que disponible. Par défaut, ce mode parallèle est
 289 désactivé ("*EnableMultiProcessing=0*").
 290
 291 Les principales conditions pour réaliser ces calculs parallèles viennent de la
 292 fonction définie par l'utilisateur, qui représente l'opérateur direct. Cette
 293 fonction doit au moins être "thread safe" pour être exécutée dans un
 294 environnement Python parallèle (notions au-delà du cadre de ce paragraphe). Il
 295 n'est pas évident de donner des règles générales, donc il est recommandé, à
 296 l'utilisateur qui active ce parallélisme interne, de vérifier soigneusement sa
 297 fonction et les résultats obtenus.
 298
 299 D'un point de vue utilisateur, certaines conditions, qui doivent être réunies
 300 pour mettre en place des calculs parallèles pour les approximations des
 301 opérateurs tangent et adjoint, sont les suivantes :
 302
 303 #. La dimension du vecteur d'état est supérieure à 2 ou 3.
 304 #. Le calcul unitaire de la fonction utilisateur directe "dure un certain temps", c'est-à-dire plus que quelques minutes.
 305 #. 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).
 306 #. 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.
 307 #. 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.
 308
 309 Si ces conditions sont satisfaites, l'utilisateur peut choisir d'activer le
 310 parallélisme interne pour le calcul des dérivées numériques. Malgré la
 311 simplicité d'activation, obtenue en définissant une variable seulement,
 312 l'utilisateur est fortement invité à vérifier les résultats de ses calculs. Il
 313 faut au moins les effectuer une fois avec le parallélisme activé, et une autre
 314 fois avec le parallélisme désactivé, pour comparer les résultats. Si cette mise
 315 en oeuvre échoue à un moment ou à un autre, il faut savoir que ce schéma de
 316 parallélisme fonctionne pour des codes complexes, comme *Code_Aster* dans
 317 *SalomeMeca* [SalomeMeca]_ par exemple. Donc, si cela ne marche pas dans votre
 318 cas, vérifiez bien votre fonction d'opérateur avant et pendant l'activation du
 319 parallélisme...
 320
 321 .. warning::
 322
 323   en cas de doute, il est recommandé de NE PAS ACTIVER ce parallélisme.
 324
 325 On rappelle aussi qu'il faut choisir dans YACS un container par défaut de type
 326 "*multi*" pour le lancement du schéma, pour permettre une exécution
 327 véritablement parallèle.
 328
 329 Passer d'une version d'ADAO à une nouvelle
 330 ------------------------------------------
 331
 332 .. index:: single: Version
 333
 334 Le module ADAO et ses fichiers de cas ".comm" sont identifiés par des versions,
 335 avec des caractéristiques "Major", "Minor" et "Revision". Une version
 336 particulière est numérotée "Major.Minor.Revision", avec un lien fort avec la
 337 numérotation de la plateforme SALOME.
 338
 339 Chaque version "Major.Minor.Revision" du module ADAO peut lire les fichiers de
 340 cas ADAO de la précédente version mineure "Major.Minor-1.*". En général, elle
 341 peut aussi lire les fichiers de cas de toutes les versions mineures "Major.*.*"
 342 d'une branche majeure, mais ce n'est pas obligatoirement vrai pour toutes les
 343 commandes ou tous les mots-clés. En général aussi, un fichier de cas ADAO d'une
 344 version ne peut pas être lu par une précédente version mineure ou majeure du
 345 module ADAO.
 346
 347 Passer de la version 7.5 à la 7.6
 348 +++++++++++++++++++++++++++++++++
 349
 350 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 351 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 352 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom. Cette
 353 procédure effectue automatiquement les modifications requises dans
 354 l'arborescence de stockage du fichier de cas ADAO.
 355
 356 Passer de la version 7.4 à la 7.5
 357 +++++++++++++++++++++++++++++++++
 358
 359 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 360 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 361 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 362
 363 Passer de la version 7.3 à la 7.4
 364 +++++++++++++++++++++++++++++++++
 365
 366 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 367 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 368 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 369
 370 Passer de la version 7.2 à la 7.3
 371 +++++++++++++++++++++++++++++++++
 372
 373 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 374 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 375 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 376
 377 Passer de la version 6.6 à la 7.2
 378 +++++++++++++++++++++++++++++++++
 379
 380 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 381 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 382 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 383
 384 Il y a une incompatibilité introduite dans les fichiers de script de
 385 post-processing ou d'observers. L'ancienne syntaxe pour interroger un objet
 386 résultat, comme celui d'analyse "*Analysis*" (fourni dans un script à travers le
 387 mot-clé "*UserPostAnalysis*"), était par exemple::
 388
 389     Analysis = ADD.get("Analysis").valueserie(-1)
 390     Analysis = ADD.get("Analysis").valueserie()
 391
 392 La nouvelle syntaxe est entièrement compatible avec celle (classique) pour les
 393 objets de type liste ou tuple::
 394
 395     Analysis = ADD.get("Analysis")[-1]
 396     Analysis = ADD.get("Analysis")[:]
 397
 398 Les scripts de post-processing doivent être modifiés.
 399
 400 Passer de la version 6.5 à la 6.6
 401 +++++++++++++++++++++++++++++++++
 402
 403 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 404 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 405 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 406
 407 Il y a une incompatibilité introduite dans la dénomination des opérateurs
 408 élémentaires utilisés pour l'opérateur d'observation par script. Les nouveaux
 409 noms requis sont "*DirectOperator*", "*TangentOperator*" et "*AdjointOperator*",
 410 comme décrit dans la quatrième partie du chapitre :ref:`section_reference`. Les
 411 scripts d'opérateur doivent être modifiés.
 412
 413 Passer de la version 6.4 à la 6.5
 414 +++++++++++++++++++++++++++++++++
 415
 416 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 417 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 418 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 419
 420 Passer de la version 6.3 à la 6.4
 421 +++++++++++++++++++++++++++++++++
 422
 423 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 424 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 425 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.