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