doc/en/ref_output_variables.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 .. _section_ref_output_variables:
  25
  26 Variables and informations available at the output
  27 --------------------------------------------------
  28
  29 How to obtain the information available at the output
  30 +++++++++++++++++++++++++++++++++++++++++++++++++++++
  31
  32 .. index:: single: UserPostAnalysis
  33 .. index:: single: algoResults
  34 .. index:: single: getResults
  35 .. index:: single: get
  36 .. index:: single: ADD
  37
  38 At the output, after executing data assimilation, optimization or checking
  39 study, there are variables and information originating from the calculation. The
  40 obtaining of this information is then carried out in a standardized way using
  41 the post-processing step of calculation.
  42
  43 The step is easily identified by the user into its ADAO definition case (by the
  44 keyword "*UserPostAnalysis*") or in its YACS execution scheme (by nodes or
  45 blocks located after the calculation block, and graphically connected to the
  46 output port "*algoResults*" of the calculation block):
  47
  48 #. In the case where the user defines the post-processing in his ADAO case, it uses an external script file or commands in the field type "*String*" or "*Template*". The script it provides has a fixed variable "*ADD*" in the namespace.
  49 #. In the case where the user defines the post-processing in its YACS scheme by a Python node located after the block of calculation, it should add a input port of type "*pyobj*" named for example "*Study*", graphically connected to the output port "*algoResults*" of the calculation block. The Python post-processing node must then start with ``ADD = Study.getResults()``.
  50
  51 Templates are given hereafter as :ref:`subsection_r_o_v_Template`. In all cases,
  52 the post-processing of the user has in the namespace a variable whose name is
  53 "*ADD*", and whose only available method is named ``get``. The arguments of this
  54 method are an output information name, as described in the
  55 :ref:`subsection_r_o_v_Inventaire`.
  56
  57 For example, to have the optimal state after a data assimilation or optimization
  58 calculation, one use the following call::
  59
  60     ADD.get("Analysis")
  61
  62 This call returns a list of values of the requested notion (or, in the case of
  63 input variables that are by nature only a unique specimen, the value itself).
  64 One can then request a particular item in the list by the standard list commands
  65 (especially ``[-1]`` for the last, and ``[:]`` for all items).
  66
  67 .. _subsection_r_o_v_Template:
  68
  69 Examples of Python scripts to obtain or treat the outputs
  70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  71
  72 .. index:: single: Template
  73 .. index:: single: AnalysisPrinter
  74 .. index:: single: AnalysisSaver
  75 .. index:: single: AnalysisPrinterAndSaver
  76
  77 These examples present Python commands or scripts which allow to obtain or to
  78 treat the ouput of an algorithm run. To help the user, they are directly
  79 available in the user interface, when building the ADAO case in the embedded
  80 case editor, in the "*Template*" type fields. In an equivalent way, these
  81 commands can be integrated in an external user script (and inserted in the ADAO
  82 case by a "*Script*" type input) or can exist as a string, including line feeds
  83 (and inserted in the ADAO case by a "*String*" type input). Lot of variants can
  84 be build from these simple examples, the main objective beeing to help the user
  85 to elaborate the exact procedure he needs in output.
  86
  87 The first example (named "*AnalysisPrinter*" in the inputs of type
  88 "*Template*") consists in printing, in the standard log output, the value of the
  89 analysis or the optimal state, noted as :math:`\mathbf{x}^a` in the section
  90 :ref:`section_theory`. It is realized by the commands::
  91
  92     import numpy
  93     xa=numpy.ravel(ADD.get('Analysis')[-1])
  94     print 'Analysis:',xa"
  95
  96 The ``numpy.ravel`` function is here to be sure that the ``xa`` variable will
  97 contain a real unidimensional vector, whatever the previoux computing choices
  98 are.
  99
 100 A second example (named "*AnalysisSaver*" in the inputs of type  "*Template*")
 101 consists in saving on file the value of the analysis or the optimal state
 102 :math:`\mathbf{x}^a`. It is realized by the commands::
 103
 104     import numpy
 105     xa=numpy.ravel(ADD.get('Analysis')[-1])
 106     f='/tmp/analysis.txt'
 107     print 'Analysis saved in "%s"'%f
 108     numpy.savetxt(f,xa)"
 109
 110 The chosen recording file is a text one named ``/tmp/analysis.txt``.
 111
 112 It is easy to combine these two examples by building a third one (named
 113 "*AnalysisPrinterAndSaver*" in the inputs of type  "*Template*"). It consists in
 114 simultaneously printing in the standard log output and in saving on file the
 115 value of :math:`\mathbf{x}^a`. It is realized by the commands::
 116
 117     import numpy
 118     xa=numpy.ravel(ADD.get('Analysis')[-1])
 119     print 'Analysis:',xa
 120     f='/tmp/analysis.txt'
 121     print 'Analysis saved in "%s"'%f
 122     numpy.savetxt(f,xa)
 123
 124 To facilitate these examples extension for user needs, we recall that all the
 125 SALOME functions are available at the same level than these commands. The user
 126 can for example request for graphical representation with the PARAVIS [#]_ or
 127 other modules, for computating operations driven by YACS [#]_ or an another
 128 module, etc.
 129
 130 Other usage examples are also given for :ref:`section_u_step4` of the
 131 :ref:`section_using` section, or in part :ref:`section_examples`.
 132
 133 Cross compliance of the information available at the output
 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 135
 136 .. index:: single: AlgorithmParameters
 137 .. index:: single: Stored
 138
 139 The availability of information after the calculation is conditioned by the fact
 140 that they have been calculated or requested.
 141
 142 Each algorithm does not necessarily provide the same information, and not
 143 necessarily for example uses the same intermediate quantities. Thus, there is
 144 information that are always present such as the optimal state resulting from the
 145 calculation. The other information are only present for certain algorithms
 146 and/or if they have been requested before the execution of the calculation.
 147
 148 It is recalled that the user can request additional information during the
 149 preparation of its ADAO case, using the optional control "*AlgorithmParameters*" of
 150 ADAO case. Reference will be made to the
 151 :ref:`section_ref_options_Algorithm_Parameters` for the proper use of this
 152 command, and to the description of each algorithm for the information available
 153 by algorithm. One can also ask to keep some input information by changing the
 154 boolean "* * Stored" associated with it in the edition of the ADAO case.
 155
 156 .. _subsection_r_o_v_Inventaire:
 157
 158 Inventory of potentially available information at the output
 159 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 160
 161 .. index:: single: Dry
 162 .. index:: single: Forecast
 163
 164 The set of potentially available information at the output is listed here
 165 regardless of algorithms, for inventory.
 166
 167 The optimal state is an information that is always naturally available after an
 168 optimization or a data assimilation calculation. It is indicated by the
 169 following keywords:
 170
 171   Analysis
 172     *List of vectors*. Each element is an optimal state :math:`\mathbf{x}*` in
 173     optimization or an analysis :math:`\mathbf{x}^a` in data assimilation.
 174
 175     Example : ``Xa = ADD.get("Analysis")[-1]``
 176
 177 The following variables are input variables.  They are made available to the
 178 user at the output in order to facilitate the writing of post-processing
 179 procedures, and are conditioned by a user request using a boolean "*Stored*"
 180 at the input.
 181
 182   Background
 183     *Vector*, whose availability is conditioned by "*Stored*" at the input. It
 184     is the background vector :math:`\mathbf{x}^b`.
 185
 186     Example : ``Xb = ADD.get("Background")``
 187
 188   BackgroundError
 189     *Matrix*, whose availability is conditioned by "*Stored*" at the input. It
 190     is the matrix :math:`\mathbf{B}` of *a priori* background errors
 191     covariances.
 192
 193     Example : ``B = ADD.get("BackgroundError")``
 194
 195   EvolutionError
 196     *Matrix*, whose availability is conditioned by "*Stored*" at the input. It
 197     is the matrix :math:`\mathbf{M}` of *a priori* evolution errors covariances.
 198
 199     Example : ``M = ADD.get("EvolutionError")``
 200
 201   Observation
 202     *Vector*, whose availability is conditioned by "*Stored*" at the input. It
 203     is the observation vector :math:`\mathbf{y}^o`.
 204
 205     Example : ``Yo = ADD.get("Observation")``
 206
 207   ObservationError
 208     *Matrix*, whose availability is conditioned by "*Stored*" at the input. It
 209     is the matrix :math:`\mathbf{R}` of *a priori* observation errors
 210     covariances.
 211
 212     Example : ``R = ADD.get("ObservationError")``
 213
 214 All other information are conditioned by the algorithm and/or the user requests
 215 of availability. They are the following, in alphabetical order:
 216
 217   APosterioriCorrelations
 218     *List of matrices*. Each element is an *a posteriori* error correlations
 219     matrix of the optimal state, coming from the :math:`\mathbf{A}*` covariance
 220     matrix.
 221
 222     Example : ``C = ADD.get("APosterioriCorrelations")[-1]``
 223
 224   APosterioriCovariance
 225     *List of matrices*. Each element is an *a posteriori* error covariance
 226     matrix :math:`\mathbf{A}*` of the optimal state.
 227
 228     Example : ``A = ADD.get("APosterioriCovariance")[-1]``
 229
 230   APosterioriStandardDeviations
 231     *List of matrices*. Each element is an *a posteriori* error standard errors
 232     diagonal matrix of the optimal state, coming from the :math:`\mathbf{A}*`
 233     covariance matrix.
 234
 235     Example : ``S = ADD.get("APosterioriStandardDeviations")[-1]``
 236
 237   APosterioriVariances
 238     *List of matrices*. Each element is an *a posteriori* error variances
 239     diagonal matrix of the optimal state, coming from the :math:`\mathbf{A}*`
 240     covariance matrix.
 241
 242     Example : ``V = ADD.get("APosterioriVariances")[-1]``
 243
 244   BMA
 245     *List of vectors*. Each element is a vector of difference between the
 246     background and the optimal state.
 247
 248     Example : ``bma = ADD.get("BMA")[-1]``
 249
 250   CostFunctionJ
 251     *List of values*. Each element is a value of the error function :math:`J`.
 252
 253     Example : ``J = ADD.get("CostFunctionJ")[:]``
 254
 255   CostFunctionJb
 256     *List of values*. Each element is a value of the error function :math:`J^b`,
 257     that is of the background difference part.
 258
 259     Example : ``Jb = ADD.get("CostFunctionJb")[:]``
 260
 261   CostFunctionJo
 262     *List of values*. Each element is a value of the error function :math:`J^o`,
 263     that is of the observation difference part.
 264
 265     Example : ``Jo = ADD.get("CostFunctionJo")[:]``
 266
 267   CostFunctionJAtCurrentOptimum
 268     *List of values*. Each element is a value of the error function :math:`J`.
 269     At each step, the value corresponds to the optimal state found from the
 270     beginning.
 271
 272     Example : ``JACO = ADD.get("CostFunctionJAtCurrentOptimum")[:]``
 273
 274   CostFunctionJbAtCurrentOptimum
 275     *List of values*. Each element is a value of the error function :math:`J^b`,
 276     that is of the background difference part. At each step, the value
 277     corresponds to the optimal state found from the beginning.
 278
 279     Example : ``JbACO = ADD.get("CostFunctionJbAtCurrentOptimum")[:]``
 280
 281   CostFunctionJoAtCurrentOptimum
 282     *List of values*. Each element is a value of the error function :math:`J^o`,
 283     that is of the observation difference part. At each step, the value
 284     corresponds to the optimal state found from the beginning.
 285
 286     Example : ``JoACO = ADD.get("CostFunctionJoAtCurrentOptimum")[:]``
 287
 288   CurrentOptimum
 289     *List of vectors*. Each element is the optimal state obtained at the current
 290     step of the optimization algorithm. It is not necessarely the last state.
 291
 292     Example : ``Xo = ADD.get("CurrentOptimum")[:]``
 293
 294   CurrentState
 295     *List of vectors*. Each element is a usual state vector used during the
 296     optimization algorithm procedure.
 297
 298     Example : ``Xs = ADD.get("CurrentState")[:]``
 299
 300   IndexOfOptimum
 301     *List of integers*. Each element is the iteration index of the optimum
 302     obtained at the current step the optimization algorithm. It is not
 303     necessarely the number of the last iteration.
 304
 305     Example : ``i = ADD.get("MahalanobisConsistency")[-1]``
 306
 307   Innovation
 308     *List of vectors*. Each element is an innovation vector, which is in static
 309     the difference between the optimal and the background, and in dynamic the
 310     evolution increment.
 311
 312     Example : ``d = ADD.get("Innovation")[-1]``
 313
 314   InnovationAtCurrentState
 315     *List of vectors*. Each element is an innovation vector at current state.
 316
 317     Example : ``ds = ADD.get("InnovationAtCurrentState")[-1]``
 318
 319   MahalanobisConsistency
 320     *List of values*. Each element is a value of the Mahalanobis quality
 321     indicator.
 322
 323     Example : ``m = ADD.get("MahalanobisConsistency")[-1]``
 324
 325   OMA
 326     *List of vectors*. Each element is a vector of difference between the
 327     observation and the optimal state in the observation space.
 328
 329     Example : ``oma = ADD.get("OMA")[-1]``
 330
 331   OMB
 332     *List of vectors*. Each element is a vector of difference between the
 333     observation and the background state in the observation space.
 334
 335     Example : ``omb = ADD.get("OMB")[-1]``
 336
 337   Residu
 338     *List of values*. Each element is the value of the particular residu
 339     verified during a checking algorithm, in the order of the tests.
 340
 341     Example : ``r = ADD.get("Residu")[:]``
 342
 343   SigmaBck2
 344     *List of values*. Each element is a value of the quality indicator
 345     :math:`(\sigma^b)^2` of the background part.
 346
 347     Example : ``sb2 = ADD.get("SigmaBck")[-1]``
 348
 349   SigmaObs2
 350     *List of values*. Each element is a value of the quality indicator
 351     :math:`(\sigma^o)^2` of the observation part.
 352
 353     Example : ``so2 = ADD.get("SigmaObs")[-1]``
 354
 355   SimulatedObservationAtBackground
 356     *List of vectors*. Each element is a vector of observation simulated from
 357     the background :math:`\mathbf{x}^b`. It is the forecast using the
 358     background, and it is sometimes called "*Dry*".
 359
 360     Example : ``hxb = ADD.get("SimulatedObservationAtBackground")[-1]``
 361
 362   SimulatedObservationAtCurrentOptimum
 363     *List of vectors*. Each element is a vector of observation simulated from
 364     the optimal state obtained at the current step the optimization algorithm,
 365     that is, in the observation space.
 366
 367     Example : ``hxo = ADD.get("SimulatedObservationAtCurrentOptimum")[-1]``
 368
 369   SimulatedObservationAtCurrentState
 370     *List of vectors*. Each element is an observed vector at the current state,
 371     that is, in the observation space.
 372
 373     Example : ``hxs = ADD.get("SimulatedObservationAtCurrentState")[-1]``
 374
 375   SimulatedObservationAtOptimum
 376     *List of vectors*. Each element is a vector of observation simulated from
 377     the analysis or the optimal state :math:`\mathbf{x}^a`. It is the forecast
 378     using the analysis or the optimal state, and it is sometimes called
 379     "*Forecast*".
 380
 381     Example : ``hxa = ADD.get("SimulatedObservationAtOptimum")[-1]``
 382
 383   SimulationQuantiles
 384     *List of vectors*. Each element is a vector corresponding to the observed
 385     state which realize the required quantile, in the same order than the
 386     quantiles required by the user.
 387
 388     Example : ``sQuantiles = ADD.get("SimulationQuantiles")[:]``
 389
 390 .. [#] For more information on PARAVIS, see the *PARAVIS module* and its integrated help available from the main menu *Help* of the SALOME platform.
 391
 392 .. [#] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform.