doc/en/ref_algorithm_SamplingTest.rst

   1 ..
   2    Copyright (C) 2008-2016 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 .. index:: single: SamplingTest
  25 .. _section_ref_algorithm_SamplingTest:
  26
  27 Checking algorithm "*SamplingTest*"
  28 -----------------------------------
  29
  30 Description
  31 +++++++++++
  32
  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.
  38
  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.
  42
  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.
  47
  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*".
  51
  52 To perform distributed or more complex sampling, see other modules available in
  53 SALOME : PARAMETRIC or OPENTURNS.
  54
  55 Optional and required commands
  56 ++++++++++++++++++++++++++++++
  57
  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
  72
  73 The general required commands, available in the editing user interface, are the
  74 following:
  75
  76   CheckingPoint
  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.
  80
  81   BackgroundError
  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.
  86
  87   Observation
  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.
  91
  92   ObservationError
  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*"
  96     type object.
  97
  98   ObservationOperator
  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
 107     :math:`(X,U)`.
 108
 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
 114 command.
 115
 116 The options of the algorithm are the following:
 117
 118   SampleAsnUplet
 119     This key describes the calculations points as a list of n-uplets, each
 120     n-uplet being a state.
 121
 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
 123
 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.
 128
 129     Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` for a state space of dimension 2
 130
 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
 135     are included.
 136
 137     Example : ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` for a state space of dimension 2
 138
 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.
 148
 149     Example : ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` for a state space of dimension 2
 150
 151   QualityCriterion
 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"].
 158
 159     Example : ``{"QualityCriterion":"DA"}``
 160
 161   SetDebug
 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
 164     "False".
 165
 166     Example : ``{"SetDebug":False}``
 167
 168   SetSeed
 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.
 173
 174     Example : ``{"SetSeed":1000}``
 175
 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"].
 183
 184     Example : ``{"StoreSupplementaryCalculations":["CostFunctionJ", "SimulatedObservationAtCurrentState"]}``
 185
 186 Information and variables available at the end of the algorithm
 187 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 188
 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`.
 196
 197 The unconditional outputs of the algorithm are the following:
 198
 199   CostFunctionJ
 200     *List of values*. Each element is a value of the error function :math:`J`.
 201
 202     Example : ``J = ADD.get("CostFunctionJ")[:]``
 203
 204   CostFunctionJb
 205     *List of values*. Each element is a value of the error function :math:`J^b`,
 206     that is of the background difference part.
 207
 208     Example : ``Jb = ADD.get("CostFunctionJb")[:]``
 209
 210   CostFunctionJo
 211     *List of values*. Each element is a value of the error function :math:`J^o`,
 212     that is of the observation difference part.
 213
 214     Example : ``Jo = ADD.get("CostFunctionJo")[:]``
 215
 216 The conditional outputs of the algorithm are the following:
 217
 218   CurrentState
 219     *List of vectors*. Each element is a usual state vector used during the
 220     optimization algorithm procedure.
 221
 222     Example : ``Xs = ADD.get("CurrentState")[:]``
 223
 224   InnovationAtCurrentState
 225     *List of vectors*. Each element is an innovation vector at current state.
 226
 227     Example : ``ds = ADD.get("InnovationAtCurrentState")[-1]``
 228
 229   SimulatedObservationAtCurrentState
 230     *List of vectors*. Each element is an observed vector at the current state,
 231     that is, in the observation space.
 232
 233     Example : ``hxs = ADD.get("SimulatedObservationAtCurrentState")[-1]``
 234
 235 See also
 236 ++++++++
 237
 238 References to other sections:
 239   - :ref:`section_ref_algorithm_FunctionTest`
 240
 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