2 Copyright (C) 2008-2014 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 This is a useful algorithm to test the sensitivity, of the error function
40 :math:`J` in particular, to the state :math:`\mathbf{x}` variations. When a
41 state is not 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 hypercubes.
46 Optional and required commands
47 ++++++++++++++++++++++++++++++
49 .. index:: single: CheckingPoint
50 .. index:: single: BackgroundError
51 .. index:: single: Observation
52 .. index:: single: ObservationError
53 .. index:: single: ObservationOperator
54 .. index:: single: SampleAsnUplet
55 .. index:: single: SampleAsExplicitHyperCube
56 .. index:: single: SampleAsMinMaxStepHyperCube
57 .. index:: single: QualityCriterion
58 .. index:: single: SetDebug
59 .. index:: single: StoreSupplementaryCalculations
61 The general required commands, available in the editing user interface, are the
65 *Required command*. This indicates the vector used as the state around which
66 to perform the required check, noted :math:`\mathbf{x}` and similar to the
67 background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
70 *Required command*. This indicates the background error covariance matrix,
71 previously noted as :math:`\mathbf{B}`. Its value is defined as a "*Matrix*"
72 type object, a "*ScalarSparseMatrix*" type object, or a
73 "*DiagonalSparseMatrix*" type object.
76 *Required command*. This indicates the observation vector used for data
77 assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
78 is defined as a "*Vector*" or a *VectorSerie* type object.
81 *Required command*. This indicates the observation error covariance matrix,
82 previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
83 object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
87 *Required command*. This indicates the observation operator, previously
88 noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
89 results :math:`\mathbf{y}` to be compared to observations
90 :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
91 a "*Matrix*" type one. In the case of "*Function*" type, different
92 functional forms can be used, as described in the section
93 :ref:`section_ref_operator_requirements`. If there is some control :math:`U`
94 included in the observation, the operator has to be applied to a pair
97 The general optional commands, available in the editing user interface, are
98 indicated in :ref:`section_ref_assimilation_keywords`. In particular, the
99 optional command "*AlgorithmParameters*" allows to choose the specific options,
100 described hereafter, of the algorithm. See
101 :ref:`section_ref_options_AlgorithmParameters` for the good use of this command.
103 The options of the algorithm are the following:
106 This key describes the calculations points as a list of n-uplets, each
107 n-uplet being a state.
109 Example : ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` for 3 points in a state space of dimension 4
111 SampleAsExplicitHyperCube
112 This key describes the calculations points as an hypercube, from which one
113 gives the list of sampling of each variable as a list. That is then a list
114 of lists, each of them being potentially of different size.
116 Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.],[-2,2,1]]}`` for a state space of dimension 2
118 SampleAsMinMaxStepHyperCube
119 This key describes the calculations points as an hypercube from which one
120 the sampling of each variable by a triplet *[min,max,step]*. That is then a
121 list of the same size than the one of the state. The bounds are included.
123 Example : ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` for a state space of dimension 2
126 This key indicates the quality criterion, used to find the state estimate.
127 The default is the usual data assimilation criterion named "DA", the
128 augmented weighted least squares. The possible criteria has to be in the
129 following list, where the equivalent names are indicated by the sign "=":
130 ["AugmentedWeightedLeastSquares"="AWLS"="DA", "WeightedLeastSquares"="WLS",
131 "LeastSquares"="LS"="L2", "AbsoluteValue"="L1", "MaximumError"="ME"].
133 Example : ``{"QualityCriterion":"DA"}``
136 This key requires the activation, or not, of the debug mode during the
137 function evaluation. The default is "True", the choices are "True" or
140 Example : ``{"SetDebug":False}``
142 StoreSupplementaryCalculations
143 This list indicates the names of the supplementary variables that can be
144 available at the end of the algorithm. It involves potentially costly
145 calculations or memory consumptions. The default is a void list, none of
146 these variables being calculated and stored by default. The possible names
147 are in the following list: ["CostFunctionJ", "CurrentState", "Innovation",
150 Example : ``{"StoreSupplementaryCalculations":["CostFunctionJ", "ObservedState"]}``
155 References to other sections:
156 - :ref:`section_ref_algorithm_FunctionTest`