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 YACS)
 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 .. index:: single: NumberOfProcesses
 274
 275 Lors de la définition d'un opérateur, comme décrit dans le chapitre des
 276 :ref:`section_ref_operator_requirements`, l'utilisateur peut choisir la forme
 277 fonctionnelle "*ScriptWithOneFunction*". Cette forme conduit explicitement à
 278 approximer les opérateurs tangent et adjoint par un calcul par différences
 279 finies. Il requiert de nombreux appels à l'opérateur direct (fonction définie
 280 par l'utilisateur), au moins autant de fois que la dimension du vecteur d'état.
 281 Ce sont ces appels qui peuvent être potentiellement exécutés en parallèle.
 282
 283 Sous certaines conditions, il est alors possible d'accélérer les calculs de
 284 dérivées numériques en utilisant un mode parallèle pour l'approximation par
 285 différences finies. Lors de la définition d'un cas ADAO, c'est effectué en
 286 ajoutant le mot-clé optionnel "*EnableMultiProcessing*", mis à "1", de la
 287 commande "*SCRIPTWITHONEFUNCTION*" dans la définition de l'opérateur. Le mode
 288 parallèle utilise uniquement des ressources locales (à la fois multi-coeurs ou
 289 multi-processeurs) de l'ordinateur sur lequel SALOME est en train de tourner,
 290 demandant autant de ressources que disponible. Si nécessaire, on peut réduire
 291 les ressources disponibles en limitant le nombre possible de processus
 292 parallèles grâce au mot-clé optionnel "*NumberOfProcesses*", que l'on met au
 293 maximum souhaité (ou à "0" pour le contrôle automatique, qui est la valeur par
 294 défaut). Par défaut, ce mode parallèle est désactivé
 295 ("*EnableMultiProcessing=0*").
 296
 297 Les principales conditions pour réaliser ces calculs parallèles viennent de la
 298 fonction définie par l'utilisateur, qui représente l'opérateur direct. Cette
 299 fonction doit au moins être "thread safe" pour être exécutée dans un
 300 environnement Python parallèle (notions au-delà du cadre de ce paragraphe). Il
 301 n'est pas évident de donner des règles générales, donc il est recommandé, à
 302 l'utilisateur qui active ce parallélisme interne, de vérifier soigneusement sa
 303 fonction et les résultats obtenus.
 304
 305 D'un point de vue utilisateur, certaines conditions, qui doivent être réunies
 306 pour mettre en place des calculs parallèles pour les approximations des
 307 opérateurs tangent et adjoint, sont les suivantes :
 308
 309 #. La dimension du vecteur d'état est supérieure à 2 ou 3.
 310 #. Le calcul unitaire de la fonction utilisateur directe "dure un certain temps", c'est-à-dire plus que quelques minutes.
 311 #. 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).
 312 #. 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.
 313 #. 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.
 314
 315 Si ces conditions sont satisfaites, l'utilisateur peut choisir d'activer le
 316 parallélisme interne pour le calcul des dérivées numériques. Malgré la
 317 simplicité d'activation, obtenue en définissant une variable seulement,
 318 l'utilisateur est fortement invité à vérifier les résultats de ses calculs. Il
 319 faut au moins les effectuer une fois avec le parallélisme activé, et une autre
 320 fois avec le parallélisme désactivé, pour comparer les résultats. Si cette mise
 321 en oeuvre échoue à un moment ou à un autre, il faut savoir que ce schéma de
 322 parallélisme fonctionne pour des codes complexes, comme *Code_Aster* dans
 323 *SalomeMeca* [SalomeMeca]_ par exemple. Donc, si cela ne marche pas dans votre
 324 cas, vérifiez bien votre fonction d'opérateur avant et pendant l'activation du
 325 parallélisme...
 326
 327 .. warning::
 328
 329   en cas de doute, il est recommandé de NE PAS ACTIVER ce parallélisme.
 330
 331 On rappelle aussi qu'il faut choisir dans YACS un container par défaut de type
 332 "*multi*" pour le lancement du schéma, pour permettre une exécution
 333 véritablement parallèle.
 334
 335 Passer d'une version d'ADAO à une nouvelle
 336 ------------------------------------------
 337
 338 .. index:: single: Version
 339
 340 Le module ADAO et ses fichiers de cas ".comm" sont identifiés par des versions,
 341 avec des caractéristiques "Major", "Minor" et "Revision". Une version
 342 particulière est numérotée "Major.Minor.Revision", avec un lien fort avec la
 343 numérotation de la plateforme SALOME.
 344
 345 Chaque version "Major.Minor.Revision" du module ADAO peut lire les fichiers de
 346 cas ADAO de la précédente version mineure "Major.Minor-1.*". En général, elle
 347 peut aussi lire les fichiers de cas de toutes les versions mineures "Major.*.*"
 348 d'une branche majeure, mais ce n'est pas obligatoirement vrai pour toutes les
 349 commandes ou tous les mots-clés. En général aussi, un fichier de cas ADAO d'une
 350 version ne peut pas être lu par une précédente version mineure ou majeure du
 351 module ADAO.
 352
 353 Passer de la version 7.5 à la 7.6
 354 +++++++++++++++++++++++++++++++++
 355
 356 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 357 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 358 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom. Cette
 359 procédure effectue automatiquement les modifications requises dans
 360 l'arborescence de stockage du fichier de cas ADAO.
 361
 362 Passer de la version 7.4 à la 7.5
 363 +++++++++++++++++++++++++++++++++
 364
 365 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 366 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 367 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 368
 369 Passer de la version 7.3 à la 7.4
 370 +++++++++++++++++++++++++++++++++
 371
 372 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 373 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 374 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 375
 376 Passer de la version 7.2 à la 7.3
 377 +++++++++++++++++++++++++++++++++
 378
 379 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 380 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 381 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 382
 383 Passer de la version 6.6 à la 7.2
 384 +++++++++++++++++++++++++++++++++
 385
 386 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 387 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 388 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 389
 390 Il y a une incompatibilité introduite dans les fichiers de script de
 391 post-processing ou d'observers. L'ancienne syntaxe pour interroger un objet
 392 résultat, comme celui d'analyse "*Analysis*" (fourni dans un script à travers le
 393 mot-clé "*UserPostAnalysis*"), était par exemple::
 394
 395     Analysis = ADD.get("Analysis").valueserie(-1)
 396     Analysis = ADD.get("Analysis").valueserie()
 397
 398 La nouvelle syntaxe est entièrement compatible avec celle (classique) pour les
 399 objets de type liste ou tuple::
 400
 401     Analysis = ADD.get("Analysis")[-1]
 402     Analysis = ADD.get("Analysis")[:]
 403
 404 Les scripts de post-processing doivent être modifiés.
 405
 406 Passer de la version 6.5 à la 6.6
 407 +++++++++++++++++++++++++++++++++
 408
 409 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 410 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 411 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 412
 413 Il y a une incompatibilité introduite dans la dénomination des opérateurs
 414 élémentaires utilisés pour l'opérateur d'observation par script. Les nouveaux
 415 noms requis sont "*DirectOperator*", "*TangentOperator*" et "*AdjointOperator*",
 416 comme décrit dans la quatrième partie du chapitre :ref:`section_reference`. Les
 417 scripts d'opérateur doivent être modifiés.
 418
 419 Passer de la version 6.4 à la 6.5
 420 +++++++++++++++++++++++++++++++++
 421
 422 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 423 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 424 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 425
 426 Passer de la version 6.3 à la 6.4
 427 +++++++++++++++++++++++++++++++++
 428
 429 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 430 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 431 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.