---------------------------------------------------
.. index:: single: Logging
+.. index:: single: Debug
+.. index:: single: setDebug
When running a calculation, useful data and messages are logged. There are two
ways to obtain theses information.
The first one, and the preferred way, is to use the built-in variable "*Debug*"
-available in every ADAO case. It is available through the edition GUI of the
-module. Setting it to "*1*" will send messages in the log window of the YACS
-scheme execution.
+available in every ADAO case. It can be reached in the module's graphical user
+interface (GUI) as well as in the textual interface (TUI). Setting it to "*1*"
+will send messages in the log window of the YACS scheme execution.
The second one consist in using the "*logging*" native module of Python (see the
Python documentation http://docs.python.org/library/logging.html for more
The standard logging module default level is "*WARNING*", the default level in
the ADAO module is "*INFO*".
-It is also recommended to include some logging or debug mechanisms in the
-simulation code, and use them in conjunction with the two previous methods. But
-be careful not to store too big variables because it cost time, whatever logging
-level is chosen (that is, even if these variables are not printed).
+It is also recommended to include logging monitoring or debugging mechanisms in
+the user's physical simulation code, and to exploit them in conjunction with
+the previous two methods. But be careful not to store "too big" variables
+because it cost time or memory, whatever logging level is chosen (that is, even
+if these variables are not printed).
.. _subsection_ref_parallel_df:
pygments_style = None
templates_path = ['_templates']
exclude_trees = ['snippets',]
+numfig = True
# -- Options for HTML output ---------------------------------------------------
over time. It uses information coming from experimental measurements or
observations, and from numerical *a priori* models, including information about
their errors. Parts of the framework are also known under the names of
-*parameter estimation*, *inverse problems*, *Bayesian estimation*, *optimal
-interpolation*, *field reconstruction*, etc. The ADAO module currently offers
-more than one hundred different algorithmic methods and allows the study of
-about 350 distinct applied problems. More details can be found in the section
-:ref:`section_theory`.
+*inverse problems*, *parameter estimation*, *Bayesian estimation*, *optimal
+interpolation*, *field reconstruction*, etc. More details can be found in the
+section :ref:`section_theory`. The ADAO module currently offers more than one
+hundred different algorithmic methods and allows the study of about 350
+distinct applied problems.
The documentation for this module is divided into several major categories,
related to the theoretical documentation (indicated in the section title by
.. include:: snippets/CostDecrementTolerance.rst
+.. include:: snippets/EstimationOf_Parameters.rst
+
.. include:: snippets/GradientNormTolerance.rst
.. include:: snippets/InitializationPoint.rst
.. include:: snippets/CostDecrementTolerance.rst
-.. include:: snippets/EstimationOf.rst
+.. include:: snippets/EstimationOf_State.rst
.. include:: snippets/GradientNormTolerance.rst
.. ------------------------------------ ..
.. include:: snippets/Header2Algo03AdOp.rst
-.. include:: snippets/EstimationOf.rst
+.. include:: snippets/EstimationOf_State.rst
.. include:: snippets/InflationFactor.rst
:align: center
:width: 100%
.. centered::
- **Timeline of steps in extended Kalman filter assimilation**
+ **Timeline of steps in extended Kalman filter data assimilation**
We notice that there is no analysis performed at the initial time step
(numbered 0 in the time indexing) because there is no forecast at this time
.. include:: snippets/ConstrainedBy.rst
-.. include:: snippets/EstimationOf.rst
+.. include:: snippets/EstimationOf_State.rst
StoreSupplementaryCalculations
.. index:: single: StoreSupplementaryCalculations
:align: center
:width: 100%
.. centered::
- **Timeline of steps in Kalman filter assimilation**
+ **Timeline of steps in Kalman filter data assimilation**
We notice that there is no analysis performed at the initial time step
(numbered 0 in the time indexing) because there is no forecast at this time
.. ------------------------------------ ..
.. include:: snippets/Header2Algo03AdOp.rst
-.. include:: snippets/EstimationOf.rst
+.. include:: snippets/EstimationOf_State.rst
StoreSupplementaryCalculations
.. index:: single: StoreSupplementaryCalculations
.. include:: snippets/ConstrainedBy.rst
-.. include:: snippets/EstimationOf.rst
+.. include:: snippets/EstimationOf_State.rst
.. include:: snippets/AlphaBeta.rst
.. centered::
**Choosing graphically an operator functional representation**
+In ADAO textual interface (TUI), in the specific case illustrated above, the
+same approach is taken by writing :
+::
+
+ ...
+ case.set( 'ObservationOperator',
+ OneFunction = True,
+ Script = 'scripts_for_JDC.py'
+ )
+ ...
+
.. _section_ref_operator_one:
First functional form: one direct operator only
+++ /dev/null
-.. index:: single: EstimationOf
-
-EstimationOf
- *Predefined name*. This key allows to choose the type of estimation to be
- performed. It can be either state-estimation, with a value of "State", or
- parameter-estimation, with a value of "Parameters". The default choice is
- "State".
-
- Example:
- ``{"EstimationOf":"Parameters"}``
--- /dev/null
+.. index:: single: EstimationOf
+
+EstimationOf
+ *Predefined name*. This key allows to choose the type of estimation to be
+ performed. It can be either state-estimation, with a value of "State", or
+ parameter-estimation, with a value of "Parameters". The default choice is
+ "Parameters".
+
+ Example:
+ ``{"EstimationOf":"Parameters"}``
--- /dev/null
+.. index:: single: EstimationOf
+
+EstimationOf
+ *Predefined name*. This key allows to choose the type of estimation to be
+ performed. It can be either state-estimation, with a value of "State", or
+ parameter-estimation, with a value of "Parameters". The default choice is
+ "State".
+
+ Example:
+ ``{"EstimationOf":"Parameters"}``
.. index:: single: true state
.. index:: single: observation
.. index:: single: a priori
+.. index:: single: EstimationOf
**Data Assimilation** is a general well established framework for computing the
optimal estimate of the true state of a system, over time if necessary. It uses
they are far more general and can be used without data assimilation concepts.
Two main types of applications exist in data assimilation, which are covered by
-the same formalism: **fields reconstruction** and **parameters identification**.
-These are also referred to as **state estimation** and **parameters estimation**
-respectively. Before introducing the `Simple description of the data
-assimilation methodological framework`_ in a next section, these two types of
-applications are briefly described. At the end, some references allow `Going
-further in the data assimilation framework`_.
+the same formalism: **fields reconstruction** (see `Fields reconstruction or
+measures interpolation`_) and **parameters identification** (see `Parameters
+identification, models adjustment, or calibration`_). These are also referred
+to as **state estimation** and **parameters estimation** respectively, and one
+can if necessary elaborate joint estimation of both (see `Joint state and
+parameter estimation in dynamics`_). In ADAO, some algorithms can be used
+either in state estimation or in parameter estimation. This is done simply by
+changing the required option "*EstimationOf*" in the algorithm parameters.
+Before introducing the `Simple description of the data assimilation
+methodological framework`_ in a next section, these two types of applications
+are briefly described. At the end, some detailed information allow `Going
+further in the data assimilation framework`_ and `Going further in the state
+estimation by optimization methods`_, as well as `Going further in data
+assimilation for dynamics`_ and having an `Overview of reduction methods and
+of reduced optimization`_.
Fields reconstruction or measures interpolation
-----------------------------------------------
.. index:: single: measures interpolation
.. index:: single: fields interpolation
.. index:: single: state estimation
+.. index:: single: background
**Fields reconstruction (or interpolation)** consists in finding, from a
restricted set of real measures, the physical field which is the most
a "consistent" manner with the evolution equations and with the measures of the
previous time steps.
-Parameters identification, models adjustment, calibration
----------------------------------------------------------
+Parameters identification, models adjustment, or calibration
+------------------------------------------------------------
.. index:: single: parameters identification
.. index:: single: parameters adjustment
the conceptually very simple approach of considering the vector of states to be
interpolated as *augmented* by the vector of parameters to be calibrated. It
can be noted that we are in *state estimation* or *reconstruction of fields*,
-and that in the temporal case, the evolution of the parameters to estimate is
-simply the identity. The assimilation or optimization algorithms can then be
-applied to the augmented vector. Valid for moderate nonlinearities in the
-simulation, this simple method extends the optimization space, and thus leads
-to larger problems, but it is often possible to reduce the representation to
-numerically computable cases. Without exhaustiveness, the separated variables
-optimization, the reduced rank filtering, or the specific treatment of
-covariance matrices, are common techniques to avoid this dimension problem.
+and that in the temporal case of parameters identification, the evolution of
+the parameters to estimate is simply the identity. The assimilation or
+optimization algorithms can then be applied to the augmented vector. Valid for
+moderate nonlinearities in the simulation, this simple method extends the
+optimization space, and thus leads to larger problems, but it is often possible
+to reduce the representation to numerically computable cases. Without
+exhaustiveness, the separated variables optimization, the reduced rank
+filtering, or the specific treatment of covariance matrices, are common
+techniques to avoid this dimension problem. In the temporal case, we will see
+below indications for a `Joint state and parameter estimation in dynamics`_.
To go further, we refer to the mathematical methods of optimization and
augmentation developed in many books or specialized articles, finding their
and "*Kalman filter (KF)*" and their derivatives. They have to take into
account an evolution operator to establish an analysis at the right time steps
of the gap between observations and simulations, and to have, at every moment,
-the propagation of the background through the evolution model. In the same way,
-these methods can be used in case of non linear observation or evolution
-operators. Many other variants have been developed to improve the numerical
-quality of the methods or to take into account computer requirements such as
-calculation size and time.
+the propagation of the background through the evolution model. The next section
+provides information on `Going further in data assimilation for dynamics`_. In
+the same way, these methods can be used in case of non linear observation or
+evolution operators. Many other variants have been developed to improve the
+numerical quality of the methods or to take into account computer requirements
+such as calculation size and time.
A schematic view of Data Assimilation and Optimization approaches
-----------------------------------------------------------------
The reader interested in the subject of optimization can look at [WikipediaMO]_
as a general entry point.
-Reduction methods and reduced optimization
-------------------------------------------
+Going further in data assimilation for dynamics
+-----------------------------------------------
+
+.. index:: single: dynamic (system)
+.. index:: single: system dynamic
+.. index:: single: temporal evolution
+.. index:: single: ODE (Ordinary Differential Equation)
+.. index:: single: EstimationOf
+
+We can analyze a system in temporal evolution (dynamics) with the help of data
+assimilation, in order to explicitly take into account the flow of time in the
+estimation of states or parameters. We briefly introduce here the problematic,
+and some theoretical or practical tools, to facilitate the user treatment of
+such situations. It is nevertheless indicated that the variety of physical and
+user problems is large, and that it is therefore recommended to adapt the
+treatment to the constraints, whether they are physical, numerical or
+computational.
+
+General form of dynamic systems
++++++++++++++++++++++++++++++++
+
+Systems in temporal evolution can be studied or represented using dynamic
+systems. In this case, it is easy to conceive the analysis of their behavior
+with the help of data assimilation (it is even in this precise case that the
+data assimilation approach was initially widely developed).
+
+We formalize the numerical simulation framework in a simple way. A simple
+dynamic system dynamic system on the state :math:`\mathbf{x}` can be described
+in the form:
+
+.. math:: \forall t \in \mathbb{R}^{+}, \frac{d\mathbf{x}}{dt} = \mathcal{D}(\mathbf{x},\mathbf{u},t)
+
+where :math:`\mathbf{x}` is the unknown state vector, :math:`\mathbf{u}` is a
+known external control vector, and :math:`\mathcal{D}` is the (possibly
+non-linear) operator of the system dynamics. It is an Ordinary Differential
+Equation (ODE), of the first order, on the state. In discrete time, this
+dynamical system can be written in the following form:
+
+.. math:: \forall n \in \mathbb{N}, \mathbf{x}_{n+1} = M(\mathbf{x}_{n},\mathbf{u}_{n},t_n\rightarrow t_{n+1})
+
+for an indexing :math:`t_n` of discrete times with :math:`n\in\mathbf{N}`.
+:math:`M` is the discrete evolution operator obtained from :math:`\mathcal{D}`.
+Usually, we omit the time notation in the evolution operator :math:`M`.
+Approximating the :math:`\mathcal{D}` operator by :math:`M` introduces (or
+adds, if it already exists) a :math:`\epsilon` model error.
+
+We can then characterize two types of estimates in dynamics, which we describe
+hereafter on the discrete time dynamical system: `State estimation in
+dynamics`_ and `Parameter estimation in dynamics`_. Combined, the two types can
+be used to make a `Joint state and parameter estimation in dynamics`_. In ADAO,
+some algorithms can be used either in state estimation or in parameter
+estimation. This is done simply by changing the required option
+"*EstimationOf*" in the algorithm parameters.
+
+State estimation in dynamics
+++++++++++++++++++++++++++++
+
+The state estimation can be conducted by data assimilation on the discrete time
+version of the dynamical system, written in the following form:
+
+.. math:: \mathbf{x}_{n+1} = M(\mathbf{x}_{n},\mathbf{u}_{n}) + \mathbf{\epsilon}_{n}
+
+.. math:: \mathbf{y}_{n} = H(\mathbf{x}_{n}) + \mathbf{\nu}_{n}
+
+where :math:`\mathbf{x}` is the system state to be estimated,
+:math:`\mathbf{x}_{n}` and :math:`\mathbf{y}_{n}` are respectively the
+(computed) unobserved and (measured) observed state of the system, :math:`M`
+and :math:`H` are the incremental evolution and observation operators,
+respectively, :math:`\mathbf{\epsilon}_{n}` and :math:`\mathbf{\nu}_{n}` are
+the evolution and observation noise or error, respectively, and
+:math:`\mathbf{u}_{n}` is a known external control. The two operators :math:`M`
+and :math:`H` are directly usable in data assimilation with ADAO.
+
+Parameter estimation in dynamics
+++++++++++++++++++++++++++++++++
+
+The parameter estimation can be written a differently to be solved by data
+assimilation. Still on the discrete time version of the dynamical system, we
+look for a nonlinear :math:`G` mapping, parameterized by :math:`\mathbf{a}`,
+between inputs :math:`\mathbf{x}_{n}` and measurements :math:`\mathbf{y}_{n}`
+at each step :math:`t_n`, the error to be controlled as a function of
+parameters :math:`\mathbf{y}_{n}` being
+:math:`\mathbf{y}_{n}-G(\mathbf{x}_{n},\mathbf{a})`. We can proceed by
+optimization on this error, with regularization, or by filtering by writing the
+problem represented in state estimation:
+
+.. math:: \mathbf{a}_{n+1} = \mathbf{a}_{n} + \mathbf{\epsilon}_{n}
+
+.. math:: \mathbf{y}_{n} = G(\mathbf{x}_{n},\mathbf{a}_{n}) + \mathbf{\nu}_{n}
+
+where, this time, the choices of the evolution and observation error models
+:math:`\mathbf{\epsilon}_{n}` and :math:`\mathbf{\nu}_{n}` condition the
+performance of convergence and observation tracking. The estimation of the
+parameters :math:`\mathbf{a}` is done by using pairs
+:math:`(\mathbf{x}_{n},\mathbf{y}_{n})` of corresponding inputs and outputs.
+
+In this case of parameter estimation, in order to apply data assimilation
+methods, we therefore impose the hypothesis that the evolution operator is the
+identity (*Note: it is therefore not used, but must be declared in ADAO, for
+example as a 1 matrix*), and the observation operator is :math:`G`.
+
+Joint state and parameter estimation in dynamics
+++++++++++++++++++++++++++++++++++++++++++++++++
+
+A special case concerns the joint estimation of state and parameters used in a
+dynamic system. One seeks to jointly estimate the state :math:`\mathbf{x}`
+(which depends on time) and the parameters :math:`\mathbf{a}` (which does not
+depend on time). There are several ways to deal with this problem, but the most
+general one is to use a state vector augmented by the parameters, and to extend
+the operators accordingly.
+
+To do this, using the notations of the previous two subsections, we define the
+auxiliary variable :math:`\mathbf{w}` such that:
+
+.. math:: \mathbf{w} = \left[
+ \begin{array}{c}
+ \mathbf{x} \\
+ \mathbf{a}
+ \end{array}
+ \right]
+ = \left[
+ \begin{array}{c}
+ \mathbf{w}_{|x} \\
+ \mathbf{w}_{|a}
+ \end{array}
+ \right]
+
+and the operators of evolution :math:`\tilde{M}` and observation
+:math:`\tilde{H}` associated to the augmented problem:
+
+.. math:: \tilde{M}(\mathbf{w},\mathbf{u}) = \left[
+ \begin{array}{c}
+ M(\mathbf{w}_{|x},\mathbf{u}) \\
+ \mathbf{w}_{|a}
+ \end{array}
+ \right]
+ = \left[
+ \begin{array}{c}
+ M(\mathbf{x},\mathbf{u}) \\
+ \mathbf{a}
+ \end{array}
+ \right]
+
+.. math:: \tilde{H}(\mathbf{w}) = \left[
+ \begin{array}{c}
+ H(\mathbf{w}_{|x}) \\
+ G(\mathbf{w}_{|x},\mathbf{w}_{|a})
+ \end{array}
+ \right]
+ = \left[
+ \begin{array}{c}
+ H(\mathbf{x}) \\
+ G(\mathbf{x},\mathbf{a})
+ \end{array}
+ \right]
+
+With these notations, by extending the noise variables
+:math:`\mathbf{\epsilon}` and :math:`\mathbf{\nu}` appropriately, the joint
+state :math:`\mathbf{x}` and parameters :math:`\mathbf{a}` discrete-time
+estimation problem, using the joint variable :math:`\mathbf{w}`, is then
+written:
+
+.. math:: \mathbf{w}_{n+1} = \tilde{M}(\mathbf{w}_{n},\mathbf{u}_{n}) + \mathbf{\epsilon}_{n}
+
+.. math:: \mathbf{y}_{n} = \tilde{H}(\mathbf{w}_{n}) + \mathbf{\nu}_{n}
+
+The incremental evolution and observation operators are therefore respectively
+the augmented operators :math:`\tilde{M}` and :math:`\tilde{H}`, and are
+directly usable in data assimilation with ADAO.
+
+Conceptual scheme for data assimilation in dynamics
++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+To complete the description, we can represent the data assimilation process in
+a dynamics specific way using a temporal scheme, which describes the action of
+the evolution (:math:`M` or :math:`\tilde{M}`) and observation (:math:`H` or
+:math:`\tilde{H}`) operators during the discrete simulation. A possible
+representation is as follows:
+
+ .. _schema_d_AD_temporel:
+ .. image:: images/schema_temporel_KF.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Timeline of steps for data assimilation operators in dynamics**
+
+The concepts described in this diagram can be directly and simply used in ADAO.
+
+Overview of reduction methods and of reduced optimization
+---------------------------------------------------------
.. index:: single: reduction
.. index:: single: reduction methods
**[DocR]** Textual User Interface for ADAO (TUI/API)
================================================================================
+.. |eficas_totui| image:: images/eficas_totui.png
+ :align: middle
+ :scale: 50%
+
This section presents advanced usage of the ADAO module using its text
programming interface (API/TUI). This interface gives ability to create a
calculation object in a similar way than the case building obtained through the
-graphical interface (GUI). When one wants to elaborate "by hand" the TUI
-calculation case, it is recommended to extensively use all the ADAO module
-documentation, and to go back if necessary to the graphical interface (GUI), to
-get all the elements allowing to correctly set the commands. The general used
-notions and terms are defined in :ref:`section_theory`. As in the graphical
-interface, we point out that the TUI approach is intended to create and manage
-a single calculation case.
+graphical interface (GUI). A scripted form of a case built in the GUI can be
+obtained directly using the TUI export button |eficas_totui| integrated in the
+interface, but more complicated or integrated cases can be build only using TUI
+approach. When one wants to elaborate "by hand" the TUI calculation case, it is
+recommended to extensively use all the ADAO module documentation, and to go
+back if necessary to the graphical interface (GUI), to get all the elements
+allowing to correctly set the commands. The general used notions and terms are
+defined in :ref:`section_theory`. As in the graphical interface, we point out
+that the TUI approach is intended to create and manage a single calculation
+case.
.. _subsection_tui_creating:
**[DocU]** Tutorials on using the ADAO module in Python
================================================================================
+.. |eficas_totui| image:: images/eficas_totui.png
+ :align: middle
+ :scale: 50%
+
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)
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`.
+can be treated in the graphical user interface in SALOME. A scripted form of a
+case built in the GUI can be obtained directly using the TUI export button
+|eficas_totui| integrated in the interface. The mathematical notations used
+afterward are explained in the section :ref:`section_theory`.
+
+Other simple examples, and their accompanying illustrations, are included at
+the end of the reference documentation of some algorithms. It is the case, in a
+non-limitative way, of :ref:`section_ref_algorithm_3DVAR`,
+:ref:`section_ref_algorithm_KalmanFilter` and
+:ref:`section_ref_algorithm_ExtendedBlue`.
.. _section_tutorials_in_python_explicit:
.. |eficas_new| image:: images/eficas_new.png
:align: middle
- :scale: 50%
+ :scale: 75%
.. |eficas_save| image:: images/eficas_save.png
:align: middle
- :scale: 50%
+ :scale: 75%
.. |eficas_saveas| image:: images/eficas_saveas.png
+ :align: middle
+ :scale: 75%
+.. |eficas_totui| image:: images/eficas_totui.png
:align: middle
:scale: 50%
.. |eficas_yacs| image:: images/eficas_yacs.png
:align: middle
- :scale: 50%
+ :scale: 75%
This section presents some examples on using the ADAO module in SALOME. The
first one shows how to build a very simple data assimilation case defining
----------------------------------------------------------
.. index:: single: Logging
+.. index:: single: Debug
+.. index:: single: setDebug
Lors du déroulement d'un calcul, des données et messages utiles sont
disponibles. Il y a deux manières d'obtenir ces informations.
La première, et la manière préférentielle, est d'utiliser la variable interne
-"*Debug*" disponible dans chaque cas ADAO. Elle est atteignable dans l'interface
-graphique d'édition du module. La mettre à "*1*" permet d'envoyer des messages
-dans la fenêtre de sortie de l'exécution dans YACS ("*YACS Container Log*").
+"*Debug*" disponible dans chaque cas ADAO. Elle est atteignable dans
+l'interface graphique d'édition (GUI) du module comme dans l'interface
+textuelle (TUI). La mettre à "*1*" permet d'envoyer des messages dans la
+fenêtre de sortie de l'exécution dans YACS ("*YACS Container Log*").
La seconde consiste à utiliser le module Python natif "*logging*" (voir la
documentation Python http://docs.python.org/library/logging.html pour de plus
niveau par défaut dans le module ADAO est "*INFO*".
Il est aussi recommandé d'inclure de la surveillance par logging ou des
-mécanismes de débogage dans le code de simulation, et de les utiliser en
-conjonction avec les deux méthodes précédentes. Néanmoins, il convient d'être
-prudent dans le stockage de "grosses" variables car cela coûte du temps,
-quel que soit le niveau de surveillance choisi (c'est-à-dire même si ces
-variables ne sont pas affichées).
+mécanismes de débogage dans le code de simulation physique de l'utilisateur, et
+de les exploiter en conjonction avec les deux méthodes précédentes. Néanmoins,
+il convient d'être prudent dans le stockage de "grosses" variables car cela
+coûte du temps ou de la mémoire, quel que soit le niveau de surveillance choisi
+(c'est-à-dire même si ces variables ne sont pas affichées).
.. _subsection_ref_parallel_df:
pygments_style = None
templates_path = ['_templates']
exclude_trees = ['snippets',]
+numfig = True
# -- Options for HTML output ---------------------------------------------------
système, éventuellement au cours du temps. Il utilise des informations
provenant de mesures expérimentales, ou observations, et de modèles numériques
*a priori*, y compris des informations sur leurs erreurs. Certaines des
-méthodes incluses dans ce cadre sont également connues sous les noms
-d'*estimation de paramètres*, de *problèmes inverses*, d'*estimation
-bayésienne*, d'*interpolation optimale*, de *reconstruction de champs*, etc. Le
+méthodes incluses dans ce cadre sont également connues sous les noms de
+*problèmes inverses*, *estimation de paramètres*, *estimation bayésienne*,
+*interpolation optimale*, *reconstruction de champs*, etc. De plus amples
+détails peuvent être trouvés dans la partie proposant :ref:`section_theory`. Le
module ADAO offre actuellement plus d'une centaine de méthodes algorithmiques
-différentes et permet l'étude d'environ 350 problèmes appliqués distincts. De
-plus amples détails peuvent être trouvés dans la partie proposant
-:ref:`section_theory`.
+différentes et permet l'étude d'environ 350 problèmes appliqués distincts.
La documentation de ce module est divisée en plusieurs grandes catégories,
relatives à la documentation théorique (indiquée dans le titre de section par
.. include:: snippets/CostDecrementTolerance.rst
+.. include:: snippets/EstimationOf_Parameters.rst
+
.. include:: snippets/GradientNormTolerance.rst
.. include:: snippets/InitializationPoint.rst
.. include:: snippets/CostDecrementTolerance.rst
-.. include:: snippets/EstimationOf.rst
+.. include:: snippets/EstimationOf_State.rst
.. include:: snippets/GradientNormTolerance.rst
.. ------------------------------------ ..
.. include:: snippets/Header2Algo03AdOp.rst
-.. include:: snippets/EstimationOf.rst
+.. include:: snippets/EstimationOf_State.rst
.. include:: snippets/InflationFactor.rst
:align: center
:width: 100%
.. centered::
- **Schéma temporel des étapes en assimilation par filtre de Kalman étendu**
+ **Schéma temporel des étapes en assimilation de données par filtre de Kalman étendu**
On remarque qu'il n'y a pas d'analyse effectuée au pas de temps initial
(numéroté 0 dans l'indexage temporel) car il n'y a pas de prévision à cet
.. include:: snippets/ConstrainedBy.rst
-.. include:: snippets/EstimationOf.rst
+.. include:: snippets/EstimationOf_State.rst
StoreSupplementaryCalculations
.. index:: single: StoreSupplementaryCalculations
:align: center
:width: 100%
.. centered::
- **Schéma temporel des étapes en assimilation par filtre de Kalman**
+ **Schéma temporel des étapes en assimilation de données par filtre de Kalman**
On remarque qu'il n'y a pas d'analyse effectuée au pas de temps initial
(numéroté 0 dans l'indexage temporel) car il n'y a pas de prévision à cet
.. ------------------------------------ ..
.. include:: snippets/Header2Algo03AdOp.rst
-.. include:: snippets/EstimationOf.rst
+.. include:: snippets/EstimationOf_State.rst
StoreSupplementaryCalculations
.. index:: single: StoreSupplementaryCalculations
.. include:: snippets/ConstrainedBy.rst
-.. include:: snippets/EstimationOf.rst
+.. include:: snippets/EstimationOf_State.rst
.. include:: snippets/AlphaBeta.rst
sont nécessaires car la troisième est incluse dans la seconde. Dans le cas de
l'interface graphique EFICAS d'ADAO, ces méthodes sont choisies dans le champ
"*FROM*" de chaque opérateur ayant une valeur "*Function*" comme
-"*INPUT_TYPE*", comme le montre la figure suivante:
+"*INPUT_TYPE*", comme le montre la figure suivante :
.. eficas_operator_function:
.. image:: images/eficas_operator_function.png
.. centered::
**Choisir graphiquement une représentation fonctionnelle de l'opérateur**
+En interface textuelle d'ADAO (TUI), dans le cas précis illustré ci-dessus, on
+réalise la même démarche en écrivant :
+::
+
+ ...
+ case.set( 'ObservationOperator',
+ OneFunction = True,
+ Script = 'scripts_for_JDC.py'
+ )
+ ...
+
.. _section_ref_operator_one:
Première forme fonctionnelle : un seul opérateur direct
+++ /dev/null
-.. index:: single: EstimationOf
-
-EstimationOf
- *Nom prédéfini*. Cette clé permet de choisir le type d'estimation à réaliser.
- Cela peut être soit une estimation de l'état, avec la valeur "State", ou une
- estimation de paramètres, avec la valeur "Parameters". Le choix par défaut
- est "State".
-
- Exemple :
- ``{"EstimationOf":"Parameters"}``
--- /dev/null
+.. index:: single: EstimationOf
+
+EstimationOf
+ *Nom prédéfini*. Cette clé permet de choisir le type d'estimation à réaliser.
+ Cela peut être soit une estimation de l'état, avec la valeur "State", ou une
+ estimation de paramètres, avec la valeur "Parameters". Le choix par défaut
+ est "Parameters".
+
+ Exemple :
+ ``{"EstimationOf":"Parameters"}``
--- /dev/null
+.. index:: single: EstimationOf
+
+EstimationOf
+ *Nom prédéfini*. Cette clé permet de choisir le type d'estimation à réaliser.
+ Cela peut être soit une estimation de l'état, avec la valeur "State", ou une
+ estimation de paramètres, avec la valeur "Parameters". Le choix par défaut
+ est "State".
+
+ Exemple :
+ ``{"EstimationOf":"State"}``
.. index:: single: état vrai
.. index:: single: observation
.. index:: single: a priori
+.. index:: single: EstimationOf
**L'assimilation de données** est un cadre général bien établi pour le calcul de
l'estimation optimale de l'état réel d'un système, au cours du temps si
utilisées sans les concepts d'assimilation de données.
Deux types principaux d'applications existent en assimilation de données, qui
-sont couverts par le même formalisme : la **reconstruction de champs** et
-**l'identification de paramètres**. On parle aussi respectivement
-**d'estimation d'états** et **d'estimation de paramètres**. Avant d'introduire
-la `Description simple du cadre méthodologique de l'assimilation de données`_
-dans une prochaine section, on décrit brièvement ces deux types d'applications.
-A la fin de ce chapitre, quelques références permettent d'`Approfondir le cadre
-méthodologique de l'assimilation de données`_ et d'`Approfondir l'estimation
-d'état par des méthodes d'optimisation`_.
+sont couverts par le même formalisme : la **reconstruction de champs** (voir
+`Reconstruction de champs ou interpolation de données`_) et **l'identification
+de paramètres** (voir `Identification de paramètres, ajustement de modèles, ou
+calage`_). On parle aussi respectivement **d'estimation d'état** et
+**d'estimation de paramètres**, et l'on peut aussi estimer les deux de manière
+conjointe si nécessaire (voir `Estimation conjointe d'états et de
+paramètres`_). Dans ADAO, certains algorithmes peuvent être utilisés soit en
+estimation d'état, soit en estimation de paramètres. Cela se fait simplement en
+changeant l'option requise "*EstimationOf*" dans les paramètres des
+algorithmes. Avant d'introduire la `Description simple du cadre méthodologique
+de l'assimilation de données`_ dans une prochaine section, on décrit brièvement
+ces deux types d'applications. A la fin de ce chapitre, quelques informations
+permettent d'aller plus loin pour `Approfondir le cadre méthodologique de
+l'assimilation de données`_ et `Approfondir l'estimation d'état par des
+méthodes d'optimisation`_, ainsi que pour `Approfondir l'assimilation de
+données pour la dynamique`_ et avoir un `Aperçu des méthodes de réduction et de
+l'optimisation réduite`_.
Reconstruction de champs ou interpolation de données
----------------------------------------------------
.. index:: single: interpolation de données
.. index:: single: interpolation de champs
.. index:: single: estimation d'état
+.. index:: single: ébauche
La **reconstruction (ou l'interpolation) de champs** consiste à trouver, à
partir d'un nombre restreint de mesures réelles, le (ou les) champ(s)
de l'espace, de manière "cohérente" avec les équations d'évolution et avec les
mesures aux précédents pas de temps.
-Identification de paramètres, ajustement de modèles, calage
------------------------------------------------------------
+Identification de paramètres, ajustement de modèles, ou calage
+--------------------------------------------------------------
.. index:: single: identification de paramètres
.. index:: single: ajustement de paramètres
Estimation conjointe d'états et de paramètres
---------------------------------------------
+.. index:: single: jointe (estimation d'états et de paramètres)
.. index:: single: estimation conjointe d'états et de paramètres
Il parfois nécessaire, en considérant les deux types d'applications
mentionner la démarche conceptuellement très simple consistant à considérer le
vecteur des états à interpoler comme *augmenté* par le vecteur des paramètres à
caler. On note que l'on est globalement en *estimation d'état* ou
-*reconstruction de champs*, et que dans le cas temporel, l'évolution des
-paramètres à estimer est simplement l'identité. Les algorithmes d'assimilation
-ou d'optimisation peuvent ensuite être appliqués au vecteur augmenté. Valable
-dans le cas de non-linéarités modérées dans la simulation, cette méthode simple
-étend l'espace d'optimisation, et conduit donc à des problèmes plus gros, mais
-il est souvent possible de réduire la représentation pour revenir à des cas
-numériquement calculables. Sans exhaustivité, l'optimisation à variables
-séparées, le filtrage de rang réduit, ou le traitement spécifique des matrices
-de covariances, sont des techniques courantes pour éviter ce problème de
-dimension.
+*reconstruction de champs*, et que dans le cas temporel de l'identification de
+paramètres, l'évolution des paramètres à estimer est simplement l'identité. Les
+algorithmes d'assimilation ou d'optimisation peuvent ensuite être appliqués au
+vecteur augmenté. Valable dans le cas de non-linéarités modérées dans la
+simulation, cette méthode simple étend l'espace d'optimisation, et conduit donc
+à des problèmes plus gros, mais il est souvent possible de réduire la
+représentation pour revenir à des cas numériquement calculables. Sans
+exhaustivité, l'optimisation à variables séparées, le filtrage de rang réduit,
+ou le traitement spécifique des matrices de covariances, sont des techniques
+courantes pour éviter ce problème de dimension. Dans le cas temporel, on verra
+ci-après des indications pour une `Estimation conjointe d'état et de paramètres
+en dynamique`_.
Pour aller plus loin, on se référera aux méthodes mathématiques d'optimisation
et d'augmentation développées dans de nombreux ouvrages ou articles
et de "*Filtre de Kalman (KF)*" et leurs dérivés. Elles doivent alors prendre
en compte un opérateur d'évolution pour établir aux bons pas de temps une
analyse de l'écart entre les observations et les simulations et pour avoir, à
-chaque instant, la propagation de l'ébauche à travers le modèle d'évolution. De
-la même manière, ces méthodes peuvent aussi être utilisées dans le cas
-d'opérateurs d'observation ou d'évolution non linéaires. Un grand nombre de
-variantes ont été développées pour accroître la qualité numérique des méthodes
-ou pour prendre en compte des contraintes informatiques comme la taille ou la
-durée des calculs.
+chaque instant, la propagation de l'ébauche à travers le modèle d'évolution. On
+se reportera à la section suivante pour `Approfondir l'assimilation de données
+pour la dynamique`_. De la même manière, ces méthodes peuvent aussi être
+utilisées dans le cas d'opérateurs d'observation ou d'évolution non linéaires.
+Un grand nombre de variantes ont été développées pour accroître la qualité
+numérique des méthodes ou pour prendre en compte des contraintes informatiques
+comme la taille ou la durée des calculs.
Une vue schématique des approches d'Assimilation de Données et d'Optimisation
-----------------------------------------------------------------------------
Le lecteur intéressé par le sujet de l'optimisation pourra utilement commencer
sa recherche grâce au point d'entrée [WikipediaMO]_.
-Méthodes de réduction et optimisation réduite
----------------------------------------------
+Approfondir l'assimilation de données pour la dynamique
+-------------------------------------------------------
+
+.. index:: single: dynamique (système)
+.. index:: single: système dynamique
+.. index:: single: évolution temporelle
+.. index:: single: EDO (Équation Différentielle Ordinaire)
+.. index:: single: ODE (Ordinary Differential Equation)
+.. index:: single: EstimationOf
+
+On peut analyser un système en évolution temporelle (dynamique) à l'aide de
+l'assimilation de données, pour tenir compte explicitement de l'écoulement du
+temps dans l'estimation d'état ou de paramètres. On introduit ici brièvement la
+problématique, et certains outils théoriques ou pratiques, pour faciliter le
+traitement utilisateur de telles situations. On indique néanmoins que la
+variété des problématiques physiques et utilisateur est grande, et qu'il est
+donc recommandé d'adapter le traitement aux contraintes, qu'elles soient
+physiques, numériques ou informatiques.
+
+Forme générale de systèmes dynamiques
++++++++++++++++++++++++++++++++++++++
+
+Les systèmes en évolution temporelle peuvent être étudiés ou représentés à
+l'aide de systèmes dynamiques. Dans ce cas, il est aisé de concevoir l'analyse
+de leur comportement à l'aide de l'assimilation de données (c'est même dans ce
+cas précis que la démarche d'assimilation de données a initialement été
+largement développée).
+
+On formalise de manière simple le cadre de simulation numérique. Un système
+dynamique simple sur l'état :math:`\mathbf{x}` peut être décrit sous la forme :
+
+.. math:: \forall t \in \mathbb{R}^{+}, \frac{d\mathbf{x}}{dt} = \mathcal{D}(\mathbf{x},\mathbf{u},t)
+
+où :math:`\mathbf{x}` est le vecteur d'état inconnu, :math:`\mathbf{u}` est un
+vecteur de contrôle externe connu, et :math:`\mathcal{D}` l'opérateur
+(éventuellement non linéaire) de la dynamique du système. C'est une Équation
+Différentielle Ordinaire (EDO, ou ODE en anglais), du premier ordre, sur
+l'état. En temps discret, ce système dynamique peut être écrit sous la forme
+suivante :
+
+.. math:: \forall n \in \mathbb{N}, \mathbf{x}_{n+1} = M(\mathbf{x}_{n},\mathbf{u}_{n},t_n\rightarrow t_{n+1})
+
+pour une indexation :math:`t_n` des temps discrets avec :math:`n\in\mathbb{N}`.
+:math:`M` est l'opérateur d'évolution discret issu de :math:`\mathcal{D}`.
+Usuellement, on omet la notation du temps dans l'opérateur d'évolution
+:math:`M`. L'approximation de l'opérateur :math:`\mathcal{D}` par :math:`M`
+introduit (ou ajoute, si elle existe déjà) une erreur de modèle
+:math:`\epsilon`.
+
+On peut alors caractériser deux types d'estimations en dynamique, que l'on
+décrit ci-après sur le système dynamique en temps discret : `Estimation d'état
+en dynamique`_ et `Estimation de paramètres en dynamique`_. Combinés, les deux
+types peuvent permettre de faire une `Estimation conjointe d'état et de
+paramètres en dynamique`_. Dans ADAO, certains algorithmes peuvent être
+utilisés soit en estimation d'état, soit en estimation de paramètres. Cela se
+fait simplement en changeant l'option requise "*EstimationOf*" dans les
+paramètres des algorithmes.
+
+Estimation d'état en dynamique
+++++++++++++++++++++++++++++++
+
+L'estimation d'état peut être conduite par assimilation de données sur la
+version en temps discret du système dynamique, écrit sous la forme suivante :
+
+.. math:: \mathbf{x}_{n+1} = M(\mathbf{x}_{n},\mathbf{u}_{n}) + \mathbf{\epsilon}_{n}
+
+.. math:: \mathbf{y}_{n} = H(\mathbf{x}_{n}) + \mathbf{\nu}_{n}
+
+où :math:`\mathbf{x}` est l'état à estimer du système, :math:`\mathbf{x}_{n}`
+et :math:`\mathbf{y}_{n}` sont respectivement l'état (calculé) non observé et
+(mesuré) observé du système, :math:`M` et :math:`H` sont respectivement les
+opérateurs d'évolution incrémentale et d'observation,
+:math:`\mathbf{\epsilon}_{n}` et :math:`\mathbf{\nu}_{n}` sont respectivement
+les bruits ou erreurs d'évolution et d'observation, et :math:`\mathbf{u}_{n}`
+est un contrôle externe connu. Les deux opérateurs :math:`M` et :math:`H` sont
+directement utilisables en assimilation de données avec ADAO.
+
+Estimation de paramètres en dynamique
++++++++++++++++++++++++++++++++++++++
+
+L'estimation de paramètres s'écrit un peu différemment pour être conduite par
+assimilation de données. Toujours sur la version en temps discret du système
+dynamique, on recherche une correspondance :math:`G` ("mapping") non-linéaire,
+paramétrée par :math:`\mathbf{a}`, entre des entrées :math:`\mathbf{x}_{n}` et
+des mesures :math:`\mathbf{y}_{n}` à chaque pas :math:`t_n`, l'erreur à
+contrôler en fonction des paramètres :math:`\mathbf{a}` étant
+:math:`\mathbf{y}_{n}-G(\mathbf{x}_{n},\mathbf{a})`. On peut procéder par
+optimisation sur cette erreur, avec régularisation, ou par filtrage en écrivant
+le problème représenté en estimation d'état :
+
+.. math:: \mathbf{a}_{n+1} = \mathbf{a}_{n} + \mathbf{\epsilon}_{n}
+
+.. math:: \mathbf{y}_{n} = G(\mathbf{x}_{n},\mathbf{a}_{n}) + \mathbf{\nu}_{n}
+
+où, cette fois, les choix des modèles d'erreurs d'évolution et d'observation
+:math:`\mathbf{\epsilon}_{n}` et :math:`\mathbf{\nu}_{n}` conditionnent la
+performance de la convergence et du suivi des observations. L'estimation des
+paramètres :math:`\mathbf{a}` se fait par utilisation de paires
+:math:`(\mathbf{x}_{n},\mathbf{y}_{n})` d'entrées et de sorties
+correspondantes.
+
+Dans ce cas de l'estimation de paramètres, pour appliquer les méthodes
+d'assimilation de données, on impose donc l'hypothèse que l'opérateur
+d'évolution est l'identité (*Remarque : il n'est donc pas utilisé, mais doit
+être déclaré dans ADAO, par exemple en matrice à 1*), et l'opérateur
+d'observation est :math:`G`.
+
+Estimation conjointe d'état et de paramètres en dynamique
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Un cas spécial concerne l'estimation conjointe d'état et de paramètres utilisés
+dans un système dynamique. On cherche à estimer conjointement l'état
+:math:`\mathbf{x}` (qui dépend du temps) et les paramètres :math:`\mathbf{a}`
+(qui ne dépendent pas du temps). Il existe plusieurs manières de traiter ce
+problème, mais la plus générale consiste à utiliser un vecteur d'état augmenté
+par les paramètres, et à étendre les opérateurs en conséquence.
+
+Pour cela, en utilisant les notations des deux sous-sections précédentes, on
+définit la variable auxiliaire :math:`\mathbf{w}` telle que :
+
+.. math:: \mathbf{w} = \left[
+ \begin{array}{c}
+ \mathbf{x} \\
+ \mathbf{a}
+ \end{array}
+ \right]
+ = \left[
+ \begin{array}{c}
+ \mathbf{w}_{|x} \\
+ \mathbf{w}_{|a}
+ \end{array}
+ \right]
+
+et les opérateurs d'évolution :math:`\tilde{M}` et d'observation
+:math:`\tilde{H}` associés au problème augmenté :
+
+.. math:: \tilde{M}(\mathbf{w},\mathbf{u}) = \left[
+ \begin{array}{c}
+ M(\mathbf{w}_{|x},\mathbf{u}) \\
+ \mathbf{w}_{|a}
+ \end{array}
+ \right]
+ = \left[
+ \begin{array}{c}
+ M(\mathbf{x},\mathbf{u}) \\
+ \mathbf{a}
+ \end{array}
+ \right]
+
+.. math:: \tilde{H}(\mathbf{w}) = \left[
+ \begin{array}{c}
+ H(\mathbf{w}_{|x}) \\
+ G(\mathbf{w}_{|x},\mathbf{w}_{|a})
+ \end{array}
+ \right]
+ = \left[
+ \begin{array}{c}
+ H(\mathbf{x}) \\
+ G(\mathbf{x},\mathbf{a})
+ \end{array}
+ \right]
+
+Avec ces notations, en étendant les variables de bruit
+:math:`\mathbf{\epsilon}` et :math:`\mathbf{\nu}` de manière adéquate, le
+problème d'estimation conjointe en temps discret d'état :math:`\mathbf{x}` et
+de paramètres :math:`\mathbf{a}`, à travers la variable conjointe
+:math:`\mathbf{w}`, s'écrit alors :
+
+.. math:: \mathbf{w}_{n+1} = \tilde{M}(\mathbf{w}_{n},\mathbf{u}_{n}) + \mathbf{\epsilon}_{n}
+
+.. math:: \mathbf{y}_{n} = \tilde{H}(\mathbf{w}_{n}) + \mathbf{\nu}_{n}
+
+Les opérateurs d'évolution incrémentale et d'observation sont donc
+respectivement les opérateurs augmentés :math:`\tilde{M}` et :math:`\tilde{H}`,
+et sont directement utilisables en assimilation de données avec ADAO.
+
+Schéma conceptuel pour l'assimilation de données en dynamique
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Pour compléter la description, on peut représenter la démarche d'assimilation
+de données de manière spécifiquement dynamique à l'aide d'un schéma temporel,
+qui décrit l'action des opérateurs d'évolution (:math:`M` ou :math:`\tilde{M}`)
+et d'observation (:math:`H` ou :math:`\tilde{H}`) lors de la simulation
+discrète. Une représentation possible est la suivante :
+
+ .. _schema_d_AD_temporel:
+ .. image:: images/schema_temporel_KF.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Schéma d'action des opérateurs pour l'assimilation de données en dynamique**
+
+Les concepts décrits dans ce schéma peuvent directement et simplement être
+utilisés dans ADAO.
+
+Aperçu des méthodes de réduction et de l'optimisation réduite
+-------------------------------------------------------------
.. index:: single: réduction
.. index:: single: méthodes de réduction
**[DocR]** Interface textuelle pour l'utilisateur (TUI/API)
================================================================================
+.. |eficas_totui| image:: images/eficas_totui.png
+ :align: middle
+ :scale: 50%
+
Cette section présente des méthodes avancées d'usage du module ADAO à l'aide de
son interface de programmation textuelle (API/TUI). Cette interface permet de
créer un objet de calcul de manière similaire à la construction d'un cas par
-l'interface graphique (GUI). Dans le cas où l'on désire réaliser à la main le
-cas de calcul TUI, on recommande de bien s'appuyer sur l'ensemble de la
-documentation du module ADAO, et de se reporter si nécessaire à l'interface
-graphique (GUI), pour disposer de l'ensemble des éléments permettant de
-renseigner correctement les commandes. Les notions générales et termes utilisés
-ici sont définis dans :ref:`section_theory`. Comme dans l'interface graphique,
-on note que la démarche en TUI est destinée à créer et gérer un unique cas de
-calcul.
+l'interface graphique (GUI). On peut d'ailleurs directement obtenir une forme
+scriptée d'un cas construit dans l'interface graphique GUI à l'aide du bouton
+d'export TUI |eficas_totui| intégré dans l'interface, mais des cas plus
+compliqués ou plus intégrés peuvent uniquement être construits avec la démarche
+TUI. Dans le cas où l'on désire réaliser à la main le cas de calcul TUI, on
+recommande de bien s'appuyer sur l'ensemble de la documentation du module ADAO,
+et de se reporter si nécessaire à l'interface graphique (GUI), pour disposer de
+l'ensemble des éléments permettant de renseigner correctement les commandes.
+Les notions générales et termes utilisés ici sont définis dans
+:ref:`section_theory`. Comme dans l'interface graphique, on note que la
+démarche en TUI est destinée à créer et gérer un unique cas de calcul.
.. _subsection_tui_creating:
**[DocU]** Tutoriaux sur l'utilisation du module ADAO dans Python
================================================================================
+.. |eficas_totui| image:: images/eficas_totui.png
+ :align: middle
+ :scale: 50%
+
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 à
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`.
+traiter dans l'interface graphique SALOME. On peut d'ailleurs directement
+obtenir une forme scriptée d'un cas construit dans l'interface graphique à
+l'aide du bouton d'export TUI |eficas_totui| intégré dans l'interface. Les
+notations mathématiques utilisées ci-dessous sont expliquées dans la section
+:ref:`section_theory`.
+
+D'autres exemples simples, et leurs illustrations, sont insérés à la fin de la
+documentation de référence de certains algorithmes. C'est le cas, de manière
+non limitative, des :ref:`section_ref_algorithm_3DVAR`,
+:ref:`section_ref_algorithm_KalmanFilter` et
+:ref:`section_ref_algorithm_ExtendedBlue`.
.. _section_tutorials_in_python_explicit:
.. |eficas_new| image:: images/eficas_new.png
:align: middle
- :scale: 50%
+ :scale: 75%
.. |eficas_save| image:: images/eficas_save.png
:align: middle
- :scale: 50%
+ :scale: 75%
.. |eficas_saveas| image:: images/eficas_saveas.png
+ :align: middle
+ :scale: 75%
+.. |eficas_totui| image:: images/eficas_totui.png
:align: middle
:scale: 50%
.. |eficas_yacs| image:: images/eficas_yacs.png
:align: middle
- :scale: 50%
+ :scale: 75%
Cette section présente quelques exemples d'utilisation du module ADAO dans
SALOME. Le premier montre comment construire un cas très simple d'assimilation
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é
+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 :
::
**Activation du module ADAO dans SALOME**
Choisir le bouton "*Nouveau*" dans cette fenêtre. On obtient directement
-l'interface de l'éditeur intégré de cas pour la définition de variables, en même
-temps que l'"*Arbre d'étude*" de SALOME. On peut alors choisir le bouton
+l'interface de l'éditeur intégré de cas pour la définition de variables, en
+même temps que l'"*Arbre d'étude*" de SALOME. On peut alors choisir le bouton
"*Nouveau*" |eficas_new| pour créer un nouveau cas ADAO, et on voit :
.. _adao_viewer:
.. centered::
**Définition des conditions d'expérience choisies pour le cas ADAO**
-Pour poursuivre, on a besoin de générer le schéma YACS à partir de la définition
-du cas ADAO. Pour faire cela, on peut activer le menu contextuel par click droit
-sur le nom du cas dans la fenêtre de l'"*Arbre d'étude*", et choisir le
-sous-menu "*Exporter vers YACS*" (ou le bouton "*Exporter vers YACS*"
-|eficas_yacs|) comme ci-dessous :
+Pour poursuivre, on a besoin de générer le schéma YACS à partir de la
+définition du cas ADAO. Pour faire cela, on peut activer le menu contextuel par
+click droit sur le nom du cas dans la fenêtre de l'"*Arbre d'étude*", et
+choisir le sous-menu "*Exporter vers YACS*" (ou le bouton "*Exporter vers
+YACS*" |eficas_yacs|) comme ci-dessous :
.. _adao_exporttoyacs00:
.. image:: images/adao_exporttoyacs.png
.. centered::
**Sous-menu contextuel "*Exporter vers YACS*" pour générer le schéma YACS à partir du cas ADAO**
-Cette commande conduit à la génération d'un schéma YACS, à l'activation du module
-YACS dans SALOME, et à ouvrir le nouveau schéma dans l'interface graphique du
-module YACS [#]_. Après avoir éventuellement réorganisé les noeuds en utilisant
-le sous-menu contextuel "*arranger les noeuds locaux*" de la vue graphique du
-schéma YACS, on obtient la représentation suivante du schéma ADAO généré :
+Cette commande conduit à la génération d'un schéma YACS, à l'activation du
+module YACS dans SALOME, et à ouvrir le nouveau schéma dans l'interface
+graphique du module YACS [#]_. Après avoir éventuellement réorganisé les noeuds
+en utilisant le sous-menu contextuel "*arranger les noeuds locaux*" de la vue
+graphique du schéma YACS, on obtient la représentation suivante du schéma ADAO
+généré :
.. _yacs_generatedscheme:
.. image:: images/yacs_generatedscheme.png
"*Noeud de script in-line*" dans la vue graphique de YACS).
Ce noeud de script va récupérer l'analyse issue de l'assimilation de données
-depuis le port de sortie "*algoResults*" du bloc de calcul (qui donne accés à un
-objet Python SALOME), et va l'afficher à la sortie standard.
+depuis le port de sortie "*algoResults*" du bloc de calcul (qui donne accés à
+un objet Python SALOME), et va l'afficher à la sortie standard.
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
print("Analysis =",Xa)
print()
-Le schéma YACS (initial ou complété) peut être enregistré (en écrasant le schéma
-généré si la commande ou le bouton "*Enregistrer*" sont utilisés, ou sinon avec
-un nom nouveau par la commande "*Enregistrer sous*"). De manière pratique, la
-mise au point d'une telle procédure de post-processing peut être réalisée dans
-YACS pour la tester, et ensuite entièrement enregistrée dans un script Python
-qui peut être intégré au cas ADAO en utilisant le mot-clé "*UserPostAnalysis*".
+Le schéma YACS (initial ou complété) peut être enregistré (en écrasant le
+schéma généré si la commande ou le bouton "*Enregistrer*" sont utilisés, ou
+sinon avec un nom nouveau par la commande "*Enregistrer sous*"). De manière
+pratique, la mise au point d'une telle procédure de post-processing peut être
+réalisée dans YACS pour la tester, et ensuite entièrement enregistrée dans un
+script Python qui peut être intégré au cas ADAO en utilisant le mot-clé
+"*UserPostAnalysis*".
Ensuite, de manière classique dans YACS, le schéma doit être compilé, et être
exécuté. Après la fin de l'exécution, les affichages sur la sortie standard
sont disponibles dans la fenêtre "*fenêtre de sortie de YACS*" (ou "*YACS
Container Log*"), obtenue par clic droit à l'aide du menu contextuel de la
-fenêtre "*proc*" du schéma YACS comme montré ci-dessous:
+fenêtre "*proc*" du schéma YACS comme montré ci-dessous :
.. _yacs_containerlog:
.. image:: images/yacs_containerlog.png
comme montré dans l'image précédente.
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, avant d'entrer dans l'étape YACS. Le cas
-ADAO en 3DVAR est entièrement similaire au cas algorithmique du BLUE, comme
-montré dans la figure suivante:
+algorithme de 3DVAR donne le même résultat. Cet algorithme peut être choisi
+lors de l'étape de construction du cas ADAO, avant d'entrer dans l'étape YACS.
+Le cas ADAO en 3DVAR est entièrement similaire au cas algorithmique du BLUE,
+comme montré dans la figure suivante :
.. _adao_jdcexample02:
.. image:: images/adao_jdcexample02.png
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 graphique ADAO et une définition implicite dans des fichiers
-externes. Le fichier script actuel ressemble à :
+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 à :
::
import numpy
fait que, au lieu de choisir l'option "*String*" pour le mot-clé "*FROM*" de
chaque variable, on choisit l'option "*Script*". Cela conduit à une entrée
"*SCRIPT_DATA/SCRIPT_FILE*" dans l'arbre graphique, permettant de choisir un
-fichier de la manière suivante:
+fichier de la manière suivante :
.. _adao_scriptentry01:
.. image:: images/adao_scriptentry01.png
données`_.
Dans la pratique, cette démarche par scripts est la manière la plus facile pour
-récupérer des informations depuis des calculs en ligne ou préalables, depuis des
-fichiers statiques, depuis des bases de données ou des flux informatiques,
+récupérer des informations 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
La liste des paramètres optionnels possibles est donnée dans la section
:ref:`section_reference` et ses sous-sections. On recommande d'utiliser la
définition explicite de valeurs à partir de la liste par défaut de paramètres
-optionnels, comme ici avec le "*MaximumNumberOfSteps*":
+optionnels, comme ici avec le "*MaximumNumberOfSteps*" :
.. _adao_scriptentry02:
.. image:: images/adao_scriptentry02.png
Conditions d'expérience
+++++++++++++++++++++++
-On continue à opérer dans un espace à 3 dimensions, afin de limiter la taille de
-l'objet numérique indiqué dans les scripts, mais le problème ne dépend pas de la
-dimension.
+On continue à opérer dans un espace à 3 dimensions, afin de limiter la taille
+de l'objet numérique indiqué dans les scripts, mais le problème ne dépend pas
+de la dimension.
On choisit un contexte d'expériences jumelles (voir la démarche
:ref:`section_methodology_twin`), en utilisant un état vrai
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 :
+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 :
::
B = 0.1 * diagonal( length(Xb) )
On suppose qu'il existe un opérateur d'observation :math:`\mathbf{H}`, qui peut
-être non linéaire. Dans une procédure réelle de recalage ou de problème inverse,
-les codes de simulation physique sont intégrés dans l'opérateur d'observation.
-On a également besoin de connaître son gradient par rapport à chaque variable
-estimée, ce qui est une information rarement connue avec les codes industriels.
-Mais on verra plus tard comment obtenir un gradient approché dans ce cas.
+être non linéaire. Dans une procédure réelle de recalage ou de problème
+inverse, les codes de simulation physique sont intégrés dans l'opérateur
+d'observation. On a également besoin de connaître son gradient par rapport à
+chaque variable estimée, ce qui est une information rarement connue avec les
+codes industriels. Mais on verra plus tard comment obtenir un gradient approché
+dans ce cas.
É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
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é
+: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`` :
::
dans les :ref:`section_ref_operator_requirements`.
On insiste sur le fait que ces opérateurs non-linéaire ``"DirectOperator"``,
-linéaire tangent ``"TangentOperator"`` et linéaire adjoint ``"AdjointOperator"``
-proviennent de la connaissance de la physique, incluant le code de simulation de
-référence physique, et doivent être soigneusement mis au point par l'utilisateur
-de l'assimilation de données ou de l'optimisation. Les erreurs de simulation ou
-d'usage des opérateurs ne peuvent pas être détectés ou corrigés par
-l'environnement seul ADAO d'assimilation de données et d'optimisation.
+linéaire tangent ``"TangentOperator"`` et linéaire adjoint
+``"AdjointOperator"`` proviennent de la connaissance de la physique, incluant
+le code de simulation de référence physique, et doivent être soigneusement mis
+au point par l'utilisateur de l'assimilation de données ou de l'optimisation.
+Les erreurs de simulation ou d'usage des opérateurs ne peuvent pas être
+détectés ou corrigés par l'environnement seul ADAO d'assimilation de données et
+d'optimisation.
Dans cet environnement d'expériences jumelles, l'observation
:math:`\mathbf{y}^o` et sa matrice des covariances d'erreur :math:`\mathbf{R}`
print()
Finalement, on obtient la description de l'ensemble des conditions
-d'expériences à travers la série de fichiers listée ici:
+d'expériences à travers la série de fichiers listée ici :
#. ``Physical_data_and_covariance_matrices.py``
#. ``Physical_simulation_functions.py``
On insiste ici sur le fait que tous ces scripts sont écrits par l'utilisateur et
ne peuvent être testés automatiquement par ADAO. Ainsi, l'utilisateur est tenu
de vérifier les scripts (et en particulier leurs entrées/sorties) afin de
-limiter les difficultés de débogage. On rappelle que: **la méthodologie par
+limiter les difficultés de débogage. On rappelle que : **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.**
for level in reversed(inspect.stack()):
__names += [name for name, value in level.frame.f_locals.items() if value is self]
__names += [name for name, value in globals().items() if value is self]
- __names.remove('self') # Devrait toujours être trouvé, donc pas d'erreur
+ while 'self' in __names: __names.remove('self') # Devrait toujours être trouvé, donc pas d'erreur
if len(__names) > 0:
- logging.debug("Cet objet est appelé par au moins une variable :",__names)
self.__objname = __names[0]
else:
self.__objname = "ADD"
