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