doc/fr/ref_observers_requirements.rst

   1 ..
   2    Copyright (C) 2008-2022 EDF R&D
   3
   4    This file is part of SALOME ADAO module.
   5
   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.
  10
  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.
  15
  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
  19
  20    See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21
  22    Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
  23
  24 .. _section_ref_observers_requirements:
  25
  26 Conditions requises pour les fonctions décrivant un "*observer*"
  27 ----------------------------------------------------------------
  28
  29 .. index:: single: Observer
  30 .. index:: single: setObserver
  31 .. index:: single: Observer Template
  32
  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
  39 suivante :
  40
  41   .. ref_observer_simple:
  42   .. image:: images/ref_observer_simple.png
  43     :align: center
  44     :width: 75%
  45   .. centered::
  46     **Définition conceptuelle d'une fonction "observer"**
  47
  48 Ces fonctions "*observer*" sont décrites dans les sous-sections suivantes.
  49
  50 Enregistrer et activer une fonction "*observer*"
  51 ++++++++++++++++++++++++++++++++++++++++++++++++
  52
  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 :
  57
  58   .. eficas_observer_nodetype:
  59   .. image:: images/eficas_observer_nodetype.png
  60     :align: center
  61     :width: 100%
  62   .. centered::
  63     **Choisir son type d'entrée pour une fonction "observer"**
  64
  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
  69 de l'éditeur graphique EFICAS d'ADAO ou de l'interface TUI, et sont détaillés
  70 dans la partie :ref:`section_ref_observers_templates` qui suit. Ces derniers
  71 sont 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.
  75
  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*").
  85
  86 Forme générale d'un script permettant de définir une fonction "*observer*"
  87 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  88
  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.
  94
  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 et/ou de
 100 temps. Seul le corps de la fonction "*observer*" doit être spécifié par
 101 l'utilisateur, pas l'appel Python ``def`` de fonction lui-même.
 102
 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
 105 surveillée :
 106 ::
 107
 108     print("    --->",info," Value =",var[-1])
 109
 110 Stockées comme un fichier Python ou une chaîne de caractères explicite, cette
 111 ou ces lignes de script peuvent être associées à chaque variable présente dans
 112 le mot-clé "*SELECTION*" de la commande "*Observers*" du cas ADAO :
 113 "*Analysis*", "*CurrentState*", "*CostFunction*"... La valeur courante de la
 114 variable sera par exemple affichée à chaque étape de l'algorithme
 115 d'optimisation ou d'assimilation. Les "*observer*" peuvent inclure des
 116 capacités d'affichage graphique, de stockage, de traitement complexe, d'analyse
 117 statistique, etc. Si une variable, à laquelle est lié un "*observer*", n'est
 118 pas requise dans le calcul et par l'utilisateur, l'exécution de cet
 119 "*observer*" n'est tout simplement jamais activée.
 120
 121 .. warning::
 122
 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
 127     difficile !
 128
 129 Certains "*observer*" permettent de créer des fichiers ou des figures
 130 successives, qui sont numérotées de manière unique et, le cas échéant,
 131 enregistrées par défaut dans le répertoire standard ``/tmp``. Dans le cas où
 132 ces informations sont à modifier (comme par exemple lorsque le répertoire
 133 ``/tmp`` est un dossier virtuel ou local non pérenne, ou lorsque l'on désire
 134 une numérotation en fonction de l'itération), l'utilisateur est invité à
 135 s'inspirer d'un modèle lui convenant pour le modifier en spécifiant
 136 différemment ces informations communes. Ensuite, la fonction modifiée peut être
 137 utilisée dans une entrée de type "*String*" ou de type "*Script*".
 138
 139 On donne ci-après l'identifiant et le contenu de tous les modèles "*observer*"
 140 disponibles.
 141
 142 .. _section_ref_observers_templates:
 143
 144 Inventaire des modèles de fonctions "*observer*" disponibles ("*Template*")
 145 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 146
 147 .. index:: single: ValuePrinter (Observer)
 148
 149 Modèle **ValuePrinter**
 150 .......................
 151
 152 Imprime sur la sortie standard la valeur courante de la variable.
 153
 154 ::
 155
 156     print(str(info)+" "+str(var[-1]))
 157
 158 .. index:: single: ValueAndIndexPrinter (Observer)
 159
 160 Modèle **ValueAndIndexPrinter**
 161 ...............................
 162
 163 Imprime sur la sortie standard la valeur courante de la variable, en ajoutant son index.
 164
 165 ::
 166
 167     print(str(info)+(" index %i:"%(len(var)-1))+" "+str(var[-1]))
 168
 169 .. index:: single: ValueSeriePrinter (Observer)
 170
 171 Modèle **ValueSeriePrinter**
 172 ............................
 173
 174 Imprime sur la sortie standard la série des valeurs de la variable.
 175
 176 ::
 177
 178     print(str(info)+" "+str(var[:]))
 179
 180 .. index:: single: ValueSaver (Observer)
 181
 182 Modèle **ValueSaver**
 183 .....................
 184
 185 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.
 186
 187 ::
 188
 189     import numpy, re
 190     v=numpy.array(var[-1], ndmin=1)
 191     global istep
 192     try:
 193         istep+=1
 194     except:
 195         istep=0
 196     f='/tmp/value_%s_%05i.txt'%(info,istep)
 197     f=re.sub('\s','_',f)
 198     print('Value saved in "%s"'%f)
 199     numpy.savetxt(f,v)
 200
 201 .. index:: single: ValueSerieSaver (Observer)
 202
 203 Modèle **ValueSerieSaver**
 204 ..........................
 205
 206 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.
 207
 208 ::
 209
 210     import numpy, re
 211     v=numpy.array(var[:], ndmin=1)
 212     global istep
 213     try:
 214         istep+=1
 215     except:
 216         istep=0
 217     f='/tmp/value_%s_%05i.txt'%(info,istep)
 218     f=re.sub('\s','_',f)
 219     print('Value saved in "%s"'%f)
 220     numpy.savetxt(f,v)
 221
 222 .. index:: single: ValuePrinterAndSaver (Observer)
 223
 224 Modèle **ValuePrinterAndSaver**
 225 ...............................
 226
 227 Imprime sur la sortie standard et, en même temps enregistre dans un fichier du répertoire '/tmp', la valeur courante de la variable.
 228
 229 ::
 230
 231     import numpy, re
 232     v=numpy.array(var[-1], ndmin=1)
 233     print(str(info)+" "+str(v))
 234     global istep
 235     try:
 236         istep+=1
 237     except:
 238         istep=0
 239     f='/tmp/value_%s_%05i.txt'%(info,istep)
 240     f=re.sub('\s','_',f)
 241     print('Value saved in "%s"'%f)
 242     numpy.savetxt(f,v)
 243
 244 .. index:: single: ValueIndexPrinterAndSaver (Observer)
 245
 246 Modèle **ValueIndexPrinterAndSaver**
 247 ....................................
 248
 249 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.
 250
 251 ::
 252
 253     import numpy, re
 254     v=numpy.array(var[-1], ndmin=1)
 255     print(str(info)+(" index %i:"%(len(var)-1))+" "+str(v))
 256     global istep
 257     try:
 258         istep+=1
 259     except:
 260         istep=0
 261     f='/tmp/value_%s_%05i.txt'%(info,istep)
 262     f=re.sub('\s','_',f)
 263     print('Value saved in "%s"'%f)
 264     numpy.savetxt(f,v)
 265
 266 .. index:: single: ValueSeriePrinterAndSaver (Observer)
 267
 268 Modèle **ValueSeriePrinterAndSaver**
 269 ....................................
 270
 271 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.
 272
 273 ::
 274
 275     import numpy, re
 276     v=numpy.array(var[:], ndmin=1)
 277     print(str(info)+" "+str(v))
 278     global istep
 279     try:
 280         istep+=1
 281     except:
 282         istep=0
 283     f='/tmp/value_%s_%05i.txt'%(info,istep)
 284     f=re.sub('\s','_',f)
 285     print('Value saved in "%s"'%f)
 286     numpy.savetxt(f,v)
 287
 288 .. index:: single: ValueGnuPlotter (Observer)
 289
 290 Modèle **ValueGnuPlotter**
 291 ..........................
 292
 293 Affiche graphiquement avec Gnuplot la valeur courante de la variable.
 294
 295 ::
 296
 297     import numpy, Gnuplot
 298     v=numpy.array(var[-1], ndmin=1)
 299     global ifig, gp
 300     try:
 301         ifig+=1
 302         gp('set style data lines')
 303     except:
 304         ifig=0
 305         gp=Gnuplot.Gnuplot(persist=1)
 306         gp('set style data lines')
 307     gp('set title "%s (Figure %i)"'%(info,ifig))
 308     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 309
 310 .. index:: single: ValueSerieGnuPlotter (Observer)
 311
 312 Modèle **ValueSerieGnuPlotter**
 313 ...............................
 314
 315 Affiche graphiquement avec Gnuplot la série des valeurs de la variable.
 316
 317 ::
 318
 319     import numpy, Gnuplot
 320     v=numpy.array(var[:], ndmin=1)
 321     global ifig, gp
 322     try:
 323         ifig+=1
 324         gp('set style data lines')
 325     except:
 326         ifig=0
 327         gp=Gnuplot.Gnuplot(persist=1)
 328         gp('set style data lines')
 329     gp('set title "%s (Figure %i)"'%(info,ifig))
 330     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 331
 332 .. index:: single: ValuePrinterAndGnuPlotter (Observer)
 333
 334 Modèle **ValuePrinterAndGnuPlotter**
 335 ....................................
 336
 337 Imprime sur la sortie standard et, en même temps, affiche graphiquement avec Gnuplot la valeur courante de la variable.
 338
 339 ::
 340
 341     print(str(info)+' '+str(var[-1]))
 342     import numpy, Gnuplot
 343     v=numpy.array(var[-1], ndmin=1)
 344     global ifig,gp
 345     try:
 346         ifig+=1
 347         gp('set style data lines')
 348     except:
 349         ifig=0
 350         gp=Gnuplot.Gnuplot(persist=1)
 351         gp('set style data lines')
 352     gp('set title "%s (Figure %i)"'%(info,ifig))
 353     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 354
 355 .. index:: single: ValueSeriePrinterAndGnuPlotter (Observer)
 356
 357 Modèle **ValueSeriePrinterAndGnuPlotter**
 358 .........................................
 359
 360 Imprime sur la sortie standard et, en même temps, affiche graphiquement avec Gnuplot la série des valeurs de la variable.
 361
 362 ::
 363
 364     print(str(info)+' '+str(var[:]))
 365     import numpy, Gnuplot
 366     v=numpy.array(var[:], ndmin=1)
 367     global ifig,gp
 368     try:
 369         ifig+=1
 370         gp('set style data lines')
 371     except:
 372         ifig=0
 373         gp=Gnuplot.Gnuplot(persist=1)
 374         gp('set style data lines')
 375     gp('set title "%s (Figure %i)"'%(info,ifig))
 376     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 377
 378 .. index:: single: ValuePrinterSaverAndGnuPlotter (Observer)
 379
 380 Modèle **ValuePrinterSaverAndGnuPlotter**
 381 .........................................
 382
 383 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.
 384
 385 ::
 386
 387     print(str(info)+' '+str(var[-1]))
 388     import numpy, re
 389     v=numpy.array(var[-1], ndmin=1)
 390     global istep
 391     try:
 392         istep+=1
 393     except:
 394         istep=0
 395     f='/tmp/value_%s_%05i.txt'%(info,istep)
 396     f=re.sub('\s','_',f)
 397     print('Value saved in "%s"'%f)
 398     numpy.savetxt(f,v)
 399     import Gnuplot
 400     global ifig,gp
 401     try:
 402         ifig+=1
 403         gp('set style data lines')
 404     except:
 405         ifig=0
 406         gp=Gnuplot.Gnuplot(persist=1)
 407         gp('set style data lines')
 408     gp('set title "%s (Figure %i)"'%(info,ifig))
 409     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 410
 411 .. index:: single: ValueSeriePrinterSaverAndGnuPlotter (Observer)
 412
 413 Modèle **ValueSeriePrinterSaverAndGnuPlotter**
 414 ..............................................
 415
 416 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.
 417
 418 ::
 419
 420     print(str(info)+' '+str(var[:]))
 421     import numpy, re
 422     v=numpy.array(var[:], ndmin=1)
 423     global istep
 424     try:
 425         istep+=1
 426     except:
 427         istep=0
 428     f='/tmp/value_%s_%05i.txt'%(info,istep)
 429     f=re.sub('\s','_',f)
 430     print('Value saved in "%s"'%f)
 431     numpy.savetxt(f,v)
 432     import Gnuplot
 433     global ifig,gp
 434     try:
 435         ifig+=1
 436         gp('set style data lines')
 437     except:
 438         ifig=0
 439         gp=Gnuplot.Gnuplot(persist=1)
 440         gp('set style data lines')
 441     gp('set title "%s (Figure %i)"'%(info,ifig))
 442     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 443
 444 .. index:: single: ValueMean (Observer)
 445
 446 Modèle **ValueMean**
 447 ....................
 448
 449 Imprime sur la sortie standard la moyenne de la valeur courante de la variable.
 450
 451 ::
 452
 453     import numpy
 454     print(str(info)+' '+str(numpy.nanmean(var[-1])))
 455
 456 .. index:: single: ValueStandardError (Observer)
 457
 458 Modèle **ValueStandardError**
 459 .............................
 460
 461 Imprime sur la sortie standard l'écart-type de la valeur courante de la variable.
 462
 463 ::
 464
 465     import numpy
 466     print(str(info)+' '+str(numpy.nanstd(var[-1])))
 467
 468 .. index:: single: ValueVariance (Observer)
 469
 470 Modèle **ValueVariance**
 471 ........................
 472
 473 Imprime sur la sortie standard la variance de la valeur courante de la variable.
 474
 475 ::
 476
 477     import numpy
 478     print(str(info)+' '+str(numpy.nanvar(var[-1])))
 479
 480 .. index:: single: ValueL2Norm (Observer)
 481
 482 Modèle **ValueL2Norm**
 483 ......................
 484
 485 Imprime sur la sortie standard la norme L2 de la valeur courante de la variable.
 486
 487 ::
 488
 489     import numpy
 490     v = numpy.ravel( var[-1] )
 491     print(str(info)+' '+str(float( numpy.linalg.norm(v) )))
 492
 493 .. index:: single: ValueRMS (Observer)
 494
 495 Modèle **ValueRMS**
 496 ...................
 497
 498 Imprime sur la sortie standard la racine de la moyenne des carrés (RMS), ou moyenne quadratique, de la valeur courante de la variable.
 499
 500 ::
 501
 502     import numpy
 503     v = numpy.ravel( var[-1] )
 504     print(str(info)+' '+str(float( numpy.sqrt((1./v.size)*numpy.dot(v,v)) )))