From: Jean-Philippe ARGAUD Date: Thu, 7 Mar 2019 17:28:21 +0000 (+0100) Subject: Updating documentation by review and snippets (7): EN part X-Git-Tag: V9_3_0rc2~27 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=7cafb969ea5d6280380f9c3a9fd65b8463e0cf39;p=modules%2Fadao.git Updating documentation by review and snippets (7): EN part --- 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/gui_in_salome.rst b/doc/en/gui_in_salome.rst new file mode 100644 index 0000000..b88684e --- /dev/null +++ b/doc/en/gui_in_salome.rst @@ -0,0 +1,263 @@ +.. + 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_gui_in_salome: + +================================================================================ +**[DocR]** Graphical User Interface for ADAO (GUI/EFICAS) +================================================================================ + +.. |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% +.. |yacs_compile| image:: images/yacs_compile.png + :align: middle + :scale: 50% + +This section presents the usage of the ADAO module in SALOME platform. Here we +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_tutorials_in_salome`. + +Logical procedure to build an ADAO case +--------------------------------------- + +The construction of an ADAO case follows a simple approach to define the set of +input data, and then generates a complete executable block diagram used in YACS +[#]_. Many variations exist for the definition of input data, but the logical +sequence remains unchanged. + +First of all, the user is considered to know its personal input data needed to +set up the data assimilation study, following :ref:`section_methodology`. These +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` + +Each step will be detailed in the next section. + +Detailed procedure to build an ADAO case +---------------------------------------- + +.. _section_u_step1: + +STEP 1: Activate the ADAO module and use the editor GUI ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +As always for a module, it has to be activated by choosing the appropriate +module button (or the menu) in the toolbar of SALOME. If there is no SALOME +study loaded, a popup appears, allowing to choose between creating a new study, +or opening an already existing one: + + .. _adao_activate1: + .. image:: images/adao_activate.png + :align: center + .. centered:: + **Activating the module ADAO in SALOME** + +Choosing the "*New*" button, an embedded case editor [#]_ will be opened, along +with the standard "*Object browser*". You can then click on the "*New*" button +|eficas_new| (or choose the "*New*" entry in the "*ADAO*" main menu) 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** + +.. _section_u_step2: + +STEP 2: Build and modify the ADAO case, and save it ++++++++++++++++++++++++++++++++++++++++++++++++++++ + +To build a case using the embedded editor, you have to go through a series of +sub-steps, by selecting, at each sub-step, a keyword and then filling in its +value. It is noted that it is in this step that is needed, among other things, +to define the call to the simulation code used in observation or evolution +operators describing the problem [#]_. + +The structured editor indicates hierarchical types, values or keywords allowed. +Incomplete or incorrect keywords are identified by a visual error red flag. +Possible values are indicated for keywords defined with a limited list of +values, and adapted entries are given for the other keywords. Some help messages +are contextually provided in the editor reserved places. + +A new case is set up with the minimal list of commands. All the mandatory +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_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 +is valid and completed (and can be saved). + + .. _adao_jdcexample00: + .. image:: images/adao_jdcexample01.png + :align: center + :scale: 75% + .. centered:: + **Example of a valid ADAO case** + +Finally, you have to save your ADAO case by pushing the "*Save*" button +|eficas_save|, or the "*Save as*" button |eficas_saveas|, or by choosing the +"*Save/Save as*" entry in the "*ADAO*" menu. You will be prompted for a location +in your file tree and a name, that will be completed by a "*.comm*" extension +used for the embedded case editor. This will generate a pair of files describing +the ADAO case, with the same base name, the first one being completed by a +"*.comm*" extension and the second one by a "*.py*" extension [#]_. + +.. _section_u_step3: + +STEP 3: Export the ADAO case as a YACS scheme ++++++++++++++++++++++++++++++++++++++++++++++ + +When the ADAO case is completed, you have to export it as a YACS scheme in order +to execute the data assimilation calculation. This can be easily done by using +the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the "*Export +to YACS*" entry in the "*ADAO*" main menu, or in the contextual case menu in the +SALOME object browser. + + .. _adao_exporttoyacs01: + .. 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 will lead to automatically generate a YACS scheme, and open the YACS module +on this scheme. The YACS file, associated with the scheme, will be stored in the +same directory and with the same base name as the ADAO saved case, only changing +its extension to "*.xml*". Be careful, *if the XML file name already exist, the +file will be overwritten without prompting for replacing the XML file*. + +.. _section_u_step4: + +STEP 4: Supplement and modify the YACS scheme, and save it +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: Analysis + +When the YACS scheme is generated and opened in SALOME through the YACS module +GUI, you can modify or supplement the scheme like any standard YACS scheme. +Nodes or blocs can be added, copied or modified to elaborate complex analysis, +or to insert data assimilation or optimization capabilities into more complex +YACS calculation schemes. It is recommended to save the modified scheme with a +new name, in order to preserve the XML file in the case you re-export the ADAO +case to YACS. + +The main supplement needed in the YACS scheme is a post-processing step. The +evaluation of the results has to be done in the physical context of the +simulation used by the data assimilation procedure. The post-processing can be +provided through the "*UserPostAnalysis*" ADAO keyword as a script or a string, +by templates, or can be build as YACS nodes. These two ways of building the +post-processing can use all the SALOME possibilities. See the part describing +:ref:`section_ref_output_variables`, or the help for each algorithm, for the +full description of these elements. + +In practice, the YACS scheme has an "*algoResults*" output port of the +computation bloc, which gives access to a structured object named hereafter +"*ADD*" for example, containing all the calculation results. These results can +be obtained by retrieving the named variables stored along the calculation. The +main information is the "*Analysis*" one, that can be obtained by the python +command (for example in an in-line script node or a script provided through the +"*UserPostAnalysis*" keyword):: + + Analysis = ADD.get("Analysis")[:] + +"*Analysis*" is a complex object, similar to a list of values calculated at each +step of data assimilation calculation. In order to get and print the optimal +data assimilation state evaluation, in a script provided through the +"*UserPostAnalysis*" keyword, one can use:: + + Xa = ADD.get("Analysis")[-1] + print("Optimal state:", Xa) + print() + +This ``Xa`` variable is a vector of values, that represents the solution of the +data assimilation or optimization evaluation problem, noted as +:math:`\mathbf{x}^a` in the section :ref:`section_theory`. + +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_tutorials_in_salome`. + +.. _section_u_step5: + +STEP 5: Execute the YACS case and obtain the results +++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The YACS scheme is now complete and can be executed. Parametrization and +execution of this YACS case is fully compliant with the standard way to deal +with a YACS scheme, as described in the *YACS module User's Guide*. + +To recall the simplest way to proceed, the YACS scheme has to be compiled using +the button |yacs_compile|, or the equivalent YACS menu entry, to prepare the +scheme to run. Then the compiled scheme can be started, executed step by step or +using breakpoints, etc. + +The standard output will be pushed into the "*YACS Container Log*", obtained +through the right click menu of the "*proc*" window in the YACS GUI. The errors +are shown either in the "*YACS Container Log*", or at the command line in the +terminal window (if SALOME has been launched by its explicit command, and not by +a menu or a desktop icon). As an example, the output of the above simple case is +of the following form:: + + Entering in the assimilation study + Name is set to........: Test + Algorithm is set to...: Blue + Launching the analysis + + Optimal state: [0.5, 0.5, 0.5] + +shown in the "*YACS Container Log*". + +The execution can also be done using a Shell script, as described in the section +:ref:`section_advanced`. + +.. [#] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform. + +.. [#] For more information on the embedded case editor, see the *EFICAS module* and its integrated help available from the main menu *Help* of the SALOME platform. + +.. [#] The use of physical simulation code in the data assimilation elementary operators is illustrated or described in the following main parts. + +.. [#] This intermediary python file can also be used as described in the section :ref:`section_advanced`. 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 +++++++++++++++++++++++ diff --git a/doc/en/using.rst b/doc/en/using.rst deleted file mode 100644 index 04f11ad..0000000 --- a/doc/en/using.rst +++ /dev/null @@ -1,263 +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_using: - -================================================================================ -**[DocU]** 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% -.. |yacs_compile| image:: images/yacs_compile.png - :align: middle - :scale: 50% - -This section presents the usage of the ADAO module in SALOME platform. Here we -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`. - -Logical procedure to build an ADAO case ---------------------------------------- - -The construction of an ADAO case follows a simple approach to define the set of -input data, and then generates a complete executable block diagram used in YACS -[#]_. Many variations exist for the definition of input data, but the logical -sequence remains unchanged. - -First of all, the user is considered to know its personal input data needed to -set up the data assimilation study, following :ref:`section_methodology`. These -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` - -Each step will be detailed in the next section. - -Detailed procedure to build an ADAO case ----------------------------------------- - -.. _section_u_step1: - -STEP 1: Activate the ADAO module and use the editor GUI -+++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -As always for a module, it has to be activated by choosing the appropriate -module button (or the menu) in the toolbar of SALOME. If there is no SALOME -study loaded, a popup appears, allowing to choose between creating a new study, -or opening an already existing one: - - .. _adao_activate1: - .. image:: images/adao_activate.png - :align: center - .. centered:: - **Activating the module ADAO in SALOME** - -Choosing the "*New*" button, an embedded case editor [#]_ will be opened, along -with the standard "*Object browser*". You can then click on the "*New*" button -|eficas_new| (or choose the "*New*" entry in the "*ADAO*" main menu) 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** - -.. _section_u_step2: - -STEP 2: Build and modify the ADAO case, and save it -+++++++++++++++++++++++++++++++++++++++++++++++++++ - -To build a case using the embedded editor, you have to go through a series of -sub-steps, by selecting, at each sub-step, a keyword and then filling in its -value. It is noted that it is in this step that is needed, among other things, -to define the call to the simulation code used in observation or evolution -operators describing the problem [#]_. - -The structured editor indicates hierarchical types, values or keywords allowed. -Incomplete or incorrect keywords are identified by a visual error red flag. -Possible values are indicated for keywords defined with a limited list of -values, and adapted entries are given for the other keywords. Some help messages -are contextually provided in the editor reserved places. - -A new case is set up with the minimal list of commands. All the mandatory -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`. - -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 -is valid and completed (and can be saved). - - .. _adao_jdcexample00: - .. image:: images/adao_jdcexample01.png - :align: center - :scale: 75% - .. centered:: - **Example of a valid ADAO case** - -Finally, you have to save your ADAO case by pushing the "*Save*" button -|eficas_save|, or the "*Save as*" button |eficas_saveas|, or by choosing the -"*Save/Save as*" entry in the "*ADAO*" menu. You will be prompted for a location -in your file tree and a name, that will be completed by a "*.comm*" extension -used for the embedded case editor. This will generate a pair of files describing -the ADAO case, with the same base name, the first one being completed by a -"*.comm*" extension and the second one by a "*.py*" extension [#]_. - -.. _section_u_step3: - -STEP 3: Export the ADAO case as a YACS scheme -+++++++++++++++++++++++++++++++++++++++++++++ - -When the ADAO case is completed, you have to export it as a YACS scheme in order -to execute the data assimilation calculation. This can be easily done by using -the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the "*Export -to YACS*" entry in the "*ADAO*" main menu, or in the contextual case menu in the -SALOME object browser. - - .. _adao_exporttoyacs01: - .. 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 will lead to automatically generate a YACS scheme, and open the YACS module -on this scheme. The YACS file, associated with the scheme, will be stored in the -same directory and with the same base name as the ADAO saved case, only changing -its extension to "*.xml*". Be careful, *if the XML file name already exist, the -file will be overwritten without prompting for replacing the XML file*. - -.. _section_u_step4: - -STEP 4: Supplement and modify the YACS scheme, and save it -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: Analysis - -When the YACS scheme is generated and opened in SALOME through the YACS module -GUI, you can modify or supplement the scheme like any standard YACS scheme. -Nodes or blocs can be added, copied or modified to elaborate complex analysis, -or to insert data assimilation or optimization capabilities into more complex -YACS calculation schemes. It is recommended to save the modified scheme with a -new name, in order to preserve the XML file in the case you re-export the ADAO -case to YACS. - -The main supplement needed in the YACS scheme is a post-processing step. The -evaluation of the results has to be done in the physical context of the -simulation used by the data assimilation procedure. The post-processing can be -provided through the "*UserPostAnalysis*" ADAO keyword as a script or a string, -by templates, or can be build as YACS nodes. These two ways of building the -post-processing can use all the SALOME possibilities. See the part describing -:ref:`section_ref_output_variables`, or the help for each algorithm, for the -full description of these elements. - -In practice, the YACS scheme has an "*algoResults*" output port of the -computation bloc, which gives access to a structured object named hereafter -"*ADD*" for example, containing all the calculation results. These results can -be obtained by retrieving the named variables stored along the calculation. The -main information is the "*Analysis*" one, that can be obtained by the python -command (for example in an in-line script node or a script provided through the -"*UserPostAnalysis*" keyword):: - - Analysis = ADD.get("Analysis")[:] - -"*Analysis*" is a complex object, similar to a list of values calculated at each -step of data assimilation calculation. In order to get and print the optimal -data assimilation state evaluation, in a script provided through the -"*UserPostAnalysis*" keyword, one can use:: - - Xa = ADD.get("Analysis")[-1] - print("Optimal state:", Xa) - print() - -This ``Xa`` variable is a vector of values, that represents the solution of the -data assimilation or optimization evaluation problem, noted as -:math:`\mathbf{x}^a` in the section :ref:`section_theory`. - -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`. - -.. _section_u_step5: - -STEP 5: Execute the YACS case and obtain the results -++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The YACS scheme is now complete and can be executed. Parametrization and -execution of this YACS case is fully compliant with the standard way to deal -with a YACS scheme, as described in the *YACS module User's Guide*. - -To recall the simplest way to proceed, the YACS scheme has to be compiled using -the button |yacs_compile|, or the equivalent YACS menu entry, to prepare the -scheme to run. Then the compiled scheme can be started, executed step by step or -using breakpoints, etc. - -The standard output will be pushed into the "*YACS Container Log*", obtained -through the right click menu of the "*proc*" window in the YACS GUI. The errors -are shown either in the "*YACS Container Log*", or at the command line in the -terminal window (if SALOME has been launched by its explicit command, and not by -a menu or a desktop icon). As an example, the output of the above simple case is -of the following form:: - - Entering in the assimilation study - Name is set to........: Test - Algorithm is set to...: Blue - Launching the analysis - - Optimal state: [0.5, 0.5, 0.5] - -shown in the "*YACS Container Log*". - -The execution can also be done using a Shell script, as described in the section -:ref:`section_advanced`. - -.. [#] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform. - -.. [#] For more information on the embedded case editor, see the *EFICAS module* and its integrated help available from the main menu *Help* of the SALOME platform. - -.. [#] The use of physical simulation code in the data assimilation elementary operators is illustrated or described in the following main parts. - -.. [#] This intermediary python file can also be used as described in the section :ref:`section_advanced`.