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 .. 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 perform distributed or complex sampling, see other modules available in
49 SALOME : PARAMETRIC or OPENTURNS.
51 Optional and required commands
52 ++++++++++++++++++++++++++++++
54 .. index:: single: AlgorithmParameters
55 .. index:: single: CheckingPoint
56 .. index:: single: BackgroundError
57 .. index:: single: Observation
58 .. index:: single: ObservationError
59 .. index:: single: ObservationOperator
60 .. index:: single: SampleAsnUplet
61 .. index:: single: SampleAsExplicitHyperCube
62 .. index:: single: SampleAsMinMaxStepHyperCube
63 .. index:: single: SampleAsIndependantRandomVariables
64 .. index:: single: QualityCriterion
65 .. index:: single: SetDebug
66 .. index:: single: SetSeed
67 .. index:: single: StoreSupplementaryCalculations
69 The general required commands, available in the editing user interface, are the
73 *Required command*. This indicates the vector used as the state around which
74 to perform the required check, noted :math:`\mathbf{x}` and similar to the
75 background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
78 *Required command*. This indicates the background error covariance matrix,
79 previously noted as :math:`\mathbf{B}`. Its value is defined as a "*Matrix*"
80 type object, a "*ScalarSparseMatrix*" type object, or a
81 "*DiagonalSparseMatrix*" type object.
84 *Required command*. This indicates the observation vector used for data
85 assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
86 is defined as a "*Vector*" or a *VectorSerie* type object.
89 *Required command*. This indicates the observation error covariance matrix,
90 previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
91 object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
95 *Required command*. This indicates the observation operator, previously
96 noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
97 results :math:`\mathbf{y}` to be compared to observations
98 :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
99 a "*Matrix*" type one. In the case of "*Function*" type, different
100 functional forms can be used, as described in the section
101 :ref:`section_ref_operator_requirements`. If there is some control :math:`U`
102 included in the observation, the operator has to be applied to a pair
105 The general optional commands, available in the editing user interface, are
106 indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters
107 of the command "*AlgorithmParameters*" allow to choose the specific options,
108 described hereafter, of the algorithm. See
109 :ref:`section_ref_options_Algorithm_Parameters` for the good use of this
112 The options of the algorithm are the following:
115 This key describes the calculations points as a list of n-uplets, each
116 n-uplet being a state.
118 Example : ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` for 3 points in a state space of dimension 4
120 SampleAsExplicitHyperCube
121 This key describes the calculations points as an hyper-cube, from a given
122 list of explicit sampling of each variable as a list. That is then a list of
123 lists, each of them being potentially of different size.
125 Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.],[-2,2,1]]}`` for a state space of dimension 2
127 SampleAsMinMaxStepHyperCube
128 This key describes the calculations points as an hyper-cube, from a given
129 list of implicit sampling of each variable by a triplet *[min,max,step]*.
130 That is then a list of the same size than the one of the state. The bounds
133 Example : ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` for a state space of dimension 2
135 SampleAsIndependantRandomVariables
136 This key describes the calculations points as an hyper-cube, for which the
137 points on each axis come from a independant random sampling of the axis
138 variable, under the specification of the distribution, its parameters and
139 the number of points in the sample, as a list ``['distribution',
140 [parametres], nombre]`` for each axis. The possible distributions are
141 'normal' of parameters (mean,std), 'lognormal' of parameters (mean,sigma),
142 'uniform' of parameters (low,high), or 'weibull' of parameter (shape). That
143 is then a list of the same size than the one of the state.
145 Example : ``{"SampleAsIndependantRandomVariables":[['normal',[0.,1.],3],['uniform',[-2,2],4]]`` for a state space of dimension 2
148 This key indicates the quality criterion, used to find the state estimate.
149 The default is the usual data assimilation criterion named "DA", the
150 augmented weighted least squares. The possible criteria has to be in the
151 following list, where the equivalent names are indicated by the sign "=":
152 ["AugmentedWeightedLeastSquares"="AWLS"="DA", "WeightedLeastSquares"="WLS",
153 "LeastSquares"="LS"="L2", "AbsoluteValue"="L1", "MaximumError"="ME"].
155 Example : ``{"QualityCriterion":"DA"}``
158 This key requires the activation, or not, of the debug mode during the
159 function evaluation. The default is "True", the choices are "True" or
162 Example : ``{"SetDebug":False}``
165 This key allow to give an integer in order to fix the seed of the random
166 generator used to generate the ensemble. A convenient value is for example
167 1000. By default, the seed is left uninitialized, and so use the default
168 initialization from the computer.
170 Example : ``{"SetSeed":1000}``
172 StoreSupplementaryCalculations
173 This list indicates the names of the supplementary variables that can be
174 available at the end of the algorithm. It involves potentially costly
175 calculations or memory consumptions. The default is a void list, none of
176 these variables being calculated and stored by default. The possible names
177 are in the following list: ["CostFunctionJ", "CurrentState", "Innovation",
178 "SimulatedObservationAtCurrentState"].
180 Example : ``{"StoreSupplementaryCalculations":["CostFunctionJ", "SimulatedObservationAtCurrentState"]}``
185 References to other sections:
186 - :ref:`section_ref_algorithm_FunctionTest`
188 References to other SALOME modules:
189 - PARAMETRIC, see the *User guide of PARAMETRIC module* in the main "*Help*" menu of SALOME platform
190 - OPENTURNS, see the *User guide of OPENTURNS module* in the main "*Help*" menu of SALOME platform