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