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 des difficultés obscures::
  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 pour 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 coute 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 Passer d'une version d'ADAO à une nouvelle
 178 ------------------------------------------
 179
 180 Le module ADAO et ses fichiers de cas ".comm" sont identifiés par des versions,
 181 avec des caractéristiques "Major", "Minor" et "Revision". Une version
 182 particulière est numérotée "Major.Minor.Revision", avec un lien fort avec la
 183 numérotation de la plateforme SALOME.
 184
 185 Chaque version "Major.Minor.Revision" du module ADAO peut lire les fichiers de
 186 cas ADAO de la précédente version mineure "Major.Minor-1.*". En général, elle
 187 peut aussi lire les fichiers de cas de toutes les versions mineures "Major.*.*"
 188 d'une branche majeure, mais ce n'est pas obligatoirement vrai pour toutes les
 189 commandes ou tous les mots-clés. En général aussi, un fichier de cas ADAO d'une
 190 version ne peut pas être lu par une précédente version mineure ou majeure du
 191 module ADAO.
 192
 193 Passer de la version 6.6 à la 7.2
 194 +++++++++++++++++++++++++++++++++
 195
 196 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 197 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 198 le nouveau module SALOME/ADAO, et de l'enregistrer avec un nouveau nom.
 199
 200 Il y a une incompatibilité introduite dans les fichiers de script de
 201 post-processing ou d'observers. L'ancienne syntaxe pour interroger un objet
 202 résultat, comme celui d'analyse "*Analysis*" (fourni dans un script à travers le
 203 mot-clé "*UserPostAnalysis*"), était par exemple::
 204
 205     Analysis = ADD.get("Analysis").valueserie(-1)
 206     Analysis = ADD.get("Analysis").valueserie()
 207
 208 La nouvelle syntaxe est entièrement compatible avec celle (classique) pour les
 209 objets de type liste ou tuple::
 210
 211     Analysis = ADD.get("Analysis")[-1]
 212     Analysis = ADD.get("Analysis")[:]
 213
 214 Les scripts de post-processing doivent être modifiés.
 215
 216 Passer de la version 6.5 à la 6.6
 217 +++++++++++++++++++++++++++++++++
 218
 219 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 220 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 221 le nouveau module SALOME/ADAO, et de l'enregistrer avec un nouveau nom.
 222
 223 Il y a une incompatibilité introduite dans la dénomination des opérateurs
 224 élémentaires utilisés pour l'opérateur d'observation par script. Les nouveaux
 225 noms requis sont "*DirectOperator*", "*TangentOperator*" et "*AdjointOperator*",
 226 comme décrit dans la quatrième partie du chapitre :ref:`section_reference`. Les
 227 scripts d'opérateur doivent être modifiés.
 228
 229 Passer de la version 6.4 à la 6.5
 230 +++++++++++++++++++++++++++++++++
 231
 232 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 233 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 234 le nouveau module SALOME/ADAO, et de l'enregistrer avec un nouveau nom.
 235
 236 Passer de la version 6.3 à la 6.4
 237 +++++++++++++++++++++++++++++++++
 238
 239 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
 240 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
 241 le nouveau module SALOME/ADAO, et de l'enregistrer avec un nouveau nom.