2 Copyright (C) 2008-2015 EDF R&D
4 This file is part of SALOME ADAO module.
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.
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.
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
20 See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
22 Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
24 .. _section_ref_output_variables:
26 Variables and informations available at the output
27 --------------------------------------------------
29 How to obtain the information available at the output
30 +++++++++++++++++++++++++++++++++++++++++++++++++++++
32 .. index:: single: UserPostAnalysis
33 .. index:: single: algoResults
34 .. index:: single: getResults
35 .. index:: single: get
36 .. index:: single: ADD
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.
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):
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()``.
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`.
57 For example, to have the optimal state after a data assimilation or optimization
58 calculation, one use the following call::
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).
67 .. _subsection_r_o_v_Template:
69 Examples of Python scripts to obtain or treat the outputs
70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
72 .. index:: single: Template
73 .. index:: single: AnalysisPrinter
74 .. index:: single: AnalysisSaver
75 .. index:: single: AnalysisPrinterAndSaver
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.
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::
93 xa=numpy.ravel(ADD.get('Analysis')[-1])
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
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::
105 xa=numpy.ravel(ADD.get('Analysis')[-1])
106 f='/tmp/analysis.txt'
107 print 'Analysis saved in "%s"'%f
110 The chosen recording file is a text one named ``/tmp/analysis.txt``.
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::
118 xa=numpy.ravel(ADD.get('Analysis')[-1])
120 f='/tmp/analysis.txt'
121 print 'Analysis saved in "%s"'%f
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
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`.
133 Cross compliance of the information available at the output
134 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
136 .. index:: single: AlgorithmParameters
137 .. index:: single: Stored
139 The availability of information after the calculation is conditioned by the fact
140 that they have been calculated or requested.
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.
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.
156 .. _subsection_r_o_v_Inventaire:
158 Inventory of potentially available information at the output
159 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
161 .. index:: single: Dry
162 .. index:: single: Forecast
164 The set of potentially available information at the output is listed here
165 regardless of algorithms, for inventory.
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
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.
175 Example : ``Xa = ADD.get("Analysis")[-1]``
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*"
183 *Vector*, whose availability is conditioned by "*Stored*" at the input. It
184 is the background vector :math:`\mathbf{x}^b`.
186 Example : ``Xb = ADD.get("Background")``
189 *Matrix*, whose availability is conditioned by "*Stored*" at the input. It
190 is the matrix :math:`\mathbf{B}` of *a priori* background errors
193 Example : ``B = ADD.get("BackgroundError")``
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.
199 Example : ``M = ADD.get("EvolutionError")``
202 *Vector*, whose availability is conditioned by "*Stored*" at the input. It
203 is the observation vector :math:`\mathbf{y}^o`.
205 Example : ``Yo = ADD.get("Observation")``
208 *Matrix*, whose availability is conditioned by "*Stored*" at the input. It
209 is the matrix :math:`\mathbf{R}` of *a priori* observation errors
212 Example : ``R = ADD.get("ObservationError")``
214 All other information are conditioned by the algorithm and/or the user requests
215 of availability. They are the following, in alphabetical order:
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
222 Example : ``C = ADD.get("APosterioriCorrelations")[-1]``
224 APosterioriCovariance
225 *List of matrices*. Each element is an *a posteriori* error covariance
226 matrix :math:`\mathbf{A}*` of the optimal state.
228 Example : ``A = ADD.get("APosterioriCovariance")[-1]``
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}*`
235 Example : ``S = ADD.get("APosterioriStandardDeviations")[-1]``
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}*`
242 Example : ``V = ADD.get("APosterioriVariances")[-1]``
245 *List of vectors*. Each element is a vector of difference between the
246 background and the optimal state.
248 Example : ``bma = ADD.get("BMA")[-1]``
251 *List of values*. Each element is a value of the error function :math:`J`.
253 Example : ``J = ADD.get("CostFunctionJ")[:]``
256 *List of values*. Each element is a value of the error function :math:`J^b`,
257 that is of the background difference part.
259 Example : ``Jb = ADD.get("CostFunctionJb")[:]``
262 *List of values*. Each element is a value of the error function :math:`J^o`,
263 that is of the observation difference part.
265 Example : ``Jo = ADD.get("CostFunctionJo")[:]``
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
272 Example : ``JACO = ADD.get("CostFunctionJAtCurrentOptimum")[:]``
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.
279 Example : ``JbACO = ADD.get("CostFunctionJbAtCurrentOptimum")[:]``
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.
286 Example : ``JoACO = ADD.get("CostFunctionJoAtCurrentOptimum")[:]``
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.
292 Example : ``Xo = ADD.get("CurrentOptimum")[:]``
295 *List of vectors*. Each element is a usual state vector used during the
296 optimization algorithm procedure.
298 Example : ``Xs = ADD.get("CurrentState")[:]``
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.
305 Example : ``i = ADD.get("MahalanobisConsistency")[-1]``
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
312 Example : ``d = ADD.get("Innovation")[-1]``
314 InnovationAtCurrentState
315 *List of vectors*. Each element is an innovation vector at current state.
317 Example : ``ds = ADD.get("InnovationAtCurrentState")[-1]``
319 MahalanobisConsistency
320 *List of values*. Each element is a value of the Mahalanobis quality
323 Example : ``m = ADD.get("MahalanobisConsistency")[-1]``
326 *List of vectors*. Each element is a vector of difference between the
327 observation and the optimal state in the observation space.
329 Example : ``oma = ADD.get("OMA")[-1]``
332 *List of vectors*. Each element is a vector of difference between the
333 observation and the background state in the observation space.
335 Example : ``omb = ADD.get("OMB")[-1]``
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.
341 Example : ``r = ADD.get("Residu")[:]``
344 *List of values*. Each element is a value of the quality indicator
345 :math:`(\sigma^b)^2` of the background part.
347 Example : ``sb2 = ADD.get("SigmaBck")[-1]``
350 *List of values*. Each element is a value of the quality indicator
351 :math:`(\sigma^o)^2` of the observation part.
353 Example : ``so2 = ADD.get("SigmaObs")[-1]``
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*".
360 Example : ``hxb = ADD.get("SimulatedObservationAtBackground")[-1]``
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.
367 Example : ``hxo = ADD.get("SimulatedObservationAtCurrentOptimum")[-1]``
369 SimulatedObservationAtCurrentState
370 *List of vectors*. Each element is an observed vector at the current state,
371 that is, in the observation space.
373 Example : ``hxs = ADD.get("SimulatedObservationAtCurrentState")[-1]``
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
381 Example : ``hxa = ADD.get("SimulatedObservationAtOptimum")[-1]``
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.
388 Example : ``sQuantiles = ADD.get("SimulationQuantiles")[:]``
390 .. [#] For more information on PARAVIS, see the *PARAVIS module* and its integrated help available from the main menu *Help* of the SALOME platform.
392 .. [#] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform.