doc/en/ref_observers_requirements.rst

   1 ..
   2    Copyright (C) 2008-2017 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 .. _ref_observers_requirements:
  25
  26 Requirements for functions describing an "*observer*"
  27 -----------------------------------------------------
  28
  29 .. index:: single: Observer
  30 .. index:: single: Observer Template
  31
  32 Some special variables, internal to the optimization process, used inside
  33 calculation, can be monitored during an ADAO calculation. These variables can be
  34 printed, plotted, saved, etc. It can be done using some "*observer*", sometimes
  35 also called "callback". They are Python scripts, each one associated to a given
  36 variable. They are activated for each variable modification.
  37
  38 There are 3 practical methods to provide an "*observer*" in an ADAO case. The
  39 method is chosen with the "*NodeType*" keyword of each "*observer*" entry type, as
  40 shown in the following figure:
  41
  42   .. eficas_observer_nodetype:
  43   .. image:: images/eficas_observer_nodetype.png
  44     :align: center
  45     :width: 100%
  46   .. centered::
  47     **Choosing for an "*observer*" its entry type**
  48
  49 The "*observer*" can be given as a explicit script (entry of type "*String*"),
  50 as a script in an external file (entry of type "*Script*"), or by using a
  51 template or pattern (entry of type"*Template*") available by default in ADAO
  52 when using the graphical editor. These templates are simple scripts that can be
  53 tuned by the user, either in the integrated edtition stage of the case, or in
  54 the edition stage of the schema before execution, to improve the ADAO case
  55 performance in the SALOME execution supervisor.
  56
  57 General form of a script to define an *observer*
  58 ++++++++++++++++++++++++++++++++++++++++++++++++
  59
  60 To use this capability, the user must have or build scripts that have on
  61 standard input (that is, in the naming space) the variables ``var`` and
  62 ``info``. The variable ``var`` is to be used as an object of list/tuple type,
  63 that contains the variable of interest indexed by the updating step.
  64
  65 As an example, here is a very simple script (similar to the model
  66 "*ValuePrinter*"), that can be used to print the value of the monitored
  67 variable::
  68
  69     print "    --->",info," Value =",var[-1]
  70
  71 Stored as a Python file or as an explicit string, these script lines can be
  72 associated to each variable found in the keyword "*SELECTION*" of the
  73 "*Observers*" command of the ADAO case: "*Analysis*", "*CurrentState*",
  74 "*CostFunction*"... The current value of the variable will be printed at each
  75 step of the optimization or data assimilation algorithm. The "*observer*" can
  76 include graphical output, storage capacities, complex treatment, statistical
  77 analysis, etc.
  78
  79 Hereinafter we give the identifier and the contents of each model available.
  80
  81 Inventory of available *observer* models ("*Template*")
  82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
  83
  84 .. index:: single: ValuePrinter (Observer)
  85
  86 Template **ValuePrinter** :
  87 ...........................
  88
  89 Print on standard output the current value of the variable.
  90
  91 ::
  92
  93     print(str(info)+" "+str(var[-1]))
  94
  95 .. index:: single: ValueAndIndexPrinter (Observer)
  96
  97 Template **ValueAndIndexPrinter** :
  98 ...................................
  99
 100 Print on standard output the current value of the variable, adding its index.
 101
 102 ::
 103
 104     print(str(info)+(" index %i:"%(len(var)-1))+" "+str(var[-1]))
 105
 106 .. index:: single: ValueSeriePrinter (Observer)
 107
 108 Template **ValueSeriePrinter** :
 109 ................................
 110
 111 Print on standard output the value series of the variable.
 112
 113 ::
 114
 115     print(str(info)+" "+str(var[:]))
 116
 117 .. index:: single: ValueSaver (Observer)
 118
 119 Template **ValueSaver** :
 120 .........................
 121
 122 Save the current value of the variable in a file of the '/tmp' directory named 'value...txt' from the variable name and the saving step.
 123
 124 ::
 125
 126     import numpy, re
 127     v=numpy.array(var[-1], ndmin=1)
 128     global istep
 129     try:
 130         istep += 1
 131     except:
 132         istep = 0
 133     f='/tmp/value_%s_%05i.txt'%(info,istep)
 134     f=re.sub('\s','_',f)
 135     print('Value saved in "%s"'%f)
 136     numpy.savetxt(f,v)
 137
 138 .. index:: single: ValueSerieSaver (Observer)
 139
 140 Template **ValueSerieSaver** :
 141 ..............................
 142
 143 Save the value series of the variable in a file of the '/tmp' directory named 'value...txt' from the variable name and the saving step.
 144
 145 ::
 146
 147     import numpy, re
 148     v=numpy.array(var[:],  ndmin=1)
 149     global istep
 150     try:
 151         istep += 1
 152     except:
 153         istep = 0
 154     f='/tmp/value_%s_%05i.txt'%(info,istep)
 155     f=re.sub('\s','_',f)
 156     print('Value saved in "%s"'%f)
 157     numpy.savetxt(f,v)
 158
 159 .. index:: single: ValuePrinterAndSaver (Observer)
 160
 161 Template **ValuePrinterAndSaver** :
 162 ...................................
 163
 164 Print on standard output and, in the same time save in a file, the current value of the variable.
 165
 166 ::
 167
 168     import numpy, re
 169     v=numpy.array(var[-1], ndmin=1)
 170     print(str(info)+" "+str(v))
 171     global istep
 172     try:
 173         istep += 1
 174     except:
 175         istep = 0
 176     f='/tmp/value_%s_%05i.txt'%(info,istep)
 177     f=re.sub('\s','_',f)
 178     print('Value saved in "%s"'%f)
 179     numpy.savetxt(f,v)
 180
 181 .. index:: single: ValueIndexPrinterAndSaver (Observer)
 182
 183 Template **ValueIndexPrinterAndSaver** :
 184 ........................................
 185
 186 Print on standard output and, in the same time save in a file, the current value of the variable, adding its index.
 187
 188 ::
 189
 190     import numpy, re
 191     v=numpy.array(var[-1], ndmin=1)
 192     print(str(info)+(" index %i:"%(len(var)-1))+" "+str(v))
 193     global istep
 194     try:
 195         istep += 1
 196     except:
 197         istep = 0
 198     f='/tmp/value_%s_%05i.txt'%(info,istep)
 199     f=re.sub('\s','_',f)
 200     print('Value saved in "%s"'%f)
 201     numpy.savetxt(f,v)
 202
 203 .. index:: single: ValueSeriePrinterAndSaver (Observer)
 204
 205 Template **ValueSeriePrinterAndSaver** :
 206 ........................................
 207
 208 Print on standard output and, in the same time, save in a file the value series of the variable.
 209
 210 ::
 211
 212     import numpy, re
 213     v=numpy.array(var[:],  ndmin=1)
 214     print(str(info)+" "+str(v))
 215     global istep
 216     try:
 217         istep += 1
 218     except:
 219         istep = 0
 220     f='/tmp/value_%s_%05i.txt'%(info,istep)
 221     f=re.sub('\s','_',f)
 222     print('Value saved in "%s"'%f)
 223     numpy.savetxt(f,v)
 224
 225 .. index:: single: ValueGnuPlotter (Observer)
 226
 227 Template **ValueGnuPlotter** :
 228 ..............................
 229
 230 Graphically plot with Gnuplot the current value of the variable.
 231
 232 ::
 233
 234     import numpy, Gnuplot
 235     v=numpy.array(var[-1], ndmin=1)
 236     global ifig, gp
 237     try:
 238         ifig += 1
 239         gp(' set style data lines')
 240     except:
 241         ifig = 0
 242         gp = Gnuplot.Gnuplot(persist=1)
 243         gp(' set style data lines')
 244     gp('set title  "%s (Figure %i)"'%(info,ifig))
 245     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 246
 247 .. index:: single: ValueSerieGnuPlotter (Observer)
 248
 249 Template **ValueSerieGnuPlotter** :
 250 ...................................
 251
 252 Graphically plot with Gnuplot the value series of the variable.
 253
 254 ::
 255
 256     import numpy, Gnuplot
 257     v=numpy.array(var[:],  ndmin=1)
 258     global ifig, gp
 259     try:
 260         ifig += 1
 261         gp(' set style data lines')
 262     except:
 263         ifig = 0
 264         gp = Gnuplot.Gnuplot(persist=1)
 265         gp(' set style data lines')
 266     gp('set title  "%s (Figure %i)"'%(info,ifig))
 267     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 268
 269 .. index:: single: ValuePrinterAndGnuPlotter (Observer)
 270
 271 Template **ValuePrinterAndGnuPlotter** :
 272 ........................................
 273
 274 Print on standard output and, in the same time, graphically plot with Gnuplot the current value of the variable.
 275
 276 ::
 277
 278     print(str(info)+" "+str(var[-1]))
 279     import numpy, Gnuplot
 280     v=numpy.array(var[-1], ndmin=1)
 281     global ifig,gp
 282     try:
 283         ifig += 1
 284         gp(' set style data lines')
 285     except:
 286         ifig = 0
 287         gp = Gnuplot.Gnuplot(persist=1)
 288         gp(' set style data lines')
 289     gp('set title  "%s (Figure %i)"'%(info,ifig))
 290     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 291
 292 .. index:: single: ValueSeriePrinterAndGnuPlotter (Observer)
 293
 294 Template **ValueSeriePrinterAndGnuPlotter** :
 295 .............................................
 296
 297 Print on standard output and, in the same time, graphically plot with Gnuplot the value series of the variable.
 298
 299 ::
 300
 301     print(str(info)+" "+str(var[:]))
 302     import numpy, Gnuplot
 303     v=numpy.array(var[:],  ndmin=1)
 304     global ifig,gp
 305     try:
 306         ifig += 1
 307         gp(' set style data lines')
 308     except:
 309         ifig = 0
 310         gp = Gnuplot.Gnuplot(persist=1)
 311         gp(' set style data lines')
 312     gp('set title  "%s (Figure %i)"'%(info,ifig))
 313     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 314
 315 .. index:: single: ValuePrinterSaverAndGnuPlotter (Observer)
 316
 317 Template **ValuePrinterSaverAndGnuPlotter** :
 318 .............................................
 319
 320 Print on standard output and, in the same, time save in a file and graphically plot the current value of the variable.
 321
 322 ::
 323
 324     print(str(info)+" "+str(var[-1]))
 325     import numpy, re
 326     v=numpy.array(var[-1], ndmin=1)
 327     global istep
 328     try:
 329         istep += 1
 330     except:
 331         istep = 0
 332     f='/tmp/value_%s_%05i.txt'%(info,istep)
 333     f=re.sub('\s','_',f)
 334     print('Value saved in "%s"'%f)
 335     numpy.savetxt(f,v)
 336     import Gnuplot
 337     global ifig,gp
 338     try:
 339         ifig += 1
 340         gp(' set style data lines')
 341     except:
 342         ifig = 0
 343         gp = Gnuplot.Gnuplot(persist=1)
 344         gp(' set style data lines')
 345     gp('set title  "%s (Figure %i)"'%(info,ifig))
 346     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 347
 348 .. index:: single: ValueSeriePrinterSaverAndGnuPlotter (Observer)
 349
 350 Template **ValueSeriePrinterSaverAndGnuPlotter** :
 351 ..................................................
 352
 353 Print on standard output and, in the same, time save in a file and graphically plot the value series of the variable.
 354
 355 ::
 356
 357     print(str(info)+" "+str(var[:]))
 358     import numpy, re
 359     v=numpy.array(var[:],  ndmin=1)
 360     global istep
 361     try:
 362         istep += 1
 363     except:
 364         istep = 0
 365     f='/tmp/value_%s_%05i.txt'%(info,istep)
 366     f=re.sub('\s','_',f)
 367     print('Value saved in "%s"'%f)
 368     numpy.savetxt(f,v)
 369     import Gnuplot
 370     global ifig,gp
 371     try:
 372         ifig += 1
 373         gp(' set style data lines')
 374     except:
 375         ifig = 0
 376         gp = Gnuplot.Gnuplot(persist=1)
 377         gp(' set style data lines')
 378     gp('set title  "%s (Figure %i)"'%(info,ifig))
 379     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 380
 381 .. index:: single: ValueMean (Observer)
 382
 383 Template **ValueMean** :
 384 ........................
 385
 386 Print on standard output the mean of the current value of the variable.
 387
 388 ::
 389
 390     import numpy
 391     print(str(info)+" "+str(numpy.nanmean(var[-1])))
 392
 393 .. index:: single: ValueStandardError (Observer)
 394
 395 Template **ValueStandardError** :
 396 .................................
 397
 398 Print on standard output the standard error of the current value of the variable.
 399
 400 ::
 401
 402     import numpy
 403     print(str(info)+" "+str(numpy.nanstd(var[-1])))
 404
 405 .. index:: single: ValueVariance (Observer)
 406
 407 Template **ValueVariance** :
 408 ............................
 409
 410 Print on standard output the variance of the current value of the variable.
 411
 412 ::
 413
 414     import numpy
 415     print(str(info)+" "+str(numpy.nanvar(var[-1])))
 416
 417 .. index:: single: ValueL2Norm (Observer)
 418
 419 Template **ValueL2Norm** :
 420 ..........................
 421
 422 Print on standard output the L2 norm of the current value of the variable.
 423
 424 ::
 425
 426     import numpy
 427     v = numpy.matrix( numpy.ravel( var[-1] ) )
 428     print(str(info)+" "+str(float( numpy.linalg.norm(v) )))
 429
 430 .. index:: single: ValueRMS (Observer)
 431
 432 Template **ValueRMS** :
 433 .......................
 434
 435 Print on standard output the root mean square (RMS), or quadratic mean, of the current value of the variable.
 436
 437 ::
 438
 439     import numpy
 440     v = numpy.matrix( numpy.ravel( var[-1] ) )
 441     print(str(info)+" "+str(float( numpy.sqrt((1./v.size)*(v*v.T)) )))