From: Jean-Philippe ARGAUD Date: Sat, 2 Mar 2019 10:18:08 +0000 (+0100) Subject: Updating documentation by review and snippets (1) X-Git-Tag: V9_3_0rc2~33 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=87812df0cee62f94293f253bdca6464332620fd0;p=modules%2Fadao.git Updating documentation by review and snippets (1) --- diff --git a/doc/fr/methodology.rst b/doc/fr/methodology.rst index 588749b..d5ca22c 100644 --- a/doc/fr/methodology.rst +++ b/doc/fr/methodology.rst @@ -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 index 0000000..57fc2af --- /dev/null +++ b/doc/fr/snippets/ASSIMILATION_STUDY.rst @@ -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 index 0000000..135751b --- /dev/null +++ b/doc/fr/snippets/CHECKING_STUDY.rst @@ -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 index 0000000..9c97e83 --- /dev/null +++ b/doc/fr/snippets/ControlInput.rst @@ -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 index 0000000..f0bafe4 --- /dev/null +++ b/doc/fr/snippets/Debug.rst @@ -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 index 0000000..242e10a --- /dev/null +++ b/doc/fr/snippets/InputVariables.rst @@ -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 index 0000000..1a6bf43 --- /dev/null +++ b/doc/fr/snippets/StudyName.rst @@ -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 index 0000000..af99bf5 --- /dev/null +++ b/doc/fr/snippets/StudyRepertory.rst @@ -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 index 0000000..f5d3922 --- /dev/null +++ b/doc/fr/snippets/UserDataInit.rst @@ -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 index 0000000..a11cb3a --- /dev/null +++ b/doc/fr/snippets/UserPostAnalysis.rst @@ -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. diff --git a/doc/fr/theory.rst b/doc/fr/theory.rst index 8cd7fbd..c932431 100644 --- a/doc/fr/theory.rst +++ b/doc/fr/theory.rst @@ -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]_. diff --git a/doc/fr/tui.rst b/doc/fr/tui.rst index 1334045..1d17515 100644 --- a/doc/fr/tui.rst +++ b/doc/fr/tui.rst @@ -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 +++++++++++++++++++