2 Copyright (C) 2008-2016 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 .. index:: single: SamplingTest
25 .. _section_ref_algorithm_SamplingTest:
27 Checking algorithm "*SamplingTest*"
28 -----------------------------------
33 This algorithm allows to calculate the values, linked to a :math:`\mathbf{x}`
34 state, of a general error function :math:`J` of type :math:`L^1`, :math:`L^2` or
35 :math:`L^{\infty}`, with or without weights, and of the observation operator,
36 for an priori given states sample. The default error function is the augmented
37 weighted least squares function, classicaly used in data assimilation.
39 It is useful to test the sensitivity, of the error function :math:`J`, in
40 particular, to the state :math:`\mathbf{x}` variations. When a state is not
41 observable, a *"NaN"* value is returned.
43 The sampling of the states :math:`\mathbf{x}` can be given explicitly or under
44 the form of hyper-cubes, explicit or sampled using classic distributions. Be
45 careful to the size of the hyper-cube (and then to the number of calculations)
46 that can be reached, it can be big very quickly.
48 To be visible by the user, the results of sampling has to be explicitly asked
49 for. One use for that, on the desired variable, the final saving through
50 "*UserPostAnalysis*" or the treatment during the calculation by "*observer*".
52 To perform distributed or more complex sampling, see other modules available in
53 SALOME : PARAMETRIC or OPENTURNS.
55 Optional and required commands
56 ++++++++++++++++++++++++++++++
58 .. index:: single: AlgorithmParameters
59 .. index:: single: CheckingPoint
60 .. index:: single: BackgroundError
61 .. index:: single: Observation
62 .. index:: single: ObservationError
63 .. index:: single: ObservationOperator
64 .. index:: single: SampleAsnUplet
65 .. index:: single: SampleAsExplicitHyperCube
66 .. index:: single: SampleAsMinMaxStepHyperCube
67 .. index:: single: SampleAsIndependantRandomVariables
68 .. index:: single: QualityCriterion
69 .. index:: single: SetDebug
70 .. index:: single: SetSeed
71 .. index:: single: StoreSupplementaryCalculations
73 The general required commands, available in the editing user interface, are the
77 *Required command*. This indicates the vector used as the state around which
78 to perform the required check, noted :math:`\mathbf{x}` and similar to the
79 background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
82 *Required command*. This indicates the background error covariance matrix,
83 previously noted as :math:`\mathbf{B}`. Its value is defined as a "*Matrix*"
84 type object, a "*ScalarSparseMatrix*" type object, or a
85 "*DiagonalSparseMatrix*" type object.
88 *Required command*. This indicates the observation vector used for data
89 assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
90 is defined as a "*Vector*" or a *VectorSerie* type object.
93 *Required command*. This indicates the observation error covariance matrix,
94 previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
95 object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
99 *Required command*. This indicates the observation operator, previously
100 noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
101 results :math:`\mathbf{y}` to be compared to observations
102 :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
103 a "*Matrix*" type one. In the case of "*Function*" type, different
104 functional forms can be used, as described in the section
105 :ref:`section_ref_operator_requirements`. If there is some control :math:`U`
106 included in the observation, the operator has to be applied to a pair
109 The general optional commands, available in the editing user interface, are
110 indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters
111 of the command "*AlgorithmParameters*" allow to choose the specific options,
112 described hereafter, of the algorithm. See
113 :ref:`section_ref_options_Algorithm_Parameters` for the good use of this
116 The options of the algorithm are the following:
119 This key describes the calculations points as a list of n-uplets, each
120 n-uplet being a state.
122 Example : ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` for 3 points in a state space of dimension 4
124 SampleAsExplicitHyperCube
125 This key describes the calculations points as an hyper-cube, from a given
126 list of explicit sampling of each variable as a list. That is then a list of
127 lists, each of them being potentially of different size.
129 Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` for a state space of dimension 2
131 SampleAsMinMaxStepHyperCube
132 This key describes the calculations points as an hyper-cube, from a given
133 list of implicit sampling of each variable by a triplet *[min,max,step]*.
134 That is then a list of the same size than the one of the state. The bounds
137 Example : ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` for a state space of dimension 2
139 SampleAsIndependantRandomVariables
140 This key describes the calculations points as an hyper-cube, for which the
141 points on each axis come from a independant random sampling of the axis
142 variable, under the specification of the distribution, its parameters and
143 the number of points in the sample, as a list ``['distribution',
144 [parametres], nombre]`` for each axis. The possible distributions are
145 'normal' of parameters (mean,std), 'lognormal' of parameters (mean,sigma),
146 'uniform' of parameters (low,high), or 'weibull' of parameter (shape). That
147 is then a list of the same size than the one of the state.
149 Example : ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` for a state space of dimension 2
152 This key indicates the quality criterion, used to find the state estimate.
153 The default is the usual data assimilation criterion named "DA", the
154 augmented weighted least squares. The possible criteria has to be in the
155 following list, where the equivalent names are indicated by the sign "=":
156 ["AugmentedWeightedLeastSquares"="AWLS"="DA", "WeightedLeastSquares"="WLS",
157 "LeastSquares"="LS"="L2", "AbsoluteValue"="L1", "MaximumError"="ME"].
159 Example : ``{"QualityCriterion":"DA"}``
162 This key requires the activation, or not, of the debug mode during the
163 function evaluation. The default is "True", the choices are "True" or
166 Example : ``{"SetDebug":False}``
169 This key allow to give an integer in order to fix the seed of the random
170 generator used to generate the ensemble. A convenient value is for example
171 1000. By default, the seed is left uninitialized, and so use the default
172 initialization from the computer.
174 Example : ``{"SetSeed":1000}``
176 StoreSupplementaryCalculations
177 This list indicates the names of the supplementary variables that can be
178 available at the end of the algorithm. It involves potentially costly
179 calculations or memory consumptions. The default is a void list, none of
180 these variables being calculated and stored by default. The possible names
181 are in the following list: ["CostFunctionJ", "CurrentState",
182 "InnovationAtCurrentState", "SimulatedObservationAtCurrentState"].
184 Example : ``{"StoreSupplementaryCalculations":["CostFunctionJ", "SimulatedObservationAtCurrentState"]}``
186 Information and variables available at the end of the algorithm
187 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
189 At the output, after executing the algorithm, there are variables and
190 information originating from the calculation. The description of
191 :ref:`section_ref_output_variables` show the way to obtain them by the method
192 named ``get`` of the variable "*ADD*" of the post-processing. The input
193 variables, available to the user at the output in order to facilitate the
194 writing of post-processing procedures, are described in the
195 :ref:`subsection_r_o_v_Inventaire`.
197 The unconditional outputs of the algorithm are the following:
200 *List of values*. Each element is a value of the error function :math:`J`.
202 Example : ``J = ADD.get("CostFunctionJ")[:]``
205 *List of values*. Each element is a value of the error function :math:`J^b`,
206 that is of the background difference part.
208 Example : ``Jb = ADD.get("CostFunctionJb")[:]``
211 *List of values*. Each element is a value of the error function :math:`J^o`,
212 that is of the observation difference part.
214 Example : ``Jo = ADD.get("CostFunctionJo")[:]``
216 The conditional outputs of the algorithm are the following:
219 *List of vectors*. Each element is a usual state vector used during the
220 optimization algorithm procedure.
222 Example : ``Xs = ADD.get("CurrentState")[:]``
224 InnovationAtCurrentState
225 *List of vectors*. Each element is an innovation vector at current state.
227 Example : ``ds = ADD.get("InnovationAtCurrentState")[-1]``
229 SimulatedObservationAtCurrentState
230 *List of vectors*. Each element is an observed vector at the current state,
231 that is, in the observation space.
233 Example : ``hxs = ADD.get("SimulatedObservationAtCurrentState")[-1]``
238 References to other sections:
239 - :ref:`section_ref_algorithm_FunctionTest`
241 References to other SALOME modules:
242 - PARAMETRIC, see the *User guide of PARAMETRIC module* in the main "*Help*" menu of SALOME platform
243 - OPENTURNS, see the *User guide of OPENTURNS module* in the main "*Help*" menu of SALOME platform