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 State sampling :math:`\mathbf{x}` can be provided explicitly or in the form of
  53 hypercubes, explicit or sampled according to common distributions, or using
  54 Latin Hypercube Sampling (LHS).
  55
  56 These possible keywords are:
  57
  58 .. include:: snippets/SampleAsExplicitHyperCube.rst
  59
  60 .. include:: snippets/SampleAsIndependantRandomVariables.rst
  61
  62 .. include:: snippets/SampleAsMinMaxLatinHyperCube.rst
  63
  64 .. include:: snippets/SampleAsMinMaxStepHyperCube.rst
  65
  66 .. include:: snippets/SampleAsnUplet.rst
  67
  68 Beware of the size of the hypercube (and then to the number of computations)
  69 that can be reached, it can grow quickly to be quite large.
  70
  71 Simple examples of state-space distributions
  72 ++++++++++++++++++++++++++++++++++++++++++++
  73
  74 To illustrate the commands, we propose here simple state distributions obtained
  75 in a 2-dimensional state space (to be representable), and the commands that
  76 enable them to be obtained. We arbitrarily choose to place 25 states in each
  77 case. In most of the commands, since the states are described separately
  78 according to each coordinate, 5 coordinate values are requested per axis.
  79
  80 The first three keywords illustrate the same distribution, as they are simply
  81 different ways of describing it.
  82
  83 Explicit state distribution by keyword "*SampleAsnUplet*"
  84 .........................................................
  85
  86 Explicit sample generation command by "*SampleAsnUplet*" is as follows:
  87
  88 .. code-block:: python
  89
  90     [...]
  91     "SampleAsnUplet":[[0, 0], [0, 1], [0, 2], [0, 3], [0, 4],
  92                       [1, 0], [1, 1], [1, 2], [1, 3], [1, 4],
  93                       [2, 0], [2, 1], [2, 2], [2, 3], [2, 4],
  94                       [3, 0], [3, 1], [3, 2], [3, 3], [3, 4],
  95                       [4, 0], [4, 1], [4, 2], [4, 3], [4, 4]]
  96     [...]
  97
  98 La répartition des états ainsi décrite correspond à l'illustration  :
  99
 100   .. image:: images/sampling_01_SampleAsnUplet.png
 101     :align: center
 102
 103 Implicit state distribution by keyword "*SampleAsExplicitHyperCube*"
 104 ....................................................................
 105
 106 Implicit sample generation command by "*SampleAsExplicitHyperCube*" is as
 107 follows:
 108
 109 .. code-block:: python
 110
 111     [...]
 112     "SampleAsExplicitHyperCube":[[0, 1, 2, 3, 4], [0, 1, 2, 3, 4]]
 113     # ou
 114     "SampleAsExplicitHyperCube":[range(0, 5), range(0, 5)]
 115     [...]
 116
 117 The distribution of states thus described corresponds to the illustration:
 118
 119   .. image:: images/sampling_02_SampleAsExplicitHyperCube.png
 120     :align: center
 121
 122 Implicit state distribution by keyword "*SampleAsMinMaxStepHyperCube*"
 123 ......................................................................
 124
 125 Implicit sample generation command by "*SampleAsMinMaxStepHyperCube*" is as
 126 follows:
 127
 128 .. code-block:: python
 129
 130     [...]
 131     "SampleAsMinMaxStepHyperCube":[[0, 4, 1], [0, 4, 1]]
 132     [...]
 133
 134 The distribution of states thus described corresponds to the illustration:
 135
 136   .. image:: images/sampling_03_SampleAsMinMaxStepHyperCube.png
 137     :align: center
 138
 139 Implicit state distribution by keyword "*SampleAsMinMaxLatinHyperCube*"
 140 .......................................................................
 141
 142 Implicit sample generation command by "*SampleAsMinMaxLatinHyperCube*" is as
 143 follows:
 144
 145 .. code-block:: python
 146
 147     [...]
 148     "SampleAsMinMaxLatinHyperCube":[[0, 4], [0, 4], [2, 25]]
 149     [...]
 150
 151 The distribution of states thus described corresponds to the illustration:
 152
 153   .. image:: images/sampling_04_SampleAsMinMaxLatinHyperCube.png
 154     :align: center
 155
 156 Implicit state distribution by keyword "*SampleAsIndependantRandomVariables*" with normal law
 157 .............................................................................................
 158
 159 Implicit sample generation command by "*SampleAsIndependantRandomVariables*" is as
 160 follows, using a normal distribution (0,1) by coordinate:
 161
 162 .. code-block:: python
 163
 164     [...]
 165     "SampleAsIndependantRandomVariables":[['normal', [0, 1], 5], ['normal', [0, 1], 5]]
 166     [...]
 167
 168 The distribution of states thus described corresponds to the illustration:
 169
 170   .. image:: images/sampling_05_SampleAsIndependantRandomVariables_normal.png
 171     :align: center
 172
 173 Implicit state distribution by keyword "*SampleAsIndependantRandomVariables*" with uniform law
 174 ..............................................................................................
 175
 176 Implicit sample generation command by "*SampleAsIndependantRandomVariables*" is
 177 as follows, using a uniform distribution between 0 and 5 for coordinate
 178 distribution:
 179
 180 .. code-block:: python
 181
 182     [...]
 183     "SampleAsIndependantRandomVariables":[['uniform', [0, 5], 5], ['uniform', [0, 5], 5]]
 184     [...]
 185
 186 The distribution of states thus described corresponds to the illustration:
 187
 188   .. image:: images/sampling_06_SampleAsIndependantRandomVariables_uniform.png
 189     :align: center
 190
 191 Implicit state distribution by keyword "*SampleAsIndependantRandomVariables*" with Weibull law
 192 ..............................................................................................
 193
 194 Implicit sample generation command by "*SampleAsIndependantRandomVariables*" is
 195 as follows, using a 1-parameter Weibull distribution of value 5 for coordinate
 196 distribution:
 197
 198 .. code-block:: python
 199
 200     [...]
 201     "SampleAsIndependantRandomVariables":[['weibull', [5], 5], ['weibull', [5], 5]]
 202     [...]
 203
 204 The distribution of states thus described corresponds to the illustration:
 205
 206   .. image:: images/sampling_07_SampleAsIndependantRandomVariables_weibull.png
 207     :align: center