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