doc/en/ref_observers_requirements.rst

   1 ..
   2    Copyright (C) 2008-2015 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 info, var[-1]
  94
  95 .. index:: single: ValueSeriePrinter (Observer)
  96
  97 Template **ValueSeriePrinter** :
  98 ................................
  99
 100 Print on standard output the value serie of the variable.
 101
 102 ::
 103
 104     print info, var[:]
 105
 106 .. index:: single: ValueSaver (Observer)
 107
 108 Template **ValueSaver** :
 109 .........................
 110
 111 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.
 112
 113 ::
 114
 115     import numpy, re
 116     v=numpy.array(var[-1], ndmin=1)
 117     global istep
 118     try:
 119         istep += 1
 120     except:
 121         istep = 0
 122     f='/tmp/value_%s_%05i.txt'%(info,istep)
 123     f=re.sub('\s','_',f)
 124     print 'Value saved in "%s"'%f
 125     numpy.savetxt(f,v)
 126
 127 .. index:: single: ValueSerieSaver (Observer)
 128
 129 Template **ValueSerieSaver** :
 130 ..............................
 131
 132 Save the value serie of the variable in a file of the '/tmp' directory named 'value...txt' from the variable name and the saving step.
 133
 134 ::
 135
 136     import numpy, re
 137     v=numpy.array(var[:],  ndmin=1)
 138     global istep
 139     try:
 140         istep += 1
 141     except:
 142         istep = 0
 143     f='/tmp/value_%s_%05i.txt'%(info,istep)
 144     f=re.sub('\s','_',f)
 145     print 'Value saved in "%s"'%f
 146     numpy.savetxt(f,v)
 147
 148 .. index:: single: ValuePrinterAndSaver (Observer)
 149
 150 Template **ValuePrinterAndSaver** :
 151 ...................................
 152
 153 Print on standard output and, in the same time, save in a file the current value of the variable.
 154
 155 ::
 156
 157     import numpy, re
 158     v=numpy.array(var[-1], ndmin=1)
 159     print info,v
 160     global istep
 161     try:
 162         istep += 1
 163     except:
 164         istep = 0
 165     f='/tmp/value_%s_%05i.txt'%(info,istep)
 166     f=re.sub('\s','_',f)
 167     print 'Value saved in "%s"'%f
 168     numpy.savetxt(f,v)
 169
 170 .. index:: single: ValueSeriePrinterAndSaver (Observer)
 171
 172 Template **ValueSeriePrinterAndSaver** :
 173 ........................................
 174
 175 Print on standard output and, in the same time, save in a file the value serie of the variable.
 176
 177 ::
 178
 179     import numpy, re
 180     v=numpy.array(var[:],  ndmin=1)
 181     print info,v
 182     global istep
 183     try:
 184         istep += 1
 185     except:
 186         istep = 0
 187     f='/tmp/value_%s_%05i.txt'%(info,istep)
 188     f=re.sub('\s','_',f)
 189     print 'Value saved in "%s"'%f
 190     numpy.savetxt(f,v)
 191
 192 .. index:: single: ValueGnuPlotter (Observer)
 193
 194 Template **ValueGnuPlotter** :
 195 ..............................
 196
 197 Graphically plot with Gnuplot the current value of the variable.
 198
 199 ::
 200
 201     import numpy, Gnuplot
 202     v=numpy.array(var[-1], ndmin=1)
 203     global ifig, gp
 204     try:
 205         ifig += 1
 206         gp(' set style data lines')
 207     except:
 208         ifig = 0
 209         gp = Gnuplot.Gnuplot(persist=1)
 210         gp(' set style data lines')
 211     gp('set title  "%s (Figure %i)"'%(info,ifig))
 212     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 213
 214 .. index:: single: ValueSerieGnuPlotter (Observer)
 215
 216 Template **ValueSerieGnuPlotter** :
 217 ...................................
 218
 219 Graphically plot with Gnuplot the value serie of the variable.
 220
 221 ::
 222
 223     import numpy, Gnuplot
 224     v=numpy.array(var[:],  ndmin=1)
 225     global ifig, gp
 226     try:
 227         ifig += 1
 228         gp(' set style data lines')
 229     except:
 230         ifig = 0
 231         gp = Gnuplot.Gnuplot(persist=1)
 232         gp(' set style data lines')
 233     gp('set title  "%s (Figure %i)"'%(info,ifig))
 234     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 235
 236 .. index:: single: ValuePrinterAndGnuPlotter (Observer)
 237
 238 Template **ValuePrinterAndGnuPlotter** :
 239 ........................................
 240
 241 Print on standard output and, in the same time, graphically plot with Gnuplot the current value of the variable.
 242
 243 ::
 244
 245     print info, var[-1]
 246     import numpy, Gnuplot
 247     v=numpy.array(var[-1], ndmin=1)
 248     global ifig,gp
 249     try:
 250         ifig += 1
 251         gp(' set style data lines')
 252     except:
 253         ifig = 0
 254         gp = Gnuplot.Gnuplot(persist=1)
 255         gp(' set style data lines')
 256     gp('set title  "%s (Figure %i)"'%(info,ifig))
 257     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 258
 259 .. index:: single: ValueSeriePrinterAndGnuPlotter (Observer)
 260
 261 Template **ValueSeriePrinterAndGnuPlotter** :
 262 .............................................
 263
 264 Print on standard output and, in the same time, graphically plot with Gnuplot the value serie of the variable.
 265
 266 ::
 267
 268     print info, var[:]
 269     import numpy, Gnuplot
 270     v=numpy.array(var[:],  ndmin=1)
 271     global ifig,gp
 272     try:
 273         ifig += 1
 274         gp(' set style data lines')
 275     except:
 276         ifig = 0
 277         gp = Gnuplot.Gnuplot(persist=1)
 278         gp(' set style data lines')
 279     gp('set title  "%s (Figure %i)"'%(info,ifig))
 280     gp.plot( Gnuplot.Data( v, with_='lines lw 2' ) )
 281
 282 .. index:: single: ValuePrinterSaverAndGnuPlotter (Observer)
 283
 284 Template **ValuePrinterSaverAndGnuPlotter** :
 285 .............................................
 286
 287 Print on standard output and, in the same, time save in a file and graphically plot the current value of the variable.
 288
 289 ::
 290
 291     print info, var[-1]
 292     import numpy, re
 293     v=numpy.array(var[-1], ndmin=1)
 294     global istep
 295     try:
 296         istep += 1
 297     except:
 298         istep = 0
 299     f='/tmp/value_%s_%05i.txt'%(info,istep)
 300     f=re.sub('\s','_',f)
 301     print 'Value saved in "%s"'%f
 302     numpy.savetxt(f,v)
 303     import Gnuplot
 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: ValueSeriePrinterSaverAndGnuPlotter (Observer)
 316
 317 Template **ValueSeriePrinterSaverAndGnuPlotter** :
 318 ..................................................
 319
 320 Print on standard output and, in the same, time save in a file and graphically plot the value serie of the variable.
 321
 322 ::
 323
 324     print info, var[:]
 325     import numpy, re
 326     v=numpy.array(var[:],  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: ValueMean (Observer)
 349
 350 Template **ValueMean** :
 351 ........................
 352
 353 Print on standard output the mean of the current value of the variable.
 354
 355 ::
 356
 357     import numpy
 358     print info, numpy.nanmean(var[-1])
 359
 360 .. index:: single: ValueStandardError (Observer)
 361
 362 Template **ValueStandardError** :
 363 .................................
 364
 365 Print on standard output the standard error of the current value of the variable.
 366
 367 ::
 368
 369     import numpy
 370     print info, numpy.nanstd(var[-1])
 371
 372 .. index:: single: ValueVariance (Observer)
 373
 374 Template **ValueVariance** :
 375 ............................
 376
 377 Print on standard output the variance of the current value of the variable.
 378
 379 ::
 380
 381     import numpy
 382     print info, numpy.nanvar(var[-1])
 383
 384 .. index:: single: ValueL2Norm (Observer)
 385
 386 Template **ValueL2Norm** :
 387 ..........................
 388
 389 Print on standard output the L2 norm of the current value of the variable.
 390
 391 ::
 392
 393     import numpy
 394     v = numpy.matrix( numpy.ravel( var[-1] ) )
 395     print info, float( numpy.linalg.norm(v) )
 396
 397 .. index:: single: ValueRMS (Observer)
 398
 399 Template **ValueRMS** :
 400 .......................
 401
 402 Print on standard output the root mean square (RMS), or quadratic mean, of the current value of the variable.
 403
 404 ::
 405
 406     import numpy
 407     v = numpy.matrix( numpy.ravel( var[-1] ) )
 408     print info, float( numpy.sqrt((1./v.size)*(v*v.T)) )