2 Copyright (C) 2008-2018 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 incluses 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. 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.
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
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
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
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
78 Il faut ensuite le rendre exécutable pour l'exécuter.
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::
88 echo -e "\nUsage: $0 <Schéma xml YACS ADAO>\n"
93 if (test ! -e $USERFILE)
95 echo -e "\nErreur : le fichier XML nommé $USERFILE n'existe pas.\n"
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
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::
114 echo -e "\nUsage: $0 <Cas .comm/.py ADAO>\n"
118 F=`basename -s .comm $1`
119 F=`basename -s .py $F`
122 if (test ! -e $USERFILE.py)
124 echo -e "\nErreur : le fichier PY nommé $USERFILE.py n'existe pas.\n"
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
135 Dans tous les cas, les sorties standard et d'erreur se font dans le terminal de
138 Exécuter un schéma de calcul ADAO dans YACS en utilisant le mode "texte" (TUI YACS)
139 -----------------------------------------------------------------------------------
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::
151 #-*- coding: utf-8 -*-
155 SALOMERuntime.RuntimeSALOME_setRuntime()
157 r = pilot.getRuntime()
158 xmlLoader = loader.YACSLoader()
159 xmlLoader.registerProcCataLoader()
161 catalogAd = r.loadCatalog("proc", "<Schéma xml YACS ADAO>")
162 r.addCatalog(catalogAd)
167 p = xmlLoader.load("<Schéma xml YACS ADAO>")
169 print "IO exception:",ex
171 logger = p.getLogger("parser")
172 if not logger.isEmpty():
173 print "The imported file has errors :"
174 print logger.getStr()
177 print "Le schéma n'est pas valide et ne peut pas être exécuté"
178 print p.getErrorReport()
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()
186 e = pilot.ExecutorSwig()
188 if p.getEffectiveState() != pilot.DONE:
189 print p.getErrorReport()
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.
194 .. _section_advanced_R:
196 Exécuter un calcul ADAO en environnement R en utilisant l'interface TUI ADAO
197 ----------------------------------------------------------------------------
200 .. index:: single: rPython
202 Pour étendre les possibilités d'analyse et de traitement, il est possible
203 d'utiliser les calculs ADAO dans l'environnement **R** (voir [R]_ pour plus de
204 détails). Ce dernier est disponible dans SALOME en lançant l'interpréteur R dans
205 le shell "``salome shell``". Il faut de plus disposer, en R, du package
206 "*rPython*", qui peut si nécessaire être installé par l'utilisateur à l'aide de
207 la commande R suivante::
209 #-*- coding: utf-8 -*-
211 # IMPORTANT : à exécuter dans l'interpréteur R
212 # --------------------------------------------
213 install.packages("rPython")
215 On se reportera à la documentation [GilBellosta15]_ pour de plus amples
216 renseignements sur ce package.
218 Les calculs ADAO définis en interface textuelle (API/TUI, voir la
219 :ref:`section_tui`) peuvent alors être interprétés depuis l'environnement R, en
220 utilisant des données et des informations depuis R. La démarche est illustrée
221 sur :ref:`subsection_tui_example`, proposé dans la description de l'interface
222 API/TUI. Dans l'interpréteur R, on peut exécuter les commandes suivantes,
223 directement issues de l'exemple simple::
225 #-*- coding: utf-8 -*-
227 # IMPORTANT : à exécuter dans l'interpréteur R
228 # --------------------------------------------
231 from numpy import array
233 case = adaoBuilder.New()
234 case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
235 case.set( 'Background', Vector=[0, 1, 2] )
236 case.set( 'BackgroundError', ScalarSparseMatrix=1.0 )
237 case.set( 'Observation', Vector=array([0.5, 1.5, 2.5]) )
238 case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
239 case.set( 'ObservationOperator', Matrix='1 0 0;0 2 0;0 0 3' )
240 case.set( 'Observer', Variable='Analysis', Template='ValuePrinter' )
244 dont le résultat est::
246 Analysis [ 0.25000264 0.79999797 0.94999939]
248 Dans la rédaction des calculs ADAO exécutés depuis R, il convient d'être très
249 attentif au bon usage des guillemets simples et doubles, qui ne doivent pas
250 collisionner entre les deux langages.
252 Les données peuvent venir l'environnement R et doivent être rangées dans des
253 variables correctement assignées, pour être utilisées ensuite en Python pour
254 ADAO. On se reportera à la documentation [GilBellosta15]_ pour la mise en
255 oeuvre. On peut transformer l'exemple ci-dessus pour utiliser des données
256 provenant de R pour alimenter les trois variables d'ébauche, d'observation et
257 d'opérateur d'observation. On récupère à la fin l'état optimal dans une variable
258 R aussi. Les autres lignes sont identiques. L'exemple devient ainsi::
260 #-*- coding: utf-8 -*-
262 # IMPORTANT : à exécuter dans l'interpréteur R
263 # --------------------------------------------
268 yo <- c(0.5, 1.5, 2.5)
269 h <- '1 0 0;0 2 0;0 0 3'
274 python.assign( "xb", xb )
275 python.assign( "yo", yo )
276 python.assign( "h", h )
278 from numpy import array
280 case = adaoBuilder.New()
281 case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
282 case.set( 'Background', Vector=xb )
283 case.set( 'BackgroundError', ScalarSparseMatrix=1.0 )
284 case.set( 'Observation', Vector=array(yo) )
285 case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
286 case.set( 'ObservationOperator', Matrix=str(h) )
287 case.set( 'Observer', Variable='Analysis', Template='ValuePrinter' )
289 xa = list(case.get('Analysis')[-1])
294 xa <- python.get("xa")
296 On remarquera les conversions explicite de type ``str`` et ``list`` pour
297 s'assurer que les données sont bien transmises en type standards connus du
298 package "*rPython*". De plus, ce sont les données qui peuvent être transférées
299 entre les deux langages, et pas des fonctions ou méthodes. Il convient donc
300 d'élaborer en Python de manière générique les fonctions d'exécution requises par
301 ADAO, et de leur transmettre ensuite de manière correcte les données disponibles
304 Les cas plus complets, proposés dans les :ref:`subsection_tui_advanced`, peuvent
305 être exécutés de la même manière, et ils donnent le même résultat que dans
306 l'interface API/TUI en Python standard.
308 .. _section_advanced_observer:
310 Obtenir des informations sur des variables spéciales au cours d'un calcul ADAO en YACS
311 --------------------------------------------------------------------------------------
313 .. index:: single: Observer
314 .. index:: single: Observer Template
316 Certaines variables spéciales internes à l'optimisation, utilisées au cours des
317 calculs, peuvent être surveillées durant un calcul ADAO. Ces variables peuvent
318 être affichées, tracées, enregistrées, etc. C'est réalisable en utilisant des
319 "*observer*", qui sont des commandes rassemblées sous forme de scripts, chacun
320 associé à une variable.
322 Des modèles ("templates") sont disponibles lors de l'édition le cas ADAO dans
323 l'éditeur graphique. Ces scripts simples peuvent être adaptés par l'utilisateur,
324 soit dans l'étape d'édition intégrée, ou dans l'étape d'édition avant
325 l'exécution, pour améliorer l'adaptation du calcul ADAO dans le superviseur
326 d'exécution de SALOME.
328 Pour mettre en oeuvre ces "*observer*" de manière efficace, on se reportera aux
329 :ref:`ref_observers_requirements`.
331 Obtenir plus d'information lors du déroulement d'un calcul
332 ----------------------------------------------------------
334 .. index:: single: Logging
336 Lors du déroulement d'un calcul, des données et messages utiles sont
337 disponibles. Il y a deux manières d'obtenir ces informations.
339 La première, et la manière préférentielle, est d'utiliser la variable interne
340 "*Debug*" disponible dans chaque cas ADAO. Elle est atteignable dans l'interface
341 graphique d'édition du module. La mettre à "*1*" permet d'envoyer des messages
342 dans la fenêtre de sortie de l'exécution dans YACS ("*YACS Container Log*").
344 La seconde consiste à utiliser le module Python natif "*logging*" (voir la
345 documentation Python http://docs.python.org/library/logging.html pour de plus
346 amples informations sur ce module). Dans l'ensemble du schéma YACS,
347 principalement à travers les entrées sous forme de scripts, l'utilisateur peut
348 fixer le niveau de logging en accord avec les besoins d'informations détaillées.
349 Les différents niveaux de logging sont : "*DEBUG*", "*INFO*", "*WARNING*",
350 "*ERROR*", "*CRITICAL*". Toutes les informations associées à un niveau sont
351 affichées à tous les niveaux au-dessus de celui-ci (inclut). La méthode la plus
352 facile consiste à changer le niveau de surveillance en utilisant les lignes
356 logging.getLogger().setLevel(logging.DEBUG)
358 Le niveau par défaut standard de surveillance par logging est "*WARNING*", le
359 niveau par défaut dans le module ADAO est "*INFO*".
361 Il est aussi recommandé d'inclure de la surveillance par logging ou des
362 mécanismes de débogage dans le code de simulation, et de les utiliser en
363 conjonction avec les deux méthodes précédentes. Néanmoins, il convient d'être
364 prudent dans le stockage de "grosses" variables car cela coûte du temps,
365 quel que soit le niveau de surveillance choisi (c'est-à-dire même si ces
366 variables ne sont pas affichées).
368 .. _subsection_ref_parallel_df:
370 Accélérer les calculs de dérivées numériques en utilisant un mode parallèle
371 ---------------------------------------------------------------------------
373 .. index:: single: EnableMultiProcessing
374 .. index:: single: NumberOfProcesses
376 Lors de la définition d'un opérateur, comme décrit dans le chapitre des
377 :ref:`section_ref_operator_requirements`, l'utilisateur peut choisir la forme
378 fonctionnelle "*ScriptWithOneFunction*". Cette forme conduit explicitement à
379 approximer les opérateurs tangent et adjoint par un calcul par différences
380 finies. Il requiert de nombreux appels à l'opérateur direct (fonction définie
381 par l'utilisateur), au moins autant de fois que la dimension du vecteur d'état.
382 Ce sont ces appels qui peuvent être potentiellement exécutés en parallèle.
384 Sous certaines conditions, il est alors possible d'accélérer les calculs de
385 dérivées numériques en utilisant un mode parallèle pour l'approximation par
386 différences finies. Lors de la définition d'un cas ADAO, c'est effectué en
387 ajoutant le mot-clé optionnel "*EnableMultiProcessing*", mis à "1", de la
388 commande "*SCRIPTWITHONEFUNCTION*" dans la définition de l'opérateur. Le mode
389 parallèle utilise uniquement des ressources locales (à la fois multi-coeurs ou
390 multi-processeurs) de l'ordinateur sur lequel SALOME est en train de tourner,
391 demandant autant de ressources que disponible. Si nécessaire, on peut réduire
392 les ressources disponibles en limitant le nombre possible de processus
393 parallèles grâce au mot-clé optionnel "*NumberOfProcesses*", que l'on met au
394 maximum souhaité (ou à "0" pour le contrôle automatique, qui est la valeur par
395 défaut). Par défaut, ce mode parallèle est désactivé
396 ("*EnableMultiProcessing=0*").
398 Les principales conditions pour réaliser ces calculs parallèles viennent de la
399 fonction définie par l'utilisateur, qui représente l'opérateur direct. Cette
400 fonction doit au moins être "thread safe" pour être exécutée dans un
401 environnement Python parallèle (notions au-delà du cadre de ce paragraphe). Il
402 n'est pas évident de donner des règles générales, donc il est recommandé, à
403 l'utilisateur qui active ce parallélisme interne, de vérifier soigneusement sa
404 fonction et les résultats obtenus.
406 D'un point de vue utilisateur, certaines conditions, qui doivent être réunies
407 pour mettre en place des calculs parallèles pour les approximations des
408 opérateurs tangent et adjoint, sont les suivantes :
410 #. La dimension du vecteur d'état est supérieure à 2 ou 3.
411 #. Le calcul unitaire de la fonction utilisateur directe "dure un certain temps", c'est-à-dire plus que quelques minutes.
412 #. 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).
413 #. 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.
414 #. 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.
416 Si ces conditions sont satisfaites, l'utilisateur peut choisir d'activer le
417 parallélisme interne pour le calcul des dérivées numériques. Malgré la
418 simplicité d'activation, obtenue en définissant une variable seulement,
419 l'utilisateur est fortement invité à vérifier les résultats de ses calculs. Il
420 faut au moins les effectuer une fois avec le parallélisme activé, et une autre
421 fois avec le parallélisme désactivé, pour comparer les résultats. Si cette mise
422 en oeuvre échoue à un moment ou à un autre, il faut savoir que ce schéma de
423 parallélisme fonctionne pour des codes complexes, comme *Code_Aster* dans
424 *SalomeMeca* [SalomeMeca]_ par exemple. Donc, si cela ne marche pas dans votre
425 cas, vérifiez bien votre fonction d'opérateur avant et pendant l'activation du
430 en cas de doute, il est recommandé de NE PAS ACTIVER ce parallélisme.
432 On rappelle aussi qu'il faut choisir dans YACS un container par défaut de type
433 "*multi*" pour le lancement du schéma, pour permettre une exécution
434 véritablement parallèle.
436 Passer d'une version d'ADAO à une nouvelle
437 ------------------------------------------
439 .. index:: single: Version
441 Le module ADAO et ses fichiers de cas ".comm" sont identifiés par des versions,
442 avec des caractéristiques "Major", "Minor" et "Revision". Une version
443 particulière est numérotée "Major.Minor.Revision", avec un lien fort avec la
444 numérotation de la plateforme SALOME.
446 Chaque version "Major.Minor.Revision" du module ADAO peut lire les fichiers de
447 cas ADAO de la précédente version mineure "Major.Minor-1.*". En général, elle
448 peut aussi lire les fichiers de cas de toutes les versions mineures "Major.*.*"
449 d'une branche majeure, mais ce n'est pas obligatoirement vrai pour toutes les
450 commandes ou tous les mots-clés. En général aussi, un fichier de cas ADAO d'une
451 version ne peut pas être lu par une précédente version mineure ou majeure du
454 Passer de la version 8.x à la 8.y avec x < y
455 ++++++++++++++++++++++++++++++++++++++++++++
457 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
458 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
459 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
461 Pour faciliter les futures évolutions, il est fortement recommandé de veiller à
462 ce que vos fichiers scripts utilisateurs utilisent une syntaxe compatibible avec
463 Python 2 et avec Python 3. En particulier, on recommande d'utiliser la syntaxe
464 fonctionnelle pour les "*print*" et non pas la syntaxe "*commande*", comme par
469 print( "x = %s %s"%(str(x),str(unit)) )
475 print( "x = {0} {1}".format(str(x),str(unit)) )
479 # Python 2 uniquement
483 Passer de la version 7.8 à la 8.1
484 +++++++++++++++++++++++++++++++++
486 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
487 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
488 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
490 Passer de la version 7.x à la 7.y avec x < y
491 ++++++++++++++++++++++++++++++++++++++++++++
493 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
494 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
495 avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
497 Passer de la version 6.6 à la 7.2
498 +++++++++++++++++++++++++++++++++
500 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
501 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
502 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
504 Il y a une incompatibilité introduite dans les fichiers de script de
505 post-processing ou d'observers. L'ancienne syntaxe pour interroger un objet
506 résultat, comme celui d'analyse "*Analysis*" (fourni dans un script à travers le
507 mot-clé "*UserPostAnalysis*"), était par exemple::
509 Analysis = ADD.get("Analysis").valueserie(-1)
510 Analysis = ADD.get("Analysis").valueserie()
512 La nouvelle syntaxe est entièrement compatible avec celle (classique) pour les
513 objets de type liste ou tuple::
515 Analysis = ADD.get("Analysis")[-1]
516 Analysis = ADD.get("Analysis")[:]
518 Les scripts de post-processing doivent être modifiés.
520 Passer de la version 6.x à la 6.y avec x < y
521 ++++++++++++++++++++++++++++++++++++++++++++
523 Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
524 procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
525 le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
527 Il y a une incompatibilité introduite dans les fichiers de script d'opérateur,
528 lors de la dénomination des opérateurs élémentaires utilisés pour l'opérateur
529 d'observation par script. Les nouveaux noms requis sont "*DirectOperator*",
530 "*TangentOperator*" et "*AdjointOperator*", comme décrit dans la quatrième
531 partie du chapitre :ref:`section_reference`. Les fichiers de script d'opérateur
532 doivent être modifiés.