From 872d75072753736388e0031ee3939f29d47843b3 Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Tue, 12 Apr 2022 16:02:08 +0200 Subject: [PATCH] Documentation improvements and review --- doc/en/glossary.rst | 33 ++++++++++------ doc/en/snippets/MaximumNumberOfIterations.rst | 14 +++---- .../snippets/MaximumNumberOfIterations_50.rst | 7 ++-- doc/fr/glossary.rst | 39 ++++++++++++------- doc/fr/snippets/MaximumNumberOfIterations.rst | 14 +++---- .../snippets/MaximumNumberOfIterations_50.rst | 8 ++-- 6 files changed, 67 insertions(+), 48 deletions(-) diff --git a/doc/en/glossary.rst b/doc/en/glossary.rst index ee06156..dc8c0b2 100644 --- a/doc/en/glossary.rst +++ b/doc/en/glossary.rst @@ -31,18 +31,27 @@ Glossary case One ADAO case is defined by a set of data and of choices, packed together - through the user interface of the module. The data are physical - measurements that have technically to be available before or during the - case execution. The simulation code(s) and the data assimilation or - optimization method, and their parameters, has to be chosen, they define - the execution properties of the case. - - iteration - One iteration occurs when using iterative optimizers (e.g. 3DVAR), and it - is entirely hidden in the main YACS OptimizerLoop Node named - "*compute_bloc*". Nevertheless, the user can watch the iterative process - through the "*YACS Container Log*" window, which is updated during the - process, and using "*Observers*" attached to calculation variables. + through the user interface of the module (in TUI as in GUI). The data are + physical measurements that have technically to be available before or + during the case execution. The simulation code(s) and the data + assimilation or optimization method, and their parameters, has to be + chosen, they define the execution properties of the case. + + iteration (internal) + An (internal) iteration takes place when using iterative optimization + methods (e.g. for the 3DVAR algorithm). Internal iterations are performed + within each iterative optimization operation. The iterative behavior is + fully integrated into the execution of the iterative algorithms, and is + only apparent to the user when his observation is explicitly requested + using "*Observer*" attached to computational variables. See also + :term:`step (of assimilation)`. + + step (of assimilation) + An assimilation step takes place when a new observation, or a new set of + observations, is used, for example to follow the temporal course of a + dynamic system. Remark: a *single step* of assimilation can contain by + nature *several iterations* of optimization when the assimilation uses an + iterative optimization method. See also :term:`iteration (internal)`. physical system This is the object of study that will be represented by numerical diff --git a/doc/en/snippets/MaximumNumberOfIterations.rst b/doc/en/snippets/MaximumNumberOfIterations.rst index 0aa003b..1c0764e 100644 --- a/doc/en/snippets/MaximumNumberOfIterations.rst +++ b/doc/en/snippets/MaximumNumberOfIterations.rst @@ -1,13 +1,13 @@ .. index:: single: MaximumNumberOfIterations MaximumNumberOfIterations - *Integer value*. This key indicates the maximum number of iterations allowed - for iterative optimization. The default is 15000, which is very similar to no - limit on iterations. It is then recommended to adapt this parameter to the - needs on real problems. For some optimizers, the effective stopping step can - be slightly different of the limit due to algorithm internal control - requirements. One can refer to the section describing ways for - :ref:`subsection_iterative_convergence_control` for more detailed + *Integer value*. This key indicates the maximum number of internal iterations + allowed for iterative optimization. The default is 15000, which is very + similar to no limit on iterations. It is then recommended to adapt this + parameter to the needs on real problems. For some optimizers, the effective + stopping step can be slightly different of the limit due to algorithm + internal control requirements. One can refer to the section describing ways + for :ref:`subsection_iterative_convergence_control` for more detailed recommendations. Example: diff --git a/doc/en/snippets/MaximumNumberOfIterations_50.rst b/doc/en/snippets/MaximumNumberOfIterations_50.rst index 45e4659..817690d 100644 --- a/doc/en/snippets/MaximumNumberOfIterations_50.rst +++ b/doc/en/snippets/MaximumNumberOfIterations_50.rst @@ -1,9 +1,10 @@ .. index:: single: MaximumNumberOfIterations MaximumNumberOfIterations - *Integer value*. This key indicates the maximum number of iterations allowed - for iterative optimization. The default is 50, which is an arbitrary limit. - It is then recommended to adapt this parameter to the needs on real problems. + *Integer value*. This key indicates the maximum number of internal iterations + allowed for iterative optimization. The default is 50, which is an arbitrary + limit. It is then recommended to adapt this parameter to the needs on real + problems. Example: ``{"MaximumNumberOfIterations":50}`` diff --git a/doc/fr/glossary.rst b/doc/fr/glossary.rst index 5c4328c..8ef27c9 100644 --- a/doc/fr/glossary.rst +++ b/doc/fr/glossary.rst @@ -31,21 +31,30 @@ Glossaire cas Un cas ADAO est défini par un jeu de données et de choix, rassemblés par - l'intermédiaire de l'interface utilisateur du module. Les données sont les - mesures physiques qui doivent être techniquement disponibles avant ou - pendant l'exécution du cas. Le (ou les) code(s) de simulation et la - méthode d'assimilation de données ou d'optimisation, ainsi que leurs - paramètres, doivent être choisis, ils définissent les propriétés - d'exécution du cas. - - itération - Une itération a lieu lorsque l'on utilise des méthodes d'optimisation - itératives (par exemple le 3DVAR), et c'est entièrement caché à - l'intérieur du noeud principal de type YACS OptimizerLoop nommé - "*compute_bloc*". Néanmoins, l'utilisateur peut observer le processus - itératif à l'aide de la fenêtre "*YACS Container Log*", qui est mise à - jour au fur et à mesure du déroulement du calcul, et en utilisant des - "*Observers*" attachés à des variables de calcul. + l'intermédiaire de l'interface utilisateur du module (en TUI comme en + GUI). Les données sont les mesures physiques qui doivent être + techniquement disponibles avant ou pendant l'exécution du cas. Le (ou + les) code(s) de simulation et la méthode d'assimilation de données ou + d'optimisation, ainsi que leurs paramètres, doivent être choisis, ils + définissent les propriétés d'exécution du cas. + + itération (interne) + Une itération (interne) a lieu lorsque l'on utilise des méthodes + d'optimisation itératives (par exemple pour l'algorithme de 3DVAR). Les + itérations internes sont effectuées à l'intérieur de chaque opération + d'optimisation itérative. Le comportement itératif est entièrement + intégré dans l'exécution des algorithmes itératifs, et il n'est apparent + pour l'utilisateur que lorsque son observation est explicitement demandée + en utilisant des "*Observer*" attachés à des variables de calcul. Voir + aussi :term:`pas (d'assimilation)`. + + pas (d'assimilation) + Un pas (d'assimilation) a lieu lorsqu'une nouvelle observation, ou un + nouveau jeu d'observations, est utilisé, pour suivre par exemple le + déroulement temporel d'un système dynamique. Remarque : un *unique pas* + d'assimilation peut contenir par nature *plusieurs itérations* + d'optimisation lorsque l'assimilation utilise une méthode itérative + d'optimisation. Voir aussi :term:`itération (interne)`. système physique C'est l'objet d'étude que l'on va représenter par simulation numérique, diff --git a/doc/fr/snippets/MaximumNumberOfIterations.rst b/doc/fr/snippets/MaximumNumberOfIterations.rst index 3ede565..4ea877e 100644 --- a/doc/fr/snippets/MaximumNumberOfIterations.rst +++ b/doc/fr/snippets/MaximumNumberOfIterations.rst @@ -1,13 +1,13 @@ .. index:: single: MaximumNumberOfIterations MaximumNumberOfIterations - *Valeur entière*. Cette clé indique le nombre maximum d'itérations possibles - en optimisation itérative. Le défaut est 15000, qui est très similaire à une - absence de limite sur les itérations. Il est ainsi recommandé d'adapter ce - paramètre aux besoins pour des problèmes réels. Pour certains optimiseurs, le - nombre de pas effectif d'arrêt peut être légèrement différent de la limite à - cause d'exigences de contrôle interne de l'algorithme. On peut se reporter à - la partie décrivant les manières de + *Valeur entière*. Cette clé indique le nombre maximum d'itérations internes + possibles en optimisation itérative. Le défaut est 15000, qui est très + similaire à une absence de limite sur les itérations. Il est ainsi recommandé + d'adapter ce paramètre aux besoins pour des problèmes réels. Pour certains + optimiseurs, le nombre de pas effectif d'arrêt peut être légèrement différent + de la limite à cause d'exigences de contrôle interne de l'algorithme. On peut + se reporter à la partie décrivant les manières de :ref:`subsection_iterative_convergence_control` pour des recommandations plus détaillées. diff --git a/doc/fr/snippets/MaximumNumberOfIterations_50.rst b/doc/fr/snippets/MaximumNumberOfIterations_50.rst index 86b7e87..ca00821 100644 --- a/doc/fr/snippets/MaximumNumberOfIterations_50.rst +++ b/doc/fr/snippets/MaximumNumberOfIterations_50.rst @@ -1,10 +1,10 @@ .. index:: single: MaximumNumberOfIterations MaximumNumberOfIterations - *Valeur entière*. Cette clé indique le nombre maximum d'itérations possibles - en optimisation itérative. Le défaut est 50, qui est une limite arbitraire. - Il est ainsi recommandé d'adapter ce paramètre aux besoins pour des problèmes - réels. + *Valeur entière*. Cette clé indique le nombre maximum d'itérations interne + possibles en optimisation itérative. Le défaut est 50, qui est une limite + arbitraire. Il est ainsi recommandé d'adapter ce paramètre aux besoins pour + des problèmes réels. Exemple : ``{"MaximumNumberOfIterations":50}`` -- 2.39.2