]> SALOME platform Git repositories - modules/adao.git/commitdiff
Salome HOME
Updating documentation by review and snippets (1)
authorJean-Philippe ARGAUD <jean-philippe.argaud@edf.fr>
Sat, 2 Mar 2019 10:18:08 +0000 (11:18 +0100)
committerJean-Philippe ARGAUD <jean-philippe.argaud@edf.fr>
Sat, 2 Mar 2019 10:18:08 +0000 (11:18 +0100)
12 files changed:
doc/fr/methodology.rst
doc/fr/snippets/ASSIMILATION_STUDY.rst [new file with mode: 0644]
doc/fr/snippets/CHECKING_STUDY.rst [new file with mode: 0644]
doc/fr/snippets/ControlInput.rst [new file with mode: 0644]
doc/fr/snippets/Debug.rst [new file with mode: 0644]
doc/fr/snippets/InputVariables.rst [new file with mode: 0644]
doc/fr/snippets/StudyName.rst [new file with mode: 0644]
doc/fr/snippets/StudyRepertory.rst [new file with mode: 0644]
doc/fr/snippets/UserDataInit.rst [new file with mode: 0644]
doc/fr/snippets/UserPostAnalysis.rst [new file with mode: 0644]
doc/fr/theory.rst
doc/fr/tui.rst

index 588749bf8ad400f3080595a737e9c3e10873342f..d5ca22c618d7cb4c2b691c477757b270125114a8 100644 (file)
@@ -31,7 +31,8 @@ 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
-efficacement une telle étude.
+efficacement une telle étude. Les notations sont les mêmes que celles utilisées
+dans :ref:`section_theory`.
 
 Procédure logique pour une étude
 --------------------------------
@@ -39,13 +40,13 @@ Procédure logique pour une étude
 Pour une étude générique d'Assimilation de Données ou d'Optimisation, les
 principales étapes méthodologiques peuvent être les suivantes:
 
-    - :ref:`section_m_step1`
-    - :ref:`section_m_step2`
-    - :ref:`section_m_step3`
-    - :ref:`section_m_step4`
-    - :ref:`section_m_step5`
-    - :ref:`section_m_step6`
-    - :ref:`section_m_step7`
+- :ref:`section_m_step1`
+- :ref:`section_m_step2`
+- :ref:`section_m_step3`
+- :ref:`section_m_step4`
+- :ref:`section_m_step5`
+- :ref:`section_m_step6`
+- :ref:`section_m_step7`
 
 Chaque étape est détaillée dans la section suivante.
 
@@ -153,7 +154,7 @@ Optimisation permettent d'améliorer l'information à propos de la représentati
 détaillée du système physique étudié.
 
 La connaissance *a-priori* de l'état du système peut être représentée en
-utilisant l'**ébauche**, notée :math:`\mathbf{x}^b`, et la **matrice de
+utilisant une **ébauche**, notée :math:`\mathbf{x}^b`, et la **matrice de
 covariance des erreurs d'ébauche**, notée :math:`\mathbf{B}`. Ces informations
 sont extrêmement importantes à compléter, en particulier pour obtenir des
 résultats signifiants en Assimilation de Données.
diff --git a/doc/fr/snippets/ASSIMILATION_STUDY.rst b/doc/fr/snippets/ASSIMILATION_STUDY.rst
new file mode 100644 (file)
index 0000000..57fc2af
--- /dev/null
@@ -0,0 +1,6 @@
+.. index:: single: ASSIMILATION_STUDY
+
+**ASSIMILATION_STUDY**
+  *Commande obligatoire*. C'est la commande générale qui décrit le cas
+  d'assimilation de données ou d'optimisation. Elle contient hiérarchiquement
+  toutes les autres commandes.
diff --git a/doc/fr/snippets/CHECKING_STUDY.rst b/doc/fr/snippets/CHECKING_STUDY.rst
new file mode 100644 (file)
index 0000000..135751b
--- /dev/null
@@ -0,0 +1,5 @@
+.. index:: single: CHECKING_STUDY
+
+**CHECKING_STUDY**
+  *Commande obligatoire*. C'est la commande générale qui décrit le cas de
+  vérification. Elle contient hiérarchiquement toutes les autres commandes.
diff --git a/doc/fr/snippets/ControlInput.rst b/doc/fr/snippets/ControlInput.rst
new file mode 100644 (file)
index 0000000..9c97e83
--- /dev/null
@@ -0,0 +1,8 @@
+.. index:: single: ControlInput
+
+ControlInput
+  *Commande optionnelle*. Elle indique le vecteur de contrôle utilisé pour
+  forcer le modèle d'évolution à chaque pas, usuellement noté
+  :math:`\mathbf{U}`. Sa valeur est définie comme un objet de type "*Vector*"
+  ou de type "*VectorSerie*". Lorsqu'il n'y a pas de contrôle, sa valeur doit
+  être une chaîne vide ''.
diff --git a/doc/fr/snippets/Debug.rst b/doc/fr/snippets/Debug.rst
new file mode 100644 (file)
index 0000000..f0bafe4
--- /dev/null
@@ -0,0 +1,6 @@
+.. index:: single: Debug
+
+Debug
+  *Commande optionnelle*. Elle définit le niveau de sorties et d'informations
+  intermédiaires de débogage. Les choix sont limités entre 0 (pour False) et 1
+  (pour True).
diff --git a/doc/fr/snippets/InputVariables.rst b/doc/fr/snippets/InputVariables.rst
new file mode 100644 (file)
index 0000000..242e10a
--- /dev/null
@@ -0,0 +1,7 @@
+.. index:: single: InputVariables
+
+InputVariables
+  *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des
+  variables physiques qui sont rassemblées dans le vecteur d'état. Cette
+  information est destinée à être utilisée dans le traitement algorithmique
+  interne des données.
diff --git a/doc/fr/snippets/StudyName.rst b/doc/fr/snippets/StudyName.rst
new file mode 100644 (file)
index 0000000..1a6bf43
--- /dev/null
@@ -0,0 +1,5 @@
+.. index:: single: StudyName
+
+StudyName
+  *Commande obligatoire*. C'est une chaîne de caractères quelconque pour
+  décrire l'étude ADAO par un nom ou une déclaration.
diff --git a/doc/fr/snippets/StudyRepertory.rst b/doc/fr/snippets/StudyRepertory.rst
new file mode 100644 (file)
index 0000000..af99bf5
--- /dev/null
@@ -0,0 +1,7 @@
+.. index:: single: StudyRepertory
+
+StudyRepertory
+  *Commande optionnelle*. S'il existe, ce répertoire est utilisé comme base
+  pour les calculs, et il est utilisé pour trouver les fichiers de script,
+  donnés par nom sans répertoire, qui peuvent être utilisés pour définir
+  certaines variables.
diff --git a/doc/fr/snippets/UserDataInit.rst b/doc/fr/snippets/UserDataInit.rst
new file mode 100644 (file)
index 0000000..f5d3922
--- /dev/null
@@ -0,0 +1,8 @@
+.. index:: single: UserDataInit
+
+UserDataInit
+  *Commande optionnelle*. Elle permet d'initialiser certains paramètres ou
+  certaines données automatiquement avant le traitement de données d'entrée
+  pour l'assimilation de données ou l'optimisation. Pour cela, elle indique un
+  nom de fichier de script à exécuter avant d'entrer dans l'initialisation des
+  variables choisies.
diff --git a/doc/fr/snippets/UserPostAnalysis.rst b/doc/fr/snippets/UserPostAnalysis.rst
new file mode 100644 (file)
index 0000000..a11cb3a
--- /dev/null
@@ -0,0 +1,10 @@
+.. index:: single: UserPostAnalysis
+.. index:: single: UserPostAnalysis Template
+
+UserPostAnalysis
+  *Commande optionnelle*. Elle permet de traiter des paramètres ou des
+  résultats après le déroulement de l'algorithme d'assimilation de données ou
+  d'optimisation. Sa valeur est définie comme un fichier script ou une chaîne
+  de caractères, permettant de produire directement du code de post-processing
+  dans un cas ADAO. Des exemples courants (squelettes) sont fournis pour aider
+  l'utilisateur ou pour faciliter l'élaboration d'un cas.
index 8cd7fbd11e468c82989f37609200c44d91b13454..c932431aec1f84ad934cee523fdbd290fa6f99fe 100644 (file)
@@ -159,8 +159,8 @@ Description simple du cadre méthodologique de l'assimilation de données
 .. index:: single: Blue
 
 On peut décrire ces démarches de manière simple. Par défaut, toutes les
-variables sont des vecteurs, puisqu'il y a plusieurs paramètres à ajuster, ou un
-champ discrétisé à reconstruire.
+variables sont des vecteurs, puisqu'il y a plusieurs paramètres à ajuster, ou
+un champ discrétisé à reconstruire.
 
 Selon les notations standards en assimilation de données, on note
 :math:`\mathbf{x}^a` les paramètres optimaux qui doivent être déterminés par
@@ -179,13 +179,14 @@ directement comparés aux observations :math:`\mathbf{y}^o` :
 
 .. math:: \mathbf{y} = H(\mathbf{x})
 
-De plus, on utilise l'opérateur linéarisé :math:`\mathbf{H}` pour représenter
-l'effet de l'opérateur complet :math:`H` autour d'un point de linéarisation (et
-on omettra ensuite de mentionner :math:`H` même si l'on peut le conserver). En
-réalité, on a déjà indiqué que la nature stochastique des variables est
-essentielle, provenant du fait que le modèle, l'ébauche et les observations sont
-tous incorrects. On introduit donc des erreurs d'observations additives, sous la
-forme d'un vecteur aléatoire :math:`\mathbf{\epsilon}^o` tel que :
+De plus, on utilise l'opérateur linéarisé (ou tangent) :math:`\mathbf{H}` pour
+représenter l'effet de l'opérateur complet :math:`H` autour d'un point de
+linéarisation (et on omettra ensuite de mentionner :math:`H` même si l'on peut
+le conserver). En réalité, on a déjà indiqué que la nature stochastique des
+variables est essentielle, provenant du fait que le modèle, l'ébauche et les
+observations sont tous incorrects. On introduit donc des erreurs d'observations
+additives, sous la forme d'un vecteur aléatoire :math:`\mathbf{\epsilon}^o` tel
+que :
 
 .. math:: \mathbf{y}^o = \mathbf{H} \mathbf{x}^t + \mathbf{\epsilon}^o
 
@@ -197,15 +198,14 @@ d'erreurs d'observation par l'expression :
 
 .. math:: \mathbf{R} = E[\mathbf{\epsilon}^o.{\mathbf{\epsilon}^o}^T]
 
-L'ébauche peut aussi être écrite formellement comme une fonction de la valeur
-vraie, en introduisant le vecteur d'erreurs :math:`\mathbf{\epsilon}^b` tel que
-:
+L'ébauche peut être écrite formellement comme une fonction de la valeur vraie,
+en introduisant le vecteur d'erreurs :math:`\mathbf{\epsilon}^b` tel que :
 
 .. math:: \mathbf{x}^b = \mathbf{x}^t + \mathbf{\epsilon}^b
 
-Les erreurs :math:`\mathbf{\epsilon}^b` sont aussi supposées de moyenne nulle,
-de la même manière que pour les observations. On définit la matrice
-:math:`\mathbf{B}` des covariances d'erreurs d'ébauche par :
+Les erreurs d'ébauche :math:`\mathbf{\epsilon}^b` sont aussi supposées de
+moyenne nulle, de la même manière que pour les observations. On définit la
+matrice :math:`\mathbf{B}` des covariances d'erreurs d'ébauche par :
 
 .. math:: \mathbf{B} = E[\mathbf{\epsilon}^b.{\mathbf{\epsilon}^b}^T]
 
@@ -253,15 +253,18 @@ L'avantage du filtrage est le calcul explicite du gain, pour produire ensuite la
 matrice *a posteriori* de covariance d'analyse.
 
 Dans ce cas statique simple, on peut montrer, sous une hypothèse de
-distributions gaussiennes d'erreurs (très peu restrictive en pratique), que les
-deux approches *variationnelle* et *de filtrage* donnent la même solution.
-
-On indique que ces méthodes de "*3D-VAR*" et de "*BLUE*" peuvent être étendues à
-des problèmes dynamiques, sous les noms respectifs de "*4D-VAR*" et de "*filtre
-de Kalman*". Elles peuvent prendre en compte l'opérateur d'évolution pour
-établir aux bons pas de temps une analyse de l'écart entre les observations et
-les simulations et pour avoir, à chaque instant, la propagation de l'ébauche à
-travers le modèle d'évolution. Un grand nombre de variantes ont été développées
+distributions gaussiennes d'erreurs (très peu restrictive en pratique) et de
+linéarité de :math:`H`, que les deux approches *variationnelle* et *de
+filtrage* donnent la même solution.
+
+On indique que ces méthodes de "*3D-VAR*" et de "*BLUE*" peuvent être étendues
+à des problèmes dynamiques, sous les noms respectifs de "*4D-VAR*" et de
+"*filtre de Kalman*". Elles doivent alors prendre en compte l'opérateur
+d'évolution pour établir aux bons pas de temps une analyse de l'écart entre les
+observations et les simulations et pour avoir, à chaque instant, la propagation
+de l'ébauche à travers le modèle d'évolution. De la même manière, ces méthodes
+peuvent aussi être utilisées dans le cas d'opérateurs d'observation ou
+d'évolution non linéaires. Un grand nombre de variantes ont été développées
 pour accroître la qualité numérique des méthodes ou pour prendre en compte des
 contraintes informatiques comme la taille ou la durée des calculs.
 
@@ -302,6 +305,10 @@ Approfondir l'estimation d'état par des méthodes d'optimisation
 
 .. index:: single: estimation d'état
 .. index:: single: méthodes d'optimisation
+.. index:: single: DerivativeFreeOptimization
+.. index:: single: ParticleSwarmOptimization
+.. index:: single: DifferentialEvolution
+.. index:: single: QuantileRegression
 
 Comme vu précédemment, dans un cas de simulation statique, l'assimilation
 variationnelle de données nécessite de minimiser la fonction objectif :math:`J`:
@@ -322,25 +329,28 @@ plus explicite des méthodes d'optimisation et leurs propriétés, peuvent être
 imaginées de deux manières.
 
 En premier lieu, les méthodes classiques d'optimisation impliquent l'usage de
-méthodes de minimisation variées basées sur un gradient. Elles sont extrêmement
-efficaces pour rechercher un minimum local isolé. Mais elles nécessitent que la
-fonctionnelle :math:`J` soit suffisamment régulière et différentiable, et elles
-ne sont pas en mesure de saisir des propriétés globales du problème de
-minimisation, comme par exemple : minimum global, ensemble de solutions
-équivalentes dues à une sur-paramétrisation, multiples minima locaux, etc. **Une
-méthode pour étendre les possibilités d'estimation consiste donc à utiliser
-l'ensemble des méthodes d'optimisation existantes, permettant la minimisation
-globale, diverses propriétés de robustesse de la recherche, etc**. Il existe de
-nombreuses méthodes de minimisation, comme les méthodes stochastiques,
-évolutionnaires, les heuristiques et méta-heuristiques pour les problèmes à
-valeurs réelles, etc. Elles peuvent traiter des fonctionnelles :math:`J` en
-partie irrégulières ou bruitées, peuvent caractériser des minima locaux, etc. Le
-principal désavantage de ces méthodes est un coût numérique souvent bien
-supérieur pour trouver les estimations d'états, et pas de garantie de
-convergence en temps fini. Ici, on ne mentionne que des méthodes qui sont
-disponibles dans le module ADAO : la *régression de quantile (Quantile
-Regression)* [WikipediaQR]_ et l'*optimisation par essaim de particules
-(Particle Swarm Optimization)* [WikipediaPSO]_.
+méthodes de minimisation variées souvent basées sur un gradient. Elles sont
+extrêmement efficaces pour rechercher un minimum local isolé. Mais elles
+nécessitent que la fonctionnelle :math:`J` soit suffisamment régulière et
+différentiable, et elles ne sont pas en mesure de saisir des propriétés
+globales du problème de minimisation, comme par exemple : minimum global,
+ensemble de solutions équivalentes dues à une sur-paramétrisation, multiples
+minima locaux, etc. **Une méthode pour étendre les possibilités d'estimation
+consiste donc à utiliser l'ensemble des méthodes d'optimisation existantes,
+permettant la minimisation globale, diverses propriétés de robustesse de la
+recherche, etc**. Il existe de nombreuses méthodes de minimisation, comme les
+méthodes stochastiques, évolutionnaires, les heuristiques et méta-heuristiques
+pour les problèmes à valeurs réelles, etc. Elles peuvent traiter des
+fonctionnelles :math:`J` en partie irrégulières ou bruitées, peuvent
+caractériser des minima locaux, etc. Les principaux désavantages de ces
+méthodes sont un coût numérique souvent bien supérieur pour trouver les
+estimations d'états, et fréquemment aucune garantie de convergence en temps
+fini. Ici, on ne mentionne que quelques méthodes disponibles dans ADAO :
+
+- l'*optimisation sans dérivées (Derivative Free Optimization ou DFO)* (voir :ref:`section_ref_algorithm_DerivativeFreeOptimization`),
+- l'*optimisation par essaim de particules (Particle Swarm Optimization ou PSO)* (voir :ref:`section_ref_algorithm_ParticleSwarmOptimization`),
+- l'*évolution différentielle (Differential Evolution ou DE)* (voir :ref:`section_ref_algorithm_DifferentialEvolution`),
+- la *régression de quantile (Quantile Regression ou QR)* (voir :ref:`section_ref_algorithm_QuantileRegression`).
 
 En second lieu, les méthodes d'optimisation cherchent usuellement à minimiser
 des mesures quadratiques d'erreurs, car les propriétés naturelles de ces
@@ -348,15 +358,18 @@ fonctions objectifs sont bien adaptées à l'optimisation classique par gradient
 Mais d'autres mesures d'erreurs peuvent être mieux adaptées aux problèmes de
 simulation de la physique réelle. Ainsi, **une autre manière d'étendre les
 possibilités d'estimation consiste à utiliser d'autres mesures d'erreurs à
-réduire**. Par exemple, on peut citer l'**erreur absolue**, l'**erreur
+réduire**. Par exemple, on peut citer une **erreur absolue**, une **erreur
 maximale**, etc. Ces mesures d'erreurs ne sont pas différentiables, mais
 certaines méthodes d'optimisation peuvent les traiter: heuristiques et
-méta-heuristiques pour les problèmes à valeurs réelles, etc. Comme précédemment,
-le principal désavantage de ces méthodes est un coût numérique souvent bien
-supérieur pour trouver les estimations d'états, et pas de garantie de
-convergence en temps fini. Ici encore, on ne mentionne que des méthodes qui sont
-disponibles dans le module ADAO : l'*optimisation par essaim de particules
-(Particle Swarm Optimization)* [WikipediaPSO]_.
+méta-heuristiques pour les problèmes à valeurs réelles, etc. Comme
+précédemment, les principaux désavantages de ces méthodes sont un coût
+numérique souvent bien supérieur pour trouver les estimations d'états, et pas
+de garantie de convergence en temps fini. Ici encore, on ne mentionne que
+quelques méthodes qui sont disponibles dans ADAO :
+
+- l'*optimisation sans dérivées (Derivative Free Optimization ou DFO)* (voir :ref:`section_ref_algorithm_DerivativeFreeOptimization`),
+- l'*optimisation par essaim de particules (Particle Swarm Optimization ou PSO)* (voir :ref:`section_ref_algorithm_ParticleSwarmOptimization`),
+- l'*évolution différentielle (Differential Evolution ou DE)* (voir :ref:`section_ref_algorithm_DifferentialEvolution`).
 
 Le lecteur intéressé par le sujet de l'optimisation pourra utilement commencer
 sa recherche grâce au point d'entrée [WikipediaMO]_.
index 1334045d80b06dac1c5ad78db6138251569eb09a..1d175153cfa3ce5ef90d26579b9a37c62c41051c 100644 (file)
@@ -27,7 +27,7 @@
 .. _section_tui:
 
 ================================================================================
-**[DocR]** Interface de programmation textuelle pour l'utilisateur (API/TUI)
+**[DocR]** Interface textuelle pour l'utilisateur (TUI/API)
 ================================================================================
 
 Cette section présente des méthodes avancées d'usage du module ADAO à l'aide de
@@ -500,15 +500,15 @@ Paramétrer le calcul, les sorties, etc.
 **setObserver** (*Variable, Template, String, Script, Info*)
     Cette commande permet de définir un *observer* sur une variable courante ou
     finale du calcul. On se reportera à la description des
-    :ref:`ref_observers_requirements` pour avoir leur liste et leur format, et
-    à la :ref:`section_reference` pour savoir quelles sont les quantités
-    observables. On définit comme un "*String*" le corps de l'*observer*, en
-    utilisant une chaîne de caractères incluant si nécessaire des sauts de
-    lignes. On recommande d'utiliser les patrons disponibles par l'argument
-    "*Template*". Dans le cas d'une définition par "*Script*", le fichier
-    indiqué doit contenir uniquement le corps de la fonction, comme décrit dans
-    les :ref:`ref_observers_requirements`. La variable "*Info*" contient une
-    chaîne de caractère d'information ou une chaine vide.
+    :ref:`section_ref_observers_requirements` pour avoir leur liste et leur
+    format, et à la :ref:`section_reference` pour savoir quelles sont les
+    quantités observables. On définit comme un "*String*" le corps de
+    l'*observer*, en utilisant une chaîne de caractères incluant si nécessaire
+    des sauts de lignes. On recommande d'utiliser les patrons disponibles par
+    l'argument "*Template*". Dans le cas d'une définition par "*Script*", le
+    fichier indiqué doit contenir uniquement le corps de la fonction, comme
+    décrit dans les :ref:`section_ref_observers_requirements`. La variable
+    "*Info*" contient une chaîne de caractère d'information ou une chaine vide.
 
 Effectuer le calcul
 +++++++++++++++++++