doc/en/ref_sampling_requirements.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 .. _section_ref_sampling_requirements:
  25
  26 Requirements for describing a state sampling
  27 --------------------------------------------
  28
  29 .. index:: single: SamplingTest
  30 .. index:: single: State sampling
  31 .. index:: single: Sampling
  32
  33 In general, it is useful to have a sampling of states when you are interested
  34 in analyses that benefit from knowledge of a set of simulations or a set of
  35 similar measurements, but each obtained for a different state.
  36
  37 This is the case for the explicit definition of simulatable states of
  38 :ref:`section_ref_algorithm_SamplingTest`,
  39 :ref:`section_ref_algorithm_EnsembleOfSimulationGenerationTask` and
  40 :ref:`section_ref_algorithm_MeasurementsOptimalPositioningTask`.
  41
  42 All these states can be described explicitly or implicitly, to simplify their
  43 listing. Possible descriptions are given below, followed by very simple
  44 examples to show the types of state distribution obtained in the space.
  45
  46 Explicit or implicit description of the state sampling collection
  47 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  48
  49 The state sampling collection can be described using dedicated keywords in the
  50 command set of an algorithm that requires it.
  51
  52 The sampling of the states :math:`\mathbf{x}` can be provided explicitly or in
  53 the form of hypercubes, explicit or sampled according to common distributions,
  54 or using Latin Hypercube Sampling (LHS) or Sobol sequences. Depending on the
  55 method, the sample will be included in the domain described by its bounds, or
  56 will be descriptive of the unbounded domain of state variables.
  57
  58 These possible keywords are:
  59
  60 .. include:: snippets/SampleAsExplicitHyperCube.rst
  61
  62 .. include:: snippets/SampleAsIndependantRandomVariables.rst
  63
  64 .. include:: snippets/SampleAsMinMaxLatinHyperCube.rst
  65
  66 .. include:: snippets/SampleAsMinMaxSobolSequence.rst
  67
  68 .. include:: snippets/SampleAsMinMaxStepHyperCube.rst
  69
  70 .. include:: snippets/SampleAsnUplet.rst
  71
  72 Beware of the size of the hypercube (and then to the number of computations)
  73 that can be reached, it can grow quickly to be quite large.
  74
  75 Simple examples of state-space distributions
  76 ++++++++++++++++++++++++++++++++++++++++++++
  77
  78 To illustrate the commands, we propose here simple state distributions obtained
  79 in a 2-dimensional state space (to be representable), and the commands that
  80 enable them to be obtained. We arbitrarily choose to place 25 states in each
  81 case. In most of the commands, since the states are described separately
  82 according to each coordinate, 5 coordinate values are requested per axis.
  83
  84 The first three keywords illustrate the same distribution, as they are simply
  85 different ways of describing it.
  86
  87 Explicit state distribution by keyword "*SampleAsnUplet*"
  88 .........................................................
  89
  90 Explicit sample generation command by "*SampleAsnUplet*" is as follows:
  91
  92 .. code-block:: python
  93
  94     [...]
  95     "SampleAsnUplet":[[0, 0], [0, 1], [0, 2], [0, 3], [0, 4],
  96                       [1, 0], [1, 1], [1, 2], [1, 3], [1, 4],
  97                       [2, 0], [2, 1], [2, 2], [2, 3], [2, 4],
  98                       [3, 0], [3, 1], [3, 2], [3, 3], [3, 4],
  99                       [4, 0], [4, 1], [4, 2], [4, 3], [4, 4]]
 100     [...]
 101
 102 La répartition des états ainsi décrite correspond à l'illustration  :
 103
 104   .. image:: images/sampling_01_SampleAsnUplet.png
 105     :align: center
 106
 107 Implicit state distribution by keyword "*SampleAsExplicitHyperCube*"
 108 ....................................................................
 109
 110 Implicit sample generation command by "*SampleAsExplicitHyperCube*" is as
 111 follows:
 112
 113 .. code-block:: python
 114
 115     [...]
 116     "SampleAsExplicitHyperCube":[[0, 1, 2, 3, 4], [0, 1, 2, 3, 4]]
 117     # ou
 118     "SampleAsExplicitHyperCube":[range(0, 5), range(0, 5)]
 119     [...]
 120
 121 The distribution of states thus described corresponds to the illustration:
 122
 123   .. image:: images/sampling_02_SampleAsExplicitHyperCube.png
 124     :align: center
 125
 126 Implicit state distribution by keyword "*SampleAsMinMaxStepHyperCube*"
 127 ......................................................................
 128
 129 Implicit sample generation command by "*SampleAsMinMaxStepHyperCube*" is as
 130 follows:
 131
 132 .. code-block:: python
 133
 134     [...]
 135     "SampleAsMinMaxStepHyperCube":[[0, 4, 1], [0, 4, 1]]
 136     [...]
 137
 138 The distribution of states thus described corresponds to the illustration:
 139
 140   .. image:: images/sampling_03_SampleAsMinMaxStepHyperCube.png
 141     :align: center
 142
 143 Implicit state distribution by keyword "*SampleAsMinMaxLatinHyperCube*"
 144 .......................................................................
 145
 146 Implicit sample generation command by "*SampleAsMinMaxLatinHyperCube*" is as
 147 follows:
 148
 149 .. code-block:: python
 150
 151     [...]
 152     "SampleAsMinMaxLatinHyperCube":[[0, 4], [0, 4], [2, 25]]
 153     [...]
 154
 155 The distribution of states thus described corresponds to the illustration:
 156
 157   .. image:: images/sampling_04_SampleAsMinMaxLatinHyperCube.png
 158     :align: center
 159
 160 Implicit state distribution by keyword "*SampleAsMinMaxSobolSequence*"
 161 .......................................................................
 162
 163 Implicit sample generation command by "*SampleAsMinMaxSobolSequence*" is as
 164 follows:
 165
 166 .. code-block:: python
 167
 168     [...]
 169     "SampleAsMinMaxSobolSequence":[[0, 4], [0, 4], [2, 25]]
 170     [...]
 171
 172 The distribution of states (there will be 32 here by construction principle of
 173 the Sobol sequence) thus described corresponds to the illustration:
 174
 175   .. image:: images/sampling_05_SampleAsMinMaxSobolSequence.png
 176     :align: center
 177
 178 Implicit state distribution by keyword "*SampleAsIndependantRandomVariables*" with normal law
 179 .............................................................................................
 180
 181 Implicit sample generation command by "*SampleAsIndependantRandomVariables*" is as
 182 follows, using a normal distribution (0,1) by coordinate:
 183
 184 .. code-block:: python
 185
 186     [...]
 187     "SampleAsIndependantRandomVariables":[['normal', [0, 1], 5], ['normal', [0, 1], 5]]
 188     [...]
 189
 190 The distribution of states thus described corresponds to the illustration:
 191
 192   .. image:: images/sampling_06_SampleAsIndependantRandomVariables_normal.png
 193     :align: center
 194
 195 Implicit state distribution by keyword "*SampleAsIndependantRandomVariables*" with uniform law
 196 ..............................................................................................
 197
 198 Implicit sample generation command by "*SampleAsIndependantRandomVariables*" is
 199 as follows, using a uniform distribution between 0 and 5 for coordinate
 200 distribution:
 201
 202 .. code-block:: python
 203
 204     [...]
 205     "SampleAsIndependantRandomVariables":[['uniform', [0, 5], 5], ['uniform', [0, 5], 5]]
 206     [...]
 207
 208 The distribution of states thus described corresponds to the illustration:
 209
 210   .. image:: images/sampling_07_SampleAsIndependantRandomVariables_uniform.png
 211     :align: center
 212
 213 Implicit state distribution by keyword "*SampleAsIndependantRandomVariables*" with Weibull law
 214 ..............................................................................................
 215
 216 Implicit sample generation command by "*SampleAsIndependantRandomVariables*" is
 217 as follows, using a 1-parameter Weibull distribution of value 5 for coordinate
 218 distribution:
 219
 220 .. code-block:: python
 221
 222     [...]
 223     "SampleAsIndependantRandomVariables":[['weibull', [5], 5], ['weibull', [5], 5]]
 224     [...]
 225
 226 The distribution of states thus described corresponds to the illustration:
 227
 228   .. image:: images/sampling_08_SampleAsIndependantRandomVariables_weibull.png
 229     :align: center