From: Jean-Philippe ARGAUD Date: Wed, 8 Nov 2023 15:24:25 +0000 (+0100) Subject: Documentation for sampling update and examples improvement X-Git-Tag: V9_12_0b1~4 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=3b60a2e9a2d84cd8c6c63b2f3f6236072b006703;p=modules%2Fadao.git Documentation for sampling update and examples improvement --- diff --git a/doc/en/images/sampling_01_SampleAsnUplet.png b/doc/en/images/sampling_01_SampleAsnUplet.png new file mode 100644 index 0000000..664d093 Binary files /dev/null and b/doc/en/images/sampling_01_SampleAsnUplet.png differ diff --git a/doc/en/images/sampling_02_SampleAsExplicitHyperCube.png b/doc/en/images/sampling_02_SampleAsExplicitHyperCube.png new file mode 100644 index 0000000..664d093 Binary files /dev/null and b/doc/en/images/sampling_02_SampleAsExplicitHyperCube.png differ diff --git a/doc/en/images/sampling_03_SampleAsMinMaxStepHyperCube.png b/doc/en/images/sampling_03_SampleAsMinMaxStepHyperCube.png new file mode 100644 index 0000000..664d093 Binary files /dev/null and b/doc/en/images/sampling_03_SampleAsMinMaxStepHyperCube.png differ diff --git a/doc/en/images/sampling_04_SampleAsMinMaxLatinHyperCube.png b/doc/en/images/sampling_04_SampleAsMinMaxLatinHyperCube.png new file mode 100644 index 0000000..00330ad Binary files /dev/null and b/doc/en/images/sampling_04_SampleAsMinMaxLatinHyperCube.png differ diff --git a/doc/en/images/sampling_05_SampleAsIndependantRandomVariables_normal.png b/doc/en/images/sampling_05_SampleAsIndependantRandomVariables_normal.png new file mode 100644 index 0000000..af69551 Binary files /dev/null and b/doc/en/images/sampling_05_SampleAsIndependantRandomVariables_normal.png differ diff --git a/doc/en/images/sampling_06_SampleAsIndependantRandomVariables_uniform.png b/doc/en/images/sampling_06_SampleAsIndependantRandomVariables_uniform.png new file mode 100644 index 0000000..3ed60a4 Binary files /dev/null and b/doc/en/images/sampling_06_SampleAsIndependantRandomVariables_uniform.png differ diff --git a/doc/en/images/sampling_07_SampleAsIndependantRandomVariables_weibull.png b/doc/en/images/sampling_07_SampleAsIndependantRandomVariables_weibull.png new file mode 100644 index 0000000..7f656aa Binary files /dev/null and b/doc/en/images/sampling_07_SampleAsIndependantRandomVariables_weibull.png differ diff --git a/doc/en/ref_algorithm_EnsembleOfSimulationGenerationTask.rst b/doc/en/ref_algorithm_EnsembleOfSimulationGenerationTask.rst index f5ee628..20f3a22 100644 --- a/doc/en/ref_algorithm_EnsembleOfSimulationGenerationTask.rst +++ b/doc/en/ref_algorithm_EnsembleOfSimulationGenerationTask.rst @@ -49,10 +49,11 @@ to the chosen homogeneous collection of state vectors :math:`\mathbf{x}` The sampling of the states :math:`\mathbf{x}` can be given explicitly or under form of hypercubes, explicit or sampled according to classic distributions, or using Latin hypercube sampling (LHS). The computations are optimized according -to the computer resources available and the options requested by the user. -Beware of the size of the hypercube (and then to the number of computations) -that can be reached, it can grow quickly to be quite large. When a state is not -observable, a *"NaN"* value is returned. +to the computer resources available and the options requested by the user. You +can refer to the :ref:`section_ref_sampling_requirements` for an illustration +of sampling. Beware of the size of the hypercube (and then to the number of +computations) that can be reached, it can grow quickly to be quite large. When +a state is not observable, a *"NaN"* value is returned. To be visible by the user while reducing the risk of storage difficulties, the results of sampling or simulations has to be **explicitly** asked for using the diff --git a/doc/en/ref_algorithm_MeasurementsOptimalPositioningTask.rst b/doc/en/ref_algorithm_MeasurementsOptimalPositioningTask.rst index d1f6ecd..ce58671 100644 --- a/doc/en/ref_algorithm_MeasurementsOptimalPositioningTask.rst +++ b/doc/en/ref_algorithm_MeasurementsOptimalPositioningTask.rst @@ -80,9 +80,10 @@ If the design of experiments is supplied, the sampling of the states under form of hypercubes, explicit or sampled according to classic distributions, or using Latin hypercube sampling (LHS). The computations are optimized according to the computer resources available and the options -requested by the user. Beware of the size of the hypercube (and then to the -number of computations) that can be reached, it can grow quickly to be quite -large. +requested by the user. You can refer to the +:ref:`section_ref_sampling_requirements` for an illustration of sampling. +Beware of the size of the hypercube (and then to the number of computations) +that can be reached, it can grow quickly to be quite large. .. _mop_determination: .. image:: images/mop_determination.png diff --git a/doc/en/ref_algorithm_SamplingTest.rst b/doc/en/ref_algorithm_SamplingTest.rst index be1dae3..1da38a2 100644 --- a/doc/en/ref_algorithm_SamplingTest.rst +++ b/doc/en/ref_algorithm_SamplingTest.rst @@ -43,10 +43,11 @@ to variations in the state :math:`\mathbf{x}` in particular. The sampling of the states :math:`\mathbf{x}` can be given explicitly or under form of hypercubes, explicit or sampled according to classic distributions, or using Latin hypercube sampling (LHS). The computations are optimized according -to the computer resources available and the options requested by the user. -Beware of the size of the hypercube (and then to the number of computations) -that can be reached, it can grow quickly to be quite large. When a state is not -observable, a *"NaN"* value is returned. +to the computer resources available and the options requested by the user. You +can refer to the :ref:`section_ref_sampling_requirements` for an illustration +of sampling. Beware of the size of the hypercube (and then to the number of +computations) that can be reached, it can grow quickly to be quite large. When +a state is not observable, a *"NaN"* value is returned. It is also possible to supply a set of simulations :math:`\mathbf{y}` already established elsewhere (so there's no explicit need for an operator diff --git a/doc/en/ref_sampling_requirements.rst b/doc/en/ref_sampling_requirements.rst new file mode 100644 index 0000000..fa7cb9a --- /dev/null +++ b/doc/en/ref_sampling_requirements.rst @@ -0,0 +1,207 @@ +.. + Copyright (C) 2008-2023 EDF R&D + + This file is part of SALOME ADAO module. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com + + Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D + +.. _section_ref_sampling_requirements: + +Requirements for describing a state sampling +-------------------------------------------- + +.. index:: single: SamplingTest +.. index:: single: State sampling +.. index:: single: Sampling + +In general, it is useful to have a sampling of states when you are interested +in analyses that benefit from knowledge of a set of simulations or a set of +similar measurements, but each obtained for a different state. + +This is the case for the explicit definition of simulatable states of +:ref:`section_ref_algorithm_SamplingTest`, +:ref:`section_ref_algorithm_EnsembleOfSimulationGenerationTask` and +:ref:`section_ref_algorithm_MeasurementsOptimalPositioningTask`. + +All these states can be described explicitly or implicitly, to simplify their +listing. Possible descriptions are given below, followed by very simple +examples to show the types of state distribution obtained in the space. + +Explicit or implicit description of the state sampling collection ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The state sampling collection can be described using dedicated keywords in the +command set of an algorithm that requires it. + +State sampling :math:`\mathbf{x}` can be provided explicitly or in the form of +hypercubes, explicit or sampled according to common distributions, or using +Latin Hypercube Sampling (LHS). + +These possible keywords are: + +.. include:: snippets/SampleAsExplicitHyperCube.rst + +.. include:: snippets/SampleAsIndependantRandomVariables.rst + +.. include:: snippets/SampleAsMinMaxLatinHyperCube.rst + +.. include:: snippets/SampleAsMinMaxStepHyperCube.rst + +.. include:: snippets/SampleAsnUplet.rst + +Beware of the size of the hypercube (and then to the number of computations) +that can be reached, it can grow quickly to be quite large. + +Simple examples of state-space distributions +++++++++++++++++++++++++++++++++++++++++++++ + +To illustrate the commands, we propose here simple state distributions obtained +in a 2-dimensional state space (to be representable), and the commands that +enable them to be obtained. We arbitrarily choose to place 25 states in each +case. In most of the commands, since the states are described separately +according to each coordinate, 5 coordinate values are requested per axis. + +The first three keywords illustrate the same distribution, as they are simply +different ways of describing it. + +Explicit state distribution by keyword "*SampleAsnUplet*" +......................................................... + +Explicit sample generation command by "*SampleAsnUplet*" is as follows: + +.. code-block:: python + + [...] + "SampleAsnUplet":[[0, 0], [0, 1], [0, 2], [0, 3], [0, 4], + [1, 0], [1, 1], [1, 2], [1, 3], [1, 4], + [2, 0], [2, 1], [2, 2], [2, 3], [2, 4], + [3, 0], [3, 1], [3, 2], [3, 3], [3, 4], + [4, 0], [4, 1], [4, 2], [4, 3], [4, 4]] + [...] + +La répartition des états ainsi décrite correspond à l'illustration : + + .. image:: images/sampling_01_SampleAsnUplet.png + :align: center + +Implicit state distribution by keyword "*SampleAsExplicitHyperCube*" +.................................................................... + +Implicit sample generation command by "*SampleAsExplicitHyperCube*" is as +follows: + +.. code-block:: python + + [...] + "SampleAsExplicitHyperCube":[[0, 1, 2, 3, 4], [0, 1, 2, 3, 4]] + # ou + "SampleAsExplicitHyperCube":[range(0, 5), range(0, 5)] + [...] + +The distribution of states thus described corresponds to the illustration: + + .. image:: images/sampling_02_SampleAsExplicitHyperCube.png + :align: center + +Implicit state distribution by keyword "*SampleAsMinMaxStepHyperCube*" +...................................................................... + +Implicit sample generation command by "*SampleAsMinMaxStepHyperCube*" is as +follows: + +.. code-block:: python + + [...] + "SampleAsMinMaxStepHyperCube":[[0, 4, 1], [0, 4, 1]] + [...] + +The distribution of states thus described corresponds to the illustration: + + .. image:: images/sampling_03_SampleAsMinMaxStepHyperCube.png + :align: center + +Implicit state distribution by keyword "*SampleAsMinMaxLatinHyperCube*" +....................................................................... + +Implicit sample generation command by "*SampleAsMinMaxLatinHyperCube*" is as +follows: + +.. code-block:: python + + [...] + "SampleAsMinMaxLatinHyperCube":[[0, 4], [0, 4], [2, 25]] + [...] + +The distribution of states thus described corresponds to the illustration: + + .. image:: images/sampling_04_SampleAsMinMaxLatinHyperCube.png + :align: center + +Implicit state distribution by keyword "*SampleAsIndependantRandomVariables*" with normal law +............................................................................................. + +Implicit sample generation command by "*SampleAsIndependantRandomVariables*" is as +follows, using a normal distribution (0,1) by coordinate: + +.. code-block:: python + + [...] + "SampleAsIndependantRandomVariables":[['normal', [0, 1], 5], ['normal', [0, 1], 5]] + [...] + +The distribution of states thus described corresponds to the illustration: + + .. image:: images/sampling_05_SampleAsIndependantRandomVariables_normal.png + :align: center + +Implicit state distribution by keyword "*SampleAsIndependantRandomVariables*" with uniform law +.............................................................................................. + +Implicit sample generation command by "*SampleAsIndependantRandomVariables*" is +as follows, using a uniform distribution between 0 and 5 for coordinate +distribution: + +.. code-block:: python + + [...] + "SampleAsIndependantRandomVariables":[['uniform', [0, 5], 5], ['uniform', [0, 5], 5]] + [...] + +The distribution of states thus described corresponds to the illustration: + + .. image:: images/sampling_06_SampleAsIndependantRandomVariables_uniform.png + :align: center + +Implicit state distribution by keyword "*SampleAsIndependantRandomVariables*" with Weibull law +.............................................................................................. + +Implicit sample generation command by "*SampleAsIndependantRandomVariables*" is +as follows, using a 1-parameter Weibull distribution of value 5 for coordinate +distribution: + +.. code-block:: python + + [...] + "SampleAsIndependantRandomVariables":[['weibull', [5], 5], ['weibull', [5], 5]] + [...] + +The distribution of states thus described corresponds to the illustration: + + .. image:: images/sampling_07_SampleAsIndependantRandomVariables_weibull.png + :align: center diff --git a/doc/en/reference.rst b/doc/en/reference.rst index ab5f655..60e8727 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -76,6 +76,7 @@ related to these inputs are explained in section :ref:`section_theory`. ref_observations_requirements ref_operator_requirements ref_covariance_requirements + ref_sampling_requirements ref_observers_requirements ref_userpostanalysis_requirements diff --git a/doc/en/scripts/simple_3DVAR1.png b/doc/en/scripts/simple_3DVAR1.png index 987dcaa..185b682 100644 Binary files a/doc/en/scripts/simple_3DVAR1.png and b/doc/en/scripts/simple_3DVAR1.png differ diff --git a/doc/en/scripts/simple_3DVAR1Plus.png b/doc/en/scripts/simple_3DVAR1Plus.png index 5cf726a..a69e203 100644 Binary files a/doc/en/scripts/simple_3DVAR1Plus.png and b/doc/en/scripts/simple_3DVAR1Plus.png differ diff --git a/doc/en/scripts/simple_3DVAR2_state.png b/doc/en/scripts/simple_3DVAR2_state.png index 0f0f588..c734d1b 100644 Binary files a/doc/en/scripts/simple_3DVAR2_state.png and b/doc/en/scripts/simple_3DVAR2_state.png differ diff --git a/doc/en/scripts/simple_3DVAR2_variance.png b/doc/en/scripts/simple_3DVAR2_variance.png index 943e5e1..5b8db59 100644 Binary files a/doc/en/scripts/simple_3DVAR2_variance.png and b/doc/en/scripts/simple_3DVAR2_variance.png differ diff --git a/doc/en/scripts/simple_3DVAR3_state.png b/doc/en/scripts/simple_3DVAR3_state.png index 9f4ccc3..16be4de 100644 Binary files a/doc/en/scripts/simple_3DVAR3_state.png and b/doc/en/scripts/simple_3DVAR3_state.png differ diff --git a/doc/en/scripts/simple_3DVAR3_variance.png b/doc/en/scripts/simple_3DVAR3_variance.png index 3c3bec3..3b4af7a 100644 Binary files a/doc/en/scripts/simple_3DVAR3_variance.png and b/doc/en/scripts/simple_3DVAR3_variance.png differ diff --git a/doc/en/scripts/simple_DerivativeFreeOptimization.png b/doc/en/scripts/simple_DerivativeFreeOptimization.png index 6bb44ce..0f9d11b 100644 Binary files a/doc/en/scripts/simple_DerivativeFreeOptimization.png and b/doc/en/scripts/simple_DerivativeFreeOptimization.png differ diff --git a/doc/en/scripts/simple_KalmanFilter1_state.png b/doc/en/scripts/simple_KalmanFilter1_state.png index fce0c7c..dda60c9 100644 Binary files a/doc/en/scripts/simple_KalmanFilter1_state.png and b/doc/en/scripts/simple_KalmanFilter1_state.png differ diff --git a/doc/en/scripts/simple_KalmanFilter1_variance.png b/doc/en/scripts/simple_KalmanFilter1_variance.png index 9b13815..bb3e47f 100644 Binary files a/doc/en/scripts/simple_KalmanFilter1_variance.png and b/doc/en/scripts/simple_KalmanFilter1_variance.png differ diff --git a/doc/en/scripts/simple_KalmanFilter2_state.png b/doc/en/scripts/simple_KalmanFilter2_state.png index fce0c7c..dda60c9 100644 Binary files a/doc/en/scripts/simple_KalmanFilter2_state.png and b/doc/en/scripts/simple_KalmanFilter2_state.png differ diff --git a/doc/en/scripts/simple_KalmanFilter2_variance.png b/doc/en/scripts/simple_KalmanFilter2_variance.png index 9b13815..bb3e47f 100644 Binary files a/doc/en/scripts/simple_KalmanFilter2_variance.png and b/doc/en/scripts/simple_KalmanFilter2_variance.png differ diff --git a/doc/en/scripts/simple_NonLinearLeastSquares.png b/doc/en/scripts/simple_NonLinearLeastSquares.png index 6bb44ce..0f9d11b 100644 Binary files a/doc/en/scripts/simple_NonLinearLeastSquares.png and b/doc/en/scripts/simple_NonLinearLeastSquares.png differ diff --git a/doc/en/scripts/simple_ParticleSwarmOptimization1.png b/doc/en/scripts/simple_ParticleSwarmOptimization1.png index e29ee4d..99d859a 100644 Binary files a/doc/en/scripts/simple_ParticleSwarmOptimization1.png and b/doc/en/scripts/simple_ParticleSwarmOptimization1.png differ diff --git a/doc/en/snippets/ModuleCompatibility.rst b/doc/en/snippets/ModuleCompatibility.rst index c77a27f..4277ccc 100644 --- a/doc/en/snippets/ModuleCompatibility.rst +++ b/doc/en/snippets/ModuleCompatibility.rst @@ -17,6 +17,6 @@ versions within the range described below. Python, 3.6.5, 3.11.6 Numpy, 1.14.3, 1.26.0 Scipy, 0.19.1, 1.11.3 - MatplotLib, 2.2.2, 3.8.0 + MatplotLib, 2.2.2, 3.8.1 GnuplotPy, 1.8, 1.8 NLopt, 2.4.2, 2.7.1 diff --git a/doc/en/snippets/QualityCriterion.rst b/doc/en/snippets/QualityCriterion.rst index a187c8c..80e6ab1 100644 --- a/doc/en/snippets/QualityCriterion.rst +++ b/doc/en/snippets/QualityCriterion.rst @@ -11,6 +11,8 @@ QualityCriterion "LeastSquares" <=> "LS" <=> "L2", "AbsoluteValue" <=> "L1", "MaximumError" <=> "ME" <=> "Linf"]. + See the section for :ref:`section_theory_optimization` to have a detailed + definition of these quality criteria. Example: ``{"QualityCriterion":"DA"}`` diff --git a/doc/en/snippets/SampleAsExplicitHyperCube.rst b/doc/en/snippets/SampleAsExplicitHyperCube.rst index 9a74e88..5e549bf 100644 --- a/doc/en/snippets/SampleAsExplicitHyperCube.rst +++ b/doc/en/snippets/SampleAsExplicitHyperCube.rst @@ -6,4 +6,4 @@ SampleAsExplicitHyperCube list. That is then a list of lists, each of them being potentially of different size. - Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` for a state space of dimension 2 + Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` for a state space of dimension 2. diff --git a/doc/en/snippets/SampleAsIndependantRandomVariables.rst b/doc/en/snippets/SampleAsIndependantRandomVariables.rst index 3c36155..e9a83db 100644 --- a/doc/en/snippets/SampleAsIndependantRandomVariables.rst +++ b/doc/en/snippets/SampleAsIndependantRandomVariables.rst @@ -12,4 +12,4 @@ SampleAsIndependantRandomVariables the one of the state. Example : - ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` for a state space of dimension 2 + ``{"SampleAsIndependantRandomVariables":[['normal',[0.,1.],3], ['uniform',[-2,2],4]]}`` for a state space of dimension 2. diff --git a/doc/en/snippets/SampleAsMinMaxLatinHyperCube.rst b/doc/en/snippets/SampleAsMinMaxLatinHyperCube.rst index 4af5700..4907dab 100644 --- a/doc/en/snippets/SampleAsMinMaxLatinHyperCube.rst +++ b/doc/en/snippets/SampleAsMinMaxLatinHyperCube.rst @@ -10,4 +10,4 @@ SampleAsMinMaxLatinHyperCube using the Latin hypercube method (LHS). Example : - ``{"SampleAsMinMaxLatinHyperCube":[[0.,1.],[-1,3]]+[[2,11]]}`` for a state space of dimension 2 and 11 sampling points + ``{"SampleAsMinMaxLatinHyperCube":[[0.,1.],[-1,3]]+[[2,11]]}`` for a state space of dimension 2 and 11 sampling points. diff --git a/doc/en/snippets/SampleAsMinMaxStepHyperCube.rst b/doc/en/snippets/SampleAsMinMaxStepHyperCube.rst index f3b18d1..a2681a6 100644 --- a/doc/en/snippets/SampleAsMinMaxStepHyperCube.rst +++ b/doc/en/snippets/SampleAsMinMaxStepHyperCube.rst @@ -7,4 +7,4 @@ SampleAsMinMaxStepHyperCube of the state. The bounds are included. Example : - ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` for a state space of dimension 2 + ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` for a state space of dimension 2. diff --git a/doc/en/snippets/SampleAsnUplet.rst b/doc/en/snippets/SampleAsnUplet.rst index fddd92c..513c4c4 100644 --- a/doc/en/snippets/SampleAsnUplet.rst +++ b/doc/en/snippets/SampleAsnUplet.rst @@ -5,4 +5,4 @@ SampleAsnUplet n-uplets, each n-uplet being a state. Example : - ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` for 3 points in a state space of dimension 4 + ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` for 3 points in a state space of dimension 4. diff --git a/doc/fr/images/sampling_01_SampleAsnUplet.png b/doc/fr/images/sampling_01_SampleAsnUplet.png new file mode 100644 index 0000000..60a72aa Binary files /dev/null and b/doc/fr/images/sampling_01_SampleAsnUplet.png differ diff --git a/doc/fr/images/sampling_02_SampleAsExplicitHyperCube.png b/doc/fr/images/sampling_02_SampleAsExplicitHyperCube.png new file mode 100644 index 0000000..60a72aa Binary files /dev/null and b/doc/fr/images/sampling_02_SampleAsExplicitHyperCube.png differ diff --git a/doc/fr/images/sampling_03_SampleAsMinMaxStepHyperCube.png b/doc/fr/images/sampling_03_SampleAsMinMaxStepHyperCube.png new file mode 100644 index 0000000..60a72aa Binary files /dev/null and b/doc/fr/images/sampling_03_SampleAsMinMaxStepHyperCube.png differ diff --git a/doc/fr/images/sampling_04_SampleAsMinMaxLatinHyperCube.png b/doc/fr/images/sampling_04_SampleAsMinMaxLatinHyperCube.png new file mode 100644 index 0000000..0249fd2 Binary files /dev/null and b/doc/fr/images/sampling_04_SampleAsMinMaxLatinHyperCube.png differ diff --git a/doc/fr/images/sampling_05_SampleAsIndependantRandomVariables_normal.png b/doc/fr/images/sampling_05_SampleAsIndependantRandomVariables_normal.png new file mode 100644 index 0000000..5ede766 Binary files /dev/null and b/doc/fr/images/sampling_05_SampleAsIndependantRandomVariables_normal.png differ diff --git a/doc/fr/images/sampling_06_SampleAsIndependantRandomVariables_uniform.png b/doc/fr/images/sampling_06_SampleAsIndependantRandomVariables_uniform.png new file mode 100644 index 0000000..964fb44 Binary files /dev/null and b/doc/fr/images/sampling_06_SampleAsIndependantRandomVariables_uniform.png differ diff --git a/doc/fr/images/sampling_07_SampleAsIndependantRandomVariables_weibull.png b/doc/fr/images/sampling_07_SampleAsIndependantRandomVariables_weibull.png new file mode 100644 index 0000000..7a9a5e8 Binary files /dev/null and b/doc/fr/images/sampling_07_SampleAsIndependantRandomVariables_weibull.png differ diff --git a/doc/fr/ref_algorithm_EnsembleOfSimulationGenerationTask.rst b/doc/fr/ref_algorithm_EnsembleOfSimulationGenerationTask.rst index de32ba7..ea1f77d 100644 --- a/doc/fr/ref_algorithm_EnsembleOfSimulationGenerationTask.rst +++ b/doc/fr/ref_algorithm_EnsembleOfSimulationGenerationTask.rst @@ -51,10 +51,12 @@ L'échantillonnage des états :math:`\mathbf{x}` peut être fourni explicitement ou sous la forme d'hypercubes, explicites ou échantillonnés selon des distributions courantes, ou à l'aide d'un échantillonnage par hypercube latin (LHS). Les calculs sont optimisés selon les ressources informatiques -disponibles et les options demandées par l'utilisateur. Attention à la taille -de l'hypercube (et donc au nombre de calculs) qu'il est possible d'atteindre, -elle peut rapidement devenir importante. Lorsqu'un état n'est pas observable, -une valeur *"NaN"* est retournée. +disponibles et les options demandées par l'utilisateur. On pourra se reporter +aux :ref:`section_ref_sampling_requirements` pour une illustration de +l'échantillonnage. Attention à la taille de l'hypercube (et donc au nombre de +calculs) qu'il est possible d'atteindre, elle peut rapidement devenir +importante. Lorsqu'un état n'est pas observable, une valeur *"NaN"* est +retournée. Pour apparaître pour l'utilisateur tout en réduisant les difficultés de stockage, les résultats de l'échantillonnage ou des simulations doivent être diff --git a/doc/fr/ref_algorithm_MeasurementsOptimalPositioningTask.rst b/doc/fr/ref_algorithm_MeasurementsOptimalPositioningTask.rst index 27ae90b..8f8adda 100644 --- a/doc/fr/ref_algorithm_MeasurementsOptimalPositioningTask.rst +++ b/doc/fr/ref_algorithm_MeasurementsOptimalPositioningTask.rst @@ -83,9 +83,11 @@ Dans le cas où l'on fournit le plan d'expérience, l'échantillonnage des état ou sous la forme d'hypercubes, explicites ou échantillonnés selon des distributions courantes, ou à l'aide d'un échantillonnage par hypercube latin (LHS). Les calculs sont optimisés selon les ressources informatiques -disponibles et les options demandées par l'utilisateur. Attention à la taille -de l'hypercube (et donc au nombre de calculs) qu'il est possible d'atteindre, -elle peut rapidement devenir importante. +disponibles et les options demandées par l'utilisateur. On pourra se reporter +aux :ref:`section_ref_sampling_requirements` pour une illustration de +l'échantillonnage. Attention à la taille de l'hypercube (et donc au nombre de +calculs) qu'il est possible d'atteindre, elle peut rapidement devenir +importante. .. _mop_determination: .. image:: images/mop_determination.png diff --git a/doc/fr/ref_algorithm_SamplingTest.rst b/doc/fr/ref_algorithm_SamplingTest.rst index f88a875..d5c6bb0 100644 --- a/doc/fr/ref_algorithm_SamplingTest.rst +++ b/doc/fr/ref_algorithm_SamplingTest.rst @@ -45,10 +45,12 @@ L'échantillonnage des états :math:`\mathbf{x}` peut être fourni explicitement ou sous la forme d'hypercubes, explicites ou échantillonnés selon des distributions courantes, ou à l'aide d'un échantillonnage par hypercube latin (LHS). Les calculs sont optimisés selon les ressources informatiques -disponibles et les options demandées par l'utilisateur. Attention à la taille -de l'hypercube (et donc au nombre de calculs) qu'il est possible d'atteindre, -elle peut rapidement devenir importante. Lorsqu'un état n'est pas observable, -une valeur *"NaN"* est retournée. +disponibles et les options demandées par l'utilisateur. On pourra se reporter +aux :ref:`section_ref_sampling_requirements` pour une illustration de +l'échantillonnage. Attention à la taille de l'hypercube (et donc au nombre de +calculs) qu'il est possible d'atteindre, elle peut rapidement devenir +importante. Lorsqu'un état n'est pas observable, une valeur *"NaN"* est +retournée. Il est aussi possible de fournir un ensemble de simulations :math:`\mathbf{y}` déjà établies par ailleurs (donc sans besoin explicite d'un opérateur diff --git a/doc/fr/ref_sampling_requirements.rst b/doc/fr/ref_sampling_requirements.rst new file mode 100644 index 0000000..09c5047 --- /dev/null +++ b/doc/fr/ref_sampling_requirements.rst @@ -0,0 +1,213 @@ +.. + Copyright (C) 2008-2023 EDF R&D + + This file is part of SALOME ADAO module. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com + + Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D + +.. _section_ref_sampling_requirements: + +Conditions requises pour décrire un échantillonnage d'états +----------------------------------------------------------- + +.. index:: single: SamplingTest +.. index:: single: Echantillonnage d'états +.. index:: single: Echantillonnage + +De manière générale, il est utile de disposer d'un échantillonnage des états +lorsque l'on s'intéresse à des analyses qui bénéficient de la connaissance d'un +ensemble de simulations ou d'un ensemble de mesures similaires, mais chacune +obtenue pour un état différent. + +C'est le cas pour la définition explicite des états simulables des +:ref:`section_ref_algorithm_SamplingTest`, +:ref:`section_ref_algorithm_EnsembleOfSimulationGenerationTask` et +:ref:`section_ref_algorithm_MeasurementsOptimalPositioningTask`. + +L'ensemble de ces états peut être décrit de manière explicite ou implicite pour +en faciliter l'inventaire. On indique ci-dessous les descriptions possibles, et +on les fait suivre d'exemples très simples pour montrer les types de +répartitions obtenues dans l'espace des états. + +Description explicite ou implicite de la collection d'échantillonnage des états ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +La collection d'échantillonnage des états peut être décrite à l'aide de +mots-clés dédiés dans le jeu de commandes d'un algorithme qui le nécessite. + +L'échantillonnage des états :math:`\mathbf{x}` peut être fourni explicitement +ou sous la forme d'hypercubes, explicites ou échantillonnés selon des +distributions courantes, ou à l'aide d'un échantillonnage par hypercube latin +(LHS). + +Ces mots-clés possibles sont les suivants : + +.. include:: snippets/SampleAsExplicitHyperCube.rst + +.. include:: snippets/SampleAsIndependantRandomVariables.rst + +.. include:: snippets/SampleAsMinMaxLatinHyperCube.rst + +.. include:: snippets/SampleAsMinMaxStepHyperCube.rst + +.. include:: snippets/SampleAsnUplet.rst + +Attention à la taille de l'hypercube (et donc au nombre de calculs) qu'il est +possible d'atteindre, elle peut rapidement devenir importante. + +Exemples très simples de répartitions dans l'espace des états ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Pour illustrer les commandes, on propose ici des répartitions simples obtenues +dans un espace d'état à 2 dimensions (pour être représentable), et les +commandes qui permettent de les obtenir. On choisit arbitrairement de +positionner 25 états dans chaque cas. Dans la majeure partie des commandes, +comme on décrit les états séparément selon chaque coordonnée, on demande donc 5 +valeurs de coordonnées par axe. + +Les trois premiers mots-clés illustrent la même répartition car ce sont +simplement des manières différentes de la décrire. + +Répartition explicite d'états par le mot-clé "*SampleAsnUplet*" +............................................................... + +La commande de génération explicite d'échantillons par "*SampleAsnUplet*" est +la suivante : + +.. code-block:: python + + [...] + "SampleAsnUplet":[[0, 0], [0, 1], [0, 2], [0, 3], [0, 4], + [1, 0], [1, 1], [1, 2], [1, 3], [1, 4], + [2, 0], [2, 1], [2, 2], [2, 3], [2, 4], + [3, 0], [3, 1], [3, 2], [3, 3], [3, 4], + [4, 0], [4, 1], [4, 2], [4, 3], [4, 4]] + [...] + +La répartition des états ainsi décrite correspond à l'illustration : + + .. image:: images/sampling_01_SampleAsnUplet.png + :align: center + +Répartition implicite d'états par le mot-clé "*SampleAsExplicitHyperCube*" +.......................................................................... + +La commande de génération implicite d'échantillons par +"*SampleAsExplicitHyperCube*" est la suivante : + +.. code-block:: python + + [...] + "SampleAsExplicitHyperCube":[[0, 1, 2, 3, 4], [0, 1, 2, 3, 4]] + # ou + "SampleAsExplicitHyperCube":[range(0, 5), range(0, 5)] + [...] + +La répartition des états ainsi décrite correspond à l'illustration : + + .. image:: images/sampling_02_SampleAsExplicitHyperCube.png + :align: center + +Répartition implicite d'états par le mot-clé "*SampleAsMinMaxStepHyperCube*" +............................................................................ + +La commande de génération implicite d'échantillons par +"*SampleAsMinMaxStepHyperCube*" est la suivante : + +.. code-block:: python + + [...] + "SampleAsMinMaxStepHyperCube":[[0, 4, 1], [0, 4, 1]] + [...] + +La répartition des états ainsi décrite correspond à l'illustration : + + .. image:: images/sampling_03_SampleAsMinMaxStepHyperCube.png + :align: center + +Répartition implicite d'états par le mot-clé "*SampleAsMinMaxLatinHyperCube*" +............................................................................. + +La commande de génération implicite d'échantillons par +"*SampleAsMinMaxLatinHyperCube*" est la suivante : + +.. code-block:: python + + [...] + "SampleAsMinMaxLatinHyperCube":[[0, 4], [0, 4], [2, 25]] + [...] + +La répartition des états ainsi décrite correspond à l'illustration : + + .. image:: images/sampling_04_SampleAsMinMaxLatinHyperCube.png + :align: center + +Répartition implicite d'états par le mot-clé "*SampleAsIndependantRandomVariables*" avec loi normale +.................................................................................................... + +La commande de génération implicite d'échantillons par +"*SampleAsIndependantRandomVariables*" est la suivante, en utilisant une loi +normale (0,1) de répartition par coordonnée : + +.. code-block:: python + + [...] + "SampleAsIndependantRandomVariables":[['normal', [0, 1], 5], ['normal', [0, 1], 5]] + [...] + +La répartition des états ainsi décrite correspond à l'illustration : + + .. image:: images/sampling_05_SampleAsIndependantRandomVariables_normal.png + :align: center + +Répartition implicite d'états par le mot-clé "*SampleAsIndependantRandomVariables*" avec loi uniforme +..................................................................................................... + +La commande de génération implicite d'échantillons par +"*SampleAsIndependantRandomVariables*" est la suivante, en utilisant une loi +uniforme entre 0 et 5 de répartition par coordonnée : + +.. code-block:: python + + [...] + "SampleAsIndependantRandomVariables":[['uniform', [0, 5], 5], ['uniform', [0, 5], 5]] + [...] + +La répartition des états ainsi décrite correspond à l'illustration : + + .. image:: images/sampling_06_SampleAsIndependantRandomVariables_uniform.png + :align: center + +Répartition implicite par le mot-clé "*SampleAsIndependantRandomVariables*" avec loi de Weibull +............................................................................................... + +La commande de génération implicite d'échantillons par +"*SampleAsIndependantRandomVariables*" est la suivante, en utilisant une loi de +Weibull à un paramètre de valeur 5 de répartition par coordonnée : + +.. code-block:: python + + [...] + "SampleAsIndependantRandomVariables":[['weibull', [5], 5], ['weibull', [5], 5]] + [...] + +La répartition des états ainsi décrite correspond à l'illustration : + + .. image:: images/sampling_07_SampleAsIndependantRandomVariables_weibull.png + :align: center diff --git a/doc/fr/reference.rst b/doc/fr/reference.rst index 5ff8ab2..98cfb01 100644 --- a/doc/fr/reference.rst +++ b/doc/fr/reference.rst @@ -77,6 +77,7 @@ notations mathématiques relatives à ces entrées sont expliquées dans la sect ref_observations_requirements ref_operator_requirements ref_covariance_requirements + ref_sampling_requirements ref_observers_requirements ref_userpostanalysis_requirements diff --git a/doc/fr/scripts/simple_3DVAR1.png b/doc/fr/scripts/simple_3DVAR1.png index 9db9d39..3935912 100644 Binary files a/doc/fr/scripts/simple_3DVAR1.png and b/doc/fr/scripts/simple_3DVAR1.png differ diff --git a/doc/fr/scripts/simple_3DVAR1Plus.png b/doc/fr/scripts/simple_3DVAR1Plus.png index 010dd98..e531c00 100644 Binary files a/doc/fr/scripts/simple_3DVAR1Plus.png and b/doc/fr/scripts/simple_3DVAR1Plus.png differ diff --git a/doc/fr/scripts/simple_3DVAR2_state.png b/doc/fr/scripts/simple_3DVAR2_state.png index 512b8ab..c006b54 100644 Binary files a/doc/fr/scripts/simple_3DVAR2_state.png and b/doc/fr/scripts/simple_3DVAR2_state.png differ diff --git a/doc/fr/scripts/simple_3DVAR2_variance.png b/doc/fr/scripts/simple_3DVAR2_variance.png index 91ff438..c38451d 100644 Binary files a/doc/fr/scripts/simple_3DVAR2_variance.png and b/doc/fr/scripts/simple_3DVAR2_variance.png differ diff --git a/doc/fr/scripts/simple_3DVAR3_state.png b/doc/fr/scripts/simple_3DVAR3_state.png index b8dd2a0..65534f3 100644 Binary files a/doc/fr/scripts/simple_3DVAR3_state.png and b/doc/fr/scripts/simple_3DVAR3_state.png differ diff --git a/doc/fr/scripts/simple_3DVAR3_variance.png b/doc/fr/scripts/simple_3DVAR3_variance.png index d74815d..40891f0 100644 Binary files a/doc/fr/scripts/simple_3DVAR3_variance.png and b/doc/fr/scripts/simple_3DVAR3_variance.png differ diff --git a/doc/fr/scripts/simple_DerivativeFreeOptimization.png b/doc/fr/scripts/simple_DerivativeFreeOptimization.png index 00388ba..bba5210 100644 Binary files a/doc/fr/scripts/simple_DerivativeFreeOptimization.png and b/doc/fr/scripts/simple_DerivativeFreeOptimization.png differ diff --git a/doc/fr/scripts/simple_KalmanFilter1_state.png b/doc/fr/scripts/simple_KalmanFilter1_state.png index 5379aff..0127f34 100644 Binary files a/doc/fr/scripts/simple_KalmanFilter1_state.png and b/doc/fr/scripts/simple_KalmanFilter1_state.png differ diff --git a/doc/fr/scripts/simple_KalmanFilter1_variance.png b/doc/fr/scripts/simple_KalmanFilter1_variance.png index 080c0cd..e336b22 100644 Binary files a/doc/fr/scripts/simple_KalmanFilter1_variance.png and b/doc/fr/scripts/simple_KalmanFilter1_variance.png differ diff --git a/doc/fr/scripts/simple_KalmanFilter2_state.png b/doc/fr/scripts/simple_KalmanFilter2_state.png index 5379aff..0127f34 100644 Binary files a/doc/fr/scripts/simple_KalmanFilter2_state.png and b/doc/fr/scripts/simple_KalmanFilter2_state.png differ diff --git a/doc/fr/scripts/simple_KalmanFilter2_variance.png b/doc/fr/scripts/simple_KalmanFilter2_variance.png index 080c0cd..e336b22 100644 Binary files a/doc/fr/scripts/simple_KalmanFilter2_variance.png and b/doc/fr/scripts/simple_KalmanFilter2_variance.png differ diff --git a/doc/fr/scripts/simple_NonLinearLeastSquares.png b/doc/fr/scripts/simple_NonLinearLeastSquares.png index 00388ba..bba5210 100644 Binary files a/doc/fr/scripts/simple_NonLinearLeastSquares.png and b/doc/fr/scripts/simple_NonLinearLeastSquares.png differ diff --git a/doc/fr/scripts/simple_ParticleSwarmOptimization1.png b/doc/fr/scripts/simple_ParticleSwarmOptimization1.png index 4b11578..51bfa84 100644 Binary files a/doc/fr/scripts/simple_ParticleSwarmOptimization1.png and b/doc/fr/scripts/simple_ParticleSwarmOptimization1.png differ diff --git a/doc/fr/snippets/ModuleCompatibility.rst b/doc/fr/snippets/ModuleCompatibility.rst index 78b9942..dc4fca2 100644 --- a/doc/fr/snippets/ModuleCompatibility.rst +++ b/doc/fr/snippets/ModuleCompatibility.rst @@ -18,6 +18,6 @@ l'étendue décrite ci-dessous. Python, 3.6.5, 3.11.6 Numpy, 1.14.3, 1.26.0 Scipy, 0.19.1, 1.11.3 - MatplotLib, 2.2.2, 3.8.0 + MatplotLib, 2.2.2, 3.8.1 GnuplotPy, 1.8, 1.8 NLopt, 2.4.2, 2.7.1 diff --git a/doc/fr/snippets/QualityCriterion.rst b/doc/fr/snippets/QualityCriterion.rst index 21b5109..7cb9a2d 100644 --- a/doc/fr/snippets/QualityCriterion.rst +++ b/doc/fr/snippets/QualityCriterion.rst @@ -11,6 +11,8 @@ QualityCriterion "LeastSquares" <=> "LS" <=> "L2", "AbsoluteValue" <=> "L1", "MaximumError" <=> "ME" <=> "Linf"]. + On pourra se reporter à la section pour :ref:`section_theory_optimization` + afin de disposer de la définition détaillée de ces critères de qualité. Exemple : ``{"QualityCriterion":"DA"}`` diff --git a/doc/fr/snippets/SampleAsExplicitHyperCube.rst b/doc/fr/snippets/SampleAsExplicitHyperCube.rst index ca33e36..756ad97 100644 --- a/doc/fr/snippets/SampleAsExplicitHyperCube.rst +++ b/doc/fr/snippets/SampleAsExplicitHyperCube.rst @@ -6,4 +6,4 @@ SampleAsExplicitHyperCube explicites de chaque variable comme une liste. C'est donc une liste de listes, chacune étant de taille potentiellement différente. - Exemple : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` pour un espace d'état de dimension 2 + Exemple : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` pour un espace d'état de dimension 2. diff --git a/doc/fr/snippets/SampleAsIndependantRandomVariables.rst b/doc/fr/snippets/SampleAsIndependantRandomVariables.rst index df83f2e..1f46a83 100644 --- a/doc/fr/snippets/SampleAsIndependantRandomVariables.rst +++ b/doc/fr/snippets/SampleAsIndependantRandomVariables.rst @@ -12,4 +12,4 @@ SampleAsIndependantRandomVariables donc une liste de la même taille que celle de l'état. Exemple : - ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` pour un espace d'état de dimension 2 + ``{"SampleAsIndependantRandomVariables":[['normal',[0.,1.],3], ['uniform',[-2,2],4]]}`` pour un espace d'état de dimension 2. diff --git a/doc/fr/snippets/SampleAsMinMaxLatinHyperCube.rst b/doc/fr/snippets/SampleAsMinMaxLatinHyperCube.rst index e9684c2..ce2bf8e 100644 --- a/doc/fr/snippets/SampleAsMinMaxLatinHyperCube.rst +++ b/doc/fr/snippets/SampleAsMinMaxLatinHyperCube.rst @@ -11,4 +11,4 @@ SampleAsMinMaxLatinHyperCube selon la méthode de l'hypercube Latin (LHS). Exemple : - ``{"SampleAsMinMaxLatinHyperCube":[[0.,1.],[-1,3]]+[[2,11]]}`` pour un espace d'état de dimension 2 et 11 points d'échantillonnage + ``{"SampleAsMinMaxLatinHyperCube":[[0.,1.],[-1,3]]+[[2,11]]}`` pour un espace d'état de dimension 2 et 11 points d'échantillonnage. diff --git a/doc/fr/snippets/SampleAsMinMaxStepHyperCube.rst b/doc/fr/snippets/SampleAsMinMaxStepHyperCube.rst index f47dccc..711a37b 100644 --- a/doc/fr/snippets/SampleAsMinMaxStepHyperCube.rst +++ b/doc/fr/snippets/SampleAsMinMaxStepHyperCube.rst @@ -7,4 +7,4 @@ SampleAsMinMaxStepHyperCube liste de la même taille que celle de l'état. Les bornes sont incluses. Exemple : - ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` pour un espace d'état de dimension 2 + ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` pour un espace d'état de dimension 2. diff --git a/doc/fr/snippets/SampleAsnUplet.rst b/doc/fr/snippets/SampleAsnUplet.rst index 8e8648c..3bfd5ea 100644 --- a/doc/fr/snippets/SampleAsnUplet.rst +++ b/doc/fr/snippets/SampleAsnUplet.rst @@ -5,4 +5,4 @@ SampleAsnUplet liste de n-uplets, chaque n-uplet étant un état. Exemple : - ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` pour 3 points dans un espace d'état de dimension 4 + ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` pour 3 points dans un espace d'état de dimension 4.