2 Copyright (C) 2008-2023 EDF R&D
4 This file is part of SALOME ADAO module.
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.
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.
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
20 See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
22 Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
24 .. _section_ref_sampling_requirements:
26 Requirements for describing a state sampling
27 --------------------------------------------
29 .. index:: single: SamplingTest
30 .. index:: single: State sampling
31 .. index:: single: Sampling
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.
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`.
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.
46 Explicit or implicit description of the state sampling collection
47 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
49 The state sampling collection can be described using dedicated keywords in the
50 command set of an algorithm that requires it.
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). Depending on the method, the sample
55 will be included in the domain described by its bounds, or will be descriptive
56 of the unbounded domain of state variables.
58 These possible keywords are:
60 .. include:: snippets/SampleAsExplicitHyperCube.rst
62 .. include:: snippets/SampleAsIndependantRandomVariables.rst
64 .. include:: snippets/SampleAsMinMaxLatinHyperCube.rst
66 .. include:: snippets/SampleAsMinMaxSobolSequence.rst
68 .. include:: snippets/SampleAsMinMaxStepHyperCube.rst
70 .. include:: snippets/SampleAsnUplet.rst
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.
75 Simple examples of state-space distributions
76 ++++++++++++++++++++++++++++++++++++++++++++
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.
84 The first three keywords illustrate the same distribution, as they are simply
85 different ways of describing it.
87 Explicit state distribution by keyword "*SampleAsnUplet*"
88 .........................................................
90 Explicit sample generation command by "*SampleAsnUplet*" is as follows:
92 .. code-block:: python
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]]
102 La répartition des états ainsi décrite correspond à l'illustration :
104 .. image:: images/sampling_01_SampleAsnUplet.png
107 Implicit state distribution by keyword "*SampleAsExplicitHyperCube*"
108 ....................................................................
110 Implicit sample generation command by "*SampleAsExplicitHyperCube*" is as
113 .. code-block:: python
116 "SampleAsExplicitHyperCube":[[0, 1, 2, 3, 4], [0, 1, 2, 3, 4]]
118 "SampleAsExplicitHyperCube":[range(0, 5), range(0, 5)]
121 The distribution of states thus described corresponds to the illustration:
123 .. image:: images/sampling_02_SampleAsExplicitHyperCube.png
126 Implicit state distribution by keyword "*SampleAsMinMaxStepHyperCube*"
127 ......................................................................
129 Implicit sample generation command by "*SampleAsMinMaxStepHyperCube*" is as
132 .. code-block:: python
135 "SampleAsMinMaxStepHyperCube":[[0, 4, 1], [0, 4, 1]]
138 The distribution of states thus described corresponds to the illustration:
140 .. image:: images/sampling_03_SampleAsMinMaxStepHyperCube.png
143 Implicit state distribution by keyword "*SampleAsMinMaxLatinHyperCube*"
144 .......................................................................
146 Implicit sample generation command by "*SampleAsMinMaxLatinHyperCube*" is as
149 .. code-block:: python
152 "SampleAsMinMaxLatinHyperCube":[[0, 4], [0, 4], [2, 25]]
155 The distribution of states thus described corresponds to the illustration:
157 .. image:: images/sampling_04_SampleAsMinMaxLatinHyperCube.png
160 Implicit state distribution by keyword "*SampleAsMinMaxSobolSequence*"
161 .......................................................................
163 Implicit sample generation command by "*SampleAsMinMaxSobolSequence*" is as
166 .. code-block:: python
169 "SampleAsMinMaxSobolSequence":[[0, 4], [0, 4], [2, 25]]
172 The distribution of states (there will be 32 here by construction principle of
173 the Sobol sequence) thus described corresponds to the illustration:
175 .. image:: images/sampling_05_SampleAsMinMaxSobolSequence.png
178 Implicit state distribution by keyword "*SampleAsIndependantRandomVariables*" with normal law
179 .............................................................................................
181 Implicit sample generation command by "*SampleAsIndependantRandomVariables*" is as
182 follows, using a normal distribution (0,1) by coordinate:
184 .. code-block:: python
187 "SampleAsIndependantRandomVariables":[['normal', [0, 1], 5], ['normal', [0, 1], 5]]
190 The distribution of states thus described corresponds to the illustration:
192 .. image:: images/sampling_06_SampleAsIndependantRandomVariables_normal.png
195 Implicit state distribution by keyword "*SampleAsIndependantRandomVariables*" with uniform law
196 ..............................................................................................
198 Implicit sample generation command by "*SampleAsIndependantRandomVariables*" is
199 as follows, using a uniform distribution between 0 and 5 for coordinate
202 .. code-block:: python
205 "SampleAsIndependantRandomVariables":[['uniform', [0, 5], 5], ['uniform', [0, 5], 5]]
208 The distribution of states thus described corresponds to the illustration:
210 .. image:: images/sampling_07_SampleAsIndependantRandomVariables_uniform.png
213 Implicit state distribution by keyword "*SampleAsIndependantRandomVariables*" with Weibull law
214 ..............................................................................................
216 Implicit sample generation command by "*SampleAsIndependantRandomVariables*" is
217 as follows, using a 1-parameter Weibull distribution of value 5 for coordinate
220 .. code-block:: python
223 "SampleAsIndependantRandomVariables":[['weibull', [5], 5], ['weibull', [5], 5]]
226 The distribution of states thus described corresponds to the illustration:
228 .. image:: images/sampling_08_SampleAsIndependantRandomVariables_weibull.png