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