From ca6d08046e864e4fcde78ed34193fad0ac459792 Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Mon, 22 Jun 2020 15:03:37 +0200 Subject: [PATCH] Minor documentation review corrections --- doc/en/advanced.rst | 8 ++++---- doc/en/notations.rst | 2 +- doc/en/ref_observers_requirements.rst | 4 ++-- doc/en/ref_operator_requirements.rst | 14 ++++++------- doc/en/ref_options_AlgorithmParameters.rst | 2 +- doc/en/tutorials_in_salome.rst | 20 +++++++++++-------- doc/fr/advanced.rst | 8 ++++---- doc/fr/methodology.rst | 4 ++-- doc/fr/notations.rst | 2 +- .../ref_algorithm_NonLinearLeastSquares.rst | 2 +- doc/fr/ref_observers_requirements.rst | 12 +++++------ doc/fr/ref_operator_requirements.rst | 4 ++-- doc/fr/ref_options_AlgorithmParameters.rst | 2 +- doc/fr/tutorials_in_salome.rst | 20 +++++++++++-------- 14 files changed, 56 insertions(+), 48 deletions(-) diff --git a/doc/en/advanced.rst b/doc/en/advanced.rst index 3f4f04a..5650fee 100644 --- a/doc/en/advanced.rst +++ b/doc/en/advanced.rst @@ -292,11 +292,11 @@ Python interface. .. _section_advanced_eficas_gui: -Using the EFICAS graphical interface as an ADAO TUI command ------------------------------------------------------------ +Using the ADAO EFICAS graphical interface as an ADAO TUI command +---------------------------------------------------------------- -To make it easier to quickly edit an ADAO command file with EFICAS (JDC, or -pair of files ".comm/.py", that are together in a directory), you can launch +To make it easier to quickly edit an ADAO command file with ADAO EFICAS (JDC, +or pair of files ".comm/.py", that are together in a directory), you can launch the graphical user interface from the Python interpreter. To do this, in a Python interpreter obtained from the "SALOME shell", the following commands are used:: diff --git a/doc/en/notations.rst b/doc/en/notations.rst index 03642f1..d527f12 100644 --- a/doc/en/notations.rst +++ b/doc/en/notations.rst @@ -44,7 +44,7 @@ File type and naming conventions rely heavily on the extensions of the files themselves. Some of them are briefly specified here, without being exhaustive: - extension ``.py`` : data or commands text file of Python source type -- extension ``.comm`` : commands text file of EFICAS type +- extension ``.comm`` : commands text file of ADAO EFICAS type - extension ``.xml`` : data text file of XML type or commands (for YACS, not exclusive) - extension ``.txt`` : data text file with space separator - extension ``.dat`` : data text file with space separator diff --git a/doc/en/ref_observers_requirements.rst b/doc/en/ref_observers_requirements.rst index 6905b1b..485c2e1 100644 --- a/doc/en/ref_observers_requirements.rst +++ b/doc/en/ref_observers_requirements.rst @@ -55,8 +55,8 @@ template or pattern (entry of type"*Template*") available by default in ADAO when using the graphical editor and detailed in the following part :ref:`section_ref_observers_templates`. These templates are simple scripts that can be tuned by the user, either in the integrated edition stage of the case -with EFICAS, or in the edition stage of the schema before execution, to improve -the ADAO case performance in the SALOME execution supervisor YACS. +with ADAO EFICAS, or in the edition stage of the schema before execution, to +improve the ADAO case performance in the SALOME execution supervisor YACS. In the textual interface (TUI) of ADAO (see the part :ref:`section_tui`), the same information can be given with the command "*setObserver*" applied to a diff --git a/doc/en/ref_operator_requirements.rst b/doc/en/ref_operator_requirements.rst index 7dda4f8..941484d 100644 --- a/doc/en/ref_operator_requirements.rst +++ b/doc/en/ref_operator_requirements.rst @@ -101,13 +101,13 @@ First functional form: one direct operator only The first one consist in providing only one function, potentially non-linear, and to approximate the associated tangent and adjoint operators. -This is done in ADAO by using in the graphical interface EFICAS the keyword -"*ScriptWithOneFunction*" for the description by a script. In the textual -interface, it is the keyword "*OneFunction*", possibly combined with "*Script*" -keyword depending on whether it is a function or a script. If it is by external -script, the user must provide a file containing a function that has the -mandatory name "*DirectOperator*". For example, an external script can follow -the generic template:: +This is done in ADAO by using, in the ADAO graphical interface EFICAS, the +keyword "*ScriptWithOneFunction*" for the description by a script. In the +textual interface, it is the keyword "*OneFunction*", possibly combined with +"*Script*" keyword depending on whether it is a function or a script. If it is +by external script, the user must provide a file containing a function that has +the mandatory name "*DirectOperator*". For example, an external script can +follow the generic template:: def DirectOperator( X ): """ Direct non-linear simulation operator """ diff --git a/doc/en/ref_options_AlgorithmParameters.rst b/doc/en/ref_options_AlgorithmParameters.rst index dc90da2..cc72d33 100644 --- a/doc/en/ref_options_AlgorithmParameters.rst +++ b/doc/en/ref_options_AlgorithmParameters.rst @@ -36,7 +36,7 @@ command "*AlgorithmParameters*". There are 3 practical methods for the user of the EFICAS graphical user interface of ADAO (GUI) to provide these options. The method is determined as -follows in the EFICAS graphical user interface: +follows in the ADAO EFICAS graphical user interface: #. firstly using the "*Parameters*" keyword in the "*AlgorithmParameters*" command, which allows to choose between "*Defaults*" (use of explicit diff --git a/doc/en/tutorials_in_salome.rst b/doc/en/tutorials_in_salome.rst index 6497692..0b7fbfd 100644 --- a/doc/en/tutorials_in_salome.rst +++ b/doc/en/tutorials_in_salome.rst @@ -433,12 +433,11 @@ Skeletons of the scripts describing the setup We give here the essential parts of each script used afterward to build the ADAO case. Remember that using these scripts in real Python files requires to -correctly define the path to imported modules or codes (even if the module is in -the same directory that the importing Python file. We indicate the path -adjustment using the mention ``"# INSERT PHYSICAL SCRIPT PATH"``), the encoding -if necessary, etc. The indicated file names for the following scripts are -arbitrary. Examples of complete file scripts are available in the ADAO examples -standard directory. +correctly define the path to imported modules or codes (even if the module is +in the same directory that the importing Python file. One have to mention the +encoding if necessary, etc. The indicated file names for the following scripts +are arbitrary. Examples of complete file scripts are available in the ADAO +examples standard directory. We first define the true state :math:`\mathbf{x}^t` and some convenient matrix building function, in a Python script file named @@ -523,7 +522,9 @@ convenience: return numpy.array( HX ) We does not need the linear companion operators ``"TangentOperator"`` and -``"AdjointOperator"`` because they will be approximated using ADAO capabilities. +``"AdjointOperator"`` because they will be approximated using ADAO +capabilities. Detailed information on these operators can be found in the +:ref:`section_ref_operator_requirements`. We insist on the fact that these non-linear operator ``"DirectOperator"``, tangent operator ``"TangentOperator"`` and adjoint operator @@ -581,6 +582,9 @@ the following parameters can be defined in a Python script file named [ 0., 4. ], # Bound on the second parameter [ 0., None ], # Bound on the third parameter ], + "StoreSupplementaryCalculations" : [ + "CurrentState", + ], } Finally, it is common to post-process the results, retrieving them after the @@ -644,7 +648,7 @@ an estimation case with explicit data definition`_ previous section. Using the simple linear operator :math:`\mathbf{H}` from the Python script file ``Physical_simulation_functions.py`` in the ADAO examples standard directory, -the results will look like: +the results will look like (it may depend on the system): :: xt = [1 2 3] diff --git a/doc/fr/advanced.rst b/doc/fr/advanced.rst index 5e7e4db..d6ba88c 100644 --- a/doc/fr/advanced.rst +++ b/doc/fr/advanced.rst @@ -307,11 +307,11 @@ l'interface API/TUI en Python standard. .. _section_advanced_eficas_gui: -Utiliser l'interface graphique EFICAS comme une commande TUI d'ADAO -------------------------------------------------------------------- +Utiliser l'interface graphique EFICAS d'ADAO comme une commande TUI d'ADAO +-------------------------------------------------------------------------- -Pour faciliter l'édition rapide avec EFICAS d'un fichier de commandes ADAO -(JDC, ou paire de fichiers ".comm/.py", qui se trouvent ensemble dans un +Pour faciliter l'édition rapide avec EFICAS d'ADAO d'un fichier de commandes +ADAO (JDC, ou paire de fichiers ".comm/.py", qui se trouvent ensemble dans un répertoire), on peut lancer l'interface graphique depuis l'interpréteur Python. Pour cela, dans un interpréteur Python obtenu depuis le "SALOME shell", on utilise les commandes suivantes:: diff --git a/doc/fr/methodology.rst b/doc/fr/methodology.rst index 0991ce5..fb6e94d 100644 --- a/doc/fr/methodology.rst +++ b/doc/fr/methodology.rst @@ -30,7 +30,7 @@ Cette section présente un méthodologie générique pour construire une étude d'Assimilation de Données ou d'Optimisation. Elle décrit les étapes conceptuelles pour établir de manière indépendante cette étude. Elle est -indépendante de tout outil, mais le module ADAO permet de mettre en oeuvre +indépendante de tout outil, mais le module ADAO permet de mettre en œuvre efficacement une telle étude. Les notations sont les mêmes que celles utilisées dans :ref:`section_theory`. @@ -92,7 +92,7 @@ En pratique, les méthodes d'optimisation peuvent requérir une information de type gradient de la simulation par rapport aux inconnues. Dans ce cas, le gradient explicite du code doit être donné, ou le gradient numérique doit être établi. Sa qualité est en relation avec la stabilité ou la régularité du code de -simulation, et elle doit être vérifiée avec soin avant de mettre en oeuvre les +simulation, et elle doit être vérifiée avec soin avant de mettre en œuvre les calculs d'optimisation. Des conditions spécifiques doivent être utilisées pour ces vérifications. diff --git a/doc/fr/notations.rst b/doc/fr/notations.rst index e777c2e..b71ad9d 100644 --- a/doc/fr/notations.rst +++ b/doc/fr/notations.rst @@ -48,7 +48,7 @@ extensions des fichiers eux-mêmes. On en précise brièvement certaines ici, sa être exhaustifs : - extension ``.py`` : fichier texte de données ou commandes de type source Python -- extension ``.comm`` : fichier texte de données de commandes EFICAS +- extension ``.comm`` : fichier texte de données de commandes EFICAS d'ADAO - extension ``.xml`` : fichier texte de données de type XML (pour YACS, non exclusif) - extension ``.txt`` : fichier texte de données à séparateur espace - extension ``.dat`` : fichier texte de données à séparateur espace diff --git a/doc/fr/ref_algorithm_NonLinearLeastSquares.rst b/doc/fr/ref_algorithm_NonLinearLeastSquares.rst index e88d703..1b5d56a 100644 --- a/doc/fr/ref_algorithm_NonLinearLeastSquares.rst +++ b/doc/fr/ref_algorithm_NonLinearLeastSquares.rst @@ -118,7 +118,7 @@ StoreSupplementaryCalculations *Astuce pour cet algorithme :* Comme la commande *"BackgroundError"* est requise pour TOUS les algorithmes - de calcul dans l'interface graphique ADAO EFICAS, vous devez fournir une + de calcul dans l'interface graphique EFICAS d'ADAO, vous devez fournir une valeur, malgré le fait que cette commande ne soit pas nécessaire pour cet algorithme, et n'est donc pas utilisée. La manière la plus simple est de donner "1" comme un STRING. diff --git a/doc/fr/ref_observers_requirements.rst b/doc/fr/ref_observers_requirements.rst index 5831e96..db1cbf8 100644 --- a/doc/fr/ref_observers_requirements.rst +++ b/doc/fr/ref_observers_requirements.rst @@ -52,12 +52,12 @@ la figure qui suit : L'"*observer*" peut être fourni sous la forme d'un script explicite (entrée de type "*String*"), d'un script contenu dans un fichier externe (entrée de type "*Script*"), ou en utilisant un modèle (entrée de type "*Template*") fourni par -défaut dans ADAO lors de l'usage de l'éditeur graphique EFICAS et détaillé dans -la partie :ref:`section_ref_observers_templates` qui suit. Ces derniers sont -des scripts simples qui peuvent être adaptés par l'utilisateur, soit dans -l'étape d'édition intégrée du cas avec EFICAS, soit dans l'étape d'édition du -schéma avant l'exécution, pour améliorer la performance du calcul ADAO dans le -superviseur d'exécution de SALOME. +défaut dans ADAO lors de l'usage de l'éditeur graphique EFICAS d'ADAO et +détaillé dans la partie :ref:`section_ref_observers_templates` qui suit. Ces +derniers sont des scripts simples qui peuvent être adaptés par l'utilisateur, +soit dans l'étape d'édition intégrée du cas avec EFICAS d'ADAO, soit dans +l'étape d'édition du schéma avant l'exécution, pour améliorer la performance du +calcul ADAO dans le superviseur d'exécution de SALOME. Dans l'interface textuelle (TUI) d'ADAO (voir la partie :ref:`section_tui`), les mêmes informations peuvent être données à l'aide de la commande diff --git a/doc/fr/ref_operator_requirements.rst b/doc/fr/ref_operator_requirements.rst index 34d42e9..39e98c3 100644 --- a/doc/fr/ref_operator_requirements.rst +++ b/doc/fr/ref_operator_requirements.rst @@ -104,8 +104,8 @@ Première forme fonctionnelle : un seul opérateur direct La première consiste à ne fournir qu'une seule fonction, potentiellement non linéaire, et à approximer les opérateurs tangent et adjoint associés. -Ceci est fait dans ADAO en utilisant dans l'interface graphique EFICAS le -mot-clé "*ScriptWithOneFunction*" pour la description par un script. Dans +Ceci est fait dans ADAO en utilisant, dans l'interface graphique EFICAS d'ADAO, +le mot-clé "*ScriptWithOneFunction*" pour la description par un script. Dans l'interface textuelle, c'est le mot-clé "*OneFunction*", éventuellement combiné avec le mot-clé "*Script*" selon que c'est une fonction ou un script. Si c'est par script externe, l'utilisateur doit fournir un fichier contenant une diff --git a/doc/fr/ref_options_AlgorithmParameters.rst b/doc/fr/ref_options_AlgorithmParameters.rst index b773004..d2d67a7 100644 --- a/doc/fr/ref_options_AlgorithmParameters.rst +++ b/doc/fr/ref_options_AlgorithmParameters.rst @@ -36,7 +36,7 @@ incluse dans la commande obligatoire "*AlgorithmParameters*". Il y a 3 méthodes pratiques pour l'utilisateur de l'interface graphique EFICAS d'ADAO (GUI) pour fournir ces options. La méthode est déterminée de la manière -suivante dans l'interface graphique EFICAS : +suivante dans l'interface graphique EFICAS d'ADAO : #. premièrement à l'aide du mot-clé "*Parameters*" dans la commande "*AlgorithmParameters*", qui permet de choisir entre "*Defaults*" diff --git a/doc/fr/tutorials_in_salome.rst b/doc/fr/tutorials_in_salome.rst index 8fbb929..b9ce86f 100644 --- a/doc/fr/tutorials_in_salome.rst +++ b/doc/fr/tutorials_in_salome.rst @@ -458,12 +458,11 @@ Squelettes des scripts décrivant les conditions d'expérience On donne ici les éléments essentiels de chaque script utilisé par la suite pour construire le cas ADAO. On rappelle que l'utilisation de ces scripts dans de réels fichiers Python nécessite de définir correctement le chemin de modules ou -des codes importés (même si le module est dans le même répertoire que le fichier -Python qui l'importe. On indique le chemin à renseigner en utilisant la mention -``"# INSERT PHYSICAL SCRIPT PATH"``), l'encodage si nécessaire, etc. Les noms de -fichiers indiqués pour les scripts qui suivent sont arbitraires. Des exemples -complets de fichiers scripts sont disponibles dans le répertoire standard des -exemples ADAO. +des codes importés (même si le module est dans le même répertoire que le +fichier Python qui l'importe. On doit aussi indiquer l'encodage si nécessaire, +etc. Les noms de fichiers indiqués pour les scripts qui suivent sont +arbitraires. Des exemples complets de fichiers scripts sont disponibles dans le +répertoire standard des exemples ADAO. On définit en premier lieu l'état vrai :math:`\mathbf{x}^t` et une fonction utiles à la construction de matrices, dans un fichier script Python nommé @@ -550,7 +549,8 @@ ici par facilité : On n'a pas besoin des opérateurs linéaires associés ``"TangentOperator"`` et ``"AdjointOperator"`` car ils vont être approximés en utilisant les capacités -d'ADAO. +d'ADAO. Des informations détaillées sur ces opérateurs peuvent être trouvées +dans les :ref:`section_ref_operator_requirements`. On insiste sur le fait que ces opérateurs non-linéaire ``"DirectOperator"``, linéaire tangent ``"TangentOperator"`` et linéaire adjoint ``"AdjointOperator"`` @@ -610,6 +610,9 @@ définis dans un fichier de script Python nommé [ 0., 4. ], # Bound on the second parameter [ 0., None ], # Bound on the third parameter ], + "StoreSupplementaryCalculations" : [ + "CurrentState", + ], } Enfin, il est courant de post-traiter les résultats, en les récupérant aprés la @@ -677,7 +680,8 @@ explicite des données`_. En utilisant l'opérateur linéaire simple :math:`\mathbf{H}` du fichier script Python ``Physical_simulation_functions.py`` disponible dans le répertoire -standard des exemples, les résultats ressemblent à : +standard des exemples, les résultats ressemblent à (cela peut dépendre du +système) : :: xt = [1 2 3] -- 2.39.2