doc/en/ref_algorithm_SamplingTest.rst

   1 ..
   2    Copyright (C) 2008-2015 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 perform distributed or complex sampling, see other modules available in
  49 SALOME : PARAMETRIC or OPENTURNS.
  50
  51 Optional and required commands
  52 ++++++++++++++++++++++++++++++
  53
  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
  68
  69 The general required commands, available in the editing user interface, are the
  70 following:
  71
  72   CheckingPoint
  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.
  76
  77   BackgroundError
  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.
  82
  83   Observation
  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.
  87
  88   ObservationError
  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*"
  92     type object.
  93
  94   ObservationOperator
  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
 103     :math:`(X,U)`.
 104
 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
 110 command.
 111
 112 The options of the algorithm are the following:
 113
 114   SampleAsnUplet
 115     This key describes the calculations points as a list of n-uplets, each
 116     n-uplet being a state.
 117
 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
 119
 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.
 124
 125     Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.],[-2,2,1]]}`` for a state space of dimension 2
 126
 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
 131     are included.
 132
 133     Example : ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` for a state space of dimension 2
 134
 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.
 144
 145     Example : ``{"SampleAsIndependantRandomVariables":[['normal',[0.,1.],3],['uniform',[-2,2],4]]`` for a state space of dimension 2
 146
 147   QualityCriterion
 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"].
 154
 155     Example : ``{"QualityCriterion":"DA"}``
 156
 157   SetDebug
 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
 160     "False".
 161
 162     Example : ``{"SetDebug":False}``
 163
 164   SetSeed
 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.
 169
 170     Example : ``{"SetSeed":1000}``
 171
 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"].
 179
 180     Example : ``{"StoreSupplementaryCalculations":["CostFunctionJ", "SimulatedObservationAtCurrentState"]}``
 181
 182 See also
 183 ++++++++
 184
 185 References to other sections:
 186   - :ref:`section_ref_algorithm_FunctionTest`
 187
 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