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