From 7cafb969ea5d6280380f9c3a9fd65b8463e0cf39 Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Thu, 7 Mar 2019 18:28:21 +0100 Subject: [PATCH] Updating documentation by review and snippets (7): EN part --- doc/en/Makefile.am | 8 +- doc/en/examples.rst | 642 ------------------ doc/en/{using.rst => gui_in_salome.rst} | 20 +- doc/en/ref_algorithm_TabuSearch.rst | 151 ++++ doc/en/ref_algorithm_TangentTest.rst | 93 ++- .../ref_algorithm_UnscentedKalmanFilter.rst | 141 ++-- doc/en/snippets/AlphaBeta.rst | 14 + doc/en/snippets/CrossOverProbability_CR.rst | 4 +- doc/en/snippets/LengthOfTabuList.rst | 9 + doc/en/snippets/NoiseAddingProbability.rst | 9 + doc/en/snippets/NoiseDistribution.rst | 10 + doc/en/snippets/NoiseHalfRange.rst | 14 + .../NumberOfElementaryPerturbations.rst | 10 + doc/en/snippets/Observers.rst | 2 + doc/en/snippets/SampleAsExplicitHyperCube.rst | 8 + .../SampleAsIndependantRandomVariables.rst | 14 + .../snippets/SampleAsMinMaxStepHyperCube.rst | 10 + doc/en/snippets/SampleAsnUplet.rst | 8 + doc/en/snippets/StandardDeviation.rst | 14 + doc/en/tui.rst | 12 +- 20 files changed, 394 insertions(+), 799 deletions(-) delete mode 100644 doc/en/examples.rst rename doc/en/{using.rst => gui_in_salome.rst} (96%) create mode 100644 doc/en/ref_algorithm_TabuSearch.rst create mode 100644 doc/en/snippets/AlphaBeta.rst create mode 100644 doc/en/snippets/LengthOfTabuList.rst create mode 100644 doc/en/snippets/NoiseAddingProbability.rst create mode 100644 doc/en/snippets/NoiseDistribution.rst create mode 100644 doc/en/snippets/NoiseHalfRange.rst create mode 100644 doc/en/snippets/NumberOfElementaryPerturbations.rst create mode 100644 doc/en/snippets/SampleAsExplicitHyperCube.rst create mode 100644 doc/en/snippets/SampleAsIndependantRandomVariables.rst create mode 100644 doc/en/snippets/SampleAsMinMaxStepHyperCube.rst create mode 100644 doc/en/snippets/SampleAsnUplet.rst create mode 100644 doc/en/snippets/StandardDeviation.rst diff --git a/doc/en/Makefile.am b/doc/en/Makefile.am index c2cf3b8..40b330e 100644 --- a/doc/en/Makefile.am +++ b/doc/en/Makefile.am @@ -26,11 +26,11 @@ include $(top_srcdir)/adm_local/make_common_starter.am DOCLANG = en SPHINXOPTS = SPHINXBUILD = sphinx-build -PAPER = +PAPER = letter BUILDDIR = $(top_builddir)/doc/build/$(DOCLANG) SRCDIR = $(top_srcdir)/doc/$(DOCLANG) -EXTRA_DIST = conf.py advanced.rst examples.rst index.rst intro.rst theory.rst using.rst \ +EXTRA_DIST = conf.py advanced.rst index.rst intro.rst theory.rst tutorials_in_salome.rst gui_in_salome.rst \ resources/ADAO.png \ resources/ADAO_small.png \ resources/ADAO_small_rouge.png \ @@ -71,8 +71,8 @@ clean-local: # Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter +PAPEROPT_a4 = -D latex_elements.papersize='a4paper' +PAPEROPT_letter = -D latex_elements.papersize='letterpaper' ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR) .PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest diff --git a/doc/en/examples.rst b/doc/en/examples.rst deleted file mode 100644 index c95d06a..0000000 --- a/doc/en/examples.rst +++ /dev/null @@ -1,642 +0,0 @@ -.. - Copyright (C) 2008-2019 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_examples: - -================================================================================ -**[DocU]** Tutorials on using the ADAO module -================================================================================ - -.. |eficas_new| image:: images/eficas_new.png - :align: middle - :scale: 50% -.. |eficas_save| image:: images/eficas_save.png - :align: middle - :scale: 50% -.. |eficas_saveas| image:: images/eficas_saveas.png - :align: middle - :scale: 50% -.. |eficas_yacs| image:: images/eficas_yacs.png - :align: middle - :scale: 50% - -This section presents some examples on using the ADAO module in SALOME. The -first one shows how to build a simple data assimilation case defining explicitly -all the required input data through the GUI. The second one shows, on the same -case, how to define input data using external sources through scripts. We -describe here always Python scripts because they can be directly inserted in -YACS script nodes, but external files can use other languages. - -The mathematical notations used afterward are explained in the section -:ref:`section_theory`. - -Building an estimation case with explicit data definition ---------------------------------------------------------- - -This simple example is a demonstration one, and describes how to set a BLUE -estimation framework in order to get the *fully weighted least square estimated -state* of a system from an observation of the state and from an *a priori* -knowledge (or background) of this state. In other words, we look for the -weighted middle between the observation and the background vectors. All the -numerical values of this example are arbitrary. - -Experimental setup -++++++++++++++++++ - -We choose to operate in a 3-dimensional space. 3D is chosen in order to restrict -the size of numerical object to explicitly enter by the user, but the problem is -not dependent of the dimension and can be set in dimension 10, 100, 1000... The -observation :math:`\mathbf{y}^o` is of value 1 in each direction, so:: - - Yo = [1 1 1] - -The background state :math:`\mathbf{x}^b`, which represent some *a priori* -knowledge or a mathematical regularization, is of value of 0 in each direction, -which is:: - - Xb = [0 0 0] - -Data assimilation requires information on errors covariances :math:`\mathbf{R}` -and :math:`\mathbf{B}`, respectively for observation and background variables. -We choose here to have uncorrelated errors (that is, diagonal matrices) and to -have the same variance of 1 for all variables (that is, identity matrices). We -set:: - - B = R = [1 0 0 ; 0 1 0 ; 0 0 1] - -Last, we need an observation operator :math:`\mathbf{H}` to convert the -background value in the space of observation values. Here, because the space -dimensions are the same, we can choose the identity as the observation -operator:: - - H = [1 0 0 ; 0 1 0 ; 0 0 1] - -With such choices, the "Best Linear Unbiased Estimator" (BLUE) will be the -average vector between :math:`\mathbf{y}^o` and :math:`\mathbf{x}^b`, named the -*analysis*, denoted by :math:`\mathbf{x}^a`, and its value is:: - - Xa = [0.5 0.5 0.5] - -As an extension of this example, one can change the variances represented by -:math:`\mathbf{B}` or :math:`\mathbf{R}` independently, and the analysis -:math:`\mathbf{x}^a` will move to :math:`\mathbf{y}^o` or to -:math:`\mathbf{x}^b`, in inverse proportion of the variances in -:math:`\mathbf{B}` and :math:`\mathbf{R}`. As an other extension, it is also -equivalent to search for the analysis thought a BLUE algorithm or a 3DVAR one. - -Using the graphical interface (GUI) to build the ADAO case -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -First, you have to activate the ADAO module by choosing the appropriate module -button or menu of SALOME, and you will see: - - .. _adao_activate2: - .. image:: images/adao_activate.png - :align: center - :width: 100% - .. centered:: - **Activating the module ADAO in SALOME** - -Choose the "*New*" button in this window. You will directly get the embedded -case editor interface for variables definition, along with the SALOME "*Object -browser*". You can then click on the "*New*" button |eficas_new| to create a new -ADAO case, and you will see: - - .. _adao_viewer: - .. image:: images/adao_viewer.png - :align: center - :width: 100% - .. centered:: - **The embedded editor for cases definition in module ADAO** - -Then, fill in the variables to build the ADAO case by using the experimental set -up described above. All the technical information given above will be directly -inserted in the ADAO case definition, by using the *String* type for all the -variables. When the case definition is ready, save it to a "*JDC (\*.comm)*" -native file somewhere in your path. Remember that other files will be also -created near this first one, so it is better to make a specific directory for -your case, and to save the file inside. The name of the file will appear in the -"*Object browser*" window, under the "*ADAO*" menu. The final case definition -looks like this: - - .. _adao_jdcexample01: - .. image:: images/adao_jdcexample01.png - :align: center - :width: 100% - .. centered:: - **Definition of the experimental setup chosen for the ADAO case** - -To go further, we need now to generate the YACS scheme from the ADAO case -definition. In order to do that, right click on the name of the file case in the -"*Object browser*" window, and choose the "*Export to YACS*" sub-menu (or the -"*Export to YACS*" button |eficas_yacs|) as below: - - .. _adao_exporttoyacs00: - .. image:: images/adao_exporttoyacs.png - :align: center - :scale: 75% - .. centered:: - **"Export to YACS" sub-menu to generate the YACS scheme from the ADAO case** - -This command will generate the YACS scheme, activate YACS module in SALOME, and -open the new scheme in the GUI of the YACS module [#]_. After eventually -reordering the nodes by using the "*arrange local nodes*" sub-menu of the YACS -graphical view of the scheme, you get the following representation of the -generated ADAO scheme: - - .. _yacs_generatedscheme: - .. image:: images/yacs_generatedscheme.png - :align: center - :width: 100% - .. centered:: - **YACS generated scheme from the ADAO case** - -After that point, all the modifications, executions and post-processing of the -data assimilation scheme will be done in the YACS module. In order to check the -result in a simple way, we use the "*UserPostAnalysis*" node (or we create here -a new YACS node by using the "*in-line script node*" sub-menu of the YACS -graphical view). - -This script node will retrieve the data assimilation analysis from the -"*algoResults*" output port of the computation bloc (which gives access to a -SALOME Python Object), and will print it on the standard output. - -To obtain this, the in-line script node need to have an input port of type -"*pyobj*", named "*Study*" for example, that have to be linked graphically to -the "*algoResults*" output port of the computation bloc. Then, the code to fill -in the script node is:: - - Xa = Study.getResults().get("Analysis")[-1] - - print() - print("Analysis =",Xa) - print() - -The (initial or augmented) YACS scheme can be saved (overwriting the generated -scheme if the "*Save*" command or button are used, or with a new name through -the "*Save as*" command). Ideally, the implementation of such post-processing -procedure can be done in YACS to test, and then entirely saved in one Python -script that can be integrated in the ADAO case by using the keyword -"*UserPostAnalysis*". - -Then, classically in YACS, the scheme have to be compiled for run, and then -executed. After completion, the printing on standard output is available in the -"*YACS Container Log*", obtained through the right click menu of the "*proc*" -window in the YACS scheme as shown below: - - .. _yacs_containerlog: - .. image:: images/yacs_containerlog.png - :align: center - :width: 100% - .. centered:: - **YACS menu for Container Log, and dialog window showing the log** - -We verify that the result is correct by checking that the log dialog window -contains the following line:: - - Analysis = [0.5, 0.5, 0.5] - -as shown in the image above. - -As a simple extension of this example, one can notice that the same problem -solved with a 3DVAR algorithm gives the same result. This algorithm can be -chosen at the ADAO case building step, before entering in YACS step. The -ADAO 3DVAR case will look completely similar to the BLUE algorithmic case, as -shown by the following figure: - - .. _adao_jdcexample02: - .. image:: images/adao_jdcexample02.png - :align: center - :width: 100% - .. centered:: - **Defining an ADAO 3DVAR case looks completely similar to a BLUE case** - -There is only one command changing, with "*3DVAR*" value in the "*Algorithm*" -field instead of "*Blue*". - -Building an estimation case with external data definition by scripts --------------------------------------------------------------------- - -It is useful to get parts or all of the data from external definition, using -Python script files to provide access to the data. As an example, we build here -an ADAO case representing the same experimental setup as in the above example -`Building an estimation case with explicit data definition`_, but using data -from a single one external Python script file. - -First, we write the following script file, using conventional names for the -required variables. Here, all the input variables are defined in the same -script, but the user can choose to split the file in several ones, or to mix -explicit data definition in the ADAO GUI and implicit data definition by -external files. The present script file looks like:: - - import numpy - # - # Definition of the Background as a vector - # ---------------------------------------- - Background = [0, 0, 0] - # - # Definition of the Observation as a vector - # ----------------------------------------- - Observation = "1 1 1" - # - # Definition of the Background Error covariance as a matrix - # --------------------------------------------------------- - BackgroundError = numpy.array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]) - # - # Definition of the Observation Error covariance as a matrix - # ---------------------------------------------------------- - ObservationError = numpy.matrix("1 0 0 ; 0 1 0 ; 0 0 1") - # - # Definition of the Observation Operator as a matrix - # -------------------------------------------------- - ObservationOperator = numpy.identity(3) - -The names of the Python variables above are mandatory, in order to define the -right case variables, but the Python script can be bigger and define classes, -functions, file or database access, etc. with other names. Moreover, the above -script shows different ways to define arrays and matrices, using list, string -(as in Numpy or Octave), Numpy array type or Numpy matrix type, and Numpy -special functions. All of these syntax are valid. - -After saving this script in a file (named here "*script.py*" for the example) -somewhere in your path, we use the graphical interface (GUI) to build the ADAO -case. The procedure to fill in the case is similar to the previous example -except that, instead of selecting the "*String*" option for the "*FROM*" keyword -of each variable, we select the "*Script*" one. This leads to a -"*SCRIPT_DATA/SCRIPT_FILE*" entry in the graphical tree, allowing to choose a -file as: - - .. _adao_scriptentry01: - .. image:: images/adao_scriptentry01.png - :align: center - :width: 100% - .. centered:: - **Defining an input value using an external script file** - -Other steps and results are exactly the same as in the `Building an estimation -case with explicit data definition`_ previous example. - -In fact, this script methodology is the easiest way to retrieve data from -in-line or previous calculations, from static files, from database or from -stream, all of them inside or outside of SALOME. It allows also to modify easily -some input data, for example for debug purpose or for repetitive execution -process, and it is the most versatile method in order to parametrize the input -data. **But be careful, script methodology is not a "safe" procedure, in the -sense that erroneous data, or errors in calculations, can be directly injected -into the YACS scheme execution. The user have to carefully verify the content of -his scripts.** - -Adding parameters to control the data assimilation algorithm ------------------------------------------------------------- - -One can add some optional parameters to control the data assimilation algorithm -calculation. This is done by using optional parameters in the -"*AlgorithmParameters*" command of the ADAO case definition, which is a keyword -of the "*ASSIMILATION_STUDY*" general command. This keyword requires an explicit -definition of the values from default ones, or from a Python dictionary, -containing some key/value pairs. The list of possible optional parameters are -given in the section :ref:`section_reference` and its subsections. The -recommandation is to use the explicit definition of values from the default list -of optionnal parameters, as here with the "*MaximumNumberOfSteps*": - - .. _adao_scriptentry02: - .. image:: images/adao_scriptentry02.png - :align: center - :width: 100% - .. centered:: - **Adding parameters to control the algorithm and the outputs** - -This dictionary can be defined, for example, in an external Python script -file, using the mandatory variable name "*AlgorithmParameters*" for the -dictionary. All the keys inside the dictionary are optional, they all have -default values, and can exist without being used. For example:: - - AlgorithmParameters = { - "Minimizer" : "LBFGSB", # Recommended - "MaximumNumberOfSteps" : 10, - } - -If no bounds at all are required on the control variables, then one can choose -the "*BFGS*" or "*CG*" minimization algorithm for all the variational data -assimilation or optimization algorithms. For constrained optimization, the -minimizer "*LBFGSB*" is often more robust, but the "*TNC*" is sometimes more -effective. In a general way, the "*LBFGSB*" algorithm choice is recommended. -Then the script can be added to the ADAO case, in a file entry describing the -"*Parameters*" keyword. - -Other steps and results are exactly the same as in the `Building an estimation -case with explicit data definition`_ previous example. The dictionary can also -be directly given in the input field of string type associated for the keyword. - -Building a complex case with external data definition by scripts ----------------------------------------------------------------- - -This more complex and complete example has to been considered as a framework for -user inputs treatment, that need to be tailored for each real application. -Nevertheless, the file skeletons are sufficiently general to have been used for -various applications in neutronic, fluid mechanics... Here, we will not focus on -the results, but more on the user control of inputs and outputs in an ADAO case. -As previously, all the numerical values of this example are arbitrary. - -The objective is to setup the input and output definitions of a physical -estimation case by external python scripts, using a general non-linear operator, -adding control on parameters and so on... The complete framework scripts can be -found in the ADAO skeletons examples directory under the name -"*External_data_definition_by_scripts*". - -Experimental setup -++++++++++++++++++ - -We continue to operate in a 3-dimensional space, in order to restrict -the size of numerical object shown in the scripts, but the problem is -not dependent of the dimension. - -We choose a twin experiment context, using a known true state -:math:`\mathbf{x}^t` but of arbitrary value:: - - Xt = [1 2 3] - -The background state :math:`\mathbf{x}^b`, which represent some *a priori* -knowledge of the true state, is build as a normal random perturbation of 20% of -the true state :math:`\mathbf{x}^t` for each component, which is:: - - Xb = Xt + normal(0, 20%*Xt) - -To describe the background error covariances matrix :math:`\mathbf{B}`, we make -as previously the hypothesis of uncorrelated errors (that is, a diagonal matrix, -of size 3x3 because :math:`\mathbf{x}^b` is of lenght 3) and to have the same -variance of 0.1 for all variables. We get:: - - B = 0.1 * diagonal( length(Xb) ) - -We suppose that there exist an observation operator :math:`\mathbf{H}`, which -can be non linear. In real calibration procedure or inverse problems, the -physical simulation codes are embedded in the observation operator. We need also -to know its gradient with respect to each calibrated variable, which is a rarely -known information with industrial codes. But we will see later how to obtain an -approximated gradient in this case. - -Being in twin experiments, the observation :math:`\mathbf{y}^o` and its error -covariances matrix :math:`\mathbf{R}` are generated by using the true state -:math:`\mathbf{x}^t` and the observation operator :math:`\mathbf{H}`:: - - Yo = H( Xt ) - -and, with an arbitrary standard deviation of 1% on each error component:: - - R = 0.0001 * diagonal( length(Yo) ) - -All the information required for estimation by data assimilation are then -defined. - -Skeletons of the scripts describing the setup -+++++++++++++++++++++++++++++++++++++++++++++ - -We give here the essential parts of each script used afterward to build the -ADAO case. Remember that using these scripts in real Python files requires to -correctly define the path to imported modules or codes (even if the module is in -the same directory that the importing Python file. We indicate the path -adjustment using the mention ``"# INSERT PHYSICAL SCRIPT PATH"``), the encoding -if necessary, etc. The indicated file names for the following scripts are -arbitrary. Examples of complete file scripts are available in the ADAO examples -standard directory. - -We first define the true state :math:`\mathbf{x}^t` and some convenient matrix -building function, in a Python script file named -``Physical_data_and_covariance_matrices.py``:: - - import numpy - # - def True_state(): - """ - Arbitrary values and names, as a tuple of two series of same length - """ - return (numpy.array([1, 2, 3]), ['Para1', 'Para2', 'Para3']) - # - def Simple_Matrix( size, diagonal=None ): - """ - Diagonal matrix, with either 1 or a given vector on the diagonal - """ - if diagonal is not None: - S = numpy.diag( diagonal ) - else: - S = numpy.matrix(numpy.identity(int(size))) - return S - -We can then define the background state :math:`\mathbf{x}^b` as a random -perturbation of the true state, adding a *required ADAO variable* at the end of -the script the definition, in order to export the defined value. It is done in a -Python script file named ``Script_Background_xb.py``:: - - from Physical_data_and_covariance_matrices import True_state - import numpy - # - xt, names = True_state() - # - Standard_deviation = 0.2*xt # 20% for each variable - # - xb = xt + abs(numpy.random.normal(0.,Standard_deviation,size=(len(xt),))) - # - # Creating the required ADAO variable - # ----------------------------------- - Background = list(xb) - -In the same way, we define the background error covariance matrix -:math:`\mathbf{B}` as a diagonal matrix, of the same diagonal length as the -background of the true state, using the convenient function already defined. It -is done in a Python script file named ``Script_BackgroundError_B.py``:: - - from Physical_data_and_covariance_matrices import True_state, Simple_Matrix - # - xt, names = True_state() - # - B = 0.1 * Simple_Matrix( size = len(xt) ) - # - # Creating the required ADAO variable - # ----------------------------------- - BackgroundError = B - -To continue, we need the observation operator :math:`\mathbf{H}` as a function -of the state. It is here defined in an external file named -``"Physical_simulation_functions.py"``, which should contain one function -conveniently named here ``"DirectOperator"``. This function is user one, -representing as programming function the :math:`\mathbf{H}` operator. We suppose -this function is then given by the user. A simple skeleton is given here for -convenience:: - - def DirectOperator( XX ): - """ Direct non-linear simulation operator """ - # - # --------------------------------------> EXAMPLE TO BE REMOVED - if type(XX) is type(numpy.matrix([])): # EXAMPLE TO BE REMOVED - HX = XX.A1.tolist() # EXAMPLE TO BE REMOVED - elif type(XX) is type(numpy.array([])): # EXAMPLE TO BE REMOVED - HX = numpy.matrix(XX).A1.tolist() # EXAMPLE TO BE REMOVED - else: # EXAMPLE TO BE REMOVED - HX = XX # EXAMPLE TO BE REMOVED - # --------------------------------------> EXAMPLE TO BE REMOVED - # - return numpy.array( HX ) - -We does not need the linear companion operators ``"TangentOperator"`` and -``"AdjointOperator"`` because they will be approximated using ADAO capabilities. - -We insist on the fact that these non-linear operator ``"DirectOperator"``, -tangent operator ``"TangentOperator"`` and adjoint operator -``"AdjointOperator"`` come from the physical knowledge, include the reference -physical simulation code, and have to be carefully setup by the data -assimilation or optimization user. The simulation errors or missuses of the -operators can not be detected or corrected by the data assimilation and -optimization ADAO framework alone. - -In this twin experiments framework, the observation :math:`\mathbf{y}^o` and its -error covariances matrix :math:`\mathbf{R}` can be generated. It is done in two -Python script files, the first one being named ``Script_Observation_yo.py``:: - - from Physical_data_and_covariance_matrices import True_state - from Physical_simulation_functions import DirectOperator - # - xt, noms = True_state() - # - yo = DirectOperator( xt ) - # - # Creating the required ADAO variable - # ----------------------------------- - Observation = list(yo) - -and the second one named ``Script_ObservationError_R.py``:: - - from Physical_data_and_covariance_matrices import True_state, Simple_Matrix - from Physical_simulation_functions import DirectOperator - # - xt, names = True_state() - # - yo = DirectOperator( xt ) - # - R = 0.0001 * Simple_Matrix( size = len(yo) ) - # - # Creating the required ADAO variable - # ----------------------------------- - ObservationError = R - -As in previous examples, it can be useful to define some parameters for the data -assimilation algorithm. For example, if we use the standard "*3DVAR*" algorithm, -the following parameters can be defined in a Python script file named -``Script_AlgorithmParameters.py``:: - - # Creating the required ADAO variable - # ----------------------------------- - AlgorithmParameters = { - "Minimizer" : "LBFGSB", # Recommended - "MaximumNumberOfSteps" : 15, # Number of global iterative steps - "Bounds" : [ - [ None, None ], # Bound on the first parameter - [ 0., 4. ], # Bound on the second parameter - [ 0., None ], # Bound on the third parameter - ], - } - -Finally, it is common to post-process the results, retrieving them after the -data assimilation phase in order to analyze, print or show them. It requires to -use a intermediary Python script file in order to extract these results at the -end of the a data assimilation or optimization process. The following example -Python script file, named ``Script_UserPostAnalysis.py``, illustrates the fact:: - - from Physical_data_and_covariance_matrices import True_state - import numpy - # - xt, names = True_state() - xa = ADD.get("Analysis")[-1] - x_series = ADD.get("CurrentState")[:] - J = ADD.get("CostFunctionJ")[:] - # - # Verifying the results by printing - # --------------------------------- - print() - print("xt = %s"%xt) - print("xa = %s"%numpy.array(xa)) - print() - for i in range( len(x_series) ): - print("Step %2i : J = %.5e and X = %s"%(i, J[i], x_series[i])) - print() - -At the end, we get a description of the whole case setup through a set of files -listed here: - -#. ``Physical_data_and_covariance_matrices.py`` -#. ``Physical_simulation_functions.py`` -#. ``Script_AlgorithmParameters.py`` -#. ``Script_BackgroundError_B.py`` -#. ``Script_Background_xb.py`` -#. ``Script_ObservationError_R.py`` -#. ``Script_Observation_yo.py`` -#. ``Script_UserPostAnalysis.py`` - -We insist here that all these scripts are written by the user and can not be -automatically tested by ADAO. So the user is required to verify the scripts (and -in particular their input/output) in order to limit the difficulty of debug. We -recall: **script methodology is not a "safe" procedure, in the sense that -erroneous data, or errors in calculations, can be directly injected into the -YACS scheme execution.** - -Building the case with external data definition by scripts -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -All these scripts can then be used to define the ADAO case with external data -definition by Python script files. It is entirely similar to the method -described in the `Building an estimation case with external data definition by -scripts`_ previous section. For each variable to be defined, we select the -"*Script*" option of the "*FROM*" keyword, which leads to a -"*SCRIPT_DATA/SCRIPT_FILE*" entry in the tree. For the "*ObservationOperator*" -keyword, we choose the "*ScriptWithOneFunction*" form and keep the default -differential increment. - -The other steps to build the ADAO case are exactly the same as in the `Building -an estimation case with explicit data definition`_ previous section. - -Using the simple linear operator :math:`\mathbf{H}` from the Python script file -``Physical_simulation_functions.py`` in the ADAO examples standard directory, -the results will look like:: - - xt = [1 2 3] - xa = [ 1.000014 2.000458 3.000390] - - Step 0 : J = 1.81750e+03 and X = [1.014011, 2.459175, 3.390462] - Step 1 : J = 1.81750e+03 and X = [1.014011, 2.459175, 3.390462] - Step 2 : J = 1.79734e+01 and X = [1.010771, 2.040342, 2.961378] - Step 3 : J = 1.79734e+01 and X = [1.010771, 2.040342, 2.961378] - Step 4 : J = 1.81909e+00 and X = [1.000826, 2.000352, 3.000487] - Step 5 : J = 1.81909e+00 and X = [1.000826, 2.000352, 3.000487] - Step 6 : J = 1.81641e+00 and X = [1.000247, 2.000651, 3.000156] - Step 7 : J = 1.81641e+00 and X = [1.000247, 2.000651, 3.000156] - Step 8 : J = 1.81569e+00 and X = [1.000015, 2.000432, 3.000364] - Step 9 : J = 1.81569e+00 and X = [1.000015, 2.000432, 3.000364] - Step 10 : J = 1.81568e+00 and X = [1.000013, 2.000458, 3.000390] - ... - -The state at the first step is the randomly generated background state -:math:`\mathbf{x}^b`. During calculation, these printings on standard output are -available in the "*YACS Container Log*" window, obtained through the right click -menu of the "*proc*" window in the YACS executed scheme. - -.. [#] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform. diff --git a/doc/en/using.rst b/doc/en/gui_in_salome.rst similarity index 96% rename from doc/en/using.rst rename to doc/en/gui_in_salome.rst index 04f11ad..b88684e 100644 --- a/doc/en/using.rst +++ b/doc/en/gui_in_salome.rst @@ -21,10 +21,10 @@ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D -.. _section_using: +.. _section_gui_in_salome: ================================================================================ -**[DocU]** Using the ADAO module +**[DocR]** Graphical User Interface for ADAO (GUI/EFICAS) ================================================================================ .. |eficas_new| image:: images/eficas_new.png @@ -48,7 +48,7 @@ describe the general progression to establish an ADAO case, the details being given in the following chapters. It is completed by the detailed description of all the commands and keywords in the section :ref:`section_reference`, by advanced usage procedures in the section :ref:`section_advanced`, and by -examples in the section :ref:`section_examples`. +examples in the section :ref:`section_tutorials_in_salome`. Logical procedure to build an ADAO case --------------------------------------- @@ -64,11 +64,11 @@ data can already be available in SALOME or not. Basically, the procedure of using ADAO involves the following steps: - - :ref:`section_u_step1` - - :ref:`section_u_step2` - - :ref:`section_u_step3` - - :ref:`section_u_step4` - - :ref:`section_u_step5` +- :ref:`section_u_step1` +- :ref:`section_u_step2` +- :ref:`section_u_step3` +- :ref:`section_u_step4` +- :ref:`section_u_step5` Each step will be detailed in the next section. @@ -125,7 +125,7 @@ commands or keywords are already present, none of them can be suppressed. Optional keywords can be added by choosing them in a list of suggestions of allowed ones for the main command, for example the "*ASSIMILATION_STUDY*" command. As an example, one can add parameters in the "*AlgorithmParameters*" -keyword, as described in the last part of the section :ref:`section_examples`. +keyword, as described in the last part of the section :ref:`section_tutorials_in_salome`. At the end, when all fields or keywords have been correctly defined, each line of the commands tree must have a green flag. This indicates that the whole case @@ -219,7 +219,7 @@ data assimilation or optimization evaluation problem, noted as Such method can be used to print results, or to convert these ones to structures that can be used in the native or external SALOME post-processing. A -simple example is given in the section :ref:`section_examples`. +simple example is given in the section :ref:`section_tutorials_in_salome`. .. _section_u_step5: diff --git a/doc/en/ref_algorithm_TabuSearch.rst b/doc/en/ref_algorithm_TabuSearch.rst new file mode 100644 index 0000000..72f7bb9 --- /dev/null +++ b/doc/en/ref_algorithm_TabuSearch.rst @@ -0,0 +1,151 @@ +.. + Copyright (C) 2008-2019 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 + +.. index:: single: TabuSearch +.. _section_ref_algorithm_TabuSearch: + +Calculation algorithm "*TabuSearch*" +------------------------------------ + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo01.rst + +This algorithm realizes an estimation of the state of a system by minimization +of a cost function :math:`J` without gradient. It is a method that does not use +the derivatives of the cost function. It falls in the same category than the +:ref:`section_ref_algorithm_DerivativeFreeOptimization`, the +:ref:`section_ref_algorithm_ParticleSwarmOptimization` or the +:ref:`section_ref_algorithm_DifferentialEvolution`. + +This is an optimization method allowing for global minimum search of a general +error function :math:`J` of type :math:`L^1`, :math:`L^2` or :math:`L^{\infty}`, +with or without weights. The default error function is the augmented weighted +least squares function, classically used in data assimilation. + +It works by iterative random exploration of the surroundings of the current +point, to choose the state that minimizes the error function. To avoid +returning to a point already explored, the algorithm's memory mechanism allows +to exclude (hence the name *tabu*) the return to the last explored states. +Positions already explored are kept in a list of finite length. + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo02.rst + +.. include:: snippets/Background.rst + +.. include:: snippets/BackgroundError.rst + +.. include:: snippets/Observation.rst + +.. include:: snippets/ObservationError.rst + +.. include:: snippets/ObservationOperator.rst + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo03AdOp.rst + +.. include:: snippets/LengthOfTabuList.rst + +.. include:: snippets/MaximumNumberOfSteps_50.rst + +.. include:: snippets/NoiseAddingProbability.rst + +.. include:: snippets/NoiseDistribution.rst + +.. include:: snippets/NoiseHalfRange.rst + +.. include:: snippets/NumberOfElementaryPerturbations.rst + +.. include:: snippets/QualityCriterion.rst + +.. include:: snippets/SetSeed.rst + +.. include:: snippets/StandardDeviation.rst + +StoreSupplementaryCalculations + .. index:: single: StoreSupplementaryCalculations + + This list indicates the names of the supplementary variables that can be + available at the end of the algorithm. It involves potentially costly + calculations or memory consumptions. The default is a void list, none of + these variables being calculated and stored by default. The possible names + are in the following list: [ + "BMA", + "OMA", + "OMB", + "CurrentState", + "CostFunctionJ", + "CostFunctionJb", + "CostFunctionJo", + "Innovation", + "SimulatedObservationAtBackground", + "SimulatedObservationAtCurrentState", + "SimulatedObservationAtOptimum", + ]. + + Example : + ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}`` + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo04.rst + +.. include:: snippets/Analysis.rst + +.. include:: snippets/CostFunctionJ.rst + +.. include:: snippets/CostFunctionJb.rst + +.. include:: snippets/CostFunctionJo.rst + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo05.rst + +.. include:: snippets/BMA.rst + +.. include:: snippets/OMA.rst + +.. include:: snippets/OMB.rst + +.. include:: snippets/CurrentState.rst + +.. include:: snippets/Innovation.rst + +.. include:: snippets/SimulatedObservationAtBackground.rst + +.. include:: snippets/SimulatedObservationAtCurrentState.rst + +.. include:: snippets/SimulatedObservationAtOptimum.rst + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo06.rst + +- :ref:`section_ref_algorithm_DerivativeFreeOptimization` +- :ref:`section_ref_algorithm_DifferentialEvolution` +- :ref:`section_ref_algorithm_ParticleSwarmOptimization` + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo07.rst + +- [Glover89]_ +- [Glover90]_ +- [WikipediaTS]_ diff --git a/doc/en/ref_algorithm_TangentTest.rst b/doc/en/ref_algorithm_TangentTest.rst index a8ce0fd..ff3f4d1 100644 --- a/doc/en/ref_algorithm_TangentTest.rst +++ b/doc/en/ref_algorithm_TangentTest.rst @@ -27,8 +27,8 @@ Checking algorithm "*TangentTest*" ---------------------------------- -Description -+++++++++++ +.. ------------------------------------ .. +.. include:: snippets/Header2Algo01.rst This algorithm allows to check the quality of the tangent operator, by calculating a residue with known theoretical properties. @@ -52,72 +52,57 @@ calculation precision is reached. One take :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` and :math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` is the calculation code. -Optional and required commands -++++++++++++++++++++++++++++++ +.. ------------------------------------ .. +.. include:: snippets/Header2Algo02.rst -The general required commands, available in the editing user interface, are the -following: +.. include:: snippets/CheckingPoint.rst - .. include:: snippets/CheckingPoint.rst +.. include:: snippets/ObservationOperator.rst - .. include:: snippets/ObservationOperator.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo03Chck.rst -The general optional commands, available in the editing user interface, are -indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters -of the command "*AlgorithmParameters*" allow to choose the specific options, -described hereafter, of the algorithm. See -:ref:`section_ref_options_Algorithm_Parameters` for the good use of this -command. +.. include:: snippets/AmplitudeOfInitialDirection.rst -The options of the algorithm are the following: +.. include:: snippets/EpsilonMinimumExponent.rst - .. include:: snippets/AmplitudeOfInitialDirection.rst +.. include:: snippets/InitialDirection.rst - .. include:: snippets/EpsilonMinimumExponent.rst +.. include:: snippets/SetSeed.rst - .. include:: snippets/InitialDirection.rst +StoreSupplementaryCalculations + .. index:: single: StoreSupplementaryCalculations - .. include:: snippets/SetSeed.rst + This list indicates the names of the supplementary variables that can be + available at the end of the algorithm. It involves potentially costly + calculations or memory consumptions. The default is a void list, none of + these variables being calculated and stored by default. The possible names + are in the following list: [ + "CurrentState", + "Residu", + "SimulatedObservationAtCurrentState", + ]. - StoreSupplementaryCalculations - .. index:: single: StoreSupplementaryCalculations + Example : + ``{"StoreSupplementaryCalculations":["CurrentState"]}`` - This list indicates the names of the supplementary variables that can be - available at the end of the algorithm. It involves potentially costly - calculations or memory consumptions. The default is a void list, none of - these variables being calculated and stored by default. The possible names - are in the following list: ["CurrentState", "Residu", - "SimulatedObservationAtCurrentState"]. +.. ------------------------------------ .. +.. include:: snippets/Header2Algo04.rst - Example : - ``{"StoreSupplementaryCalculations":["CurrentState"]}`` +.. include:: snippets/Residu.rst -Information and variables available at the end of the algorithm -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. ------------------------------------ .. +.. include:: snippets/Header2Algo05.rst -At the output, after executing the algorithm, there are variables and -information originating from the calculation. The description of -:ref:`section_ref_output_variables` show the way to obtain them by the method -named ``get`` of the variable "*ADD*" of the post-processing. The input -variables, available to the user at the output in order to facilitate the -writing of post-processing procedures, are described in the -:ref:`subsection_r_o_v_Inventaire`. +.. include:: snippets/CurrentState.rst -The unconditional outputs of the algorithm are the following: +.. include:: snippets/SimulatedObservationAtCurrentState.rst - .. include:: snippets/Residu.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo06.rst -The conditional outputs of the algorithm are the following: - - .. include:: snippets/CurrentState.rst - - .. include:: snippets/SimulatedObservationAtCurrentState.rst - -See also -++++++++ - -References to other sections: - - :ref:`section_ref_algorithm_FunctionTest` - - :ref:`section_ref_algorithm_LinearityTest` - - :ref:`section_ref_algorithm_AdjointTest` - - :ref:`section_ref_algorithm_GradientTest` +- :ref:`section_ref_algorithm_FunctionTest` +- :ref:`section_ref_algorithm_LinearityTest` +- :ref:`section_ref_algorithm_AdjointTest` +- :ref:`section_ref_algorithm_GradientTest` +- :ref:`section_ref_algorithm_LocalSensitivityTest` diff --git a/doc/en/ref_algorithm_UnscentedKalmanFilter.rst b/doc/en/ref_algorithm_UnscentedKalmanFilter.rst index f472695..3c48907 100644 --- a/doc/en/ref_algorithm_UnscentedKalmanFilter.rst +++ b/doc/en/ref_algorithm_UnscentedKalmanFilter.rst @@ -27,8 +27,8 @@ Calculation algorithm "*UnscentedKalmanFilter*" ----------------------------------------------- -Description -+++++++++++ +.. ------------------------------------ .. +.. include:: snippets/Header2Algo01.rst This algorithm realizes an estimation of the state of a dynamic system by a "unscented" Kalman Filter, avoiding to have to perform the tangent and adjoint @@ -46,114 +46,93 @@ In case of linear of "slightly" non-linear operators, one can easily use the to evaluate on small systems. One can verify the linearity of the operators with the help of the :ref:`section_ref_algorithm_LinearityTest`. -Optional and required commands -++++++++++++++++++++++++++++++ +.. ------------------------------------ .. +.. include:: snippets/Header2Algo02.rst -The general required commands, available in the editing user interface, are the -following: +.. include:: snippets/Background.rst - .. include:: snippets/Background.rst +.. include:: snippets/BackgroundError.rst - .. include:: snippets/BackgroundError.rst +.. include:: snippets/EvolutionError.rst - .. include:: snippets/EvolutionError.rst +.. include:: snippets/EvolutionModel.rst - .. include:: snippets/EvolutionModel.rst +.. include:: snippets/Observation.rst - .. include:: snippets/Observation.rst +.. include:: snippets/ObservationError.rst - .. include:: snippets/ObservationError.rst +.. include:: snippets/ObservationOperator.rst - .. include:: snippets/ObservationOperator.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo03AdOp.rst -The general optional commands, available in the editing user interface, are -indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters -of the command "*AlgorithmParameters*" allows to choose the specific options, -described hereafter, of the algorithm. See -:ref:`section_ref_options_Algorithm_Parameters` for the good use of this -command. +.. include:: snippets/BoundsWithExtremes.rst -The options of the algorithm are the following: +.. include:: snippets/ConstrainedBy.rst - .. include:: snippets/BoundsWithExtremes.rst +.. include:: snippets/EstimationOf.rst - .. include:: snippets/ConstrainedBy.rst +.. include:: snippets/AlphaBeta.rst - .. include:: snippets/EstimationOf.rst +StoreSupplementaryCalculations + .. index:: single: StoreSupplementaryCalculations - Alpha, Beta, Kappa, Reconditioner - .. index:: single: Alpha - .. index:: single: Beta - .. index:: single: Kappa - .. index:: single: Reconditioner + This list indicates the names of the supplementary variables that can be + available at the end of the algorithm. It involves potentially costly + calculations or memory consumptions. The default is a void list, none of + these variables being calculated and stored by default. The possible names + are in the following list: [ + "APosterioriCorrelations", + "APosterioriCovariance", + "APosterioriStandardDeviations", + "APosterioriVariances", + "BMA", + "CostFunctionJ", + "CostFunctionJb", + "CostFunctionJo", + "CurrentState", + "Innovation", + ]. - These keys are internal scaling parameters. "Alpha" requires a value between - 1.e-4 and 1. "Beta" has an optimal value of 2 for Gaussian *a priori* - distribution. "Kappa" requires an integer value, and the right default is - obtained by setting it to 0. "Reconditioner" requires a value between 1.e-3 - and 10, it defaults to 1. + Example : + ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}`` - Example : - ``{"Alpha":1,"Beta":2,"Kappa":0,"Reconditioner":1}`` +.. ------------------------------------ .. +.. include:: snippets/Header2Algo04.rst - StoreSupplementaryCalculations - .. index:: single: StoreSupplementaryCalculations +.. include:: snippets/Analysis.rst - This list indicates the names of the supplementary variables that can be - available at the end of the algorithm. It involves potentially costly - calculations or memory consumptions. The default is a void list, none of - these variables being calculated and stored by default. The possible names - are in the following list: ["APosterioriCorrelations", - "APosterioriCovariance", "APosterioriStandardDeviations", - "APosterioriVariances", "BMA", "CostFunctionJ", "CostFunctionJb", - "CostFunctionJo", "CurrentState", "Innovation"]. +.. ------------------------------------ .. +.. include:: snippets/Header2Algo05.rst - Example : - ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}`` +.. include:: snippets/APosterioriCorrelations.rst -Information and variables available at the end of the algorithm -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. include:: snippets/APosterioriCovariance.rst -At the output, after executing the algorithm, there are variables and -information originating from the calculation. The description of -:ref:`section_ref_output_variables` show the way to obtain them by the method -named ``get`` of the variable "*ADD*" of the post-processing. The input -variables, available to the user at the output in order to facilitate the -writing of post-processing procedures, are described in the -:ref:`subsection_r_o_v_Inventaire`. +.. include:: snippets/APosterioriStandardDeviations.rst -The unconditional outputs of the algorithm are the following: +.. include:: snippets/APosterioriVariances.rst - .. include:: snippets/Analysis.rst +.. include:: snippets/BMA.rst -The conditional outputs of the algorithm are the following: +.. include:: snippets/CostFunctionJ.rst - .. include:: snippets/APosterioriCorrelations.rst +.. include:: snippets/CostFunctionJb.rst - .. include:: snippets/APosterioriCovariance.rst +.. include:: snippets/CostFunctionJo.rst - .. include:: snippets/APosterioriStandardDeviations.rst +.. include:: snippets/CurrentState.rst - .. include:: snippets/APosterioriVariances.rst +.. include:: snippets/Innovation.rst - .. include:: snippets/BMA.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo06.rst - .. include:: snippets/CostFunctionJ.rst +- :ref:`section_ref_algorithm_KalmanFilter` +- :ref:`section_ref_algorithm_ExtendedKalmanFilter` +- :ref:`section_ref_algorithm_EnsembleKalmanFilter` - .. include:: snippets/CostFunctionJb.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo07.rst - .. include:: snippets/CostFunctionJo.rst - - .. include:: snippets/CurrentState.rst - - .. include:: snippets/Innovation.rst - -See also -++++++++ - -References to other sections: - - :ref:`section_ref_algorithm_KalmanFilter` - - :ref:`section_ref_algorithm_ExtendedKalmanFilter` - -Bibliographical references: - - [WikipediaUKF]_ +- [WikipediaUKF]_ diff --git a/doc/en/snippets/AlphaBeta.rst b/doc/en/snippets/AlphaBeta.rst new file mode 100644 index 0000000..6cd29c5 --- /dev/null +++ b/doc/en/snippets/AlphaBeta.rst @@ -0,0 +1,14 @@ +.. index:: single: Alpha +.. index:: single: Beta +.. index:: single: Kappa +.. index:: single: Reconditioner + +Alpha, Beta, Kappa, Reconditioner + These keys are internal scaling parameters. "Alpha" requires a value between + 1.e-4 and 1. "Beta" has an optimal value of 2 for Gaussian *a priori* + distribution. "Kappa" requires an integer value, and the right default is + obtained by setting it to 0. "Reconditioner" requires a value between 1.e-3 + and 10, it defaults to 1. + + Example : + ``{"Alpha":1,"Beta":2,"Kappa":0,"Reconditioner":1}`` diff --git a/doc/en/snippets/CrossOverProbability_CR.rst b/doc/en/snippets/CrossOverProbability_CR.rst index 7b16227..0244700 100644 --- a/doc/en/snippets/CrossOverProbability_CR.rst +++ b/doc/en/snippets/CrossOverProbability_CR.rst @@ -3,8 +3,8 @@ CrossOverProbability_CR This key is used to define the probability of recombination or crossover during the differential evolution. This variable is usually noted as ``CR`` - in the literature. The default value is 0.7, and it is recommended to change - it if necessary. + in the literature, and it is required to be between 0 and 1. The default + value is 0.7, and it is recommended to change it if necessary. Example: ``{"CrossOverProbability_CR":0.7}`` diff --git a/doc/en/snippets/LengthOfTabuList.rst b/doc/en/snippets/LengthOfTabuList.rst new file mode 100644 index 0000000..36b0b52 --- /dev/null +++ b/doc/en/snippets/LengthOfTabuList.rst @@ -0,0 +1,9 @@ +.. index:: single: LengthOfTabuList + +LengthOfTabuList + This key indicates the length of the tabu list, that is the maximum number of + previously executed perturbations and kept for the record. The default is 50, + and it is recommended to adapt it to the needs on real problems. + + Example : + ``{"LengthOfTabuList":50}`` diff --git a/doc/en/snippets/NoiseAddingProbability.rst b/doc/en/snippets/NoiseAddingProbability.rst new file mode 100644 index 0000000..2ad63f5 --- /dev/null +++ b/doc/en/snippets/NoiseAddingProbability.rst @@ -0,0 +1,9 @@ +.. index:: single: NoiseAddingProbability + +NoiseAddingProbability + This key indicates the probability of perturbing a state component. It is a + mandatory value between 0 and 1. The default is 1, and it is not recommended + to change it. + + Example : + ``{"NoiseAddingProbability":1.}`` diff --git a/doc/en/snippets/NoiseDistribution.rst b/doc/en/snippets/NoiseDistribution.rst new file mode 100644 index 0000000..52eda93 --- /dev/null +++ b/doc/en/snippets/NoiseDistribution.rst @@ -0,0 +1,10 @@ +.. index:: single: NoiseDistribution + +NoiseDistribution + This key indicates the type of the distribution used to generate the state + perturbations. This distribution can be of "Uniform" or "Gaussian" type. The + default is a distribution of "Uniform" type, and it is recommended to adapt + it to the needs on real problems. + + Example : + ``{"NoiseDistribution":"Uniform"}`` diff --git a/doc/en/snippets/NoiseHalfRange.rst b/doc/en/snippets/NoiseHalfRange.rst new file mode 100644 index 0000000..ce3916f --- /dev/null +++ b/doc/en/snippets/NoiseHalfRange.rst @@ -0,0 +1,14 @@ +.. index:: single: NoiseHalfRange + +NoiseHalfRange + This key indicates,, only in the case of a "Uniform" distribution type asked + through the keyword "*NoiseDistribution*", the half-amplitude of the uniform + state centred perturbations for each component of the state. The default is + an empty list, this key must therefore be filled in in the case of a + "Uniform" distribution. A simple way to do this is to give a list of the + length of the desired state with identical half-amplitudes, as in the example + below with half-amplitudes of 3%. It is recommended to take half-amplitudes + of a few percent maximum. + + Example : + ``{"NoiseHalfRange":*[0.03]}`` diff --git a/doc/en/snippets/NumberOfElementaryPerturbations.rst b/doc/en/snippets/NumberOfElementaryPerturbations.rst new file mode 100644 index 0000000..260e47b --- /dev/null +++ b/doc/en/snippets/NumberOfElementaryPerturbations.rst @@ -0,0 +1,10 @@ +.. index:: single: NumberOfElementaryPerturbations + +NumberOfElementaryPerturbations + This key indicates the number of elementary perturbations that will be + performed to select a complete state perturbation. The default is 1, and it + is recommended to adapt it carefully to the needs of real problems, without + choosing too many elementary perturbations. + + Example : + ``{"NumberOfElementaryPerturbations":1}`` diff --git a/doc/en/snippets/Observers.rst b/doc/en/snippets/Observers.rst index 1e7bf19..19fa1b0 100644 --- a/doc/en/snippets/Observers.rst +++ b/doc/en/snippets/Observers.rst @@ -1,4 +1,6 @@ +.. index:: single: Observer .. index:: single: Observers +.. index:: single: Observer Template Observers *List of functions linked to variables*. This command allows to set internal diff --git a/doc/en/snippets/SampleAsExplicitHyperCube.rst b/doc/en/snippets/SampleAsExplicitHyperCube.rst new file mode 100644 index 0000000..05b5b3d --- /dev/null +++ b/doc/en/snippets/SampleAsExplicitHyperCube.rst @@ -0,0 +1,8 @@ +.. index:: single: SampleAsExplicitHyperCube + +SampleAsExplicitHyperCube + This key describes the calculations points as an hyper-cube, from a given + list of explicit sampling of each variable as a 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 diff --git a/doc/en/snippets/SampleAsIndependantRandomVariables.rst b/doc/en/snippets/SampleAsIndependantRandomVariables.rst new file mode 100644 index 0000000..beea7a9 --- /dev/null +++ b/doc/en/snippets/SampleAsIndependantRandomVariables.rst @@ -0,0 +1,14 @@ +.. index:: single: SampleAsIndependantRandomVariables + +SampleAsIndependantRandomVariables + This key describes the calculations points as an hyper-cube, for which the + points on each axis come from a independent random sampling of the axis + variable, under the specification of the distribution, its parameters and + the number of points in the sample, as a list ``['distribution', + [parameters], number]`` for each axis. The possible distributions are + 'normal' of parameters (mean,std), 'lognormal' of parameters (mean,sigma), + 'uniform' of parameters (low,high), or 'weibull' of parameter (shape). That + is then a list of the same size than the one of the state. + + Example : + ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` for a state space of dimension 2 diff --git a/doc/en/snippets/SampleAsMinMaxStepHyperCube.rst b/doc/en/snippets/SampleAsMinMaxStepHyperCube.rst new file mode 100644 index 0000000..b083e8a --- /dev/null +++ b/doc/en/snippets/SampleAsMinMaxStepHyperCube.rst @@ -0,0 +1,10 @@ +.. index:: single: SampleAsMinMaxStepHyperCube + +SampleAsMinMaxStepHyperCube + This key describes the calculations points as an hyper-cube, from a given + list of implicit sampling of each variable by a triplet *[min,max,step]*. + That is then a list of the same size than the one of the state. The bounds + are included. + + Example : + ``{"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 new file mode 100644 index 0000000..54b54c3 --- /dev/null +++ b/doc/en/snippets/SampleAsnUplet.rst @@ -0,0 +1,8 @@ +.. index:: single: SampleAsnUplet + +SampleAsnUplet + This key describes the calculations points as a list of 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 diff --git a/doc/en/snippets/StandardDeviation.rst b/doc/en/snippets/StandardDeviation.rst new file mode 100644 index 0000000..f3f657a --- /dev/null +++ b/doc/en/snippets/StandardDeviation.rst @@ -0,0 +1,14 @@ +.. index:: single: StandardDeviation + +StandardDeviation + This key indicates, only in the case of a "Gaussian" distribution type asked + through the keyword "*NoiseDistribution*", the standard deviation of the + state Gaussian perturbations for each state component. The default is an + empty list, this key must therefore be filled in in the case of a "Gaussian" + distribution. A simple way to do this is to give a list of the length of the + desired state with identical standard deviations, as in the example below + with standard deviations of 5%. It is recommended to take standard deviations + of a few percent maximum. + + Example : + ``{"StandardDeviation":*[0.05]}`` diff --git a/doc/en/tui.rst b/doc/en/tui.rst index 47da0ad..0911b9f 100644 --- a/doc/en/tui.rst +++ b/doc/en/tui.rst @@ -27,7 +27,7 @@ .. _section_tui: ================================================================================ -**[DocR]** Textual Application Programming Interface for the user (API/TUI) +**[DocR]** Textual User Interface for ADAO (TUI/API) ================================================================================ This section presents advanced usage of the ADAO module using its text @@ -481,14 +481,14 @@ Setting the calculation, outputs, etc. **setObserver** (*Variable, Template, String, Script, Info*) This command allows to set an *observer* on the current or final calculation variable. Reference should be made to the description of the - ':ref:`ref_observers_requirements` for their list and content, and to the - :ref:`section_reference` to know what are the observable quantities. One - defines as "*String*" the *observer* body, using a string including if + ':ref:`section_ref_observers_requirements` for their list and content, and + to the :ref:`section_reference` to know what are the observable quantities. + One defines as "*String*" the *observer* body, using a string including if necessary line breaks. It is recommended to use the patterns available by the argument "*Template*". In the case of a definition as "*Script*", the file must contain only the body of the function, as described in the - :ref:`ref_observers_requirements`. The "*Info*" variable contains an - information string or can be void. + :ref:`section_ref_observers_requirements`. The "*Info*" variable contains + an information string or can be void. Perform the calculation +++++++++++++++++++++++ -- 2.39.2