doc/fr/ref_observers_requirements.rst

   1 ..
   2    Copyright (C) 2008-2021 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 Exigences 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 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.
  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. Seul le
 100 corps de la fonction "*observer*" doit être spécifié par l'utilisateur, pas
 101 l'appel 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, 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.
 120
 121 .. warning::
 122     Si les modèles disponibles par défaut ne sont pas utilisés, il revient à
 123     l'utilisateur de faire des scripts de fonctions soigneusement établis ou
 124     des programmes externes qui ne se plantent pas avant d'être enregistrés
 125     comme une fonction "*observer*". Le débogage peut sinon être vraiment
 126     difficile !
 127
 128 On donne ci-après l'identifiant et le contenu de tous les modèles "*observer*"
 129 disponibles.
 130
 131 .. _section_ref_observers_templates:
 132
 133 Inventaire des modèles de fonctions "*observer*" disponibles ("*Template*")
 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 135
 136 .. index:: single: ValuePrinter (Observer)
 137
 138 Modèle **ValuePrinter**
 139 .......................
 140
 141 Imprime sur la sortie standard la valeur courante de la variable.
 142
 143 ::
 144
 145     print(str(info)+" "+str(var[-1]))
 146
 147 .. index:: single: ValueAndIndexPrinter (Observer)
 148
 149 Modèle **ValueAndIndexPrinter**
 150 ...............................
 151
 152 Imprime sur la sortie standard la valeur courante de la variable, en ajoutant son index.
 153
 154 ::
 155
 156     print(str(info)+(" index %i:"%(len(var)-1))+" "+str(var[-1]))
 157
 158 .. index:: single: ValueSeriePrinter (Observer)
 159
 160 Modèle **ValueSeriePrinter**
 161 ............................
 162
 163 Imprime sur la sortie standard la série des valeurs de la variable.
 164
 165 ::
 166
 167     print(str(info)+" "+str(var[:]))
 168
 169 .. index:: single: ValueSaver (Observer)
 170
 171 Modèle **ValueSaver**
 172 .....................
 173
 174 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.
 175
 176 ::
 177
 178     import numpy, re
 179     v=numpy.array(var[-1], ndmin=1)
 180     global istep
 181     try:
 182         istep += 1
 183     except:
 184         istep = 0
 185     f='/tmp/value_%s_%05i.txt'%(info,istep)
 186     f=re.sub('\s','_',f)
 187     print('Value saved in "%s"'%f)
 188     numpy.savetxt(f,v)
 189
 190 .. index:: single: ValueSerieSaver (Observer)
 191
 192 Modèle **ValueSerieSaver**
 193 ..........................
 194
 195 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.
 196
 197 ::
 198
 199     import numpy, re
 200     v=numpy.array(var[:],  ndmin=1)
 201     global istep
 202     try:
 203         istep += 1
 204     except:
 205         istep = 0
 206     f='/tmp/value_%s_%05i.txt'%(info,istep)
 207     f=re.sub('\s','_',f)
 208     print('Value saved in "%s"'%f)
 209     numpy.savetxt(f,v)
 210
 211 .. index:: single: ValuePrinterAndSaver (Observer)
 212
 213 Modèle **ValuePrinterAndSaver**
 214 ...............................
 215
 216 Imprime sur la sortie standard et, en même temps enregistre dans un fichier du répertoire '/tmp', la valeur courante de la variable.
 217
 218 ::
 219
 220     import numpy, re
 221     v=numpy.array(var[-1], ndmin=1)
 222     print(str(info)+" "+str(v))
 223     global istep
 224     try:
 225         istep += 1
 226     except:
 227         istep = 0
 228     f='/tmp/value_%s_%05i.txt'%(info,istep)
 229     f=re.sub('\s','_',f)
 230     print('Value saved in "%s"'%f)
 231     numpy.savetxt(f,v)
 232
 233 .. index:: single: ValueIndexPrinterAndSaver (Observer)
 234
 235 Modèle **ValueIndexPrinterAndSaver**
 236 ....................................
 237
 238 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.
 239
 240 ::
 241
 242     import numpy, re
 243     v=numpy.array(var[-1], ndmin=1)
 244     print(str(info)+(" index %i:"%(len(var)-1))+" "+str(v))
 245     global istep
 246     try:
 247         istep += 1
 248     except:
 249         istep = 0
 250     f='/tmp/value_%s_%05i.txt'%(info,istep)
 251     f=re.sub('\s','_',f)
 252     print('Value saved in "%s"'%f)
 253     numpy.savetxt(f,v)
 254
 255 .. index:: single: ValueSeriePrinterAndSaver (Observer)
 256
 257 Modèle **ValueSeriePrinterAndSaver**
 258 ....................................
 259
 260 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.
 261
 262 ::
 263
 264     import numpy, re
 265     v=numpy.array(var[:],  ndmin=1)
 266     print(str(info)+" "+str(v))
 267     global istep
 268     try:
 269         istep += 1
 270     except:
 271         istep = 0
 272     f='/tmp/value_%s_%05i.txt'%(info,istep)
 273     f=re.sub('\s','_',f)
 274     print('Value saved in "%s"'%f)
 275     numpy.savetxt(f,v)
 276
 277 .. index:: single: ValueGnuPlotter (Observer)
 278
 279 Modèle **ValueGnuPlotter**
 280 ..........................
 281
 282 Affiche graphiquement avec Gnuplot la valeur courante de la variable.
 283
 284 ::
 285
 286     import numpy, Gnuplot
 287     v=numpy.array(var[-1], ndmin=1)
 288     global ifig, gp
 289     try:
 290         ifig += 1
 291         gp(' set style data lines')
 292     except:
 293         ifig = 0
 294         gp = Gnuplot.Gnuplot(persist=1)
 295         gp(' set style data lines')
 296     gp('set title  "%s (Figure %i)"'%(info,ifig))
 297     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 298
 299 .. index:: single: ValueSerieGnuPlotter (Observer)
 300
 301 Modèle **ValueSerieGnuPlotter**
 302 ...............................
 303
 304 Affiche graphiquement avec Gnuplot la série des valeurs de la variable.
 305
 306 ::
 307
 308     import numpy, Gnuplot
 309     v=numpy.array(var[:],  ndmin=1)
 310     global ifig, gp
 311     try:
 312         ifig += 1
 313         gp(' set style data lines')
 314     except:
 315         ifig = 0
 316         gp = Gnuplot.Gnuplot(persist=1)
 317         gp(' set style data lines')
 318     gp('set title  "%s (Figure %i)"'%(info,ifig))
 319     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 320
 321 .. index:: single: ValuePrinterAndGnuPlotter (Observer)
 322
 323 Modèle **ValuePrinterAndGnuPlotter**
 324 ....................................
 325
 326 Imprime sur la sortie standard et, en même temps, affiche graphiquement avec Gnuplot la valeur courante de la variable.
 327
 328 ::
 329
 330     print(str(info)+" "+str(var[-1]))
 331     import numpy, Gnuplot
 332     v=numpy.array(var[-1], ndmin=1)
 333     global ifig,gp
 334     try:
 335         ifig += 1
 336         gp(' set style data lines')
 337     except:
 338         ifig = 0
 339         gp = Gnuplot.Gnuplot(persist=1)
 340         gp(' set style data lines')
 341     gp('set title  "%s (Figure %i)"'%(info,ifig))
 342     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 343
 344 .. index:: single: ValueSeriePrinterAndGnuPlotter (Observer)
 345
 346 Modèle **ValueSeriePrinterAndGnuPlotter**
 347 .........................................
 348
 349 Imprime sur la sortie standard et, en même temps, affiche graphiquement avec Gnuplot la série des valeurs de la variable.
 350
 351 ::
 352
 353     print(str(info)+" "+str(var[:]))
 354     import numpy, Gnuplot
 355     v=numpy.array(var[:],  ndmin=1)
 356     global ifig,gp
 357     try:
 358         ifig += 1
 359         gp(' set style data lines')
 360     except:
 361         ifig = 0
 362         gp = Gnuplot.Gnuplot(persist=1)
 363         gp(' set style data lines')
 364     gp('set title  "%s (Figure %i)"'%(info,ifig))
 365     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 366
 367 .. index:: single: ValuePrinterSaverAndGnuPlotter (Observer)
 368
 369 Modèle **ValuePrinterSaverAndGnuPlotter**
 370 .........................................
 371
 372 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.
 373
 374 ::
 375
 376     print(str(info)+" "+str(var[-1]))
 377     import numpy, re
 378     v=numpy.array(var[-1], ndmin=1)
 379     global istep
 380     try:
 381         istep += 1
 382     except:
 383         istep = 0
 384     f='/tmp/value_%s_%05i.txt'%(info,istep)
 385     f=re.sub('\s','_',f)
 386     print('Value saved in "%s"'%f)
 387     numpy.savetxt(f,v)
 388     import Gnuplot
 389     global ifig,gp
 390     try:
 391         ifig += 1
 392         gp(' set style data lines')
 393     except:
 394         ifig = 0
 395         gp = Gnuplot.Gnuplot(persist=1)
 396         gp(' set style data lines')
 397     gp('set title  "%s (Figure %i)"'%(info,ifig))
 398     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 399
 400 .. index:: single: ValueSeriePrinterSaverAndGnuPlotter (Observer)
 401
 402 Modèle **ValueSeriePrinterSaverAndGnuPlotter**
 403 ..............................................
 404
 405 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.
 406
 407 ::
 408
 409     print(str(info)+" "+str(var[:]))
 410     import numpy, re
 411     v=numpy.array(var[:],  ndmin=1)
 412     global istep
 413     try:
 414         istep += 1
 415     except:
 416         istep = 0
 417     f='/tmp/value_%s_%05i.txt'%(info,istep)
 418     f=re.sub('\s','_',f)
 419     print('Value saved in "%s"'%f)
 420     numpy.savetxt(f,v)
 421     import Gnuplot
 422     global ifig,gp
 423     try:
 424         ifig += 1
 425         gp(' set style data lines')
 426     except:
 427         ifig = 0
 428         gp = Gnuplot.Gnuplot(persist=1)
 429         gp(' set style data lines')
 430     gp('set title  "%s (Figure %i)"'%(info,ifig))
 431     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 432
 433 .. index:: single: ValueMean (Observer)
 434
 435 Modèle **ValueMean**
 436 ....................
 437
 438 Imprime sur la sortie standard la moyenne de la valeur courante de la variable.
 439
 440 ::
 441
 442     import numpy
 443     print(str(info)+" "+str(numpy.nanmean(var[-1])))
 444
 445 .. index:: single: ValueStandardError (Observer)
 446
 447 Modèle **ValueStandardError**
 448 .............................
 449
 450 Imprime sur la sortie standard l'écart-type de la valeur courante de la variable.
 451
 452 ::
 453
 454     import numpy
 455     print(str(info)+" "+str(numpy.nanstd(var[-1])))
 456
 457 .. index:: single: ValueVariance (Observer)
 458
 459 Modèle **ValueVariance**
 460 ........................
 461
 462 Imprime sur la sortie standard la variance de la valeur courante de la variable.
 463
 464 ::
 465
 466     import numpy
 467     print(str(info)+" "+str(numpy.nanvar(var[-1])))
 468
 469 .. index:: single: ValueL2Norm (Observer)
 470
 471 Modèle **ValueL2Norm**
 472 ......................
 473
 474 Imprime sur la sortie standard la norme L2 de la valeur courante de la variable.
 475
 476 ::
 477
 478     import numpy
 479     v = numpy.ravel( var[-1] )
 480     print(str(info)+" "+str(float( numpy.linalg.norm(v) )))
 481
 482 .. index:: single: ValueRMS (Observer)
 483
 484 Modèle **ValueRMS**
 485 ...................
 486
 487 Imprime sur la sortie standard la racine de la moyenne des carrés (RMS), ou moyenne quadratique, de la valeur courante de la variable.
 488
 489 ::
 490
 491     import numpy
 492     v = numpy.ravel( var[-1] )
 493     print(str(info)+" "+str(float( numpy.sqrt((1./v.size)*numpy.dot(v,v)) )))