doc/fr/ref_observers_requirements.rst

   1 ..
   2    Copyright (C) 2008-2019 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 Ce sont des scripts Python, qui sont chacun associés à une variable donnée, et
  38 qui sont automatiquement activés à chaque modification de la variable.
  39
  40 Dans l'interface graphique EFICAS d'ADAO, il y a 3 méthodes pratiques pour
  41 intégrer un "*observer*" dans un cas ADAO. La méthode est choisie à l'aide du
  42 mot-clé "*NodeType*" de chaque entrée de type "*observer*", comme montré dans
  43 la figure qui suit :
  44
  45   .. eficas_observer_nodetype:
  46   .. image:: images/eficas_observer_nodetype.png
  47     :align: center
  48     :width: 100%
  49   .. centered::
  50     **Choisir pour un "*observer*" son type d'entrée**
  51
  52 L'"*observer*" peut être fourni sous la forme d'un script explicite (entrée de
  53 type "*String*"), d'un script contenu dans un fichier externe (entrée de type
  54 "*Script*"), ou en utilisant un modèle (entrée de type "*Template*") fourni par
  55 défaut dans ADAO lors de l'usage de l'éditeur graphique EFICAS et détaillé dans
  56 la partie :ref:`section_ref_observers_templates` qui suit. Ces derniers sont
  57 des scripts simples qui peuvent être adaptés par l'utilisateur, soit dans
  58 l'étape d'édition intégrée du cas avec EFICAS, soit dans l'étape d'édition du
  59 schéma avant l'exécution, pour améliorer la performance du calcul ADAO dans le
  60 superviseur d'exécution de SALOME.
  61
  62 Dans l'interface textuelle (TUI) d'ADAO (voir la partie :ref:`section_tui`),
  63 les mêmes informations peuvent être données à l'aide de la commande
  64 "*setObserver*" appliquée pour une variable données indiquée dans l'argument
  65 "*Variable*". Les autres arguments de cette commande permettent de le définir
  66 soit comme un template (argument "*Template*") désignant l'un des scripts
  67 détaillés dans la partie :ref:`section_ref_observers_templates`, soit comme un
  68 script explicite (argument "*String*"), soit comme un script contenu dans un
  69 fichier externe (argument "*Script*").
  70
  71 Forme générale d'un script permettant de définir un *observer*
  72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  73
  74 Pour pouvoir utiliser cette capacité, l'utilisateur doit disposer ou construire
  75 des scripts utilisant en entrée standard (i.e. disponible dans l'espace de
  76 nommage) les variables ``var`` et ``info``. La variable ``var`` est à utiliser
  77 comme un objet de type liste/tuple, contenant la variable d'intérêt indicée par
  78 l'étape de mise à jour.
  79
  80 A titre d'exemple, voici un script très simple (similaire au modèle
  81 "*ValuePrinter*"), utilisable pour afficher la valeur d'une variable
  82 surveillée::
  83
  84     print("    --->",info," Value =",var[-1])
  85
  86 Stockées comme un fichier Python ou une chaîne de caractères explicite, ces
  87 lignes de script peuvent être associées à chaque variable présente dans le
  88 mot-clé "*SELECTION*" de la commande "*Observers*" du cas ADAO : "*Analysis*",
  89 "*CurrentState*", "*CostFunction*"... La valeur courante de la variable sera
  90 affichée à chaque étape de l'algorithme d'optimisation ou d'assimilation. Les
  91 "*observer*" peuvent inclure des capacités d'affichage graphique, de stockage,
  92 de traitement complexe, d'analyse statistique, etc.
  93
  94 On donne ci-après l'identifiant et le contenu de chaque modèle disponible.
  95
  96 .. _section_ref_observers_templates:
  97
  98 Inventaire des modèles d'*observer* disponibles ("*Template*")
  99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 100
 101 .. index:: single: ValuePrinter (Observer)
 102
 103 Modèle **ValuePrinter** :
 104 .........................
 105
 106 Imprime sur la sortie standard la valeur courante de la variable.
 107
 108 ::
 109
 110     print(str(info)+" "+str(var[-1]))
 111
 112 .. index:: single: ValueAndIndexPrinter (Observer)
 113
 114 Modèle **ValueAndIndexPrinter** :
 115 .................................
 116
 117 Imprime sur la sortie standard la valeur courante de la variable, en ajoutant son index.
 118
 119 ::
 120
 121     print(str(info)+(" index %i:"%(len(var)-1))+" "+str(var[-1]))
 122
 123 .. index:: single: ValueSeriePrinter (Observer)
 124
 125 Modèle **ValueSeriePrinter** :
 126 ..............................
 127
 128 Imprime sur la sortie standard la série des valeurs de la variable.
 129
 130 ::
 131
 132     print(str(info)+" "+str(var[:]))
 133
 134 .. index:: single: ValueSaver (Observer)
 135
 136 Modèle **ValueSaver** :
 137 .......................
 138
 139 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.
 140
 141 ::
 142
 143     import numpy, re
 144     v=numpy.array(var[-1], ndmin=1)
 145     global istep
 146     try:
 147         istep += 1
 148     except:
 149         istep = 0
 150     f='/tmp/value_%s_%05i.txt'%(info,istep)
 151     f=re.sub('\s','_',f)
 152     print('Value saved in "%s"'%f)
 153     numpy.savetxt(f,v)
 154
 155 .. index:: single: ValueSerieSaver (Observer)
 156
 157 Modèle **ValueSerieSaver** :
 158 ............................
 159
 160 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.
 161
 162 ::
 163
 164     import numpy, re
 165     v=numpy.array(var[:],  ndmin=1)
 166     global istep
 167     try:
 168         istep += 1
 169     except:
 170         istep = 0
 171     f='/tmp/value_%s_%05i.txt'%(info,istep)
 172     f=re.sub('\s','_',f)
 173     print('Value saved in "%s"'%f)
 174     numpy.savetxt(f,v)
 175
 176 .. index:: single: ValuePrinterAndSaver (Observer)
 177
 178 Modèle **ValuePrinterAndSaver** :
 179 .................................
 180
 181 Imprime sur la sortie standard et, en même temps enregistre dans un fichier du répertoire '/tmp', la valeur courante de la variable.
 182
 183 ::
 184
 185     import numpy, re
 186     v=numpy.array(var[-1], ndmin=1)
 187     print(str(info)+" "+str(v))
 188     global istep
 189     try:
 190         istep += 1
 191     except:
 192         istep = 0
 193     f='/tmp/value_%s_%05i.txt'%(info,istep)
 194     f=re.sub('\s','_',f)
 195     print('Value saved in "%s"'%f)
 196     numpy.savetxt(f,v)
 197
 198 .. index:: single: ValueIndexPrinterAndSaver (Observer)
 199
 200 Modèle **ValueIndexPrinterAndSaver** :
 201 ......................................
 202
 203 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.
 204
 205 ::
 206
 207     import numpy, re
 208     v=numpy.array(var[-1], ndmin=1)
 209     print(str(info)+(" index %i:"%(len(var)-1))+" "+str(v))
 210     global istep
 211     try:
 212         istep += 1
 213     except:
 214         istep = 0
 215     f='/tmp/value_%s_%05i.txt'%(info,istep)
 216     f=re.sub('\s','_',f)
 217     print('Value saved in "%s"'%f)
 218     numpy.savetxt(f,v)
 219
 220 .. index:: single: ValueSeriePrinterAndSaver (Observer)
 221
 222 Modèle **ValueSeriePrinterAndSaver** :
 223 ......................................
 224
 225 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.
 226
 227 ::
 228
 229     import numpy, re
 230     v=numpy.array(var[:],  ndmin=1)
 231     print(str(info)+" "+str(v))
 232     global istep
 233     try:
 234         istep += 1
 235     except:
 236         istep = 0
 237     f='/tmp/value_%s_%05i.txt'%(info,istep)
 238     f=re.sub('\s','_',f)
 239     print('Value saved in "%s"'%f)
 240     numpy.savetxt(f,v)
 241
 242 .. index:: single: ValueGnuPlotter (Observer)
 243
 244 Modèle **ValueGnuPlotter** :
 245 ............................
 246
 247 Affiche graphiquement avec Gnuplot la valeur courante de la variable.
 248
 249 ::
 250
 251     import numpy, Gnuplot
 252     v=numpy.array(var[-1], ndmin=1)
 253     global ifig, gp
 254     try:
 255         ifig += 1
 256         gp(' set style data lines')
 257     except:
 258         ifig = 0
 259         gp = Gnuplot.Gnuplot(persist=1)
 260         gp(' set style data lines')
 261     gp('set title  "%s (Figure %i)"'%(info,ifig))
 262     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 263
 264 .. index:: single: ValueSerieGnuPlotter (Observer)
 265
 266 Modèle **ValueSerieGnuPlotter** :
 267 .................................
 268
 269 Affiche graphiquement avec Gnuplot la série des valeurs de la variable.
 270
 271 ::
 272
 273     import numpy, Gnuplot
 274     v=numpy.array(var[:],  ndmin=1)
 275     global ifig, gp
 276     try:
 277         ifig += 1
 278         gp(' set style data lines')
 279     except:
 280         ifig = 0
 281         gp = Gnuplot.Gnuplot(persist=1)
 282         gp(' set style data lines')
 283     gp('set title  "%s (Figure %i)"'%(info,ifig))
 284     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 285
 286 .. index:: single: ValuePrinterAndGnuPlotter (Observer)
 287
 288 Modèle **ValuePrinterAndGnuPlotter** :
 289 ......................................
 290
 291 Imprime sur la sortie standard et, en même temps, affiche graphiquement avec Gnuplot la valeur courante de la variable.
 292
 293 ::
 294
 295     print(str(info)+" "+str(var[-1]))
 296     import numpy, Gnuplot
 297     v=numpy.array(var[-1], ndmin=1)
 298     global ifig,gp
 299     try:
 300         ifig += 1
 301         gp(' set style data lines')
 302     except:
 303         ifig = 0
 304         gp = Gnuplot.Gnuplot(persist=1)
 305         gp(' set style data lines')
 306     gp('set title  "%s (Figure %i)"'%(info,ifig))
 307     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 308
 309 .. index:: single: ValueSeriePrinterAndGnuPlotter (Observer)
 310
 311 Modèle **ValueSeriePrinterAndGnuPlotter** :
 312 ...........................................
 313
 314 Imprime sur la sortie standard et, en même temps, affiche graphiquement avec Gnuplot la série des valeurs de la variable.
 315
 316 ::
 317
 318     print(str(info)+" "+str(var[:]))
 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: ValuePrinterSaverAndGnuPlotter (Observer)
 333
 334 Modèle **ValuePrinterSaverAndGnuPlotter** :
 335 ...........................................
 336
 337 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 .
 338
 339 ::
 340
 341     print(str(info)+" "+str(var[-1]))
 342     import numpy, re
 343     v=numpy.array(var[-1], ndmin=1)
 344     global istep
 345     try:
 346         istep += 1
 347     except:
 348         istep = 0
 349     f='/tmp/value_%s_%05i.txt'%(info,istep)
 350     f=re.sub('\s','_',f)
 351     print('Value saved in "%s"'%f)
 352     numpy.savetxt(f,v)
 353     import Gnuplot
 354     global ifig,gp
 355     try:
 356         ifig += 1
 357         gp(' set style data lines')
 358     except:
 359         ifig = 0
 360         gp = Gnuplot.Gnuplot(persist=1)
 361         gp(' set style data lines')
 362     gp('set title  "%s (Figure %i)"'%(info,ifig))
 363     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 364
 365 .. index:: single: ValueSeriePrinterSaverAndGnuPlotter (Observer)
 366
 367 Modèle **ValueSeriePrinterSaverAndGnuPlotter** :
 368 ................................................
 369
 370 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.
 371
 372 ::
 373
 374     print(str(info)+" "+str(var[:]))
 375     import numpy, re
 376     v=numpy.array(var[:],  ndmin=1)
 377     global istep
 378     try:
 379         istep += 1
 380     except:
 381         istep = 0
 382     f='/tmp/value_%s_%05i.txt'%(info,istep)
 383     f=re.sub('\s','_',f)
 384     print('Value saved in "%s"'%f)
 385     numpy.savetxt(f,v)
 386     import Gnuplot
 387     global ifig,gp
 388     try:
 389         ifig += 1
 390         gp(' set style data lines')
 391     except:
 392         ifig = 0
 393         gp = Gnuplot.Gnuplot(persist=1)
 394         gp(' set style data lines')
 395     gp('set title  "%s (Figure %i)"'%(info,ifig))
 396     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 397
 398 .. index:: single: ValueMean (Observer)
 399
 400 Modèle **ValueMean** :
 401 ......................
 402
 403 Imprime sur la sortie standard la moyenne de la valeur courante de la variable.
 404
 405 ::
 406
 407     import numpy
 408     print(str(info)+" "+str(numpy.nanmean(var[-1])))
 409
 410 .. index:: single: ValueStandardError (Observer)
 411
 412 Modèle **ValueStandardError** :
 413 ...............................
 414
 415 Imprime sur la sortie standard l'écart-type de la valeur courante de la variable.
 416
 417 ::
 418
 419     import numpy
 420     print(str(info)+" "+str(numpy.nanstd(var[-1])))
 421
 422 .. index:: single: ValueVariance (Observer)
 423
 424 Modèle **ValueVariance** :
 425 ..........................
 426
 427 Imprime sur la sortie standard la variance de la valeur courante de la variable.
 428
 429 ::
 430
 431     import numpy
 432     print(str(info)+" "+str(numpy.nanvar(var[-1])))
 433
 434 .. index:: single: ValueL2Norm (Observer)
 435
 436 Modèle **ValueL2Norm** :
 437 ........................
 438
 439 Imprime sur la sortie standard la norme L2 de la valeur courante de la variable.
 440
 441 ::
 442
 443     import numpy
 444     v = numpy.matrix( numpy.ravel( var[-1] ) )
 445     print(str(info)+" "+str(float( numpy.linalg.norm(v) )))
 446
 447 .. index:: single: ValueRMS (Observer)
 448
 449 Modèle **ValueRMS** :
 450 .....................
 451
 452 Imprime sur la sortie standard la racine de la moyenne des carrés (RMS), ou moyenne quadratique, de la valeur courante de la variable.
 453
 454 ::
 455
 456     import numpy
 457     v = numpy.matrix( numpy.ravel( var[-1] ) )
 458     print(str(info)+" "+str(float( numpy.sqrt((1./v.size)*(v*v.T)) )))