doc/en/ref_algorithm_SamplingTest.rst

   1 ..
   2    Copyright (C) 2008-2023 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 .. ------------------------------------ ..
  31 .. include:: snippets/Header2Algo01.rst
  32
  33 This test algorithm is used to establish the collection of values of an error
  34 functional :math:`J` of type :math:`L^1`, :math:`L^2` or :math:`L^{\infty}`,
  35 with or without weights, using the observation operator :math:`\mathcal{H}`,
  36 for an a priori given sample of states :math:`\mathbf{x}`. The default error
  37 functional is the augmented weighted least squares functional, classically used
  38 in data assimilation, using in addition to observations :math:`\mathbf{y}^o`.
  39
  40 This test is useful for analyzing the sensitivity of the functional :math:`J`
  41 to variations in the state :math:`\mathbf{x}` in particular.
  42
  43 The sampling of the states :math:`\mathbf{x}` can be given explicitly or under
  44 form of hypercubes, explicit or sampled according to classic distributions, or
  45 using Latin hypercube sampling (LHS). The computations are optimized according
  46 to the computer resources available and the options requested by the user. You
  47 can refer to the :ref:`section_ref_sampling_requirements` for an illustration
  48 of sampling. Beware of the size of the hypercube (and then to the number of
  49 computations) that can be reached, it can grow quickly to be quite large. When
  50 a state is not observable, a *"NaN"* value is returned.
  51
  52 It is also possible to supply a set of simulations :math:`\mathbf{y}` already
  53 established elsewhere (so there's no explicit need for an operator
  54 :math:`\mathcal{H}`), which are implicitly associated with a set of state
  55 samples :math:`\mathbf{x}`. In this case where the set of simulations is
  56 provided, it is imperative to also provide the set of states :math:`\mathbf{x}`
  57 by explicit sampling, whose state order corresponds to the order of the
  58 simulations :math:`\mathbf{y}`.
  59
  60 To access the calculated information, the results of the sampling or
  61 simulations must be requested **explicitly** to avoid storage difficulties (if
  62 no results are requested, nothing is available). One use for that, on the
  63 desired variable, the final saving through "*UserPostAnalysis*" or the
  64 treatment during the calculation by well suited "*observer*".
  65
  66 .. ------------------------------------ ..
  67 .. include:: snippets/Header2Algo02.rst
  68
  69 .. include:: snippets/CheckingPoint.rst
  70
  71 .. include:: snippets/BackgroundError.rst
  72
  73 .. include:: snippets/Observation.rst
  74
  75 .. include:: snippets/ObservationError.rst
  76
  77 .. include:: snippets/ObservationOperator.rst
  78
  79 .. ------------------------------------ ..
  80 .. include:: snippets/Header2Algo03Chck.rst
  81
  82 .. include:: snippets/EnsembleOfSnapshots.rst
  83
  84 .. include:: snippets/QualityCriterion.rst
  85
  86 .. include:: snippets/SampleAsExplicitHyperCube.rst
  87
  88 .. include:: snippets/SampleAsIndependantRandomVariables.rst
  89
  90 .. include:: snippets/SampleAsMinMaxLatinHyperCube.rst
  91
  92 .. include:: snippets/SampleAsMinMaxStepHyperCube.rst
  93
  94 .. include:: snippets/SampleAsnUplet.rst
  95
  96 .. include:: snippets/SetDebug.rst
  97
  98 .. include:: snippets/SetSeed.rst
  99
 100 StoreSupplementaryCalculations
 101   .. index:: single: StoreSupplementaryCalculations
 102
 103   *List of names*. This list indicates the names of the supplementary
 104   variables, that can be available during or at the end of the algorithm, if
 105   they are initially required by the user. Their availability involves,
 106   potentially, costly calculations or memory consumptions. The default is then
 107   a void list, none of these variables being calculated and stored by default
 108   (excepted the unconditional variables). The possible names are in the
 109   following list (the detailed description of each named variable is given in
 110   the following part of this specific algorithmic documentation, in the
 111   sub-section "*Information and variables available at the end of the
 112   algorithm*"): [
 113   "CostFunctionJ",
 114   "CostFunctionJb",
 115   "CostFunctionJo",
 116   "CurrentState",
 117   "EnsembleOfSimulations",
 118   "EnsembleOfStates",
 119   "Innovation",
 120   "InnovationAtCurrentState",
 121   "SimulatedObservationAtCurrentState",
 122   ].
 123
 124   Example :
 125   ``{"StoreSupplementaryCalculations":["CurrentState", "Residu"]}``
 126
 127 .. ------------------------------------ ..
 128 .. include:: snippets/Header2Algo04.rst
 129
 130 .. include:: snippets/CostFunctionJ.rst
 131
 132 .. include:: snippets/CostFunctionJb.rst
 133
 134 .. include:: snippets/CostFunctionJo.rst
 135
 136 .. ------------------------------------ ..
 137 .. include:: snippets/Header2Algo05.rst
 138
 139 .. include:: snippets/CostFunctionJ.rst
 140
 141 .. include:: snippets/CostFunctionJb.rst
 142
 143 .. include:: snippets/CostFunctionJo.rst
 144
 145 .. include:: snippets/CurrentState.rst
 146
 147 .. include:: snippets/EnsembleOfSimulations.rst
 148
 149 .. include:: snippets/EnsembleOfStates.rst
 150
 151 .. include:: snippets/Innovation.rst
 152
 153 .. include:: snippets/InnovationAtCurrentState.rst
 154
 155 .. include:: snippets/SimulatedObservationAtCurrentState.rst
 156
 157 .. ------------------------------------ ..
 158 .. _section_ref_algorithm_SamplingTest_examples:
 159
 160 .. include:: snippets/Header2Algo06.rst
 161
 162 - :ref:`section_ref_algorithm_FunctionTest`
 163 - :ref:`section_ref_algorithm_LocalSensitivityTest`
 164
 165 .. ------------------------------------ ..
 166 .. include:: snippets/Header2Algo08.rst
 167
 168 - OPENTURNS, see the *User guide of OPENTURNS module* in the main "*Help*" menu of SALOME platform