doc/en/ref_algorithm_SamplingTest.rst

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