About
-----
-**The ADAO module provides data assimilation and optimization**
-features in Python or SALOME context (see
-http://www.salome-platform.org/). Briefly stated, Data Assimilation is
-a methodological framework to compute the optimal estimate of the
-inaccessible true value of a system state, eventually 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*, etc. More details can be found in the full
-ADAO documentation (see https://www.salome-platform.org/).
+**The ADAO module provides data assimilation and optimization** features in
+Python or SALOME context (see http://www.salome-platform.org/). Briefly stated,
+Data Assimilation is a methodological framework to compute the optimal estimate
+of the inaccessible true value of a system state, eventually 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 *calibration*, *adjustment*,
+*state estimation*, *parameter estimation*, *parameter adjustment*, *inverse
+problems*, *Bayesian estimation*, *optimal interpolation*, *mathematical
+regularization*, *meta-heuristics for optimization*, *model reduction*, *data
+smoothing*, etc. More details can be found in the full ADAO documentation (see
+https://www.salome-platform.org/).
Only the use of ADAO text programming interface (API/TUI) is introduced
here. This interface gives ability to create a calculation object in a
--- /dev/null
+..
+ Copyright (C) 2008-2021 EDF R&D
+
+ This file is part of SALOME ADAO module.
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+ See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
+
+ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
+
+.. _section_ref_observations_requirements:
+
+Requirements for observation or experimental measurements description
+---------------------------------------------------------------------
+
+.. index:: single: setObservation
+.. index:: single: setObservationError
+
+The whole set of measurements of the physical system we are considering are
+called "*observations*", or even simply "*an observation*". As already
+mentioned in :ref:`section_theory`, this observation is noted in the most
+generic way by:
+
+.. math:: \mathbf{y}^o
+
+It can depend in general of the space and the time, and even of parametric
+variables, and this in a more or less complex way. We usually particularize the
+time dependence by considering that, at each instant, the quantity
+:math:`\mathbf{y}^o` is a vector of :math:`\mbox{I\hspace{-.15em}R}^d` (with
+the dimension :math:`d` of the space being able to possibly vary in time). In
+other words, **an observation is a (temporal) series of (varied)
+measurements**. One will thus speak in an equivalent way of an observation
+(vector), of a series or a vector of observations, and of a set of
+observations. In its greatest generality, the sequential aspect of the series
+of observations is related jointly to space, and/or to time, and/or to a
+parametric dependence.
+
+We can classify the ways of representing the observation according to the uses
+that we have afterwards and the links with the algorithmic methods. The
+classification that we propose is the following, each category being detailed
+below:
+
+#. `Use of a single spatial observation`_
+#. `Use of a time series of spatial observations`_
+#. `Use of a single spatio-temporal observation`_
+#. `Use of a parameterized series of spatial observations`_
+
+The numerical representations of the observations use all the possibilities
+described in the :ref:`section_ref_entry_types`. We specialize their uses here
+to indicate different possible ways of writing this information.
+
+Use of a single spatial observation
++++++++++++++++++++++++++++++++++++
+
+.. index:: single: Vector
+.. index:: single: DataFile
+
+This refers to the use of a vector series dependent only on space. This
+observation is moreover used at once, i.e. being completely known at the
+beginning of the algorithmic analysis. This can for example be a spatial field
+of measurements, or several fields physically homogeneous or not.
+
+- The mathematical representation is :math:`\mathbf{y}^o\,\in\,\mbox{I\hspace{-.15em}R}^d`.
+
+- The canonical numerical representation is **a vector**.
+
+- The numerical representation in ADAO is done with the keyword "*Vector*". All
+ the information, declared in one of the following representations, is
+ transformed into a single vector (note: lists and tuples are equivalent):
+
+ - "*numpy.array*" variable : ``numpy.array([1, 2, 3])``
+ - "*list*" variable : ``[1, 2, 3]``
+ - string variable : ``'1 2 3'``
+ - string variable : ``'1,2,3'``
+ - string variable : ``'1;2;3'``
+ - string variable : ``'[1,2,3]'``
+ - Python data file, with variable "*Observation*" in the namespace, indicated by the keyword "*Script*" with the condition ``Vector=True``
+ - data text file (TXT, CSV, TSV, DAT), with variable pointer by name in column or row, indicated by the keyword "*DataFile*" with the condition ``Vector=True``
+ - binary data file (NPY, NPZ), with variable pointer by name, indicated by the keyword "*DataFile*" with the condition ``Vector=True``
+
+- Examples of statements in TUI interface:
+
+ - ``case.setObservation( Vector = [1, 2, 3] )``
+ - ``case.setObservation( Vector = numpy.array([1, 2, 3]) )``
+ - ``case.setObservation( Vector = '1 2 3' )``
+ - ``case.setObservation( Vector=True, Script = 'script.py' )```
+ - ``case.setObservation( Vector=True, DataFile = 'data.csv' )```
+ - ``case.setObservation( Vector=True, DataFile = 'data.npy' )```
+
+Use note: in a given study, only the last record (whether a single vector or a
+series of vectors) can be used, as only one observation concept exists per CADD
+study.
+
+Use of a time series of spatial observations
+++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: VectorSerie
+.. index:: single: DataFile
+
+This refers to a vector ordered series of observations, dependent on space and
+time. At a given instant, it is assumed that only the observations of the
+current and previous instants are known. The successive observations in time
+are indexed by :math:`n`, their instant of existence or of reference. This can
+for example be a spatial field of measurements, physically homogeneous or not,
+of which we consider a history.
+
+- The mathematical representation is :math:`\forall\,n\in\{0...N\},\,\mathbf{y}^o_n\,\in\mbox{I\hspace{-.15em}R}^d`.
+
+- The canonical numerical representation is **an ordered series of vectors**.
+
+- The numerical representation in ADAO is done with the keyword
+ "*VectorSeries*". The current indexing of the information is used to
+ represent the time index when declaring in one of the following
+ representations, and the information is transformed into an ordered series of
+ vectors (note: lists and tuples are equivalent):
+
+ - "*list*" of "*numpy.array*" : ``[numpy.array([1,2,3]), numpy.array([1,2,3])]``
+ - "*numpy.array*" of "*list*" : ``numpy.array([[1,2,3], [1,2,3]])``
+ - "*list*" of "*list*" : ``[[1,2,3], [1,2,3]]``
+ - "*list*" of string variables : ``['1 2 3', '1 2 3']``
+ - "*list*" of string variables : ``['1;2;3', '1;2;3']``
+ - "*list*" of string variables : ``['[1,2,3]', '[1,2,3]']``
+ - string of "*list*" : ``'[[1,2,3], [1,2,3]]'``
+ - string of "*list*" : ``'1 2 3 ; 1 2 3'``
+ - Python data file, with variable "*Observation*" in the namespace, indicated by the keyword "*Script*" with the condition ``VectorSerie=True``
+ - data text file (TXT, CSV, TSV), with variable pointer by name in column or row, indicated by the keyword "*DataFile*" with the condition ``VectorSerie=True``
+ - binary data file (NPY, NPZ), with variable pointer by name, indicated by the keyword "*DataFile*" with the condition ``VectorSerie=True``
+
+- Examples of statements in TUI interface:
+
+ - ``case.setObservation( VectorSerie = [[1,2,3], [1,2,3]] )``
+ - ``case.setObservation( VectorSerie = [numpy.array([1,2,3]), numpy.array([1,2,3])] )``
+ - ``case.setObservation( VectorSerie = ['1 2 3', '1 2 3'] )``
+ - ``case.setObservation( VectorSerie = '[[1,2,3], [1,2,3]]' )``
+ - ``case.setObservation( VectorSerie = '1 2 3 ; 1 2 3' )``
+ - ``case.setObservation( VectorSerie=True, Script = 'script.py' )```
+ - ``case.setObservation( VectorSerie=True, DataFile = 'data.csv' )```
+ - ``case.setObservation( VectorSerie=True, DataFile = 'data.npy' )```
+
+Use note: in a given study, only the last record (whether a single vector or a
+series of vectors) can be used, as only one observation concept exists per CADD
+study.
+
+Use of a single spatio-temporal observation
++++++++++++++++++++++++++++++++++++++++++++
+
+This single spatio-temporal observation is similar to the previous one in its
+representation as a vector series, but it imposes that it must be used in a
+single run, i.e. by being fully known at the beginning of the algorithmic
+analysis. It can therefore be represented as an indexed series, in the same way
+as for a `Use of a time series of spatial observations`_.
+
+Use of a parameterized series of spatial observations
++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+One represents now a collection of observations parameterized by an index or a
+discrete parameter. This form is still similar to the previous one. It is
+therefore representable as an indexed series, in the same way as for a `Use of
+a time series of spatial observations`_.
+
+General comments on the observations
+++++++++++++++++++++++++++++++++++++
+
+.. warning::
+
+ When the assimilation explicitly establishes a **temporal iterative
+ process**, as in state data assimilation, **the first observation is not used
+ but must be present in the data description of a ADAO case**. By convention,
+ it is therefore considered to be available at the same time as the draft time
+ value, and does not lead to a correction at that time. The numbering of the
+ observations starts at 0 by convention, so it is only from number 1 that the
+ observation values are used in the temporal iterative algorithms.
+
+Observations can be provided by single time steps or by successive windows for
+iterative algorithms. In this case, a series of observations must be provided
+for each algorithmic iteration relative to a time window. In practice, for each
+window, we provide a series as in a `Use of a time series of spatial
+observations`_.
+
+The observation acquisition options are richer in the TUI textual interface, as
+not all options are necessarily available in the GUI.
+
+For data entry via files, please refer to the description of the possibilities
+around the keyword "*DataFile*" in the :ref:`section_ref_entry_types_info`.
.. _section_reference_entry:
-========================================================================================
+================================================================================
**[DocR]** General entries and outputs
-========================================================================================
+================================================================================
-This section describes in general the different possibilities of entry types and
-output variables that can be used. The mathematical notations used afterwards
-are explained in the section :ref:`section_theory`.
+This section describes in a very general way the different options of input
+types and output variables. The mathematical notations used are explained in
+section :ref:`section_theory`.
.. toctree::
:maxdepth: 1
.. _section_reference_special_entry:
-========================================================================================
-**[DocR]** Special entries: functions, matrices, "*observer*", post-processing
-========================================================================================
+============================================================================================
+**[DocR]** Special entries: measurements, functions, matrices, "*observer*", post-processing
+============================================================================================
-This section describes the special entries, as the functional or matrix forms,
-that can be used. The mathematical notations used afterwards are explained in
-the section :ref:`section_theory`.
+This section describes special inputs, such as functional or matrix forms, and
+the requirements for using them. The mathematical concepts and notations
+related to these inputs are explained in section :ref:`section_theory`.
.. toctree::
:maxdepth: 1
+ ref_observations_requirements
ref_operator_requirements
ref_covariance_requirements
ref_observers_requirements
.. _section_reference_assimilation:
-============================================================================================
+================================================================================
**[DocR]** Data assimilation or optimization calculation cases
-============================================================================================
+================================================================================
This section describes algorithmic choices to use data assimilation methods,
optimization methods or methods with reduction, available in ADAO, detailing
-their usage characteristics and their options.
+their characteristics and their options.
Some examples on these commands usage are available in the section
:ref:`section_tutorials_in_salome`, in the section
:ref:`section_tutorials_in_python` and in the sample files installed with ADAO.
-The mathematical notations used afterward are explained in the section
+The mathematical concepts and notations used are explained in the section
:ref:`section_theory`.
.. toctree::
Some examples on these commands usage are available in the section
:ref:`section_tutorials_in_salome`, in the section
:ref:`section_tutorials_in_python` and in the sample files installed with ADAO.
-The mathematical notations used afterward are explained in the section
+The mathematical concepts and notations used are explained in the section
:ref:`section_theory`.
.. toctree::
- in text format (simple text in a file with a ".txt" or ".dat" extension,
text with comma delimiter in a file with a ".csv" extension, text with
- tabulation delimiter in a file with a ".tsv" extension)
+ tabulation delimiter in a file with a ".tsv" extension), named here TXT,
+ CSV, TSV or DAT.
- in binary format (single-variable in a Numpy file with a ".npy"
- extension, multi-variables in a NumpyZ file with a ".npz" extension)
+ extension, multi-variables in a NumpyZ file with a ".npz" extension),
+ named here NPY or NPZ.
By default, the values of a variable has to be ordered in rows to be
acquired record line by record line ("ColMajor=False"), but they can also
**Vector**
*List of real values*. This indicates a variable that has to be filled as a
vector. It is a simple ordered collection of real numbers. The vectors can
- be described in row or column version without making any difference.
+ be described in row or column version without making any difference. The
+ details of the :ref:`section_ref_observations_requirements` help to
+ illustrate different possible ways of writing this entry.
**VectorSerie**
*List of list of real values*. This indicates a variable that has to be
- filled in as a list of vectors. It is an ordered collection of vectors.
+ filled in as a list of vectors. It is an ordered collection of vectors. The
+ details of the :ref:`section_ref_observations_requirements` help to
+ illustrate different possible ways of writing this entry.
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:
+in continuous time in the form:
.. math:: \forall t \in \mathbb{R}^{+}, \frac{d\mathbf{x}}{dt} = \mathcal{D}(\mathbf{x},\mathbf{u},t)
.. _section_ref_covariance_requirements:
-Exigences pour décrire les matrices de covariance
--------------------------------------------------
+Conditions requises pour décrire des matrices de covariance
+-----------------------------------------------------------
.. index:: single: setBackgroundError
.. index:: single: setObservationError
--- /dev/null
+..
+ Copyright (C) 2008-2021 EDF R&D
+
+ This file is part of SALOME ADAO module.
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+ See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
+
+ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
+
+.. _section_ref_observations_requirements:
+
+Conditions requises pour la description d'observations ou de mesures expérimentales
+-----------------------------------------------------------------------------------
+
+.. index:: single: setObservation
+.. index:: single: setObservationError
+
+L'ensemble des mesures du système physique que l'on considère sont appelées
+"*des observations*", ou même simplement "*une observation*". Comme cela a déjà
+été mentionné dans :ref:`section_theory`, cette observation est notée de
+manière la plus générique par :
+
+.. math:: \mathbf{y}^o
+
+Elle peut dépendre en général de l'espace et du temps, voire de variables
+paramétriques, et cela de manière plus ou moins complexe. On particularise
+usuellement la dépendance en temps en considérant que, à chaque instant, la
+quantité :math:`\mathbf{y}^o` est un vecteur de
+:math:`\mbox{I\hspace{-.15em}R}^d` (avec la dimension :math:`d` de l'espace
+pouvant éventuellement varier en temps). Autrement dit, **une observation est
+une série (temporelle) de mesures (variées)**. On parlera donc de manière
+équivalente d'une observation (vectorielle), d'une série ou d'un vecteur
+d'observations, et d'un ensemble d'observations. Dans sa plus grande
+généralité, l'aspect séquentiel de la série d'observations est relatif
+conjointement à l'espace, et/ou au temps, et/ou à une dépendance paramétrique.
+
+On peut classer les manières de représenter l'observation en fonction des
+usages que l'on en a ensuite et des liens avec les méthodes algorithmiques. Le
+classement que l'on propose est le suivant, dont chaque catégorie est détaillée
+ensuite :
+
+#. `Utilisation d'une unique observation spatiale`_
+#. `Utilisation d'une série temporelle d'observations spatiales`_
+#. `Utilisation d'une unique observation spatio-temporelle`_
+#. `Utilisation d'une série paramétrée d'observations spatiales`_
+
+Les représentations numériques des observations utilisent toutes les
+possibilités décrites dans la :ref:`section_ref_entry_types`. On spécialise ici
+leurs usages pour indiquer différentes manières possible d'écrire cette
+information.
+
+Utilisation d'une unique observation spatiale
++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: Vector
+.. index:: single: DataFile
+
+Cela fait référence à l'usage d'une série vectorielle dépendante uniquement de
+l'espace. Cette observation est de plus utilisée en une seule fois,
+c'est-à-dire en étant entièrement connue au début de l'analyse algorithmique.
+Cela peut par exemple être un champ spatial de mesures, ou de plusieurs champs
+physiquement homogènes ou pas.
+
+- La représentation mathématique est :math:`\mathbf{y}^o\,\in\,\mbox{I\hspace{-.15em}R}^d`.
+
+- La représentation numérique canonique est **un vecteur**.
+
+- La représentation numérique dans ADAO se fait avec le mot-clé "*Vector*". La
+ totalité de l'information, déclarée dans l'une des représentations suivantes,
+ est transformée en un unique vecteur (remarque : listes et tuples sont
+ équivalents) :
+
+ - variable "*numpy.array*" : ``numpy.array([1, 2, 3])``
+ - variable "*liste*" : ``[1, 2, 3]``
+ - chaîne de caractères : ``'1 2 3'``
+ - chaîne de caractères : ``'1,2,3'``
+ - chaîne de caractères : ``'1;2;3'``
+ - chaîne de caractères : ``'[1,2,3]'``
+ - fichier Python de données, avec variable "*Observation*" dans l'espace de nommage, indiqué par le mot-clé "*Script*" avec la condition ``Vector=True``
+ - fichier texte de données (TXT, CSV, TSV, DAT), avec pointeur de variable par nom en colonne ou en ligne, indiqué par le mot-clé "*DataFile*" avec la condition ``Vector=True``
+ - fichier binaire de données (NPY, NPZ), avec pointeur de variable par nom, indiqué par le mot-clé "*DataFile*" avec la condition ``Vector=True``
+
+- Exemples de déclaration en interface TUI :
+
+ - ``case.setObservation( Vector = [1, 2, 3] )``
+ - ``case.setObservation( Vector = numpy.array([1, 2, 3]) )``
+ - ``case.setObservation( Vector = '1 2 3' )``
+ - ``case.setObservation( Vector=True, Script = 'script.py' )```
+ - ``case.setObservation( Vector=True, DataFile = 'data.csv' )```
+ - ``case.setObservation( Vector=True, DataFile = 'data.npy' )```
+
+Remarque d'utilisation : dans une étude donnée, seul le dernier enregistrement
+(que ce soit un vecteur unique ou une série de vecteurs) est utilisable, car un
+seul concept d'observation existe par étude ADAO.
+
+Utilisation d'une série temporelle d'observations spatiales
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: VectorSerie
+.. index:: single: DataFile
+
+Cela fait référence une série ordonnée vectorielle d'observations, dépendantes
+de l'espace et du temps. A un instant donné, on suppose que l'on ne connaît que
+les observations des instants courant et précédents. Les observations
+successives en temps sont indexées par :math:`n`, leur instant d'existence ou
+de référence. Cela peut par exemple être un champs spatial de mesures,
+physiquement homogènes ou pas, dont on considère un historique.
+
+- La représentation mathématique est :math:`\forall\,n\in\{0...N\},\,\mathbf{y}^o_n\,\in\mbox{I\hspace{-.15em}R}^d`.
+
+- La représentation numérique canonique est **une série ordonnée de vecteurs**.
+
+- La représentation numérique dans ADAO se fait avec le mot-clé
+ "*VectorSerie*". L'indexation courante de l'information est utilisée pour
+ représenter l'index temporel lors de la déclaration dans l'une des
+ représentations suivantes, et l'information est transformée en une série
+ ordonnée de vecteurs (remarque : listes et tuples sont équivalents) :
+
+ - "*liste*" de "*numpy.array*" : ``[numpy.array([1,2,3]), numpy.array([1,2,3])]``
+ - "*numpy.array*" de "*liste*" : ``numpy.array([[1,2,3], [1,2,3]])``
+ - "*liste*" de "*liste*" : ``[[1,2,3], [1,2,3]]``
+ - "*liste*" de chaîne de caractères : ``['1 2 3', '1 2 3']``
+ - "*liste*" de chaîne de caractères : ``['1;2;3', '1;2;3']``
+ - "*liste*" de chaîne de caractères : ``['[1,2,3]', '[1,2,3]']``
+ - chaîne de "*liste*" : ``'[[1,2,3], [1,2,3]]'``
+ - chaîne de "*liste*" : ``'1 2 3 ; 1 2 3'``
+ - fichier Python de données, avec variable "*Observation*" dans l'espace de nommage, indiqué par le mot-clé "*Script*" avec la condition ``VectorSerie=True``
+ - fichier texte de données (TXT, CSV, TSV, DAT), avec pointeur de variable par nom en colonne ou en ligne, indiqué par le mot-clé "*DataFile*" avec la condition ``VectorSerie=True``
+ - fichier binaire de données (NPY, NPZ), avec pointeur de variable par nom, indiqué par le mot-clé "*DataFile*" avec la condition ``VectorSerie=True``
+
+- Exemples de déclaration en interface TUI :
+
+ - ``case.setObservation( VectorSerie = [[1,2,3], [1,2,3]] )``
+ - ``case.setObservation( VectorSerie = [numpy.array([1,2,3]), numpy.array([1,2,3])] )``
+ - ``case.setObservation( VectorSerie = ['1 2 3', '1 2 3'] )``
+ - ``case.setObservation( VectorSerie = '[[1,2,3], [1,2,3]]' )``
+ - ``case.setObservation( VectorSerie = '1 2 3 ; 1 2 3' )``
+ - ``case.setObservation( VectorSerie=True, Script = 'script.py' )```
+ - ``case.setObservation( VectorSerie=True, DataFile = 'data.csv' )```
+ - ``case.setObservation( VectorSerie=True, DataFile = 'data.npy' )```
+
+Remarque d'utilisation : dans une étude donnée, seul le dernier enregistrement
+(que ce soit un vecteur unique ou une série de vecteurs) est utilisable, car un
+seul concept d'observation existe par étude ADAO.
+
+Utilisation d'une unique observation spatio-temporelle
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Cette unique observation spatio-temporelle est similaire à la précédente dans
+sa représentation de série vectorielle, mais elle impose qu'elle doit être
+utilisée en une seule fois, c'est-à-dire en étant entièrement connue au début
+de l'analyse algorithmique. Elle est donc représentable comme une série
+indexée, de la même manière que pour une `Utilisation d'une série temporelle
+d'observations spatiales`_.
+
+Utilisation d'une série paramétrée d'observations spatiales
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+On représente cette fois une collection d'observations paramétrées par un
+indice ou un paramètre discret. Cette forme est encore similaire à la
+précédente. Elle est donc représentable comme une série indexée, de la même
+manière que pour une `Utilisation d'une série temporelle d'observations
+spatiales`_.
+
+Remarques générales sur les observations
+++++++++++++++++++++++++++++++++++++++++
+
+.. warning::
+
+ Lorsque l'assimilation établit explicitement un **processus itératif
+ temporel**, comme dans l'assimilation de données d'états, **la première
+ observation est non utilisée mais elle doit être présente dans la description
+ des données d'un cas ADAO**. Par convention, elle est donc considérée comme
+ disponible au même instant que la valeur temporelle d'ébauche, et ne conduit
+ pas à une correction à cet instant là. La numérotation des observations
+ commençant à 0 par convention, ce n'est donc qu'à partir du numéro 1 que les
+ valeurs d'observations sont utilisées dans les algorithmes itératifs
+ temporels.
+
+Les observations peuvent être fournies par pas de temps uniques ou par fenêtres
+successives pour les algorithmes itératifs. Dans ce cas, on doit fournir à
+chaque itération algorithmique relative à une fenêtre temporelle une série
+d'observations. Dans la pratique, pour chaque fenêtre, on fournit une série
+comme lors d'une `Utilisation d'une série temporelle d'observations
+spatiales`_.
+
+Les options d'acquisition d'observations sont plus riches en interface
+textuelle TUI, toutes les options n'étant pas obligatoirement disponibles dans
+l'interface graphique GUI.
+
+Pour l'entrée de données par fichiers, on se reportera à la description des
+possibilités autour du mot-clé "*DataFile*" dans les
+:ref:`section_ref_entry_types_info`.
.. _section_ref_observers_requirements:
-Exigences pour les fonctions décrivant un "*observer*"
-------------------------------------------------------
+Conditions requises pour les fonctions décrivant un "*observer*"
+----------------------------------------------------------------
.. index:: single: Observer
.. index:: single: setObserver
.. _section_ref_operator_requirements:
-Exigences pour les fonctions décrivant un opérateur
----------------------------------------------------
+Conditions requises pour les fonctions décrivant un opérateur
+-------------------------------------------------------------
.. index:: single: setObservationOperator
.. index:: single: setEvolutionModel
.. _section_ref_userpostanalysis_requirements:
-Exigences pour décrire un post-traitement dédié après calcul ADAO
------------------------------------------------------------------
+Conditions requises pour décrire un post-traitement dédié après calcul ADAO
+---------------------------------------------------------------------------
.. index:: single: Post-Traitement
.. index:: single: UserPostAnalysis
.. _section_reference_entry:
-========================================================================================
+================================================================================
**[DocR]** Entrées et sorties générales
-========================================================================================
+================================================================================
-Cette section décrit de manière générale les différentes possibilités de types
-d'entrées et de variables de sortie que l'on peut utiliser. Les notations
-mathématiques utilisées sont expliquées dans la section :ref:`section_theory`.
+Cette section décrit de manière générale les différentes options de types
+d'entrées et de variables de sortie. Les notations mathématiques utilisées sont
+expliquées dans la section :ref:`section_theory`.
.. toctree::
:maxdepth: 1
.. _section_reference_special_entry:
-========================================================================================
-**[DocR]** Entrées spéciales : fonctions, matrices, "*observer*", post-traitement
-========================================================================================
+==========================================================================================
+**[DocR]** Entrées spéciales : mesures, fonctions, matrices, "*observer*", post-traitement
+==========================================================================================
Cette section décrit les entrées spéciales, comme les formes fonctionnelles ou
-matricielles, que l'on peut utiliser. Les notations mathématiques utilisées
-sont expliquées dans la section :ref:`section_theory`.
+matricielles, et les conditions requises pour les utiliser. Les notions et
+notations mathématiques relatives à ces entrées sont expliquées dans la section
+:ref:`section_theory`.
.. toctree::
:maxdepth: 1
+ ref_observations_requirements
ref_operator_requirements
ref_covariance_requirements
ref_observers_requirements
.. _section_reference_assimilation:
-============================================================================================
+================================================================================
**[DocR]** Cas d'assimilation de données ou d'optimisation
-============================================================================================
+================================================================================
Cette section décrit les choix algorithmiques pour utiliser des méthodes
d'assimilation de données, des méthodes d'optimisation ou des méthodes avec
-réduction, disponibles dans ADAO, détaillant leurs caractéristiques
-d'utilisation et leurs options.
+réduction, disponibles dans ADAO, en détaillant leurs caractéristiques et leurs
+options.
Des exemples sur l'usage de ces commandes sont disponibles dans la section
:ref:`section_tutorials_in_salome`, dans la section
:ref:`section_tutorials_in_python` et dans les fichiers d'exemple installés
-avec ADAO. Les notations mathématiques utilisées sont expliquées dans la
-section :ref:`section_theory`.
+avec ADAO. Les notions et notations mathématiques utilisées sont expliquées
+dans la section :ref:`section_theory`.
.. toctree::
:maxdepth: 1
Des exemples sur l'usage de ces commandes sont disponibles dans la section
:ref:`section_tutorials_in_salome`, dans la section
:ref:`section_tutorials_in_python` et dans les fichiers d'exemple installés
-avec ADAO. Les notations mathématiques utilisées sont expliquées dans la
-section :ref:`section_theory`.
+avec ADAO. Les notions et notations mathématiques utilisées sont expliquées
+dans la section :ref:`section_theory`.
.. toctree::
:maxdepth: 1
- en format texte (texte simple dans un fichier à extension ".txt" ou
".dat", texte à séparateur virgule ou point-virgule dans un fichier à
extension ".csv", texte à séparateur tabulation dans un fichier à
- extension ".tsv")
+ extension ".tsv"), nommé ici TXT, CSV, TSV ou DAT.
- en format binaire (mono-variable dans un fichier Numpy à extension
- ".npy", multi-variables dans un fichier NumpyZ à extension ".npz").
+ ".npy", multi-variables dans un fichier NumpyZ à extension ".npz"),
+ nommé ici NPY ou NPZ.
Par défaut, les valeurs d'une variable doivent être rangées en colonnes
pour être acquises ligne d'enregistrement par ligne d'enregistrement
*Liste de valeurs réelles*. Cela indique une variable qui doit être remplie
comme un vecteur. C'est une simple collection ordonnée de nombres réels.
Les vecteurs peuvent être décrits en version ligne ou colonne sans faire de
- différence.
+ différence. Les détails des :ref:`section_ref_observations_requirements`
+ permettent d'illustrer différentes manières possible d'écrire cette entrée.
.. index:: single: VectorSerie
**VectorSerie**
- *Liste de liste de valeurs réelles*. Cela indique une variable qui doit être remplie comme
- une liste de vecteurs. C'est une collection ordonnée de vecteurs.
+ *Liste de liste de valeurs réelles*. Cela indique une variable qui doit
+ être remplie comme une liste de vecteurs. C'est une collection ordonnée de
+ vecteurs. Les détails des :ref:`section_ref_observations_requirements`
+ permettent d'illustrer différentes manières possible d'écrire cette entrée.
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 :
+dynamique simple sur l'état :math:`\mathbf{x}` peut être décrit en temps
+continu sous la forme :
.. math:: \forall t \in \mathbb{R}^{+}, \frac{d\mathbf{x}}{dt} = \mathcal{D}(\mathbf{x},\mathbf{u},t)
