doc/en/ref_algorithm_SamplingTest.rst

   1 ..
   2    Copyright (C) 2008-2018 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, classically 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 OPENTURNS module available
  53 in SALOME.
  54
  55 Optional and required commands
  56 ++++++++++++++++++++++++++++++
  57
  58 The general required commands, available in the editing user interface, are the
  59 following:
  60
  61   .. include:: snippets/CheckingPoint.rst
  62
  63   .. include:: snippets/BackgroundError.rst
  64
  65   .. include:: snippets/Observation.rst
  66
  67   .. include:: snippets/ObservationError.rst
  68
  69   .. include:: snippets/ObservationOperator.rst
  70
  71 The general optional commands, available in the editing user interface, are
  72 indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters
  73 of the command "*AlgorithmParameters*" allow to choose the specific options,
  74 described hereafter, of the algorithm. See
  75 :ref:`section_ref_options_Algorithm_Parameters` for the good use of this
  76 command.
  77
  78 The options of the algorithm are the following:
  79 .. index:: single: SampleAsnUplet
  80 .. index:: single: SampleAsExplicitHyperCube
  81 .. index:: single: SampleAsMinMaxStepHyperCube
  82 .. index:: single: SampleAsIndependantRandomVariables
  83
  84   SampleAsnUplet
  85     This key describes the calculations points as a list of n-uplets, each
  86     n-uplet being a state.
  87
  88     Example :
  89     ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` for 3 points in a state space of dimension 4
  90
  91   SampleAsExplicitHyperCube
  92     This key describes the calculations points as an hyper-cube, from a given
  93     list of explicit sampling of each variable as a list. That is then a list of
  94     lists, each of them being potentially of different size.
  95
  96     Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` for a state space of dimension 2
  97
  98   SampleAsMinMaxStepHyperCube
  99     This key describes the calculations points as an hyper-cube, from a given
 100     list of implicit sampling of each variable by a triplet *[min,max,step]*.
 101     That is then a list of the same size than the one of the state. The bounds
 102     are included.
 103
 104     Example :
 105     ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` for a state space of dimension 2
 106
 107   SampleAsIndependantRandomVariables
 108     This key describes the calculations points as an hyper-cube, for which the
 109     points on each axis come from a independent random sampling of the axis
 110     variable, under the specification of the distribution, its parameters and
 111     the number of points in the sample, as a list ``['distribution',
 112     [parameters], number]`` for each axis. The possible distributions are
 113     'normal' of parameters (mean,std), 'lognormal' of parameters (mean,sigma),
 114     'uniform' of parameters (low,high), or 'weibull' of parameter (shape). That
 115     is then a list of the same size than the one of the state.
 116
 117     Example :
 118     ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` for a state space of dimension 2
 119
 120   .. include:: snippets/QualityCriterion.rst
 121
 122   .. include:: snippets/SetDebug.rst
 123
 124   .. include:: snippets/SetSeed.rst
 125
 126   StoreSupplementaryCalculations
 127     .. index:: single: StoreSupplementaryCalculations
 128
 129     This list indicates the names of the supplementary variables that can be
 130     available at the end of the algorithm. It involves potentially costly
 131     calculations or memory consumptions. The default is a void list, none of
 132     these variables being calculated and stored by default. The possible names
 133     are in the following list: ["CostFunctionJ", "CostFunctionJb",
 134     "CostFunctionJo", "CurrentState", "InnovationAtCurrentState",
 135     "SimulatedObservationAtCurrentState"].
 136
 137     Example :
 138     ``{"StoreSupplementaryCalculations":["CostFunctionJ", "SimulatedObservationAtCurrentState"]}``
 139
 140 Information and variables available at the end of the algorithm
 141 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 142
 143 At the output, after executing the algorithm, there are variables and
 144 information originating from the calculation. The description of
 145 :ref:`section_ref_output_variables` show the way to obtain them by the method
 146 named ``get`` of the variable "*ADD*" of the post-processing. The input
 147 variables, available to the user at the output in order to facilitate the
 148 writing of post-processing procedures, are described in the
 149 :ref:`subsection_r_o_v_Inventaire`.
 150
 151 The unconditional outputs of the algorithm are the following:
 152
 153   .. include:: snippets/CostFunctionJ.rst
 154
 155   .. include:: snippets/CostFunctionJb.rst
 156
 157   .. include:: snippets/CostFunctionJo.rst
 158
 159 The conditional outputs of the algorithm are the following:
 160
 161   .. include:: snippets/CurrentState.rst
 162
 163   .. include:: snippets/InnovationAtCurrentState.rst
 164
 165   .. include:: snippets/SimulatedObservationAtCurrentState.rst
 166
 167 See also
 168 ++++++++
 169
 170 References to other sections:
 171   - :ref:`section_ref_algorithm_FunctionTest`
 172
 173 References to other SALOME modules:
 174   - OPENTURNS, see the *User guide of OPENTURNS module* in the main "*Help*" menu of SALOME platform