From 4738c3cb4185d4a742c6b6a30c331002eb469c4c Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Mon, 8 Mar 2021 20:24:16 +0100 Subject: [PATCH] Minor documentation improvements --- doc/en/index.rst | 8 +++-- doc/en/intro.rst | 22 +++++++------- doc/en/ref_algorithm_EnsembleKalmanFilter.rst | 1 + doc/en/ref_checking_keywords.rst | 10 ++++--- doc/en/reference.rst | 5 ++-- doc/en/scripts/simple_KalmanFilter2.py | 2 ++ doc/fr/index.rst | 13 +++++---- doc/fr/intro.rst | 29 ++++++++++--------- doc/fr/ref_algorithm_EnsembleKalmanFilter.rst | 1 + doc/fr/ref_checking_keywords.rst | 11 ++++--- doc/fr/reference.rst | 5 ++-- doc/fr/scripts/simple_KalmanFilter1.rst | 2 +- doc/fr/scripts/simple_KalmanFilter2.py | 2 ++ 13 files changed, 64 insertions(+), 47 deletions(-) diff --git a/doc/en/index.rst b/doc/en/index.rst index 751e888..8d56ac3 100644 --- a/doc/en/index.rst +++ b/doc/en/index.rst @@ -40,8 +40,10 @@ 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. More details can be found in the -section :ref:`section_theory`. +interpolation*, *field reconstruction*, etc. The ADAO module currently offers +more than 100 different algorithmic methods and allows the study of about 350 +distinct applied problems. More details can be found in the section +:ref:`section_theory`. The documentation for this module is divided into several major categories, related to the theoretical documentation (indicated in the section title by @@ -62,7 +64,7 @@ come back regularly to these parts. The following parts describe detailed :ref:`section_reference`, with three essential main sub-parts describing the details of commands and options of the algorithms. A :ref:`section_glossary`, some :ref:`section_notations`, a -:ref:`section_bibliography` and an extensive :ref:`genindex` are included in +:ref:`section_bibliography` and an extensive index are included in the document. And, to comply with the module requirements, be sure to read the part :ref:`section_license`. diff --git a/doc/en/intro.rst b/doc/en/intro.rst index 95ff3a9..788ab13 100644 --- a/doc/en/intro.rst +++ b/doc/en/intro.rst @@ -28,7 +28,7 @@ Introduction to ADAO ================================================================================ The aim of the ADAO module is **to help using data assimilation or optimization -methodology in conjunction with other modules or simulation codes in Python** +methodology, in conjunction with other modules or simulation codes, in Python** [Python]_ **or SALOME context** [Salome]_. The ADAO module provides a simple interface to some standard algorithms of data assimilation or optimization, as well as test or verification ones. It allows integration of their use in a @@ -37,17 +37,17 @@ one or more specific calling methods in order to be callable in the Python or SALOME framework. All the SALOME modules can be used through Python or YACS integration. -Its main objective is **to provide the use of various standard data -assimilation or optimization methods, while remaining easy to setup, and -providing a simplified path to help the implementation**. For the end user, who -has previously collected information on his physical problem, the environment -allows him to have an approach focused on simply declaring this information to -build a valid ADAO case, to evaluate it, and to draw the physical results he -needs +Its main objective is **to provide the use of standard and robust data +assimilation or optimization methods, in an efficient way, while remaining easy +to setup, and providing a simplified path to help the implementation**. For the +end user, who has previously collected information on his physical problem, the +environment allows him to have an approach focused on simply declaring this +information to build a valid ADAO case, to evaluate it, and to draw the +physical results he needs The module covers a wide variety of practical applications, in a robust way, allowing real engineering applications, but also quick experimental methodology setup to be performed. Its methodological and numerical scalability give way to -extend its applied domain. It is based on usage of other SALOME modules, namely -YACS and EFICAS if they are available, and on usage of a generic underlying -data assimilation library. +extend its applied domain. It is based on usage of other Python or SALOME +modules, in particular YACS and EFICAS if they are available, and on usage of a +generic underlying data assimilation library. diff --git a/doc/en/ref_algorithm_EnsembleKalmanFilter.rst b/doc/en/ref_algorithm_EnsembleKalmanFilter.rst index 55e9820..5f7efef 100644 --- a/doc/en/ref_algorithm_EnsembleKalmanFilter.rst +++ b/doc/en/ref_algorithm_EnsembleKalmanFilter.rst @@ -197,6 +197,7 @@ StoreSupplementaryCalculations - [Evensen94]_ - [Burgers98]_ +- [Bishop01]_ - [Evensen03]_ - [Zupanski05]_ - [WikipediaEnKF]_ diff --git a/doc/en/ref_checking_keywords.rst b/doc/en/ref_checking_keywords.rst index 72d9669..9332d0b 100644 --- a/doc/en/ref_checking_keywords.rst +++ b/doc/en/ref_checking_keywords.rst @@ -21,7 +21,6 @@ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D -.. index:: single: CHECKING_STUDY .. _section_ref_checking_keywords: List of commands and keywords for an ADAO checking case @@ -29,13 +28,16 @@ List of commands and keywords for an ADAO checking case This set of commands is related to the description of a checking case, that is a procedure to check required properties on information, used somewhere else by a -calculation case. The terms are ordered in alphabetical order, except the first, -which describes the choice between calculation or checking. +calculation case. -The different commands are the following: +The first term describes the choice between calculation or checking. In the +graphical interface, the verification is imperatively indicated by the command: .. include:: snippets/CHECKING_STUDY.rst +The other terms are ordered in alphabetical order. The different commands are +the following: + .. include:: snippets/AlgorithmParameters.rst .. include:: snippets/CheckingPoint.rst diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 32cd65d..f9307e7 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -83,8 +83,9 @@ the section :ref:`section_theory`. **[DocR]** Data assimilation or optimization calculation cases ============================================================================================ -This section describes the data assimilation or optimization algorithms -available in ADAO, detailing their usage characteristics and their options. +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. Some examples on these commands usage are available in the section :ref:`section_tutorials_in_salome`, in the section diff --git a/doc/en/scripts/simple_KalmanFilter2.py b/doc/en/scripts/simple_KalmanFilter2.py index dbd532e..cb91761 100644 --- a/doc/en/scripts/simple_KalmanFilter2.py +++ b/doc/en/scripts/simple_KalmanFilter2.py @@ -35,6 +35,8 @@ case.setObserver( Variable='Analysis', ) # +# Loop to obtain an analysis at each observation arrival +# XaStep, VaStep = 0., 1. for i in range(1,len(Yobs)): case.setBackground (Vector = "%s"%float(XaStep)) diff --git a/doc/fr/index.rst b/doc/fr/index.rst index 276d241..16a56a2 100644 --- a/doc/fr/index.rst +++ b/doc/fr/index.rst @@ -41,9 +41,10 @@ provenant de mesures expérimentales, ou observations, et de modèles numérique *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. De -plus amples détails peuvent être trouvés dans la partie proposant -:ref:`section_theory`. +bayésienne*, d'*interpolation optimale*, de *reconstruction de champs*, etc. Le +module ADAO offre actuellement plus de 100 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`. 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 @@ -66,9 +67,9 @@ expliquent comment utiliser une :ref:`section_gui_in_salome` ou une :ref:`section_reference`, avec trois sous-parties essentielles qui la composent et qui décrivent les commandes et des options d'algorithmes. Un :ref:`section_glossary`, des :ref:`section_notations`, une -:ref:`section_bibliography` et un :ref:`genindex` développés complètent le -document. Enfin, pour respecter les exigences de licence du module, n'oubliez -pas de lire la partie :ref:`section_license`. +:ref:`section_bibliography` et un index développé complètent le document. +Enfin, pour respecter les exigences de licence du module, n'oubliez pas de lire +la partie :ref:`section_license`. .. toctree:: :caption: Table des matières diff --git a/doc/fr/intro.rst b/doc/fr/intro.rst index bafe7d3..85f09b0 100644 --- a/doc/fr/intro.rst +++ b/doc/fr/intro.rst @@ -28,9 +28,9 @@ Introduction à ADAO ================================================================================ Le but du module ADAO est **d'aider à l'usage de l'assimilation de données ou -de l'optimisation en lien avec d'autres modules ou codes de simulation dans un -contexte Python** [Python]_ **ou SALOME** [Salome]_. Le module ADAO fournit une -interface simple à des algorithmes classiques d'assimilation de données ou +de l'optimisation, en lien avec d'autres modules ou codes de simulation, dans +un contexte Python** [Python]_ **ou SALOME** [Salome]_. Le module ADAO fournit +une interface simple à des algorithmes classiques d'assimilation de données ou d'optimisation, ainsi que de tests ou vérifications. Il permet d'intégrer leur usage dans une étude Python ou SALOME. Les modules utilisateurs de calcul ou de simulation doivent fournir une ou plusieurs méthodes d'appel spécifiques afin @@ -38,19 +38,20 @@ d'être appelable dans le cadre Python ou SALOME. En environnement SALOME, tous les modules natifs peuvent être utilisés grâce à l'intégration en Python ou en YACS. -Son principal objectif est de **permettre l'usage de diverses méthodes -standards d'assimilation de données ou d'optimisation, tout en restant facile à -paramétrer, et en fournissant une démarche simplifiée pour aider à la mise en -oeuvre**. Pour l'utilisateur final, qui a préalablement recueilli les -informations sur son problème physique, l'environnement lui permet d'avoir une -démarche centrée sur la simple déclaration de ces informations pour construire -un cas ADAO valide, pour l'évaluer, et pour en tirer les résultats physiques -dont il a besoin. +Son principal objectif est de **permettre l'usage de méthodes standards et +robustes d'assimilation de données ou d'optimisation, de manière performante, +tout en restant facile à paramétrer, et en fournissant une démarche simplifiée +pour aider à la mise en oeuvre**. Pour l'utilisateur final, qui a préalablement +recueilli les informations sur son problème physique, l'environnement lui +permet d'avoir une démarche centrée sur la simple déclaration de ces +informations pour construire un cas ADAO valide, pour l'évaluer, et pour en +tirer les résultats physiques dont il a besoin. Le module couvre une grande variété d'applications pratiques, de façon robuste, permettant des applications réelles, mais aussi d'effectuer de l'expérimentation méthodologique rapide. Son évolutivité, des points de vue méthodologique et numérique, permet aussi l'extension de son domaine -d'application. Il est basé sur l'utilisation d'autres modules, à savoir YACS et -EFICAS s'ils sont disponibles, et sur l'utilisation d'une bibliothèque et -d'outils génériques sous-jacents d'assimilation de données. +d'application. Il est basé sur l'utilisation d'autres modules Python ou SALOME, +en particulier YACS et EFICAS s'ils sont disponibles, et sur l'utilisation +d'une bibliothèque et d'outils génériques sous-jacents d'assimilation de +données. diff --git a/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst b/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst index 1c30849..f981840 100644 --- a/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst +++ b/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst @@ -199,6 +199,7 @@ StoreSupplementaryCalculations - [Evensen94]_ - [Burgers98]_ +- [Bishop01]_ - [Evensen03]_ - [Zupanski05]_ - [WikipediaEnKF]_ diff --git a/doc/fr/ref_checking_keywords.rst b/doc/fr/ref_checking_keywords.rst index c9ab6e0..a895af7 100644 --- a/doc/fr/ref_checking_keywords.rst +++ b/doc/fr/ref_checking_keywords.rst @@ -21,7 +21,6 @@ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D -.. index:: single: CHECKING_STUDY .. _section_ref_checking_keywords: Liste des commandes et mots-clés pour un cas de vérification @@ -29,13 +28,17 @@ Liste des commandes et mots-clés pour un cas de vérification Ce jeu de commandes est lié à la description d'un cas de vérification, qui est une procédure pour vérifier les propriétés d'une information requise, utilisée -ailleurs par un cas de calcul. Les termes sont classés par ordre alphabétique, -sauf le premier, qui décrit le choix entre le calcul ou la vérification. +ailleurs par un cas de calcul. -Les différentes commandes sont les suivantes: +Le premier terme décrit le choix entre un calcul ou une vérification. Dans +l'interface graphique, la vérification est désigné obligatoirement par la +commande: .. include:: snippets/CHECKING_STUDY.rst +Les autres termes sont classés par ordre alphabétique. Les différentes +commandes sont les suivantes: + .. include:: snippets/AlgorithmParameters.rst .. include:: snippets/CheckingPoint.rst diff --git a/doc/fr/reference.rst b/doc/fr/reference.rst index f77b8be..68d4f3e 100644 --- a/doc/fr/reference.rst +++ b/doc/fr/reference.rst @@ -83,8 +83,9 @@ sont expliquées dans la section :ref:`section_theory`. **[DocR]** Cas d'assimilation de données ou d'optimisation ============================================================================================ -Cette section décrit les algorithmes d'assimilation de données ou -d'optimisation disponibles dans ADAO, détaillant leurs caractéristiques +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. Des exemples sur l'usage de ces commandes sont disponibles dans la section diff --git a/doc/fr/scripts/simple_KalmanFilter1.rst b/doc/fr/scripts/simple_KalmanFilter1.rst index 3fc4fa9..95a52c5 100644 --- a/doc/fr/scripts/simple_KalmanFilter1.rst +++ b/doc/fr/scripts/simple_KalmanFilter1.rst @@ -3,7 +3,7 @@ Le filtre de Kalman peut être utilisé pour une **réanalyse des observations d'un modèle dynamique donné**. C'est parce que l'ensemble de l'historique complet de l'observation est déjà connu au début des fenêtres temporelles qu'on -parle de *réanalyse*, même si l'analyse itérative conserve inconnues les +parle de *réanalyse*, même si l'analyse itérative conserve comme inconnues les observations futures à un pas de temps donné. Cet exemple décrit l'estimation itérative d'une quantité physique constante diff --git a/doc/fr/scripts/simple_KalmanFilter2.py b/doc/fr/scripts/simple_KalmanFilter2.py index 749f22e..24a8558 100644 --- a/doc/fr/scripts/simple_KalmanFilter2.py +++ b/doc/fr/scripts/simple_KalmanFilter2.py @@ -35,6 +35,8 @@ case.setObserver( Variable='Analysis', ) # +# Boucle pour obtenir une analyse à l'arrivée de chaque observation +# XaStep, VaStep = 0., 1. for i in range(1,len(Yobs)): case.setBackground (Vector = "%s"%float(XaStep)) -- 2.39.2