doc/fr/advanced.rst

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