**[DocU]** Tutorials on using the ADAO module in Python
================================================================================
-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 textual user
-interface (TUI). The second one shows, on the same case, how to define input
-data using external sources through scripts.
+This section presents some examples on using the ADAO module in Python. The
+first one shows how to build a very simple data assimilation case defining
+explicitly all the required input data through the textual user interface
+(TUI). 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 script definitions of Python
+interface, but external files can use other languages.
-The mathematical notations used afterward are explained in the section
-:ref:`section_theory`.
+These examples are intentionally described in the same way than for the
+:ref:`section_tutorials_in_salome` because they are similar to the ones that
+can be treated in the graphical user interface in SALOME. The mathematical
+notations used afterward are explained in the section :ref:`section_theory`.
+
+.. _section_tutorials_in_python_explicit:
Building an estimation case with explicit data definition
---------------------------------------------------------
+This very 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 observation space, that is, we deal
+with 3 simple measures. The 3 dimensionality is chosen in order to restrict the
+size of numerical object to be explicitly entered by the user, but the problem
+is not dependent of the dimension and can be set in observation dimension of
+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 chosen of value of 0 in each
+case, which leads to:
+::
+
+ Xb = [0 0 0]
+
+Data assimilation requires information on errors covariances :math:`\mathbf{R}`
+and :math:`\mathbf{B}`, respectively for observation and background error
+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 = Id = [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 and because we state a linear selection operator, we
+can choose the identity as the observation operator:
+::
+
+ H = Id = [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
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+We have to set 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 as required a list, a
+vector or a string for each variable. We refer to the reference documentation
+:ref:`section_tui`. It will build an ADAO case, that can be saved as a standard
+Python file.
+
+The header of the file has to state the usual settings:
+::
+
+ from adao import adaoBuilder
+ case = adaoBuilder.New()
+ case.set( 'AlgorithmParameters', Algorithm='Blue' )
+
+The definition of the observations and of the error covariances are the
+following:
+::
+
+ case.set( 'Observation', Vector=[1, 1, 1] )
+ case.set( 'ObservationError', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
+
+In the same way, the *a priori* information is defined with its error
+covariances by:
+::
+
+ case.set( 'Background', Vector=[0, 0, 0] )
+ case.set( 'BackgroundError', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
+
+The observation operator, very simple and here linear, can be defined by:
+::
+
+ case.set( 'ObservationOperator', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
+
+To get an automatic printing of the optimal analyzed state, one can add an
+"*observer*" command, or add after execution some commands to treat the data
+assimilation results. In this very simple case, one can just add:
+::
+
+ case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
+
+The execution is then extremely simple to state and consist in the command
+line, eventually in the saving file:
+::
+
+ case.execute()
+
+The result of the execution of these commands (either at Python prompt, through
+the "*shell*" command of SALOME, in the Python prompt of the interface, or by
+the script execution menu) is the following:
+::
+
+ Analysis [0.5 0.5 0.5]
+
+as shown here:
+::
+
+ adao@python$ python
+ Python 3.6.5 (default, Feb 01 2019, 12:12:12)
+ [GCC] on linux
+ Type "help", "copyright", "credits" or "license" for more information.
+ >>>
+ >>> from adao import adaoBuilder
+ >>> case = adaoBuilder.New()
+ >>> case.set( 'AlgorithmParameters', Algorithm='Blue' )
+ >>> case.set( 'Observation', Vector=[1, 1, 1] )
+ >>> case.set( 'ObservationError', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
+ >>> case.set( 'Background', Vector=[0, 0, 0] )
+ >>> case.set( 'BackgroundError', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
+ >>> case.set( 'ObservationOperator', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
+ >>> case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
+ >>> case.execute()
+ Analysis [0.5 0.5 0.5]
+ 0
+ >>>
+
+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 by only changing the "*Algorithm*"
+argument on the beginning. The remaining parts of the ADAO case in 3DVAR is
+exactly similar to the BLUE algorithmic case.
+
+.. _section_tutorials_in_python_script:
+
+Building an estimation case with external data definition by scripts
+--------------------------------------------------------------------
+
+It is useful to get parts or all of the ADAO case 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 :ref:`section_tutorials_in_python_explicit`, 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 textual interface 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 ADAO 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 textual interface (TUI) to build the ADAO
+case. The procedure to fill in the case is similar to the previous example
+except that, instead of selecting the "*Vector*" or "*Matrix*" option to build
+each variable, one choose the "*Script*" option setting simultaneously the
+"*Vector*" or "*Matrix*" type of the variable. This leads to the following
+commands (either at Python prompt, through the "*shell*" command of SALOME, in
+the Python prompt of the interface, or by the script execution menu):
+::
+
+ adao@python$ python
+ Python 3.6.5 (default, Feb 01 2019, 12:12:12)
+ [GCC] on linux
+ Type "help", "copyright", "credits" or "license" for more information.
+ >>>
+ >>> from adao import adaoBuilder
+ >>> case = adaoBuilder.New()
+ >>> case.set( 'AlgorithmParameters', Algorithm='Blue' )
+ >>> case.set( 'Observation', Vector=True, Script="script.py" )
+ >>> case.set( 'ObservationError', Matrix=True, Script="script.py" )
+ >>> case.set( 'Background', Vector=True, Script="script.py" )
+ >>> case.set( 'BackgroundError', Matrix=True, Script="script.py" )
+ >>> case.set( 'ObservationOperator', Matrix=True, Script="script.py" )
+ >>> case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
+ >>> case.execute()
+ Analysis [0.5 0.5 0.5]
+ 0
+ >>>
+
+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 ADAO case execution. The user have to carefully verify the
+content of his scripts.**
: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
+first one shows how to build a very simple data assimilation case defining
explicitly all the required input data through the EFICAS graphical user
interface (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`.
+These examples are intentionally described in the same way than for the
+:ref:`section_tutorials_in_python` because they are similar to the ones that
+can be treated in the textual user interface in Python (TUI). 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
+This very 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::
+We choose to operate in a 3-dimensional observation space, that is we deal with
+3 simple measures. The 3 dimensionality is chosen in order to restrict the size
+of numerical object to be explicitly entered by the user, but the problem is
+not dependent of the dimension and can be set in observation dimension of 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::
+knowledge or a mathematical regularization, is chosen of value of 0 in each
+case, which leads to:
+::
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::
+and :math:`\mathbf{B}`, respectively for observation and background error
+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]
+ B = R = Id = [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::
+operator:
+::
- H = [1 0 0 ; 0 1 0 ; 0 0 1]
+ H = Id = [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::
+*analysis*, denoted by :math:`\mathbf{x}^a`, and its value is:
+::
Xa = [0.5 0.5 0.5]
.. 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:
+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
+each variable. 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
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::
+in the script node is:
+::
Xa = Study.getResults().get("Analysis")[-1]
**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::
+contains the following line:
+::
Analysis = [0.5, 0.5, 0.5]
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.
+It is useful to get parts or all of the ADAO case 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::
+external files. The present script file looks like:
+::
import numpy
#
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.
+right ADAO 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
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.**
+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 ADAO case execution. The user have to carefully verify the
+content of his scripts.**
Adding parameters to control the data assimilation algorithm
------------------------------------------------------------
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::
+default values, and can exist without being used. For example:
+::
AlgorithmParameters = {
"Minimizer" : "LBFGSB", # Recommended
not dependent of the dimension.
We choose a twin experiment context, using a known true state
-:math:`\mathbf{x}^t` but of arbitrary value::
+: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::
+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::
+variance of 0.1 for all variables. We get:
+::
B = 0.1 * diagonal( length(Xb) )
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}`::
+: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::
+and, with an arbitrary standard deviation of 1% on each error component:
+::
R = 0.0001 * diagonal( length(Yo) )
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``::
+``Physical_data_and_covariance_matrices.py``:
+::
import numpy
#
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``::
+Python script file named ``Script_Background_xb.py``:
+::
from Physical_data_and_covariance_matrices import True_state
import numpy
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``::
+is done in a Python script file named ``Script_BackgroundError_B.py``:
+::
from Physical_data_and_covariance_matrices import True_state, Simple_Matrix
#
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::
+convenience:
+::
def DirectOperator( XX ):
""" Direct non-linear simulation operator """
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``::
+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
# -----------------------------------
Observation = list(yo)
-and the second one named ``Script_ObservationError_R.py``::
+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
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``::
+``Script_AlgorithmParameters.py``:
+::
# Creating the required ADAO variable
# -----------------------------------
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::
+Python script file, named ``Script_UserPostAnalysis.py``, illustrates the fact:
+::
from Physical_data_and_covariance_matrices import True_state
import numpy
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::
+the results will look like:
+::
xt = [1 2 3]
xa = [ 1.000014 2.000458 3.000390]
**[DocU]** Tutoriaux sur l'utilisation du module ADAO dans Python
================================================================================
-Cette section présente quelques exemples d'utilisation du module ADAO en Python
-SALOME. Le premier montre comment construire un cas simple d'assimilation de
+Cette section présente quelques exemples d'utilisation du module ADAO en
+Python. Le premier montre comment construire un cas simple d'assimilation de
données définissant explicitement toutes les données d'entrée requises à
travers l'interface utilisateur textuelle (TUI). Le second montre, sur le même
cas, comment définir les données d'entrée à partir de sources externes à
-travers des scripts.
+travers des scripts. On présente ici toujours des scripts Python car ils sont
+directement insérables dans les définitions de script de l'interface Python,
+mais les fichiers externes peuvent utiliser d'autres langages.
-Les notations mathématiques utilisées ci-dessous sont expliquées dans la
-section :ref:`section_theory`.
+Ces exemples sont intentionnellement décrits de manière semblables aux
+:ref:`section_tutorials_in_salome` car ils sont similaires à ceux que l'on peut
+traiter dans l'interface graphique SALOME. Les notations mathématiques
+utilisées ci-dessous sont expliquées dans la section :ref:`section_theory`.
+
+.. _section_tutorials_in_python_explicit:
Construire un cas d'estimation avec une définition explicite des données
------------------------------------------------------------------------
+
+Cet exemple très simple est un cas de démonstration, et il décrit comment
+mettre au point un environnement d'estimation par BLUE de manière à obtenir un
+*état estimé par méthode de moindres carrés pondérés* d'un système à partir
+d'une observation de l'état et d'une connaissance *a priori* (ou ébauche) de
+cet état. En d'autres termes, on cherche l'intermédiaire pondéré entre les
+vecteurs d'observation et d'ébauche. Toutes les valeurs numériques de cet
+exemple sont arbitraires.
+
+Conditions d'expérience
++++++++++++++++++++++++
+
+On choisit d'opérer dans un espace d'observation à 3 dimensions. La 3D est
+choisie de manière à restreindre la taille des objets numériques à entrer
+explicitement par l'utilisateur, mais le problème n'est pas dépendant de la
+dimension et peut être posé en dimension 10, 100, 1000... L'observation
+:math:`\mathbf{y}^o` vaut 1 dans chaque direction, donc :
+::
+
+ Yo = [1 1 1]
+
+L'ébauche :math:`\mathbf{x}^b` de l'état , qui représente une connaissance *a
+priori* ou une régularisation mathématique, est choisie comme valant 0 dans
+chaque cas, ce qui donne donc :
+::
+
+ Xb = [0 0 0]
+
+La mise en oeuvre de l'assimilation de données requiert des informations sur
+les covariances d'erreur :math:`\mathbf{R}` et :math:`\mathbf{B}`,
+respectivement pour les variables d'erreur d'observation et d'ébauche. On
+choisit ici des erreurs décorrélées (c'est-à-dire des matrices diagonales) et
+d'avoir la même variance de 1 pour toutes les variables (c'est-à-dire des
+matrices identité). On pose donc :
+::
+
+ B = R = Id = [1 0 0 ; 0 1 0 ; 0 0 1]
+
+Enfin, on a besoin d'un opérateur d'observation :math:`\mathbf{H}` pour
+convertir l'état d'ébauche dans l'espace des observations. Ici, comme les
+dimensions d'espace sont les mêmes et que l'on postule un opérateur linéaire de
+sélection, on peut choisir l'identité comme opérateur d'observation :
+::
+
+ H = Id = [1 0 0 ; 0 1 0 ; 0 0 1]
+
+Avec de tels choix, l'estimateur "Best Linear Unbiased Estimator" (BLUE) sera le
+vecteur moyen entre :math:`\mathbf{y}^o` et :math:`\mathbf{x}^b`, nommé
+*analysis*, noté :math:`\mathbf{x}^a`, et valant :
+::
+
+ Xa = [0.5 0.5 0.5]
+
+Pour étendre cet exemple, on peut modifier les variances représentées par
+:math:`\mathbf{B}` ou :math:`\mathbf{R}` indépendamment, et l'analyse
+:math:`\mathbf{x}^a` se déplacera vers :math:`\mathbf{y}^o` ou vers
+:math:`\mathbf{x}^b`, en proportion inverse des variances dans
+:math:`\mathbf{B}` et :math:`\mathbf{R}`. Comme autre extension, on peut aussi
+dire qu'il est équivalent de rechercher l'analyse à l'aide d'un algorithme de
+BLUE ou d'un algorithme de 3DVAR.
+
+Utiliser l'interface textuelle (TUI) pour construire le cas ADAO
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+On va renseigner les variables pour construire le cas ADAO en utilisant les
+conditions d'expérience décrites ci-dessus. L'ensemble des informations
+techniques données au-dessus sont à insérer directement dans la définition du
+cas ADAO, en utilisant au choix une liste, un vecteur ou une chaîne de
+caractères pour chaque variable. On s'appuie sur la documentation de référence
+:ref:`section_tui`. On constitue ainsi un cas ADAO, qui peut être enregistré en
+fichier Python standard.
+
+L'entête du fichier doit comporter les déclarations habituelles du cas :
+::
+
+ from adao import adaoBuilder
+ case = adaoBuilder.New()
+ case.set( 'AlgorithmParameters', Algorithm='Blue' )
+
+La définition des observations et des covariances d'erreurs sont les suivantes :
+::
+
+ case.set( 'Observation', Vector=[1, 1, 1] )
+ case.set( 'ObservationError', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
+
+De la même manière, l'information *a priori* est définie avec ses covariances
+d'erreur par :
+::
+
+ case.set( 'Background', Vector=[0, 0, 0] )
+ case.set( 'BackgroundError', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
+
+L'opérateur d'observation, très simple et ici linéaire, peut être défini par:
+::
+
+ case.set( 'ObservationOperator', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
+
+Pour obtenir un affichage automatique de l'état optimal analysé, on peut
+ajouter une commande d'"*observer*", ou ajouter après l'exécution des commandes de
+traitement des résultats de l'assimilation de données. On peut se contenter
+dans ce cas très simple d'ajouter :
+::
+
+ case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
+
+La démarche d'exécution est extrêmement simple et consiste à effectuer à la
+ligne de commande, ou dans le fichier enregistrant le cas, la commande
+suivante :
+::
+
+ case.execute()
+
+Le résultat de l'exécution de ces commandes (que ce soit en console Python, par
+la commande "*shell*" de SALOME, dans la console Python de l'interface, ou par
+le menu d'exécution d'un script) est le suivant :
+::
+
+ Analysis [0.5 0.5 0.5]
+
+comme montré ci-après :
+::
+
+ adao@python$ python
+ Python 3.6.5 (default, Feb 01 2019, 12:12:12)
+ [GCC] on linux
+ Type "help", "copyright", "credits" or "license" for more information.
+ >>>
+ >>> from adao import adaoBuilder
+ >>> case = adaoBuilder.New()
+ >>> case.set( 'AlgorithmParameters', Algorithm='Blue' )
+ >>> case.set( 'Observation', Vector=[1, 1, 1] )
+ >>> case.set( 'ObservationError', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
+ >>> case.set( 'Background', Vector=[0, 0, 0] )
+ >>> case.set( 'BackgroundError', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
+ >>> case.set( 'ObservationOperator', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
+ >>> case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
+ >>> case.execute()
+ Analysis [0.5 0.5 0.5]
+ 0
+ >>>
+
+Pour étendre cet exemple, on peut remarquer que le même problème résolu par un
+algorithme de 3DVAR donne le même résultat. Cet algorithme peut être choisi
+lors de l'étape de construction du cas ADAO en changeant simplement l'argument
+"*Algorithm*" en entête. Le reste du cas ADAO en 3DVAR est alors entièrement
+similaire au cas algorithmique du BLUE.
+
+.. _section_tutorials_in_python_script:
+
+Construire un cas d'estimation avec une définition de données externes par scripts
+----------------------------------------------------------------------------------
+
+Il est utile d'acquérir une partie ou la totalité des données du cas ADAO
+depuis une définition externe, en utilisant des scripts Python pour donner
+accès à ces données. À titre d'exemple, on construit ici un cas ADAO présentant
+le même dispositif expérimental que dans l'exemple ci-dessus
+:ref:`section_tutorials_in_python_explicit`, mais en utilisant des données
+issues d'un unique fichier script Python externe.
+
+En premier lieu, on écrit le fichier script suivant, utilisant des noms
+conventionnels pour les variables requises. Ici toutes les variables sont
+définies dans le même script, mais l'utilisateur peut choisir de séparer le
+fichier en plusieurs autres, ou de mélanger une définition explicite des
+données dans l'interface textuelle ADAO et une définition implicite dans des
+fichiers externes. Le fichier script actuel ressemble à:
+::
+
+ 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)
+
+Les noms des variables Python sont obligatoires, de manière à définir les
+bonnes variables dans le cas ADAO, mais le script Python peut être plus
+conséquent et définir des classes, des fonctions, des accès à des fichiers ou
+des bases de données, etc. avec des noms différents. De plus, le fichier
+ci-dessus présente différentes manières de définir des vecteurs ou des
+matrices, utilisant des listes, des chaînes de caractères (comme dans Numpy ou
+Octave), des types vecteur ou matrice de Numpy, et des fonctions spéciales de
+Numpy. Toutes ces syntaxes sont valides.
+
+Après avoir enregistré ce script dans un fichier (nommé ici "*script.py*" pour
+l'exemple) à un endroit quelconque dans l'arborescence de l'utilisateur, on
+utilise l'interface textuelle pour construire le cas ADAO. La procédure pour
+compléter le cas est similaire à celle de l'exemple précédent à part le fait
+que, au lieu de choisir l'option "*Vector*" ou "*Matrix*" pour construire
+chaque variable, on choisit l'option "*Script*" en indiquant simultanément le
+type "*Vector*" ou "*Matrix*" de la variable. Cela permet d'obtenir les
+commandes suivantes (que ce soit en console Python, par la commande "*shell*"
+de SALOME, dans la console Python de l'interface, ou par le menu d'exécution
+d'un script) :
+::
+
+ adao@python$ python
+ Python 3.6.5 (default, Feb 01 2019, 12:12:12)
+ [GCC] on linux
+ Type "help", "copyright", "credits" or "license" for more information.
+ >>>
+ >>> from adao import adaoBuilder
+ >>> case = adaoBuilder.New()
+ >>> case.set( 'AlgorithmParameters', Algorithm='Blue' )
+ >>> case.set( 'Observation', Vector=True, Script="script.py" )
+ >>> case.set( 'ObservationError', Matrix=True, Script="script.py" )
+ >>> case.set( 'Background', Vector=True, Script="script.py" )
+ >>> case.set( 'BackgroundError', Matrix=True, Script="script.py" )
+ >>> case.set( 'ObservationOperator', Matrix=True, Script="script.py" )
+ >>> case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
+ >>> case.execute()
+ Analysis [0.5 0.5 0.5]
+ 0
+ >>>
+
+Les autres étapes et résultats sont exactement les mêmes que dans l'exemple
+précédent :ref:`section_tutorials_in_python_explicit`.
+
+Dans la pratique, cette démarche par scripts est la manière la plus facile pour
+récupérer des information depuis des calculs en ligne ou préalables, depuis des
+fichiers statiques, depuis des bases de données ou des flux informatiques,
+chacun pouvant être dans ou hors SALOME. Cela permet aussi de modifier aisément
+des données d'entrée, par exemple à des fin de débogage ou pour des traitements
+répétitifs, et c'est la méthode la plus polyvalente pour paramétrer les données
+d'entrée. **Mais attention, la méthodologie par scripts n'est pas une procédure
+"sûre", en ce sens que des données erronées ou des erreurs dans les calculs,
+peuvent être directement introduites dans l'exécution du cas ADAO.
+L'utilisateur doit vérifier avec attention le contenu de ses scripts.**
:scale: 50%
Cette section présente quelques exemples d'utilisation du module ADAO dans
-SALOME. Le premier montre comment construire un cas simple d'assimilation de
-données définissant explicitement toutes les données d'entrée requises à
+SALOME. Le premier montre comment construire un cas très simple d'assimilation
+de données définissant explicitement toutes les données d'entrée requises à
travers l'interface utilisateur graphique EFICAS (GUI). Le second montre, sur
le même cas, comment définir les données d'entrée à partir de sources externes
à travers des scripts. On présente ici toujours des scripts Python car ils sont
directement insérables dans les noeuds de script de YACS, mais les fichiers
externes peuvent utiliser d'autres langages.
-Les notations mathématiques utilisées ci-dessous sont expliquées dans la section
-:ref:`section_theory`.
+Ces exemples sont intentionnellement décrits de manière semblables aux
+:ref:`section_tutorials_in_python` car ils sont similaires à ceux que l'on peut
+traiter dans l'interface textuelle Python (TUI). Les notations mathématiques
+utilisées ci-dessous sont expliquées dans la section :ref:`section_theory`.
Construire un cas d'estimation avec une définition explicite des données
------------------------------------------------------------------------
-Cet exemple simple est un cas de démonstration, et il décrit comment mettre au
-point un environnement d'estimation par BLUE de manière à obtenir un *état
-estimé par méthode de moindres carrés pondérés* d'un système à partir d'une
-observation de l'état et d'une connaissance *a priori* (ou ébauche) de cet état.
-En d'autres termes, on cherche l'intermédiaire pondéré entre les vecteurs
-d'observation et d'ébauche. Toutes les valeurs numériques de cet exemple sont
-arbitraires.
+Cet exemple très simple est un cas de démonstration, et il décrit comment
+mettre au point un environnement d'estimation par BLUE de manière à obtenir un
+*état estimé par méthode de moindres carrés pondérés* d'un système à partir
+d'une observation de l'état et d'une connaissance *a priori* (ou ébauche) de
+cet état. En d'autres termes, on cherche l'intermédiaire pondéré entre les
+vecteurs d'observation et d'ébauche. Toutes les valeurs numériques de cet
+exemple sont arbitraires.
Conditions d'expérience
+++++++++++++++++++++++
-On choisit d'opérer dans un espace à 3 dimensions. La 3D est choisie de manière
-à restreindre la taille des objets numériques à entrer explicitement par
-l'utilisateur, mais le problème n'est pas dépendant de la dimension et peut être
-posé en dimension 10, 100, 1000... L'observation :math:`\mathbf{y}^o` vaut 1
-dans chaque direction, donc::
+On choisit d'opérer dans un espace d'observation à 3 dimensions, i.e on dispose
+de 3 mesures simples. La dimension 3 est choisie de manière à restreindre la
+taille des objets numériques à entrer explicitement par l'utilisateur, mais le
+problème n'est pas dépendant de la dimension et peut être posé en dimension
+d'observation de 10, 100, 1000... L'observation :math:`\mathbf{y}^o` vaut 1
+dans chaque direction, donc :
+::
Yo = [1 1 1]
L'ébauche :math:`\mathbf{x}^b` de l'état , qui représente une connaissance *a
-priori* ou une régularisation mathématique, vaut 0 dans chaque direction, ce qui
-donne donc::
+priori* ou une régularisation mathématique, est choisie comme valant 0 dans
+chaque cas, ce qui donne donc :
+::
Xb = [0 0 0]
-La mise en oeuvre de l'assimilation de données requiert des informations sur les
-covariances d'erreur :math:`\mathbf{R}` et :math:`\mathbf{B}`, respectivement
-pour les variables d'observation et d'ébauche. On choisit ici des erreurs
-décorrélées (c'est-à-dire des matrices diagonales) et d'avoir la même variance
-de 1 pour toutes les variables (c'est-à-dire des matrices identité). On pose
-donc::
+La mise en oeuvre de l'assimilation de données requiert des informations sur
+les covariances d'erreur :math:`\mathbf{R}` et :math:`\mathbf{B}`,
+respectivement pour les variables d'erreur d'observation et d'ébauche. On
+choisit ici des erreurs décorrélées (c'est-à-dire des matrices diagonales) et
+d'avoir la même variance de 1 pour toutes les variables (c'est-à-dire des
+matrices identité). On pose donc :
+::
- B = R = [1 0 0 ; 0 1 0 ; 0 0 1]
+ B = R = Id = [1 0 0 ; 0 1 0 ; 0 0 1]
Enfin, on a besoin d'un opérateur d'observation :math:`\mathbf{H}` pour
convertir l'état d'ébauche dans l'espace des observations. Ici, comme les
dimensions d'espace sont les mêmes, on peut choisir l'identité comme opérateur
-d'observation::
+d'observation :
+::
- H = [1 0 0 ; 0 1 0 ; 0 0 1]
+ H = Id = [1 0 0 ; 0 1 0 ; 0 0 1]
Avec de tels choix, l'estimateur "Best Linear Unbiased Estimator" (BLUE) sera le
vecteur moyen entre :math:`\mathbf{y}^o` et :math:`\mathbf{x}^b`, nommé
-*analysis*, noté :math:`\mathbf{x}^a`, et valant::
-
+*analysis*, noté :math:`\mathbf{x}^a`, et valant :
+::
Xa = [0.5 0.5 0.5]
Ensuite, il faut remplir les variables pour construire le cas ADAO en utilisant
les conditions d'expérience décrites ci-dessus. L'ensemble des informations
techniques données au-dessus sont à insérer directement dans la définition du
-cas ADAO, en utilisant le type *String* pour toutes les variables. Lorsque la
-définition du cas est prête, il faut l'enregistrer comme un fichier natif de ype
-"*JDC (\*.comm)*" à un endroit quelconque dans l'arborescence de l'utilisateur.
-Il faut bien se rappeler que d'autres fichiers seront aussi créés à côté de ce
-premier, donc il est judicieux de faire un répertoire spécifique pour ce cas, et
-d'enregistrer dedans le fichier. Le nom du fichier apparaît dans la fenêtre de
-l'"*Arbre d'étude*", sous le menu "*ADAO*". La définition finale du cas
-ressemble à :
+cas ADAO, en utilisant le type *String* pour chaque variable. Lorsque la
+définition du cas est prête, il faut l'enregistrer comme un fichier natif de
+ype "*JDC (\*.comm)*" à un endroit quelconque dans l'arborescence de
+l'utilisateur. Il faut bien se rappeler que d'autres fichiers seront aussi
+créés à côté de ce premier, donc il est judicieux de faire un répertoire
+spécifique pour ce cas, et d'enregistrer dedans le fichier. Le nom du fichier
+apparaît dans la fenêtre de l'"*Arbre d'étude*", sous le menu "*ADAO*". La
+définition finale du cas ressemble à :
.. _adao_jdcexample01:
.. image:: images/adao_jdcexample01.png
Pour obtenir ceci, ce noeud de script doit comporter un port d'entrée de type
"*pyobj*", nommé "*Study*" par exemple, qui doit être relié graphiquement au
port de sortie "*algoResults*" du bloc de calcul. Ensuite, le code pour remplir
-le noeud de script est::
+le noeud de script est :
+::
Xa = Study.getResults().get("Analysis")[-1]
**Menu YACS de la fenêtre de sortie, et boite de dialogue montrant la sortie**
On vérifie que le résultat est correct en observant si la fenêtre de sortie
-contient la ligne suivante::
+contient la ligne suivante :
+::
Analysis = [0.5, 0.5, 0.5]
Construire un cas d'estimation avec une définition de données externes par scripts
----------------------------------------------------------------------------------
-Il est utile d'acquérir une partie ou la totalité des données depuis une
-définition externe, en utilisant des scripts Python pour donner accès à ces
-données. À titre d'exemple, on construit ici un cas ADAO présentant le même
-dispositif expérimental que dans l'exemple ci-dessus `Construire un cas
+Il est utile d'acquérir une partie ou la totalité des données du cas ADAO
+depuis une définition externe, en utilisant des scripts Python pour donner
+accès à ces données. À titre d'exemple, on construit ici un cas ADAO présentant
+le même dispositif expérimental que dans l'exemple ci-dessus `Construire un cas
d'estimation avec une définition explicite des données`_, mais en utilisant des
données issues d'un unique fichier script Python externe.
définies dans le même script, mais l'utilisateur peut choisir de séparer le
fichier en plusieurs autres, ou de mélanger une définition explicite des données
dans l'interface graphique ADAO et une définition implicite dans des fichiers
-externes. Le fichier script actuel ressemble à::
+externes. Le fichier script actuel ressemble à :
+::
import numpy
#
# --------------------------------------------------
ObservationOperator = numpy.identity(3)
-Les noms des variables Python sont obligatoires, de manière à définir les bonnes
-variables dans le cas, mais le script Python peut être plus conséquent et
-définir des classes, des fonctions, des accès à des fichiers ou des bases de
-données, etc. avec des noms différents. De plus, le fichier ci-dessus présente
-différentes manières de définir des vecteurs ou des matrices, utilisant des
-listes, des chaînes de caractères (comme dans Numpy ou Octave), des types
-vecteur ou matrice de Numpy, et des fonctions spéciales de Numpy. Toutes ces
-syntaxes sont valides.
+Les noms des variables Python sont obligatoires, de manière à définir les
+bonnes variables dans le cas ADAO, mais le script Python peut être plus
+conséquent et définir des classes, des fonctions, des accès à des fichiers ou
+des bases de données, etc. avec des noms différents. De plus, le fichier
+ci-dessus présente différentes manières de définir des vecteurs ou des
+matrices, utilisant des listes, des chaînes de caractères (comme dans Numpy ou
+Octave), des types vecteur ou matrice de Numpy, et des fonctions spéciales de
+Numpy. Toutes ces syntaxes sont valides.
Après avoir enregistré ce script dans un fichier (nommé ici "*script.py*" pour
l'exemple) à un endroit quelconque dans l'arborescence de l'utilisateur, on
répétitifs, et c'est la méthode la plus polyvalente pour paramétrer les données
d'entrée. **Mais attention, la méthodologie par scripts n'est pas une procédure
"sûre", en ce sens que des données erronées ou des erreurs dans les calculs,
-peuvent être directement introduites dans l'exécution du schéma YACS.
+peuvent être directement introduites dans l'exécution du cas ADAO.
L'utilisateur doit vérifier avec attention le contenu de ses scripts.**
Ajout de paramètres pour contrôler l'algorithme d'assimilation de données
script Python, en utilisant le nom obligatoire de variable
"*AlgorithmParameters*" pour le dictionnaire. Toutes les clés dans le
dictionnaire sont optionnelles, elles disposent toutes d'une valeur par défaut,
-et elles peuvent être présentes sans être utiles. Par exemple::
+et elles peuvent être présentes sans être utiles. Par exemple :
+::
AlgorithmParameters = {
"Minimizer" : "LBFGSB", # Recommended
dimension.
On choisit un contexte d'expériences jumelles, en utilisant un état vrai
-:math:`\mathbf{x}^t` connu, mais de valeur arbitraire::
+:math:`\mathbf{x}^t` connu, mais de valeur arbitraire :
+::
Xt = [1 2 3]
L'état d'ébauche :math:`\mathbf{x}^b`, qui représentent une connaissance *a
priori* de l'état vrai, est construit comme une perturbation aléatoire
gaussienne de 20% de l'état vrai :math:`\mathbf{x}^t` pour chaque composante,
-qui est::
+qui est :
+::
Xb = Xt + normal(0, 20%*Xt)
Pour décrire la matrice des covariances d'erreur d'ébauche math:`\mathbf{B}`, on
fait comme précédemment l'hypothèse d'erreurs décorrélées (c'est-à-dire, une
matrice diagonale, de taille 3x3 parce-que :math:`\mathbf{x}^b` est de taille 3)
-et d'avoir la même variance de 0,1 pour toutes les variables. On obtient::
+et d'avoir la même variance de 0,1 pour toutes les variables. On obtient :
+::
B = 0.1 * diagonal( length(Xb) )
Étant en expériences jumelles, les observations :math:`\mathbf{y}^o` et leur
matrice de covariances d'erreurs :math:`\mathbf{R}` sont générées en utilisant
l'état vrai :math:`\mathbf{x}^t` et l'opérateur d'observation
-:math:`\mathbf{H}`::
+:math:`\mathbf{H}` :
+::
Yo = H( Xt )
-et, avec un écart-type arbitraire de 1% sur chaque composante de l'erreur::
+et, avec un écart-type arbitraire de 1% sur chaque composante de l'erreur :
+::
R = 0.0001 * diagonal( length(Yo) )
On définit en premier lieu l'état vrai :math:`\mathbf{x}^t` et une fonction
utiles à la construction de matrices, dans un fichier script Python nommé
-``Physical_data_and_covariance_matrices.py``::
+``Physical_data_and_covariance_matrices.py`` :
+::
import numpy
#
On définit ensuite l'état d'ébauche :math:`\mathbf{x}^b` comme une perturbation
aléatoire de l'état vrai, en ajoutant une *variable ADAO requise* à la fin du
script de définition, de manière à exporter la valeur définie. C'est réalisé
-dans un fichier de script Python nommé ``Script_Background_xb.py``::
+dans un fichier de script Python nommé ``Script_Background_xb.py`` :
+::
from Physical_data_and_covariance_matrices import True_state
import numpy
xb = xt + abs(numpy.random.normal(0.,Standard_deviation,size=(len(xt),)))
#
# Creating the required ADAO variable
- # ------------------------------------
+ # -----------------------------------
Background = list(xb)
De la même manière, on définit la matrice des covariances de l'erreur d'ébauche
:math:`\mathbf{B}` comme une matrice diagonale, de la même longueur de diagonale
que l'ébauche de la valeur vraie, en utilisant la fonction d'aide déjà définie.
C'est réalisé dans un fichier script Python nommé
-``Script_BackgroundError_B.py``::
+``Script_BackgroundError_B.py`` :
+::
from Physical_data_and_covariance_matrices import True_state, Simple_Matrix
#
``"DirectOperator"``. Cette fonction est une une fonction utilisateur,
représentant de manière programmée l'opérateur :math:`\mathbf{H}`. On suppose
que cette fonction est donnée par l'utilisateur. Un squelette simple est donné
-ici par facilité::
+ici par facilité :
+::
def DirectOperator( XX ):
""" Direct non-linear simulation operator """
Dans cet environnement d'expériences jumelles, l'observation
:math:`\mathbf{y}^o` et sa matrice des covariances d'erreur :math:`\mathbf{R}`
peuvent être générées. C'est réalisé dans deux fichiers de script Python, le
-premier étant nommé ``Script_Observation_yo.py``::
+premier étant nommé ``Script_Observation_yo.py`` :
+::
from Physical_data_and_covariance_matrices import True_state
from Physical_simulation_functions import DirectOperator
# -----------------------------------
Observation = list(yo)
-et le second nommé ``Script_ObservationError_R.py``::
+et le second nommé ``Script_ObservationError_R.py`` :
+::
from Physical_data_and_covariance_matrices import True_state, Simple_Matrix
from Physical_simulation_functions import DirectOperator
paramètres pour l'algorithme d'assimilation de données. Par exemple, si on
utilise l'algorithme standard de "*3DVAR*", les paramètres suivants peuvent être
définis dans un fichier de script Python nommé
-``Script_AlgorithmParameters.py``::
+``Script_AlgorithmParameters.py`` :
+::
# Creating the required ADAO variable
# -----------------------------------
représenter. Cela nécessite d'utiliser un fichier script Python intermédiaire de
manière à extraire ces résultats à la fin de la procédure d'assimilation de
données ou d'optimisation. L'exemple suivant de fichier script Python, nommé
-``Script_UserPostAnalysis.py``, illustre le fait::
+``Script_UserPostAnalysis.py``, illustre le fait :
+::
from Physical_data_and_covariance_matrices import True_state
import numpy
En utilisant l'opérateur linéaire simple :math:`\mathbf{H}` du fichier script
Python ``Physical_simulation_functions.py`` disponible dans le répertoire
-standard des exemples, les résultats ressemblent à::
+standard des exemples, les résultats ressemblent à :
+::
xt = [1 2 3]
xa = [ 1.000014 2.000458 3.000390]
