From: Jean-Philippe ARGAUD <jean-philippe.argaud@edf.fr>
Date: Sat, 12 Sep 2015 20:28:11 +0000 (+0200)
Subject: Documentation corrections and improvements
X-Git-Tag: V7_7_0rc1~14
X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=7ff8efb8411f6de6096feacf20a8e505a68ee7b9;p=modules%2Fadao.git

Documentation corrections and improvements
---

diff --git a/doc/en/advanced.rst b/doc/en/advanced.rst
index 8d6ec1b..e28f9d2 100644
--- a/doc/en/advanced.rst
+++ b/doc/en/advanced.rst
@@ -128,8 +128,8 @@ following Shell script::
 
 In all cases, the standard output and errors come in the launching terminal.
 
-Running an ADAO calculation scheme in YACS using a TUI user mode
-----------------------------------------------------------------
+Running an ADAO calculation scheme in YACS using the text user mode (YACS TUI)
+------------------------------------------------------------------------------
 
 This section describes how to execute in TUI (Text User Interface) YACS mode a
 YACS calculation scheme, obtained in the graphical interface by using the ADAO
@@ -255,6 +255,7 @@ Accelerating numerical derivatives calculations by using a parallel mode
 ------------------------------------------------------------------------
 
 .. index:: single: EnableMultiProcessing
+.. index:: single: NumberOfProcesses
 
 When setting an operator, as described in
 :ref:`section_ref_operator_requirements`, the user can choose a functional form
@@ -267,11 +268,14 @@ executed in parallel.
 Under some conditions, it is then possible to accelerate the numerical
 derivatives calculations by using a parallel mode for the finite differences
 approximation. When setting up an ADAO case, it is done by adding the optional
-sub-command "*EnableMultiProcessing*", set to "1", for the
-"*SCRIPTWITHONEFUNCTION*" command in the operator definition. The parallel mode
-will only use local resources (both multi-cores or multi-processors) of the
-computer on which SALOME is running, requiring as many resources as available.
-By default, this parallel mode is disabled ("*EnableMultiProcessing=0*").
+keyword "*EnableMultiProcessing*", set to "1", for the "*SCRIPTWITHONEFUNCTION*"
+command in the operator definition. The parallel mode will only use local
+resources (both multi-cores or multi-processors) of the computer on which SALOME
+is running, requiring as many resources as available. If necessary, one can
+reduce the available ressources by limiting the possible number of parallel
+processes using the keyword "*NumberOfProcesses*", set to desired maximum (or to
+"0" for automatic control, which is the default value). By default, this
+parallel mode is disabled ("*EnableMultiProcessing=0*").
 
 The main conditions to perform parallel calculations come from the user defined
 function, that represents the direct operator. This function has at least to be
diff --git a/doc/en/ref_entry_types.rst b/doc/en/ref_entry_types.rst
index 55d898e..c3f514d 100644
--- a/doc/en/ref_entry_types.rst
+++ b/doc/en/ref_entry_types.rst
@@ -26,78 +26,80 @@
 List of possible input types
 ----------------------------
 
-.. index:: single: Dict
-.. index:: single: Function
-.. index:: single: Matrix
-.. index:: single: ScalarSparseMatrix
-.. index:: single: DiagonalSparseMatrix
-.. index:: single: String
+Each ADAO variable has a pseudo-type to help filling it and validation. These
+pseudo-types explicitly represent some simple computing or mathematical types.
+Two pseudo-types, purely computing ones, allows to designate how the input
+variables are provided:
+
 .. index:: single: Script
-.. index:: single: Vector
 
-Each ADAO variable has a pseudo-type to help filling it and validation. The
-different pseudo-types are:
+**Script**
+    This indicates a script given as an external file. It can be described by a
+    full absolute path name or only by the file name without path. If the file
+    is given only by a file name without path, and if a study directory is also
+    indicated, the file is searched in the given study directory.
+
+.. index:: single: String
+
+**String**
+    This indicates a string giving a literal representation of a matrix, a
+    vector or a vector series, such as "1 2 ; 3 4" or "[[1,2],[3,4]]" for a
+    square 2x2 matrix.
+
+The various other pseudo-types are as follows. The variables they apply
+themselves may be either a data string (a "*String*"), or a script file (a
+"*Script*"):
 
 .. index:: single: Dict
 
 **Dict**
     This indicates a variable that has to be filled by a Python dictionary
-    ``{"key":"value...}``, usually given either as a string or as a script file.
+    ``{"key":"value...}``.
 
 .. index:: single: Function
 
 **Function**
-    This indicates a variable that has to be filled by a Python function,
-    usually given as a script file or a component method.
+    This indicates a variable that has to be filled by a Python function. The
+    functions are special entries described by the
+    :ref:`section_ref_operator_requirements`.
 
 .. index:: single: Matrix
 
 **Matrix**
-    This indicates a variable that has to be filled by a matrix, usually given
-    either as a string or as a script file.
+    This indicates a variable that has to be filled by a matrix.
 
 .. index:: single: ScalarSparseMatrix
 
 **ScalarSparseMatrix**
     This indicates a variable that has to be filled by a unique number (which
-    will be used to multiply an identity matrix), usually given either as a
-    string or as a script file.
+    will be used to multiply an identity matrix).
 
 .. index:: single: DiagonalSparseMatrix
 
 **DiagonalSparseMatrix**
     This indicates a variable that has to be filled by a vector (which will be
-    used to replace the diagonal of an identity matrix), usually given either as
-    a string or as a script file.
-
-.. index:: single: Script
-
-**Script**
-    This indicates a script given as an external file. It can be described by a
-    full absolute path name or only by the file name without path. If the file
-    is given only by a file name without path, and if a study directory is also
-    indicated, the file is searched in the given directory.
-
-.. index:: single: String
-
-**String**
-    This indicates a string giving a literal representation of a matrix, a
-    vector or a vector series, such as "1 2 ; 3 4" or "[[1,2],[3,4]]" for a
-    square 2x2 matrix.
+    used as the diagonal of a square matrix).
 
 .. index:: single: Vector
 
 **Vector**
-    This indicates a variable that has to be filled by a vector, usually given
-    either as a string or as a script file.
+    This indicates a variable that has to be filled by a vector.
 
 .. index:: single: VectorSerie
 
 **VectorSerie**
-    This indicates a variable that has to be filled by a list of
-    vectors, usually given either as a string or as a script file.
+    This indicates a variable that has to be filled by a list of vectors.
+
+When a command or keyword can be filled by a script file name, specified by the
+pseudo-type "*Script*", the script has to contain a variable or a method that
+has the same name as the one to be filled. In other words, when importing the
+script in a YACS Python node, it must create a variable of the good name in the
+current name space of the node. For example, a Python script making available
+the background variable, named "*Background*", must have the following form::
+
+    ...
+    Background =...
+    ...
 
-When a command or keyword can be filled by a script file name, the script has to
-contain a variable or a method that has the same name as the one to be filled.
-In other words, when importing the script in a YACS Python node, it must create
-a variable of the good name in the current name space of the node.
+Its import allows the creation of the variable "*Background*". The dots "..."
+symbolize any code around this particular beginning of the line.
diff --git a/doc/en/ref_observers_requirements.rst b/doc/en/ref_observers_requirements.rst
new file mode 100644
index 0000000..2bd7338
--- /dev/null
+++ b/doc/en/ref_observers_requirements.rst
@@ -0,0 +1,27 @@
+..
+   Copyright (C) 2008-2015 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
+
+.. _ref_observers_requirements:
+
+Requirements for functions describing an "*observer*"
+-----------------------------------------------------
diff --git a/doc/en/ref_operator_requirements.rst b/doc/en/ref_operator_requirements.rst
index 5baf5af..dc0c422 100644
--- a/doc/en/ref_operator_requirements.rst
+++ b/doc/en/ref_operator_requirements.rst
@@ -102,7 +102,11 @@ adjoint operators. The finite differences approximation order can also be chosen
 through the GUI, using the keyword "*CenteredFiniteDifference*", with 0 for an
 uncentered schema of first order (which is the default value), and with 1 for a
 centered schema of second order (of twice the first order computational cost).
-If necessary and if possible, :ref:`subsection_ref_parallel_df` can be used.
+If necessary and if possible, :ref:`subsection_ref_parallel_df` can be used. In
+all cases, an internal cache mechanism is used to restrict the number of
+operator evaluations to avoid redundant calculations, at the minimum possible in
+a sequential or parallel execution scheme for numerical approximations of the
+tangent and adjoint operators.
 
 This first operator definition form allows easily to test the functional form
 before its use in an ADAO case, greatly reducing the complexity of operator
diff --git a/doc/en/ref_output_variables.rst b/doc/en/ref_output_variables.rst
index 3d2cd8d..0373510 100644
--- a/doc/en/ref_output_variables.rst
+++ b/doc/en/ref_output_variables.rst
@@ -158,6 +158,9 @@ boolean "* * Stored" associated with it in the edition of the ADAO case.
 Inventory of potentially available information at the output
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
+.. index:: single: Dry
+.. index:: single: Forecast
+
 The set of potentially available information at the output is listed here
 regardless of algorithms, for inventory.
 
@@ -324,7 +327,8 @@ of availability. They are the following, in alphabetical order:
 
   SimulatedObservationAtBackground
     *List of vectors*. Each element is a vector of observation simulated from
-    the background :math:`\mathbf{x}^b`.
+    the background :math:`\mathbf{x}^b`. It is the forecast using the
+    background, and it is sometimes called "*Dry*".
 
     Example : ``hxb = ADD.get("SimulatedObservationAtBackground")[-1]``
 
@@ -343,7 +347,9 @@ of availability. They are the following, in alphabetical order:
 
   SimulatedObservationAtOptimum
     *List of vectors*. Each element is a vector of observation simulated from
-    the analysis or optimal state :math:`\mathbf{x}^a`.
+    the analysis or the optimal state :math:`\mathbf{x}^a`. It is the forecast
+    using the analysis or the optimal state, and it is sometimes called
+    "*Forecast*".
 
     Example : ``hxa = ADD.get("SimulatedObservationAtOptimum")[-1]``
 
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index c0d6226..079f26e 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -28,9 +28,10 @@
 ================================================================================
 
 The following sections present the reference description of the ADAO commands
-and keywords available through the GUI or through scripts. A first common
-section presents in general the :ref:`section_reference_entry`. After that, one
-describes successively the :ref:`section_reference_assimilation` and the
+and keywords available through the GUI or through scripts. Two first common
+sections present the :ref:`section_reference_entry` and the
+:ref:`section_reference_special_entry`. After that, one describes successively
+the :ref:`section_reference_assimilation` and the
 :ref:`section_reference_checking`.
 
 Each command or keyword to be defined through the ADAO GUI has some properties.
@@ -44,22 +45,36 @@ are automatically correct.
 .. _section_reference_entry:
 
 ========================================================================================
-**[DocR]** General entries and outputs, functions and matrices
+**[DocR]** General entries and outputs
 ========================================================================================
 
 This section describes in general the different possibilities of entry types and
-output variables, and the functional or matrix forms that can be used. The
-mathematical notations used afterwards are explained in the section
-:ref:`section_theory`.
+output variables that can be used. The mathematical notations used afterwards
+are explained in the section :ref:`section_theory`.
 
 .. toctree::
    :maxdepth: 1
    
    ref_entry_types
    ref_options_AlgorithmParameters
+   ref_output_variables
+
+.. _section_reference_special_entry:
+
+========================================================================================
+**[DocR]** Special entries: functions, matrices, "*observer*"
+========================================================================================
+
+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`.
+
+.. toctree::
+   :maxdepth: 1
+   
    ref_operator_requirements
    ref_covariance_requirements
-   ref_output_variables
+   ref_observers_requirements
 
 .. _section_reference_assimilation:
 
diff --git a/doc/en/tui.rst b/doc/en/tui.rst
index 78487cf..c262142 100644
--- a/doc/en/tui.rst
+++ b/doc/en/tui.rst
@@ -23,6 +23,7 @@
 
 .. index:: single: TUI
 .. index:: single: API/TUI
+.. index:: single: adaoBuilder
 .. _section_tui:
 
 ================================================================================
@@ -83,9 +84,9 @@ More details are given here on the successive steps of the setup of an ADAO TUI
 calculation case. The commands themselves are detailed just after in the
 :ref:`subsection_tui_commands`.
 
-The initial creation of a study is done using the following commands, the
-``case`` object name of the ADAO TUI calculation case being let free to the
-user choice::
+The creation and initialisation of a study are done using the following
+commands, the ``case`` object name of the ADAO TUI calculation case being let
+free to the user choice::
 
     from numpy import array
     import adaoBuilder
@@ -268,6 +269,22 @@ The choice of one or the other syntaxes is freely left to the user, according to
 its context of use. In the following, for clarity, we define the controls
 according to the second syntax.
 
+Creating a calculation case in TUI text interface
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The creation and the initialisation of a calculation case in TUI text interface
+are done by importing the interface module "*adaoBuilder*" and by by invoking
+its method "*New()*" as illustrated in the following lines (the ``case`` object
+name being let free to the user choice)::
+
+    from numpy import array
+    import adaoBuilder
+    case = adaoBuilder.New()
+
+It is recommended by default to always import the ``numpy`` module (or some of
+its embedded constructors such as the ``array`` one) to make easier its upcoming
+use in the commands.
+
 Defining the calculation data
 +++++++++++++++++++++++++++++
 
@@ -625,6 +642,18 @@ The command set execution gives the following result::
 As it should be in twin experiments, it is found that we get correctly the
 parameters that were used to artificially build the observations.
 
+.. Réconciliation de courbes à l'aide de MedCoupling
+.. +++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. Utilisation de fonctions de surveillance de type "observer"
+.. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. Suivre d'un recalage à l'aide de MatPlotLib
+.. +++++++++++++++++++++++++++++++++++++++++++
+
+.. Equivalences entre l'interface graphique (GUI) et l'interface textuelle (TUI)
+.. -----------------------------------------------------------------------------
+
 .. [HOMARD] For more information on HOMARD, see the *HOMARD module* and its integrated help available from the main menu *Help* of the SALOME platform.
 
 .. [PARAVIS] For more information on PARAVIS, see the *PARAVIS module* and its integrated help available from the main menu *Help* of the SALOME platform.
diff --git a/doc/fr/advanced.rst b/doc/fr/advanced.rst
index c49c4fa..39f56a6 100644
--- a/doc/fr/advanced.rst
+++ b/doc/fr/advanced.rst
@@ -135,8 +135,8 @@ SALOME>``, il suffit d'enregistrer le script de commandes Shell suivant::
 Dans tous les cas, les sorties standard et d'erreur se font dans le terminal de
 lancement.
 
-Exécuter un schéma de calcul ADAO dans YACS en utilisant le mode "texte" (TUI)
-------------------------------------------------------------------------------
+Exécuter un schéma de calcul ADAO dans YACS en utilisant le mode "texte" (TUI YACS)
+-----------------------------------------------------------------------------------
 
 Cette section décrit comment exécuter en mode TUI (Text User Interface) YACS un
 schéma de calcul YACS, obtenu dans l'interface graphique par la fonction
@@ -270,6 +270,7 @@ Acc
 ---------------------------------------------------------------------------
 
 .. index:: single: EnableMultiProcessing
+.. index:: single: NumberOfProcesses
 
 Lors de la définition d'un opérateur, comme décrit dans le chapitre des
 :ref:`section_ref_operator_requirements`, l'utilisateur peut choisir la forme
@@ -286,8 +287,12 @@ ajoutant le mot-cl
 commande "*SCRIPTWITHONEFUNCTION*" dans la définition de l'opérateur. Le mode
 parallèle utilise uniquement des ressources locales (à la fois multi-coeurs ou
 multi-processeurs) de l'ordinateur sur lequel SALOME est en train de tourner,
-demandant autant de ressources que disponible. Par défaut, ce mode parallèle est
-désactivé ("*EnableMultiProcessing=0*").
+demandant autant de ressources que disponible. Si nécessaire, on peut réduire
+les ressources disponibles en limitant le nombre possible de processus
+parallèles grâce au mot-clé optionnel "*NumberOfProcesses*", que l'on met au
+maximum souhaité (ou à "0" pour le contrôle automatique, qui est la valeur par
+défaut). Par défaut, ce mode parallèle est désactivé
+("*EnableMultiProcessing=0*").
 
 Les principales conditions pour réaliser ces calculs parallèles viennent de la
 fonction définie par l'utilisateur, qui représente l'opérateur direct. Cette
diff --git a/doc/fr/ref_entry_types.rst b/doc/fr/ref_entry_types.rst
index df60337..9c92ee2 100644
--- a/doc/fr/ref_entry_types.rst
+++ b/doc/fr/ref_entry_types.rst
@@ -27,76 +27,82 @@ Liste des types d'entr
 -----------------------------------
 
 Chaque variable ADAO présente un pseudo-type qui aide à la remplir et à la
-valider. Les différents pseudo-types sont:
+valider. Ces pseudo-types représentent explicitement des formes informatiques ou
+mathématiques simples. Deux pseudo-types, purement informatiques, permettent de
+désigner la manière dont on fournit les variables en entrée:
+
+.. index:: single: Script
+
+**Script**
+    Cela indique un script donné comme un fichier externe. Il peut être désigné
+    par un nom de fichier avec chemin complet ou seulement par un nom de fichier
+    sans le chemin. Si le fichier est donné uniquement par un nom sans chemin,
+    et si un répertoire d'étude est aussi indiqué, le fichier est recherché dans
+    le répertoire d'étude donné.
+
+.. index:: single: String
+
+**String**
+    Cela indique une chaîne de caractères fournissant une représentation
+    littérale d'une matrice, d'un vecteur ou d'une collection de vecteurs, comme
+    par exemple "1 2 ; 3 4" ou "[[1,2],[3,4]]" pour une matrice carrée de taille
+    2x2.
+
+Les différents autres pseudo-types sont les suivants. Les variables auquelles
+ils s'appliquent peuvent elles-mêmes être données soit par une chaîne de
+caractères (un "*String*"), soit par un fichier script (un "*Script*"):
 
 .. index:: single: Dict
 
 **Dict**
     Cela indique une variable qui doit être remplie avec un dictionnaire Python
-    ``{"clé":"valeur"...}``, usuellement donné soit par une chaîne de caractères
-    soit par un fichier script.
+    ``{"clé":"valeur"...}``.
 
 .. index:: single: Function
 
 **Function**
-    Cela indique une variable qui doit être donnée comme une fonction Python,
-    usuellement donnée soit par une chaîne de caractères soit par un fichier
-    script.
+    Cela indique une variable qui doit être donnée comme une fonction Python.
+    Les fonctions sont des entrées spéciales décrites par des
+    :ref:`section_ref_operator_requirements`.
 
 .. index:: single: Matrix
 
 **Matrix**
-    Cela indique une variable qui doit être donnée comme une matrice,
-    usuellement donnée soit par une chaîne de caractères soit par un fichier
-    script.
+    Cela indique une variable qui doit être donnée comme une matrice.
 
 .. index:: single: ScalarSparseMatrix
 
 **ScalarSparseMatrix**
     Cela indique une variable qui doit être donnée comme un nombre unique (qui
-    sera utilisé pour multiplier une matrice identité), usuellement donné soit
-    par une chaîne de caractères soit par un fichier script.
+    sera ensuite utilisé pour multiplier une matrice identité).
 
 .. index:: single: DiagonalSparseMatrix
 
 **DiagonalSparseMatrix**
-    Cela indique une variable qui doit , (qui sera
-    utilisé pour remplacer la diagonale d'une matrice identité), usuellement
-    donné soit par une chaîne de caractères soit par un fichier script.
-
-.. index:: single: Script
-
-**Script**
-    Cela indique un script donné comme un fichier externe. Il peut être désigné
-    par un nom de fichier avec chemin complet ou seulement par un nom de fichier
-    sans le chemin. Si le fichier est donné uniquement par un nom sans chemin,
-    et si un répertoire d'étude est aussi indiqué, le fichier est recherché dans
-    le répertoire d'étude donné.
-
-.. index:: single: String
-
-**String**
-    Cela indique une chaîne de caractères fournissant une représentation
-    littérale d'une matrice, d'un vecteur ou d'une collection de vecteurs, comme
-    par exemple "1 2 ; 3 4" ou "[[1,2],[3,4]]" pour une matrice carrée de taille
-    2x2.
+    Cela indique une variable qui doit doit être donnée comme un vecteur, (qui
+    sera ensuite utilisé comme la diagonale d'une matrice carrée).
 
 .. index:: single: Vector
 
 **Vector**
-    Cela indique une variable qui doit être remplie comme un vecteur,
-    usuellement donné soit par une chaîne de caractères soit par un fichier
-    script.
+    Cela indique une variable qui doit être remplie comme un vecteur.
 
 .. index:: single: VectorSerie
 
 **VectorSerie**
-    Cela indique une variable qui doit être remplie comme une liste de vecteurs,
-    usuellement donnée soit par une chaîne de caractères soit par un fichier
-    script.
-
-Lorsqu'une commande ou un mot-clé peut être rempli par un nom de fichier script,
-ce script doit présenter une variable ou une méthode que porte le même nom que
-la variable à remplir. En d'autres mots, lorsque l'on importe le script dans un
-noeud Python de YACS, il doit créer une variable du bon nom dans l'espace de
-nommage courant du noeud.
+    Cela indique une variable qui doit être remplie comme une liste de vecteurs.
+
+Lorsqu'une commande ou un mot-clé peut être rempli par un nom de fichier script
+désigné par le pseudo-type "*Script*", ce script doit présenter une variable ou
+une méthode que porte le même nom que la variable à remplir. En d'autres termes,
+lorsque l'on importe le script dans un noeud Python de YACS, il doit créer une
+variable du bon nom dans l'espace de nommage courant du noeud. Par exemple, un
+script Python rendant disponible la variable d'ébauche, nommée "*Background*",
+doit présenter la forme suivante::
+
+    ...
+    Background =...
+    ...
+
+Son importation permet ainsi de créer la variable "*Background*". Les points
+"..." symbolisent du code quelconque autour de ce début particulier de ligne.
diff --git a/doc/fr/ref_observers_requirements.rst b/doc/fr/ref_observers_requirements.rst
new file mode 100644
index 0000000..df804f2
--- /dev/null
+++ b/doc/fr/ref_observers_requirements.rst
@@ -0,0 +1,28 @@
+..
+   Copyright (C) 2008-2015 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
+
+.. _ref_observers_requirements:
+
+Exigences pour les fonctions décrivant un "*observer*"
+------------------------------------------------------
+
diff --git a/doc/fr/ref_operator_requirements.rst b/doc/fr/ref_operator_requirements.rst
index 35a72b2..68b5880 100644
--- a/doc/fr/ref_operator_requirements.rst
+++ b/doc/fr/ref_operator_requirements.rst
@@ -107,7 +107,11 @@ diff
 mot-clé "*CenteredFiniteDifference*", avec 0 pour un schéma non centré du
 premier ordre (qui est la valeur par défaut), et avec 1 pour un schéma centré du
 second ordre (qui coûte numériquement deux fois plus cher que le premier ordre).
-Si nécessaire et si possible, on peut :ref:`subsection_ref_parallel_df`.
+Si nécessaire et si possible, on peut :ref:`subsection_ref_parallel_df`. Dans
+tous les cas, un mécanisme de cache interne permet de limiter le nombre
+d'évaluations de l'opérateur pour éviter des calculs redondants, au minimum
+possible du point de vue de l'exécution séquentielle ou parallèle des
+approximations numériques des opérateurs tangent et adjoint.
 
 Cette première forme de définition de l'opérateur permet aisément de tester la
 forme fonctionnelle avant son usage dans un cas ADAO, réduisant notablement la
diff --git a/doc/fr/ref_output_variables.rst b/doc/fr/ref_output_variables.rst
index fcafacb..9fbeeee 100644
--- a/doc/fr/ref_output_variables.rst
+++ b/doc/fr/ref_output_variables.rst
@@ -164,6 +164,9 @@ dans l'
 Inventaire des informations potentiellement disponibles en sortie
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
+.. index:: single: Dry
+.. index:: single: Forecast
+
 L'ensemble des informations potentiellement disponibles en sortie est indiqué
 ici indépendamment des algorithmes, pour inventaire.
 
@@ -336,7 +339,8 @@ alphab
 
   SimulatedObservationAtBackground
     *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé à
-    partir de l'ébauche :math:`\mathbf{x}^b`.
+    partir de l'ébauche :math:`\mathbf{x}^b`. C'est la prévision à partir de
+    l'ébauche, et elle est parfois appellée "*Dry*".
 
     Exemple : ``hxb = ADD.get("SimulatedObservationAtBackground")[-1]``
 
@@ -355,7 +359,9 @@ alphab
 
   SimulatedObservationAtOptimum
     *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé à
-    partir de l'analyse ou de l'état optimal :math:`\mathbf{x}^a`.
+    partir de l'analyse ou de l'état optimal :math:`\mathbf{x}^a`. C'est la
+    prévision à partir de l'analyse ou de l'état optimal, et elle est parfois
+    appellée "*Forecast*".
 
     Exemple : ``hxa = ADD.get("SimulatedObservationAtOptimum")[-1]``
 
diff --git a/doc/fr/reference.rst b/doc/fr/reference.rst
index 3bb2a5d..774e0c5 100644
--- a/doc/fr/reference.rst
+++ b/doc/fr/reference.rst
@@ -29,9 +29,10 @@
 
 Les sections suivantes présentent la description de référence des commandes et
 mots-clés ADAO disponibles à travers l'interface graphique (GUI) ou à travers
-des scripts. Une première section commune présente de manière générale les
-:ref:`section_reference_entry`. Ensuite, on décrit successivement les
-:ref:`section_reference_assimilation` et les :ref:`section_reference_checking`.
+des scripts. Les deux premières sections communes présentent les
+:ref:`section_reference_entry` et les :ref:`section_reference_special_entry`.
+Ensuite, on décrit successivement les :ref:`section_reference_assimilation` et
+les :ref:`section_reference_checking`.
 
 Chaque commande ou mot-clé à définir par l'interface graphique (GUI) a des
 propriétés particulières. La première propriété est d'être *requise*,
@@ -45,22 +46,36 @@ l'aide de l'interface graphique sont automatiquement correctes.
 .. _section_reference_entry:
 
 ========================================================================================
-**[DocR]** Entrées et sorties générales, fonctions et matrices
+**[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, et 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`.
+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`.
 
 .. toctree::
    :maxdepth: 1
    
    ref_entry_types
    ref_options_AlgorithmParameters
+   ref_output_variables
+
+.. _section_reference_special_entry:
+
+========================================================================================
+**[DocR]** Entrées spéciales : fonctions, matrices, "*observer*"
+========================================================================================
+
+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`.
+
+.. toctree::
+   :maxdepth: 1
+   
    ref_operator_requirements
    ref_covariance_requirements
-   ref_output_variables
+   ref_observers_requirements
 
 .. _section_reference_assimilation:
 
diff --git a/doc/fr/tui.rst b/doc/fr/tui.rst
index 6abe87d..072bb73 100644
--- a/doc/fr/tui.rst
+++ b/doc/fr/tui.rst
@@ -23,6 +23,7 @@
 
 .. index:: single: TUI
 .. index:: single: API/TUI
+.. index:: single: adaoBuilder
 .. _section_tui:
 
 ================================================================================
@@ -85,7 +86,7 @@ On d
 calcul TUI ADAO. Les commandes elles-mêmes sont détaillées juste après dans
 l':ref:`subsection_tui_commands`.
 
-L'initialisation et la création d'une étude se fait par les commandes suivantes,
+La création et l'initialisation d'une étude se font par les commandes suivantes,
 le nom ``case`` de l'objet du cas de calcul TUI ADAO étant quelconque, au choix
 de l'utilisateur::
 
@@ -280,6 +281,22 @@ Le choix de l'une ou l'autre des syntaxes est librement laiss
 selon son contexte d'usage. Dans la suite, par souci de clarté, on définit les
 commandes selon la seconde syntaxe.
 
+Création d'un cas de calcul en interface textuelle TUI
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+La création et l'initialisation d'un cas de calcul en interface textuelle TUI se
+font en important le module d'interface "*adaoBuilder*" et en invoquant sa
+méthode "*New()*" comme illustré dans les quelques lignes suivantes (le nom
+``case`` de l'objet étant quelconque, au choix de l'utilisateur)::
+
+    from numpy import array
+    import adaoBuilder
+    case = adaoBuilder.New()
+
+Il est recommandé par principe de toujours importer le module ``numpy`` (ou ses
+constructeurs particuliers, comme celui d'``array``) pour faciliter ensuite son
+usage dans les commandes elle-mêmes.
+
 Définir les données de calcul
 +++++++++++++++++++++++++++++