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 Certaines variables spéciales internes à l'optimisation, utilisées au cours des
 116 calculs, peuvent être surveillées durant un calcul ADAO en YACS. Ces variables
 117 peuvent être affichées, tracées, enregistrées, etc. C'est réalisable en
 118 utilisant des "*observers*", qui sont des scripts, chacun associé à une
 119 variable. Pour pouvoir utiliser cette capacité, l'utilisateur doit construire
 120 des scripts disposant en entrée standard (i.e. disponible dans l'espace de
 121 nommage) des variables ``var`` et ``info``. La variable ``var`` est à utiliser
 122 de la même manière que l'objet final ADD, c'est-à-dire comme un objet de type
 123 liste/tuple.
 124
 125 Des modèles ("templates") sont disponibles lors de l'édition le cas ADAO dans
 126 l'éditeur EFICAS. Ces scripts simples peuvent être adaptés par l'utilisateur,
 127 soit dans l'étape EFICAS, ou dans l'étape d'édition YACS, pour améliorer
 128 l'adaptation du calcul ADAO dans YACS.
 129
 130 A titre d'exemple, voici un script trés simple (similaire au modèle
 131 "*ValuePrinter*") utilisable pour afficher la valeur d'une variable surveillée::
 132
 133     print "    --->",info," Value =",var[-1]
 134
 135 Stocké comme un fichier Python, ce script peut être associé à chaque variable
 136 présente dans le mot-clé "*SELECTION*" de la commande "*Observers*":
 137 "*Analysis*", "*CurrentState*", "*CostFunction*"... La valeur courante de la
 138 variable sera affichée à chaque étape de l'algorithme d'optimisation ou
 139 d'assimilation. Les "*observers*" peuvent inclure des capacités d'affichage
 140 graphique, de stockage, d'affichage complexe, de traitement statistique, etc.
 141
 142 Obtenir plus d'information lors du déroulement d'un calcul
 143 ----------------------------------------------------------
 144
 145 Lors du déroulement d'un calcul, des données et messages utiles sont
 146 disponibles. Il y a deux manières d'obtenir ces informations.
 147
 148 La première, et la manière préférentielle, est d'utiliser la variable interne
 149 "*Debug*" disponible dans chaque cas ADAO. Elle est atteignable dans l'interface
 150 graphique d'édition du module. La mettre à "*1*" permet d'envoyer des messages
 151 dans la fenêtre de sortie de l'exécution dans YACS ("*YACS Container Log*").
 152
 153 La seconde consiste à utiliser le module Python natif "*logging*" (voir la
 154 documentation Python http://docs.python.org/library/logging.html pour de plus
 155 amples informations sur ce module). Dans l'ensemble du schéma YACS,
 156 principalement à travers les entrées sous forme de scripts, l'utilisateur peut
 157 fixer le niveau de logging en accord avec les besoins d'informations détaillées.
 158 Les différents niveaux de logging sont : "*DEBUG*", "*INFO*", "*WARNING*",
 159 "*ERROR*", "*CRITICAL*". Toutes les informations associées à un niveau sont
 160 affichées à tous les niveaux au-dessus de celui-ci (inclut). La méthode la plus
 161 facile consiste à changer le niveau de surveillance en utilisant les lignes
 162 Python suivantes::
 163
 164     import logging
 165     logging.getLogger().setLevel(logging.DEBUG)
 166
 167 Le niveau par défaut standard de surveillance par logging est "*WARNING*", le
 168 niveau par défaut dans le module ADAO est "*INFO*".
 169
 170 Il est aussi recommandé d'inclure de la surveillance par logging ou des
 171 mécanismes de débogage dans le code de simulation, et de les utiliser en
 172 conjonction avec les deux méthodes précédentes. Néanmoins, il convient d'être
 173 prudent dans le stockage de "grosses" variables car cela coûte du temps,
 174 quel que soit le niveau de surveillance choisi (c'est-à-dire même si ces
 175 variables ne sont pas affichées).
 176
 177 Accélérer les calculs de dérivées numériques en utilisant un mode parallèle
 178 ---------------------------------------------------------------------------
 179
 180 Lors de la définition d'un opérateur, comme décrit dans la chapitre
 181 :ref:`section_reference`, l'utilisateur peut choisir la forme fonctionnelle
 182 "*ScriptWithOneFunction*". Cette forme conduit explicitement à approximer les
 183 opérateurs tangent et adjoint par un calcul par différences finies. Il requiert
 184 de nombreux appels à l'opérateur direct (fonction définie par l'utilisateur), au
 185 moins autant de fois que la dimension du vecteur d'état. Ce sont ces appels qui
 186 peuvent être potentiellement exécutés en parallèle.
 187
 188 Sous certaines conditions, il est alors possible d'accélérer les calculs de
 189 dérivées numériques en utilisant un mode parallèle pour l'approximation par
 190 différences finies. Lors de la définition d'un cas ADAO, c'est effectué en
 191 ajoutant le mot-clé optionnel "*EnableMultiProcessing*", mis à "1", de la
 192 commande "*SCRIPTWITHONEFUNCTION*" dans la définition de l'opérateur. Le mode
 193 parallèle utilise uniquement des ressources locales (à la fois multi-coeurs ou
 194 multi-processeurs) de l'ordinateur sur lequel SALOME est en train de tourner,
 195 demandant autant de ressources que disponible. Par défaut, ce mode parallèle est
 196 désactivé ("*EnableMultiProcessing=0*").
 197
 198 Les principales conditions pour réaliser ces calculs parallèles viennent de la
 199 fonction définie par l'utilisateur, qui représente l'opérateur direct. Cette
 200 fonction doit au moins être "thread safe" pour être exécutée dans un
 201 environnement Python parallèle (notions au-delà du cadre de ce paragraphe). Il
 202 n'est pas évident de donner des règles générales, donc il est recommandé, à
 203 l'utilisateur qui active ce parallélisme interne, de vérifier soigneusement sa
 204 fonction et les résultats obtenus.
 205
 206 D'un point de vue utilisateur, certaines conditions, qui doivent être réunies
 207 pour mettre en place des calculs parallèles pour les approximations des
 208 opérateurs tangent et adjoint, sont les suivantes :
 209
 210 #. La dimension du vecteur d'état est supérieure à 2 ou 3.
 211 #. Le calcul unitaire de la fonction utilisateur directe "dure un certain temps", c'est-à-dire plus que quelques minutes.
 212 #. 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).
 213 #. 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.
 214
 215 Si ces conditions sont satisfaites, l'utilisateur peut choisir d'activer le
 216 parallélisme interne pour le calcul des dérivées numériques. Malgré la
 217 simplicité d'activation, obtenue en définissant une variable seulement,
 218 l'utilisateur est fortement invité à vérifier les résultats de ses calculs. Il
 219 faut au moins les effectuer une fois avec le parallélisme activé, et une autre
 220 fois avec le parallélisme désactivé, pour comparer les résultats. Si cette mise
 221 en oeuvre échoue à un moment ou à un autre, il faut savoir que ce schéma de
 222 parallélisme fonctionne pour des codes complexes, comme *Code_Aster* dans
 223 *SalomeMeca* [SalomeMeca]_ par exemple. Donc vérifiez votre fonction d'opérateur
 224 avant et pendant l'activation du parallélisme...
 225
 226 **En cas de doute, il est recommandé de NE PAS ACTIVER ce parallélisme.**
 227
 228 Passer d'une version d'ADAO à une nouvelle
 229 ------------------------------------------
 230
 231 Le module ADAO et ses fichiers de cas ".comm" sont identifiés par des versions,
 232 avec des caractéristiques "Major", "Minor" et "Revision". Une version
 233 particulière est numérotée "Major.Minor.Revision", avec un lien fort avec la
 234 numérotation de la plateforme SALOME.
 235
 236 Chaque version "Major.Minor.Revision" du module ADAO peut lire les fichiers de
 237 cas ADAO de la précédente version mineure "Major.Minor-1.*". En général, elle
 238 peut aussi lire les fichiers de cas de toutes les versions mineures "Major.*.*"
 239 d'une branche majeure, mais ce n'est pas obligatoirement vrai pour toutes les
 240 commandes ou tous les mots-clés. En général aussi, un fichier de cas ADAO d'une
 241 version ne peut pas être lu par une précédente version mineure ou majeure du
 242 module ADAO.
 243
 244 Passer de la version 7.3 à la 7.4
 245 +++++++++++++++++++++++++++++++++
 246
 247 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 248 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 249 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 250
 251 Passer de la version 7.2 à la 7.3
 252 +++++++++++++++++++++++++++++++++
 253
 254 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 255 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
 256 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 257
 258 Passer de la version 6.6 à la 7.2
 259 +++++++++++++++++++++++++++++++++
 260
 261 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 262 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 263 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 264
 265 Il y a une incompatibilité introduite dans les fichiers de script de
 266 post-processing ou d'observers. L'ancienne syntaxe pour interroger un objet
 267 résultat, comme celui d'analyse "*Analysis*" (fourni dans un script à travers le
 268 mot-clé "*UserPostAnalysis*"), était par exemple::
 269
 270     Analysis = ADD.get("Analysis").valueserie(-1)
 271     Analysis = ADD.get("Analysis").valueserie()
 272
 273 La nouvelle syntaxe est entièrement compatible avec celle (classique) pour les
 274 objets de type liste ou tuple::
 275
 276     Analysis = ADD.get("Analysis")[-1]
 277     Analysis = ADD.get("Analysis")[:]
 278
 279 Les scripts de post-processing doivent être modifiés.
 280
 281 Passer de la version 6.5 à la 6.6
 282 +++++++++++++++++++++++++++++++++
 283
 284 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 285 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 286 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 287
 288 Il y a une incompatibilité introduite dans la dénomination des opérateurs
 289 élémentaires utilisés pour l'opérateur d'observation par script. Les nouveaux
 290 noms requis sont "*DirectOperator*", "*TangentOperator*" et "*AdjointOperator*",
 291 comme décrit dans la quatrième partie du chapitre :ref:`section_reference`. Les
 292 scripts d'opérateur doivent être modifiés.
 293
 294 Passer de la version 6.4 à la 6.5
 295 +++++++++++++++++++++++++++++++++
 296
 297 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 298 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 299 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
 300
 301 Passer de la version 6.3 à la 6.4
 302 +++++++++++++++++++++++++++++++++
 303
 304 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 305 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 306 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.