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 The set of potentially available information at the output is listed here
 162 regardless of algorithms, for inventory.
 163
 164 The optimal state is an information that is always naturally available after an
 165 optimization or a data assimilation calculation. It is indicated by the
 166 following keywords:
 167
 168   Analysis
 169     *List of vectors*. Each element is an optimal state :math:`\mathbf{x}*` in
 170     optimization or an analysis :math:`\mathbf{x}^a` in data assimilation.
 171
 172     Example : ``Xa = ADD.get("Analysis")[-1]``
 173
 174 The following variables are input variables.  They are made available to the
 175 user at the output in order to facilitate the writing of post-processing
 176 procedures, and are conditioned by a user request using a boolean "*Stored*"
 177 at the input.
 178
 179   Background
 180     *Vector*, whose availability is conditioned by "*Stored*" at the input. It
 181     is the background vector :math:`\mathbf{x}^b`.
 182
 183     Example : ``Xb = ADD.get("Background")``
 184
 185   BackgroundError
 186     *Matrix*, whose availability is conditioned by "*Stored*" at the input. It
 187     is the matrix :math:`\mathbf{B}` of *a priori* background errors
 188     covariances.
 189
 190     Example : ``B = ADD.get("BackgroundError")``
 191
 192   EvolutionError
 193     *Matrix*, whose availability is conditioned by "*Stored*" at the input. It
 194     is the matrix :math:`\mathbf{M}` of *a priori* evolution errors covariances.
 195
 196     Example : ``M = ADD.get("EvolutionError")``
 197
 198   Observation
 199     *Vector*, whose availability is conditioned by "*Stored*" at the input. It
 200     is the observation vector :math:`\mathbf{y}^o`.
 201
 202     Example : ``Yo = ADD.get("Observation")``
 203
 204   ObservationError
 205     *Matrix*, whose availability is conditioned by "*Stored*" at the input. It
 206     is the matrix :math:`\mathbf{R}` of *a priori* observation errors
 207     covariances.
 208
 209     Example : ``R = ADD.get("ObservationError")``
 210
 211 All other information are conditioned by the algorithm and/or the user requests
 212 of availability. They are the following, in alphabetical order:
 213
 214   APosterioriCorrelations
 215     *List of matrices*. Each element is an *a posteriori* error correlations
 216     matrix of the optimal state, coming from the :math:`\mathbf{A}*` covariance
 217     matrix.
 218
 219     Exemple : ``C = ADD.get("APosterioriCorrelations")[-1]``
 220
 221   APosterioriCovariance
 222     *List of matrices*. Each element is an *a posteriori* error covariance
 223     matrix :math:`\mathbf{A}*` of the optimal state.
 224
 225     Example : ``A = ADD.get("APosterioriCovariance")[-1]``
 226
 227   APosterioriStandardDeviations
 228     *List of matrices*. Each element is an *a posteriori* error standard errors
 229     diagonal matrix of the optimal state, coming from the :math:`\mathbf{A}*`
 230     covariance matrix.
 231
 232     Exemple : ``S = ADD.get("APosterioriStandardDeviations")[-1]``
 233
 234   APosterioriVariances
 235     *List of matrices*. Each element is an *a posteriori* error variances
 236     diagonal matrix of the optimal state, coming from the :math:`\mathbf{A}*`
 237     covariance matrix.
 238
 239     Exemple : ``V = ADD.get("APosterioriVariances")[-1]``
 240
 241   BMA
 242     *List of vectors*. Each element is a vector of difference between the
 243     background and the optimal state.
 244
 245     Example : ``bma = ADD.get("BMA")[-1]``
 246
 247   CostFunctionJ
 248     *List of values*. Each element is a value of the error function :math:`J`.
 249
 250     Example : ``J = ADD.get("CostFunctionJ")[:]``
 251
 252   CostFunctionJb
 253     *List of values*. Each element is a value of the error function :math:`J^b`,
 254     that is of the background difference part.
 255
 256     Example : ``Jb = ADD.get("CostFunctionJb")[:]``
 257
 258   CostFunctionJo
 259     *List of values*. Each element is a value of the error function :math:`J^o`,
 260     that is of the observation difference part.
 261
 262     Example : ``Jo = ADD.get("CostFunctionJo")[:]``
 263
 264   CurrentOptimum
 265     *List of vectors*. Each element is the optimal state obtained at the current
 266     step of the optimization algorithm. It is not necessarely the last state.
 267
 268     Exemple : ``Xo = ADD.get("CurrentOptimum")[:]``
 269
 270   CurrentState
 271     *List of vectors*. Each element is a usual state vector used during the
 272     optimization algorithm procedure.
 273
 274     Example : ``Xs = ADD.get("CurrentState")[:]``
 275
 276   IndexOfOptimum
 277     *List of integers*. Each element is the iteration index of the optimum
 278     obtained at the current step the optimization algorithm. It is not
 279     necessarely the number of the last iteration.
 280
 281     Exemple : ``i = ADD.get("MahalanobisConsistency")[-1]``
 282
 283   Innovation
 284     *List of vectors*. Each element is an innovation vector, which is in static
 285     the difference between the optimal and the background, and in dynamic the
 286     evolution increment.
 287
 288     Example : ``d = ADD.get("Innovation")[-1]``
 289
 290   MahalanobisConsistency
 291     *List of values*. Each element is a value of the Mahalanobis quality
 292     indicator.
 293
 294     Example : ``m = ADD.get("MahalanobisConsistency")[-1]``
 295
 296   OMA
 297     *List of vectors*. Each element is a vector of difference between the
 298     observation and the optimal state in the observation space.
 299
 300     Example : ``oma = ADD.get("OMA")[-1]``
 301
 302   OMB
 303     *List of vectors*. Each element is a vector of difference between the
 304     observation and the background state in the observation space.
 305
 306     Example : ``omb = ADD.get("OMB")[-1]``
 307
 308   SigmaBck2
 309     *List of values*. Each element is a value of the quality indicator
 310     :math:`(\sigma^b)^2` of the background part.
 311
 312     Example : ``sb2 = ADD.get("SigmaBck")[-1]``
 313
 314   SigmaObs2
 315     *List of values*. Each element is a value of the quality indicator
 316     :math:`(\sigma^o)^2` of the observation part.
 317
 318     Example : ``so2 = ADD.get("SigmaObs")[-1]``
 319
 320   SimulatedObservationAtBackground
 321     *List of vectors*. Each element is a vector of observation simulated from
 322     the background :math:`\mathbf{x}^b`.
 323
 324     Example : ``hxb = ADD.get("SimulatedObservationAtBackground")[-1]``
 325
 326   SimulatedObservationAtCurrentOptimum
 327     *List of vectors*. Each element is a vector of observation simulated from
 328     the optimal state obtained at the current step the optimization algorithm,
 329     that is, in the observation space.
 330
 331     Exemple : ``hxo = ADD.get("SimulatedObservationAtCurrentOptimum")[-1]``
 332
 333   SimulatedObservationAtCurrentState
 334     *List of vectors*. Each element is an observed vector at the current state,
 335     that is, in the observation space.
 336
 337     Example : ``hxs = ADD.get("SimulatedObservationAtCurrentState")[-1]``
 338
 339   SimulatedObservationAtOptimum
 340     *List of vectors*. Each element is a vector of observation simulated from
 341     the analysis or optimal state :math:`\mathbf{x}^a`.
 342
 343     Example : ``hxa = ADD.get("SimulatedObservationAtOptimum")[-1]``
 344
 345   SimulationQuantiles
 346     *List of vectors*. Each element is a vector corresponding to the observed
 347     state which realize the required quantile, in the same order than the
 348     quantiles required by the user.
 349
 350     Example : ``sQuantiles = ADD.get("SimulationQuantiles")[:]``
 351
 352 .. [#] For more information on PARAVIS, see the *PARAVIS module* and its integrated help available from the main menu *Help* of the SALOME platform.
 353
 354 .. [#] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform.