2 Copyright (C) 2008-2021 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
24 .. _section_ref_observers_requirements:
26 Exigences pour les fonctions décrivant un "*observer*"
27 ------------------------------------------------------
29 .. index:: single: Observer
30 .. index:: single: setObserver
31 .. index:: single: Observer Template
33 Certaines variables spéciales, internes à l'optimisation et utilisées au cours
34 des calculs, peuvent être surveillées durant un calcul ADAO. Ces variables
35 peuvent être affichées, tracées, enregistrées, etc. par l'utilisateur. C'est
36 réalisable en utilisant des "*observer*", parfois aussi appelés des "callback"
37 sur une variable. Ce sont des fonctions Python spéciales, qui sont chacune
38 associées à une variable donnée, comme décrit conceptuellement dans la figure
41 .. ref_observer_simple:
42 .. image:: images/ref_observer_simple.png
46 **Définition conceptuelle d'une fonction "observer"**
48 Ces fonctions "*observer*" sont décrites dans les sous-sections suivantes.
50 Enregistrer et activer une fonction "*observer*"
51 ++++++++++++++++++++++++++++++++++++++++++++++++
53 Dans l'interface graphique EFICAS d'ADAO, il y a 3 méthodes pratiques pour
54 intégrer une fonction "*observer*" dans un cas ADAO. La méthode est choisie à
55 l'aide du mot-clé "*NodeType*" de chaque entrée de type "*observer*", comme
56 montré dans la figure qui suit :
58 .. eficas_observer_nodetype:
59 .. image:: images/eficas_observer_nodetype.png
63 **Choisir son type d'entrée pour une fonction "observer"**
65 Une fonction "*observer*" peut être fourni sous la forme d'un script explicite
66 (entrée de type "*String*"), d'un script contenu dans un fichier externe
67 (entrée de type "*Script*"), ou en utilisant un modèle (entrée de type
68 "*Template*"). Les modèles sont fournis par défaut dans ADAO lors de l'usage de
69 l'éditeur graphique EFICAS d'ADAO ou de l'interface TUI, et sont détaillés dans
70 la partie :ref:`section_ref_observers_templates` qui suit. Ces derniers sont
71 des scripts simples qui peuvent être adaptés par l'utilisateur, soit dans
72 l'étape d'édition intégrée du cas avec EFICAS d'ADAO, soit dans l'étape
73 d'édition du schéma avant l'exécution, pour améliorer la performance du calcul
74 ADAO dans le superviseur d'exécution de SALOME.
76 Dans l'interface textuelle (TUI) d'ADAO (voir la partie :ref:`section_tui`),
77 les mêmes informations peuvent être données à l'aide de la commande
78 "*setObserver*" appliquée pour une variable donnée indiquée en utilisant
79 l'argument "*Variable*". Les autres arguments de cette commande permettent de
80 définir un "*observer*" soit comme un modèle (argument "*Template*") désignant
81 l'un des scripts détaillés dans la partie
82 :ref:`section_ref_observers_templates`, soit comme un script explicite
83 (argument "*String*"), soit comme un script contenu dans un fichier externe
84 (argument "*Script*").
86 Forme générale d'un script permettant de définir une fonction "*observer*"
87 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
89 Une fonction "*observer*" est un script Python spécial, associé à une variable
90 donnée, et qui est automatiquement activée à chaque modification de la variable
91 lors du calcul. Chaque fonction (soigneusement établie) qui s'applique à la
92 variable sélectionnée peut être utilisée. De nombreuses fonctions "*observer*"
93 sont disponibles par défaut.
95 Pour pouvoir utiliser directement cette capacité "*observer*", l'utilisateur
96 doit utiliser ou construire un script utilisant en entrée standard (i.e.
97 disponible dans l'espace de nommage) les variables ``var`` et ``info``. La
98 variable ``var`` est à utiliser comme un objet de type liste/tuple, contenant
99 l'historique de la variable d'intérêt, indicé par les pas d'itérations. Seul le
100 corps de la fonction "*observer*" doit être spécifié par l'utilisateur, pas
101 l'appel de fonction lui-même.
103 A titre d'exemple, voici un script très simple (similaire au modèle
104 "*ValuePrinter*"), utilisable pour afficher la valeur d'une variable
108 print(" --->",info," Value =",var[-1])
110 Stockées comme un fichier Python ou une chaîne de caractères explicite, ces
111 lignes de script peuvent être associées à chaque variable présente dans le
112 mot-clé "*SELECTION*" de la commande "*Observers*" du cas ADAO : "*Analysis*",
113 "*CurrentState*", "*CostFunction*"... La valeur courante de la variable sera
114 par exemple affichée à chaque étape de l'algorithme d'optimisation ou
115 d'assimilation. Les "*observer*" peuvent inclure des capacités d'affichage
116 graphique, de stockage, de traitement complexe, d'analyse statistique, etc. Si
117 une variable, à laquelle est lié un "*observer*", n'est pas requise dans le
118 calcul et par l'utilisateur, l'exécution de cet "*observer*" n'est tout
119 simplement jamais activée.
123 Si les modèles disponibles par défaut ne sont pas utilisés, il revient à
124 l'utilisateur de faire des scripts de fonctions soigneusement établis ou
125 des programmes externes qui ne se plantent pas avant d'être enregistrés
126 comme une fonction "*observer*". Le débogage peut sinon être vraiment
129 On donne ci-après l'identifiant et le contenu de tous les modèles "*observer*"
132 .. _section_ref_observers_templates:
134 Inventaire des modèles de fonctions "*observer*" disponibles ("*Template*")
135 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
137 .. index:: single: ValuePrinter (Observer)
139 Modèle **ValuePrinter**
140 .......................
142 Imprime sur la sortie standard la valeur courante de la variable.
146 print(str(info)+" "+str(var[-1]))
148 .. index:: single: ValueAndIndexPrinter (Observer)
150 Modèle **ValueAndIndexPrinter**
151 ...............................
153 Imprime sur la sortie standard la valeur courante de la variable, en ajoutant son index.
157 print(str(info)+(" index %i:"%(len(var)-1))+" "+str(var[-1]))
159 .. index:: single: ValueSeriePrinter (Observer)
161 Modèle **ValueSeriePrinter**
162 ............................
164 Imprime sur la sortie standard la série des valeurs de la variable.
168 print(str(info)+" "+str(var[:]))
170 .. index:: single: ValueSaver (Observer)
172 Modèle **ValueSaver**
173 .....................
175 Enregistre la valeur courante de la variable dans un fichier du répertoire '/tmp' nommé 'value...txt' selon le nom de la variable et l'étape d'enregistrement.
180 v=numpy.array(var[-1], ndmin=1)
186 f='/tmp/value_%s_%05i.txt'%(info,istep)
188 print('Value saved in "%s"'%f)
191 .. index:: single: ValueSerieSaver (Observer)
193 Modèle **ValueSerieSaver**
194 ..........................
196 Enregistre la série des valeurs de la variable dans un fichier du répertoire '/tmp' nommé 'value...txt' selon le nom de la variable et l'étape.
201 v=numpy.array(var[:], ndmin=1)
207 f='/tmp/value_%s_%05i.txt'%(info,istep)
209 print('Value saved in "%s"'%f)
212 .. index:: single: ValuePrinterAndSaver (Observer)
214 Modèle **ValuePrinterAndSaver**
215 ...............................
217 Imprime sur la sortie standard et, en même temps enregistre dans un fichier du répertoire '/tmp', la valeur courante de la variable.
222 v=numpy.array(var[-1], ndmin=1)
223 print(str(info)+" "+str(v))
229 f='/tmp/value_%s_%05i.txt'%(info,istep)
231 print('Value saved in "%s"'%f)
234 .. index:: single: ValueIndexPrinterAndSaver (Observer)
236 Modèle **ValueIndexPrinterAndSaver**
237 ....................................
239 Imprime sur la sortie standard et, en même temps enregistre dans un fichier du répertoire '/tmp', la valeur courante de la variable, en ajoutant son index.
244 v=numpy.array(var[-1], ndmin=1)
245 print(str(info)+(" index %i:"%(len(var)-1))+" "+str(v))
251 f='/tmp/value_%s_%05i.txt'%(info,istep)
253 print('Value saved in "%s"'%f)
256 .. index:: single: ValueSeriePrinterAndSaver (Observer)
258 Modèle **ValueSeriePrinterAndSaver**
259 ....................................
261 Imprime sur la sortie standard et, en même temps, enregistre dans un fichier du répertoire '/tmp', la série des valeurs de la variable.
266 v=numpy.array(var[:], ndmin=1)
267 print(str(info)+" "+str(v))
273 f='/tmp/value_%s_%05i.txt'%(info,istep)
275 print('Value saved in "%s"'%f)
278 .. index:: single: ValueGnuPlotter (Observer)
280 Modèle **ValueGnuPlotter**
281 ..........................
283 Affiche graphiquement avec Gnuplot la valeur courante de la variable.
287 import numpy, Gnuplot
288 v=numpy.array(var[-1], ndmin=1)
292 gp(' set style data lines')
295 gp = Gnuplot.Gnuplot(persist=1)
296 gp(' set style data lines')
297 gp('set title "%s (Figure %i)"'%(info,ifig))
298 gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
300 .. index:: single: ValueSerieGnuPlotter (Observer)
302 Modèle **ValueSerieGnuPlotter**
303 ...............................
305 Affiche graphiquement avec Gnuplot la série des valeurs de la variable.
309 import numpy, Gnuplot
310 v=numpy.array(var[:], ndmin=1)
314 gp(' set style data lines')
317 gp = Gnuplot.Gnuplot(persist=1)
318 gp(' set style data lines')
319 gp('set title "%s (Figure %i)"'%(info,ifig))
320 gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
322 .. index:: single: ValuePrinterAndGnuPlotter (Observer)
324 Modèle **ValuePrinterAndGnuPlotter**
325 ....................................
327 Imprime sur la sortie standard et, en même temps, affiche graphiquement avec Gnuplot la valeur courante de la variable.
331 print(str(info)+" "+str(var[-1]))
332 import numpy, Gnuplot
333 v=numpy.array(var[-1], ndmin=1)
337 gp(' set style data lines')
340 gp = Gnuplot.Gnuplot(persist=1)
341 gp(' set style data lines')
342 gp('set title "%s (Figure %i)"'%(info,ifig))
343 gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
345 .. index:: single: ValueSeriePrinterAndGnuPlotter (Observer)
347 Modèle **ValueSeriePrinterAndGnuPlotter**
348 .........................................
350 Imprime sur la sortie standard et, en même temps, affiche graphiquement avec Gnuplot la série des valeurs de la variable.
354 print(str(info)+" "+str(var[:]))
355 import numpy, Gnuplot
356 v=numpy.array(var[:], ndmin=1)
360 gp(' set style data lines')
363 gp = Gnuplot.Gnuplot(persist=1)
364 gp(' set style data lines')
365 gp('set title "%s (Figure %i)"'%(info,ifig))
366 gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
368 .. index:: single: ValuePrinterSaverAndGnuPlotter (Observer)
370 Modèle **ValuePrinterSaverAndGnuPlotter**
371 .........................................
373 Imprime sur la sortie standard et, en même temps, enregistre dans un fichier du répertoire '/tmp' et affiche graphiquement la valeur courante de la variable.
377 print(str(info)+" "+str(var[-1]))
379 v=numpy.array(var[-1], ndmin=1)
385 f='/tmp/value_%s_%05i.txt'%(info,istep)
387 print('Value saved in "%s"'%f)
393 gp(' set style data lines')
396 gp = Gnuplot.Gnuplot(persist=1)
397 gp(' set style data lines')
398 gp('set title "%s (Figure %i)"'%(info,ifig))
399 gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
401 .. index:: single: ValueSeriePrinterSaverAndGnuPlotter (Observer)
403 Modèle **ValueSeriePrinterSaverAndGnuPlotter**
404 ..............................................
406 Imprime sur la sortie standard et, en même temps, enregistre dans un fichier du répertoire '/tmp' et affiche graphiquement la série des valeurs de la variable.
410 print(str(info)+" "+str(var[:]))
412 v=numpy.array(var[:], ndmin=1)
418 f='/tmp/value_%s_%05i.txt'%(info,istep)
420 print('Value saved in "%s"'%f)
426 gp(' set style data lines')
429 gp = Gnuplot.Gnuplot(persist=1)
430 gp(' set style data lines')
431 gp('set title "%s (Figure %i)"'%(info,ifig))
432 gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
434 .. index:: single: ValueMean (Observer)
439 Imprime sur la sortie standard la moyenne de la valeur courante de la variable.
444 print(str(info)+" "+str(numpy.nanmean(var[-1])))
446 .. index:: single: ValueStandardError (Observer)
448 Modèle **ValueStandardError**
449 .............................
451 Imprime sur la sortie standard l'écart-type de la valeur courante de la variable.
456 print(str(info)+" "+str(numpy.nanstd(var[-1])))
458 .. index:: single: ValueVariance (Observer)
460 Modèle **ValueVariance**
461 ........................
463 Imprime sur la sortie standard la variance de la valeur courante de la variable.
468 print(str(info)+" "+str(numpy.nanvar(var[-1])))
470 .. index:: single: ValueL2Norm (Observer)
472 Modèle **ValueL2Norm**
473 ......................
475 Imprime sur la sortie standard la norme L2 de la valeur courante de la variable.
480 v = numpy.ravel( var[-1] )
481 print(str(info)+" "+str(float( numpy.linalg.norm(v) )))
483 .. index:: single: ValueRMS (Observer)
488 Imprime sur la sortie standard la racine de la moyenne des carrés (RMS), ou moyenne quadratique, de la valeur courante de la variable.
493 v = numpy.ravel( var[-1] )
494 print(str(info)+" "+str(float( numpy.sqrt((1./v.size)*numpy.dot(v,v)) )))