From 0c37861b0a95866500cd3c9a4beaadc491427762 Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Sun, 3 Mar 2019 22:06:22 +0100 Subject: [PATCH] Updating documentation by review and snippets (3) --- doc/fr/Makefile.am | 8 +- doc/fr/bibliography.rst | 8 +- doc/fr/{using.rst => gui_in_salome.rst} | 20 +- doc/fr/intro.rst | 41 ++- doc/fr/ref_algorithm_SamplingTest.rst | 147 +++------ doc/fr/ref_algorithm_TabuSearch.rst | 153 +++++++++ doc/fr/ref_algorithm_TangentTest.rst | 93 +++--- .../ref_algorithm_UnscentedKalmanFilter.rst | 143 ++++---- doc/fr/ref_assimilation_keywords.rst | 138 ++------ doc/fr/ref_checking_keywords.rst | 89 ++--- doc/fr/ref_covariance_requirements.rst | 43 ++- doc/fr/ref_observers_requirements.rst | 54 +-- doc/fr/ref_operator_requirements.rst | 311 +++++++++++------- doc/fr/ref_output_variables.rst | 2 +- doc/fr/reference.rst | 54 +-- doc/fr/snippets/AlphaBeta.rst | 15 + doc/fr/snippets/CrossOverProbability_CR.rst | 5 +- doc/fr/snippets/Header2Algo03AdOp.rst | 9 + doc/fr/snippets/Header2Algo03Chck.rst | 9 + .../snippets/JacobianMatrixAtBackground.rst | 10 + .../snippets/JacobianMatrixAtCurrentState.rst | 10 + doc/fr/snippets/JacobianMatrixAtOptimum.rst | 10 + doc/fr/snippets/KalmanGainAtOptimum.rst | 9 + doc/fr/snippets/LengthOfTabuList.rst | 10 + doc/fr/snippets/NoiseAddingProbability.rst | 9 + doc/fr/snippets/NoiseDistribution.rst | 10 + doc/fr/snippets/NoiseHalfRange.rst | 15 + .../NumberOfElementaryPerturbations.rst | 11 + doc/fr/snippets/OutputVariables.rst | 7 + doc/fr/snippets/SampleAsExplicitHyperCube.rst | 9 + .../SampleAsIndependantRandomVariables.rst | 14 + .../snippets/SampleAsMinMaxStepHyperCube.rst | 10 + doc/fr/snippets/SampleAsnUplet.rst | 8 + doc/fr/snippets/StandardDeviation.rst | 14 + doc/fr/tutorials_in_python.rst | 41 +++ .../{examples.rst => tutorials_in_salome.rst} | 16 +- src/daComposant/daAlgorithms/TabuSearch.py | 14 +- src/daComposant/daCore/BasicObjects.py | 2 +- 38 files changed, 956 insertions(+), 615 deletions(-) rename doc/fr/{using.rst => gui_in_salome.rst} (97%) create mode 100644 doc/fr/ref_algorithm_TabuSearch.rst create mode 100644 doc/fr/snippets/AlphaBeta.rst create mode 100644 doc/fr/snippets/Header2Algo03AdOp.rst create mode 100644 doc/fr/snippets/Header2Algo03Chck.rst create mode 100644 doc/fr/snippets/JacobianMatrixAtBackground.rst create mode 100644 doc/fr/snippets/JacobianMatrixAtCurrentState.rst create mode 100644 doc/fr/snippets/JacobianMatrixAtOptimum.rst create mode 100644 doc/fr/snippets/KalmanGainAtOptimum.rst create mode 100644 doc/fr/snippets/LengthOfTabuList.rst create mode 100644 doc/fr/snippets/NoiseAddingProbability.rst create mode 100644 doc/fr/snippets/NoiseDistribution.rst create mode 100644 doc/fr/snippets/NoiseHalfRange.rst create mode 100644 doc/fr/snippets/NumberOfElementaryPerturbations.rst create mode 100644 doc/fr/snippets/OutputVariables.rst create mode 100644 doc/fr/snippets/SampleAsExplicitHyperCube.rst create mode 100644 doc/fr/snippets/SampleAsIndependantRandomVariables.rst create mode 100644 doc/fr/snippets/SampleAsMinMaxStepHyperCube.rst create mode 100644 doc/fr/snippets/SampleAsnUplet.rst create mode 100644 doc/fr/snippets/StandardDeviation.rst create mode 100644 doc/fr/tutorials_in_python.rst rename doc/fr/{examples.rst => tutorials_in_salome.rst} (98%) diff --git a/doc/fr/Makefile.am b/doc/fr/Makefile.am index 2dcde68..abaecdf 100644 --- a/doc/fr/Makefile.am +++ b/doc/fr/Makefile.am @@ -26,11 +26,11 @@ include $(top_srcdir)/adm_local/make_common_starter.am DOCLANG = fr SPHINXOPTS = SPHINXBUILD = sphinx-build -PAPER = +PAPER = a4 BUILDDIR = $(top_builddir)/doc/build/$(DOCLANG) SRCDIR = $(top_srcdir)/doc/$(DOCLANG) -EXTRA_DIST = conf.py advanced.rst examples.rst index.rst intro.rst theory.rst using.rst \ +EXTRA_DIST = conf.py advanced.rst index.rst intro.rst theory.rst tutorials_in_salome.rst gui_in_salome.rst \ resources/ADAO.png \ resources/ADAO_small.png \ resources/ADAO_small_rouge.png \ @@ -71,8 +71,8 @@ clean-local: # Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter +PAPEROPT_a4 = -D latex_elements.papersize='a4paper' +PAPEROPT_letter = -D latex_elements.papersize='letterpaper' ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR) .PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest diff --git a/doc/fr/bibliography.rst b/doc/fr/bibliography.rst index a90b5b7..ee82854 100644 --- a/doc/fr/bibliography.rst +++ b/doc/fr/bibliography.rst @@ -47,10 +47,14 @@ Bibliographie .. [Chakraborty08] Chakraborty U.K., *Advances in differential evolution*, Studies in computational intelligence, Vol.143, Springer, 2008 -.. [Evensen94] Evensen G., *Sequential data assimilation with a nonlinear quasi-geostrophic model using monte carlo methods to forecast error statistics*, Journal of Geophysical Research, 99(C5), 10,143–10,162, 1994 +.. [Evensen94] Evensen G., *Sequential data assimilation with a nonlinear quasi-geostrophic model using Monte Carlo methods to forecast error statistics*, Journal of Geophysical Research, 99(C5), 10,143–10,162, 1994 .. [Evensen03] Evensen G., *The Ensemble Kalman Filter: theoretical formulation and practical implementation*, Seminar on Recent developments in data assimilation for atmosphere and ocean, ECMWF, 8 to 12 September 2003 +.. [Glover89] Glover F., *Tabu Search-Part I*, ORSA Journal on Computing, 1(2), pp.190-206, 1989 + +.. [Glover90] Glover F., *Tabu Search-Part II*, ORSA Journal on Computing, 2(1), pp.4-32, 1990 + .. [Ide97] Ide K., Courtier P., Ghil M., Lorenc A. C., *Unified notation for data assimilation: operational, sequential and variational*, Journal of the Meteorological Society of Japan, 75(1B), pp.181-189, 1997 .. [Johnson08] Johnson S. G., *The NLopt nonlinear-optimization package*, http://ab-initio.mit.edu/nlopt @@ -111,6 +115,8 @@ Bibliographie .. [WikipediaTI] Wikipedia, *Tikhonov regularization*, https://en.wikipedia.org/wiki/Tikhonov_regularization +.. [WikipediaTS] Wikipedia, *Tabu search*, https://en.wikipedia.org/wiki/Tabu_search + .. [WikipediaUKF] Wikipedia, *Unscented Kalman Filter*, https://en.wikipedia.org/wiki/Unscented_Kalman_filter .. [Zhu97] Zhu C., Byrd R. H., Nocedal J., *L-BFGS-B: Algorithm 778: L-BFGS-B, FORTRAN routines for large scale bound constrained optimization*, ACM Transactions on Mathematical Software, 23(4), pp.550-560, 1997 diff --git a/doc/fr/using.rst b/doc/fr/gui_in_salome.rst similarity index 97% rename from doc/fr/using.rst rename to doc/fr/gui_in_salome.rst index b23ec13..8aa54e0 100644 --- a/doc/fr/using.rst +++ b/doc/fr/gui_in_salome.rst @@ -21,10 +21,10 @@ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D -.. _section_using: +.. _section_gui_in_salome: ================================================================================ -**[DocU]** Utiliser le module ADAO +**[DocR]** Interface graphique pour l'utilisateur (GUI/EFICAS) ================================================================================ .. |eficas_new| image:: images/eficas_new.png @@ -49,7 +49,7 @@ fournis dans les chapitres suivants. Il est complété par la description détaillée de l'ensemble des commandes et mots-clés dans la section :ref:`section_reference`, par des procédures avancées d'usage dans la section :ref:`section_advanced`, et par des exemples dans la section -:ref:`section_examples`. +:ref:`section_tutorials_in_salome`. Procédure logique pour construire un cas ADAO --------------------------------------------- @@ -67,11 +67,11 @@ SALOME ou non. Fondamentalement, la procédure d'utilisation de ADAO comprend les étapes suivantes: - - :ref:`section_u_step1` - - :ref:`section_u_step2` - - :ref:`section_u_step3` - - :ref:`section_u_step4` - - :ref:`section_u_step5` +- :ref:`section_u_step1` +- :ref:`section_u_step2` +- :ref:`section_u_step3` +- :ref:`section_u_step4` +- :ref:`section_u_step5` Chaque étape est détaillée dans la section suivante. @@ -131,7 +131,7 @@ commandes ou les mots-clés obligatoires sont déjà présents, aucun d'eux ne p dans une liste de suggestions de ceux autorisés pour la commande principale, par exemple la commande "*ASSIMILATION_STUDY*". À titre d'exemple, on peut ajouter des paramètres dans le mot-clé "*AlgorithmParameters*", comme décrit dans la -dernière partie de la section :ref:`section_examples`. +dernière partie de la section :ref:`section_tutorials_in_salome`. A la fin de ces actions, lorsque tous les champs ou les mots-clés ont été correctement définis, chaque ligne de l'arborescence des commandes doit @@ -231,7 +231,7 @@ problème d'évaluation par assimilation de données ou par optimisation, notée Une telle méthode peut être utilisée pour imprimer les résultats, ou pour les convertir dans des structures qui peuvent être nécessaires à un post-processing natif ou externe à SALOME. Un exemple simple est disponible dans la section -:ref:`section_examples`. +:ref:`section_tutorials_in_salome`. .. _section_u_step5: diff --git a/doc/fr/intro.rst b/doc/fr/intro.rst index 5f0b842..748aa64 100644 --- a/doc/fr/intro.rst +++ b/doc/fr/intro.rst @@ -28,22 +28,29 @@ 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 -SALOME**. Le module ADAO fournit une interface à des algorithmes classiques -d'assimilation de données ou d'optimisation, et permet d'intégrer leur usage -dans une étude SALOME. Les modules de calcul ou de simulation doivent fournir -une ou plusieurs méthodes d'appel spécifiques afin d'être appelable dans le -cadre SALOME/ADAO, et tous les modules SALOME peuvent être utilisés grace à -l'intégration dans YACS de ADAO. - -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 à utiliser -et en fournissant une démarche 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 de type -"souris\&click" pour construire un cas ADAO valide et pour l'évaluer. +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 +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. 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, permettra l'extension de son domaine d'application. +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. diff --git a/doc/fr/ref_algorithm_SamplingTest.rst b/doc/fr/ref_algorithm_SamplingTest.rst index 61f69fb..e581a49 100644 --- a/doc/fr/ref_algorithm_SamplingTest.rst +++ b/doc/fr/ref_algorithm_SamplingTest.rst @@ -27,8 +27,8 @@ Algorithme de vérification "*SamplingTest*" ------------------------------------------- -Description -+++++++++++ +.. ------------------------------------ .. +.. include:: snippets/Header2Algo01.rst Cet algorithme permet d'établir les valeurs, liées à un état :math:`\mathbf{x}`, d'une fonctionnelle d'erreur :math:`J` quelconque de type :math:`L^1`, @@ -54,125 +54,80 @@ cours de calcul à l'aide des "*observer*" adaptés. Pour effectuer un échantillonnage distribué ou plus complexe, voir le module OPENTURNS disponible dans SALOME. -Commandes requises et optionnelles -++++++++++++++++++++++++++++++++++ +.. ------------------------------------ .. +.. include:: snippets/Header2Algo02.rst -Les commandes requises générales, disponibles dans l'interface en édition, sont -les suivantes: +.. include:: snippets/CheckingPoint.rst - .. include:: snippets/CheckingPoint.rst +.. include:: snippets/BackgroundError.rst - .. include:: snippets/BackgroundError.rst +.. include:: snippets/Observation.rst - .. include:: snippets/Observation.rst +.. include:: snippets/ObservationError.rst - .. include:: snippets/ObservationError.rst +.. include:: snippets/ObservationOperator.rst - .. include:: snippets/ObservationOperator.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo03Chck.rst -Les commandes optionnelles générales, disponibles dans l'interface en édition, -sont indiquées dans la :ref:`section_ref_checking_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les -options particulières, décrites ci-après, de l'algorithme. On se reportera à la -:ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette -commande. +.. include:: snippets/QualityCriterion.rst -Les options de l'algorithme sont les suivantes: -.. index:: single: SampleAsnUplet -.. index:: single: SampleAsExplicitHyperCube -.. index:: single: SampleAsMinMaxStepHyperCube -.. index:: single: SampleAsIndependantRandomVariables +.. include:: snippets/SampleAsExplicitHyperCube.rst - SampleAsnUplet - Cette clé décrit les points de calcul sous la forme d'une liste de n-uplets, - chaque n-uplet étant un état. +.. include:: snippets/SampleAsIndependantRandomVariables.rst - Exemple : - ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` pour 3 points dans un espace d'état de dimension 4 +.. include:: snippets/SampleAsMinMaxStepHyperCube.rst - SampleAsExplicitHyperCube - Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont on - donne la liste des échantillonnages explicites de chaque variable comme une - liste. C'est donc une liste de listes, chacune étant de taille - potentiellement différente. +.. include:: snippets/SampleAsnUplet.rst - Exemple : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` pour un espace d'état de dimension 2 +.. include:: snippets/SetDebug.rst - SampleAsMinMaxStepHyperCube - Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont on - donne la liste des échantillonnages implicites de chaque variable par un - triplet *[min,max,step]*. C'est donc une liste de la même taille que celle - de l'état. Les bornes sont incluses. +.. include:: snippets/SetSeed.rst - Exemple : - ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` pour un espace d'état de dimension 2 +StoreSupplementaryCalculations + .. index:: single: StoreSupplementaryCalculations - SampleAsIndependantRandomVariables - Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont - les points sur chaque axe proviennent de l'échantillonnage aléatoire - indépendant de la variable d'axe, selon la spécification de la - distribution, de ses paramètres et du nombre de points de l'échantillon, - sous la forme d'une liste ``['distribution', [parametres], nombre]`` pour - chaque axe. Les distributions possibles sont 'normal' de paramètres - (mean,std), 'lognormal' de paramètres (mean,sigma), 'uniform' de paramètres - (low,high), ou 'weibull' de paramètre (shape). C'est donc une liste de la - même taille que celle de l'état. + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs ou du stockage coûteux. La valeur par défaut est une liste vide, + aucune de ces variables n'étant calculée et stockée par défaut. Les noms + possibles sont dans la liste suivante : [ + "CostFunctionJ", + "CostFunctionJb", + "CostFunctionJo", + "CurrentState", + "InnovationAtCurrentState", + "SimulatedObservationAtCurrentState", + ]. - Exemple : - ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` pour un espace d'état de dimension 2 + Exemple : + ``{"StoreSupplementaryCalculations":["CostFunctionJ", "SimulatedObservationAtCurrentState"]}`` - .. include:: snippets/QualityCriterion.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo04.rst - .. include:: snippets/SetDebug.rst +.. include:: snippets/CostFunctionJ.rst - .. include:: snippets/SetSeed.rst +.. include:: snippets/CostFunctionJb.rst - StoreSupplementaryCalculations - .. index:: single: StoreSupplementaryCalculations +.. include:: snippets/CostFunctionJo.rst - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs ou du stockage coûteux. La valeur par défaut est une liste vide, - aucune de ces variables n'étant calculée et stockée par défaut. Les noms - possibles sont dans la liste suivante : ["CostFunctionJ", "CostFunctionJb", - "CostFunctionJo", "CurrentState", "InnovationAtCurrentState", - "SimulatedObservationAtCurrentState"]. +.. ------------------------------------ .. +.. include:: snippets/Header2Algo05.rst - Exemple : - ``{"StoreSupplementaryCalculations":["CostFunctionJ", "SimulatedObservationAtCurrentState"]}`` +.. include:: snippets/CurrentState.rst -Informations et variables disponibles à la fin de l'algorithme -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. include:: snippets/InnovationAtCurrentState.rst -En sortie, après exécution de l'algorithme, on dispose d'informations et de -variables issues du calcul. La description des -:ref:`section_ref_output_variables` indique la manière de les obtenir par la -méthode nommée ``get`` de la variable "*ADD*" du post-processing. Les variables -d'entrée, mises à disposition de l'utilisateur en sortie pour faciliter -l'écriture des procédures de post-processing, sont décrites dans -l':ref:`subsection_r_o_v_Inventaire`. +.. include:: snippets/SimulatedObservationAtCurrentState.rst -Les sorties non conditionnelles de l'algorithme sont les suivantes: +.. ------------------------------------ .. +.. include:: snippets/Header2Algo06.rst - .. include:: snippets/CostFunctionJ.rst +- :ref:`section_ref_algorithm_FunctionTest` +- :ref:`section_ref_algorithm_LocalSensitivityTest` - .. include:: snippets/CostFunctionJb.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo08.rst - .. include:: snippets/CostFunctionJo.rst - -Les sorties conditionnelles de l'algorithme sont les suivantes: - - .. include:: snippets/CurrentState.rst - - .. include:: snippets/InnovationAtCurrentState.rst - - .. include:: snippets/SimulatedObservationAtCurrentState.rst - -Voir aussi -++++++++++ - -Références vers d'autres sections : - - :ref:`section_ref_algorithm_FunctionTest` - -Références vers d'autres modules SALOME : - - OPENTURNS, voir le *Guide utilisateur du module OPENTURNS* dans le menu principal *Aide* de l'environnement SALOME +- OPENTURNS, voir le *Guide utilisateur du module OPENTURNS* dans le menu principal *Aide* de l'environnement SALOME diff --git a/doc/fr/ref_algorithm_TabuSearch.rst b/doc/fr/ref_algorithm_TabuSearch.rst new file mode 100644 index 0000000..501a4db --- /dev/null +++ b/doc/fr/ref_algorithm_TabuSearch.rst @@ -0,0 +1,153 @@ +.. + Copyright (C) 2008-2019 EDF R&D + + This file is part of SALOME ADAO module. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com + + Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D + +.. index:: single: TabuSearch +.. _section_ref_algorithm_TabuSearch: + +Algorithme de calcul "*TabuSearch*" +----------------------------------- + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo01.rst + +Cet algorithme réalise une estimation d'état par minimisation d'une +fonctionnelle d'écart :math:`J` sans gradient. C'est une méthode qui n'utilise +pas les dérivées de la fonctionnelle d'écart. Elle entre, par exemple, dans la +même catégorie que l':ref:`section_ref_algorithm_DerivativeFreeOptimization`, +l':ref:`section_ref_algorithm_ParticleSwarmOptimization` ou +l':ref:`section_ref_algorithm_DifferentialEvolution`. + +C'est une méthode d'optimisation permettant la recherche du minimum global d'une +fonctionnelle d'erreur :math:`J` quelconque de type :math:`L^1`, :math:`L^2` ou +:math:`L^{\infty}`, avec ou sans pondérations. La fonctionnelle d'erreur par +défaut est celle de moindres carrés pondérés augmentés, classiquement utilisée +en assimilation de données. + +Elle fonctionne par exploration aléatoire itérative du voisinage du point +courant, pour en choisir l'état qui minimise la fonctionnelle d'écart. Pour +éviter de revenir dans un point déjà exploré, le mécanisme de mémoire de +l'algorithme permet d'interdire (d'où le nom de *tabou*) le retour dans les +derniers états explorés. Les positions déjà explorées sont conservées dans une +liste de longueur finie. + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo02.rst + +.. include:: snippets/Background.rst + +.. include:: snippets/BackgroundError.rst + +.. include:: snippets/Observation.rst + +.. include:: snippets/ObservationError.rst + +.. include:: snippets/ObservationOperator.rst + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo03AdOp.rst + +.. include:: snippets/LengthOfTabuList.rst + +.. include:: snippets/MaximumNumberOfSteps_50.rst + +.. include:: snippets/NoiseAddingProbability.rst + +.. include:: snippets/NoiseDistribution.rst + +.. include:: snippets/NoiseHalfRange.rst + +.. include:: snippets/NumberOfElementaryPerturbations.rst + +.. include:: snippets/QualityCriterion.rst + +.. include:: snippets/SetSeed.rst + +.. include:: snippets/StandardDeviation.rst + +StoreSupplementaryCalculations + .. index:: single: StoreSupplementaryCalculations + + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs ou du stockage coûteux. La valeur par défaut est une liste vide, + aucune de ces variables n'étant calculée et stockée par défaut. Les noms + possibles sont dans la liste suivante : [ + "BMA", + "OMA", + "OMB", + "CurrentState", + "CostFunctionJ", + "CostFunctionJb", + "CostFunctionJo", + "Innovation", + "SimulatedObservationAtBackground", + "SimulatedObservationAtCurrentState", + "SimulatedObservationAtOptimum", + ]. + + Exemple : + ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}`` + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo04.rst + +.. include:: snippets/Analysis.rst + +.. include:: snippets/CostFunctionJ.rst + +.. include:: snippets/CostFunctionJb.rst + +.. include:: snippets/CostFunctionJo.rst + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo05.rst + +.. include:: snippets/BMA.rst + +.. include:: snippets/OMA.rst + +.. include:: snippets/OMB.rst + +.. include:: snippets/CurrentState.rst + +.. include:: snippets/Innovation.rst + +.. include:: snippets/SimulatedObservationAtBackground.rst + +.. include:: snippets/SimulatedObservationAtCurrentState.rst + +.. include:: snippets/SimulatedObservationAtOptimum.rst + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo06.rst + +- :ref:`section_ref_algorithm_DerivativeFreeOptimization` +- :ref:`section_ref_algorithm_DifferentialEvolution` +- :ref:`section_ref_algorithm_ParticleSwarmOptimization` + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo07.rst + +- [Glover89]_ +- [Glover90]_ +- [WikipediaTS]_ diff --git a/doc/fr/ref_algorithm_TangentTest.rst b/doc/fr/ref_algorithm_TangentTest.rst index e62b8d1..3152eef 100644 --- a/doc/fr/ref_algorithm_TangentTest.rst +++ b/doc/fr/ref_algorithm_TangentTest.rst @@ -27,8 +27,8 @@ Algorithme de vérification "*TangentTest*" ------------------------------------------ -Description -+++++++++++ +.. ------------------------------------ .. +.. include:: snippets/Header2Algo01.rst Cet algorithme permet de vérifier la qualité de l'opérateur tangent, en calculant un résidu dont les propriétés théoriques sont connues. @@ -53,72 +53,57 @@ ce que l'on atteigne la précision du calcul. On prend :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` et :math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` est le code de calcul. -Commandes requises et optionnelles -++++++++++++++++++++++++++++++++++ +.. ------------------------------------ .. +.. include:: snippets/Header2Algo02.rst -Les commandes requises générales, disponibles dans l'interface en édition, sont -les suivantes: +.. include:: snippets/CheckingPoint.rst - .. include:: snippets/CheckingPoint.rst +.. include:: snippets/ObservationOperator.rst - .. include:: snippets/ObservationOperator.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo03Chck.rst -Les commandes optionnelles générales, disponibles dans l'interface en édition, -sont indiquées dans la :ref:`section_ref_checking_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les -options particulières, décrites ci-après, de l'algorithme. On se reportera à la -:ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette -commande. +.. include:: snippets/AmplitudeOfInitialDirection.rst -Les options de l'algorithme sont les suivantes: +.. include:: snippets/EpsilonMinimumExponent.rst - .. include:: snippets/AmplitudeOfInitialDirection.rst +.. include:: snippets/InitialDirection.rst - .. include:: snippets/EpsilonMinimumExponent.rst +.. include:: snippets/SetSeed.rst - .. include:: snippets/InitialDirection.rst +StoreSupplementaryCalculations + .. index:: single: StoreSupplementaryCalculations - .. include:: snippets/SetSeed.rst + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs ou du stockage coûteux. La valeur par défaut est une liste vide, + aucune de ces variables n'étant calculée et stockée par défaut. Les noms + possibles sont dans la liste suivante : [ + "CurrentState", + "Residu", + "SimulatedObservationAtCurrentState", + ]. - StoreSupplementaryCalculations - .. index:: single: StoreSupplementaryCalculations + Exemple : + ``{"StoreSupplementaryCalculations":["CurrentState"]}`` - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs ou du stockage coûteux. La valeur par défaut est une liste vide, - aucune de ces variables n'étant calculée et stockée par défaut. Les noms - possibles sont dans la liste suivante : ["CurrentState", "Residu", - "SimulatedObservationAtCurrentState"]. +.. ------------------------------------ .. +.. include:: snippets/Header2Algo04.rst - Exemple : - ``{"StoreSupplementaryCalculations":["CurrentState"]}`` +.. include:: snippets/Residu.rst -Informations et variables disponibles à la fin de l'algorithme -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. ------------------------------------ .. +.. include:: snippets/Header2Algo05.rst -En sortie, après exécution de l'algorithme, on dispose d'informations et de -variables issues du calcul. La description des -:ref:`section_ref_output_variables` indique la manière de les obtenir par la -méthode nommée ``get`` de la variable "*ADD*" du post-processing. Les variables -d'entrée, mises à disposition de l'utilisateur en sortie pour faciliter -l'écriture des procédures de post-processing, sont décrites dans -l':ref:`subsection_r_o_v_Inventaire`. +.. include:: snippets/CurrentState.rst -Les sorties non conditionnelles de l'algorithme sont les suivantes: +.. include:: snippets/SimulatedObservationAtCurrentState.rst - .. include:: snippets/Residu.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo06.rst -Les sorties conditionnelles de l'algorithme sont les suivantes: - - .. include:: snippets/CurrentState.rst - - .. include:: snippets/SimulatedObservationAtCurrentState.rst - -Voir aussi -++++++++++ - -Références vers d'autres sections : - - :ref:`section_ref_algorithm_FunctionTest` - - :ref:`section_ref_algorithm_LinearityTest` - - :ref:`section_ref_algorithm_AdjointTest` - - :ref:`section_ref_algorithm_GradientTest` +- :ref:`section_ref_algorithm_FunctionTest` +- :ref:`section_ref_algorithm_LinearityTest` +- :ref:`section_ref_algorithm_AdjointTest` +- :ref:`section_ref_algorithm_GradientTest` +- :ref:`section_ref_algorithm_LocalSensitivityTest` diff --git a/doc/fr/ref_algorithm_UnscentedKalmanFilter.rst b/doc/fr/ref_algorithm_UnscentedKalmanFilter.rst index 22e59a3..bddd0c8 100644 --- a/doc/fr/ref_algorithm_UnscentedKalmanFilter.rst +++ b/doc/fr/ref_algorithm_UnscentedKalmanFilter.rst @@ -27,8 +27,8 @@ Algorithme de calcul "*UnscentedKalmanFilter*" ---------------------------------------------- -Description -+++++++++++ +.. ------------------------------------ .. +.. include:: snippets/Header2Algo01.rst Cet algorithme réalise une estimation de l'état d'un système dynamique par un filtre de Kalman "unscented", permettant d'éviter de devoir calculer les @@ -47,116 +47,93 @@ l':ref:`section_ref_algorithm_KalmanFilter`, qui sont souvent largement moins coûteux en évaluation sur de petits systèmes. On peut vérifier la linéarité des opérateurs à l'aide de l':ref:`section_ref_algorithm_LinearityTest`. -Commandes requises et optionnelles -++++++++++++++++++++++++++++++++++ +.. ------------------------------------ .. +.. include:: snippets/Header2Algo02.rst -Les commandes requises générales, disponibles dans l'interface en édition, sont -les suivantes: +.. include:: snippets/Background.rst - .. include:: snippets/Background.rst +.. include:: snippets/BackgroundError.rst - .. include:: snippets/BackgroundError.rst +.. include:: snippets/EvolutionError.rst - .. include:: snippets/EvolutionError.rst +.. include:: snippets/EvolutionModel.rst - .. include:: snippets/EvolutionModel.rst +.. include:: snippets/Observation.rst - .. include:: snippets/Observation.rst +.. include:: snippets/ObservationError.rst - .. include:: snippets/ObservationError.rst +.. include:: snippets/ObservationOperator.rst - .. include:: snippets/ObservationOperator.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo03AdOp.rst -Les commandes optionnelles générales, disponibles dans l'interface en édition, -sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les -options particulières, décrites ci-après, de l'algorithme. On se reportera à la -:ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette -commande. +.. include:: snippets/BoundsWithExtremes.rst -Les options de l'algorithme sont les suivantes: +.. include:: snippets/ConstrainedBy.rst - .. include:: snippets/BoundsWithExtremes.rst +.. include:: snippets/EstimationOf.rst - .. include:: snippets/ConstrainedBy.rst +.. include:: snippets/AlphaBeta.rst - .. include:: snippets/EstimationOf.rst +StoreSupplementaryCalculations + .. index:: single: StoreSupplementaryCalculations - Alpha, Beta, Kappa, Reconditioner - .. index:: single: Alpha - .. index:: single: Beta - .. index:: single: Kappa - .. index:: single: Reconditioner + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs ou du stockage coûteux. La valeur par défaut est une liste vide, + aucune de ces variables n'étant calculée et stockée par défaut. Les noms + possibles sont dans la liste suivante : [ + "APosterioriCorrelations", + "APosterioriCovariance", + "APosterioriStandardDeviations", + "APosterioriVariances", + "BMA", + "CostFunctionJ", + "CostFunctionJb", + "CostFunctionJo", + "CurrentState", + "Innovation", + ]. - Ces clés sont des paramètres de mise à l'échelle interne. "Alpha" requiert - une valeur comprise entre 1.e-4 et 1. "Beta" a une valeur optimale de 2 pour - une distribution *a priori* gaussienne. "Kappa" requiert une valeur entière, - dont la bonne valeur par défaut est obtenue en la mettant à 0. - "Reconditioner" requiert une valeur comprise entre 1.e-3 et 10, son défaut - étant 1. + Exemple : + ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}`` - Exemple : - ``{"Alpha":1,"Beta":2,"Kappa":0,"Reconditioner":1}`` +.. ------------------------------------ .. +.. include:: snippets/Header2Algo04.rst - StoreSupplementaryCalculations +.. include:: snippets/Analysis.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo05.rst - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs ou du stockage coûteux. La valeur par défaut est une liste vide, - aucune de ces variables n'étant calculée et stockée par défaut. Les noms - possibles sont dans la liste suivante : ["APosterioriCorrelations", - "APosterioriCovariance", "APosterioriStandardDeviations", - "APosterioriVariances", "BMA", "CostFunctionJ", "CostFunctionJb", - "CostFunctionJo", "CurrentState", "Innovation"]. +.. include:: snippets/APosterioriCorrelations.rst - Exemple : - ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}`` +.. include:: snippets/APosterioriCovariance.rst -Informations et variables disponibles à la fin de l'algorithme -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. include:: snippets/APosterioriStandardDeviations.rst -En sortie, après exécution de l'algorithme, on dispose d'informations et de -variables issues du calcul. La description des -:ref:`section_ref_output_variables` indique la manière de les obtenir par la -méthode nommée ``get`` de la variable "*ADD*" du post-processing. Les variables -d'entrée, mises à disposition de l'utilisateur en sortie pour faciliter -l'écriture des procédures de post-processing, sont décrites dans -l':ref:`subsection_r_o_v_Inventaire`. +.. include:: snippets/APosterioriVariances.rst -Les sorties non conditionnelles de l'algorithme sont les suivantes: +.. include:: snippets/BMA.rst - .. include:: snippets/Analysis.rst +.. include:: snippets/CostFunctionJ.rst -Les sorties conditionnelles de l'algorithme sont les suivantes: +.. include:: snippets/CostFunctionJb.rst - .. include:: snippets/APosterioriCorrelations.rst +.. include:: snippets/CostFunctionJo.rst - .. include:: snippets/APosterioriCovariance.rst +.. include:: snippets/CurrentState.rst - .. include:: snippets/APosterioriStandardDeviations.rst +.. include:: snippets/Innovation.rst - .. include:: snippets/APosterioriVariances.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo06.rst - .. include:: snippets/BMA.rst +- :ref:`section_ref_algorithm_KalmanFilter` +- :ref:`section_ref_algorithm_ExtendedKalmanFilter` +- :ref:`section_ref_algorithm_EnsembleKalmanFilter` - .. include:: snippets/CostFunctionJ.rst +.. ------------------------------------ .. +.. include:: snippets/Header2Algo07.rst - .. include:: snippets/CostFunctionJb.rst - - .. include:: snippets/CostFunctionJo.rst - - .. include:: snippets/CurrentState.rst - - .. include:: snippets/Innovation.rst - -Voir aussi -++++++++++ - -Références vers d'autres sections : - - :ref:`section_ref_algorithm_KalmanFilter` - - :ref:`section_ref_algorithm_ExtendedKalmanFilter` - - :ref:`section_ref_algorithm_EnsembleKalmanFilter` - -Références bibliographiques : - - [WikipediaUKF]_ +- [WikipediaUKF]_ diff --git a/doc/fr/ref_assimilation_keywords.rst b/doc/fr/ref_assimilation_keywords.rst index c75bbdf..a1d23fd 100644 --- a/doc/fr/ref_assimilation_keywords.rst +++ b/doc/fr/ref_assimilation_keywords.rst @@ -27,21 +27,6 @@ Liste des commandes et mots-clés pour un cas d'assimilation de données ou d'optimisation ---------------------------------------------------------------------------------------- -.. index:: single: Algorithm -.. index:: single: AlgorithmParameters -.. index:: single: ControlInput -.. index:: single: Debug -.. index:: single: InputVariables -.. index:: single: Observer -.. index:: single: Observers -.. index:: single: Observer Template -.. index:: single: OutputVariables -.. index:: single: StudyName -.. index:: single: StudyRepertory -.. index:: single: UserDataInit -.. index:: single: UserPostAnalysis -.. index:: single: UserPostAnalysis Template - Ce jeu de commandes est lié à la description d'un cas de calcul, qui est une procédure d'*Assimilation de Données* ou d'*Optimisation*. Les termes sont classés par ordre alphabétique, sauf le premier, qui décrit le choix entre le @@ -49,91 +34,38 @@ calcul ou la vérification. Les différentes commandes sont les suivantes: - **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. - - AlgorithmParameters - *Commande obligatoire*. Elle définit l'algorithme d'assimilation de données - ou d'optimisation choisi par le mot-clé "*Algorithm*", et ses éventuels - paramètres optionnels. Les choix d'algorithmes sont disponibles à travers - l'interface graphique. Il existe par exemple le "3DVAR", le "Blue"... Chaque - algorithme est défini, plus loin, par une sous-section spécifique. De - manière facultative, la commande permet aussi d'ajouter des paramètres pour - contrôler l'algorithme. Leurs valeurs sont définies explicitement ou dans un - objet de type "*Dict*". On se reportera à la - :ref:`section_ref_options_Algorithm_Parameters` pour l'usage détaillé de - cette partie de la commande. - - .. include:: snippets/Background.rst - - .. include:: snippets/BackgroundError.rst - - 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 ''. - - 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). - - .. include:: snippets/EvolutionError.rst - - .. include:: snippets/EvolutionModel.rst - - 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. - - .. include:: snippets/Observation.rst - - .. include:: snippets/ObservationError.rst - - .. include:: snippets/ObservationOperator.rst - - Observers - *Commande optionnelle*. Elle permet de définir des observateurs internes, - qui sont des fonctions liées à une variable particulière, qui sont exécutées - chaque fois que cette variable est modifiée. C'est une manière pratique de - suivre des variables d'intérêt durant le processus d'assimilation de données - ou d'optimisation, en l'affichant ou en la traçant, etc. Des exemples - courants (squelettes) sont fournis pour aider l'utilisateur ou pour - faciliter l'élaboration d'un cas. - - OutputVariables - *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des - variables physiques qui sont rassemblées dans le vecteur d'observation. - Cette information est destinée à être utilisée dans le traitement - algorithmique interne des données. - - 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. - - 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. - - 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. - - 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. +.. include:: snippets/ASSIMILATION_STUDY.rst + +.. include:: snippets/AlgorithmParameters.rst + +.. include:: snippets/Background.rst + +.. include:: snippets/BackgroundError.rst + +.. include:: snippets/ControlInput.rst + +.. include:: snippets/Debug.rst + +.. include:: snippets/EvolutionError.rst + +.. include:: snippets/EvolutionModel.rst + +.. include:: snippets/InputVariables.rst + +.. include:: snippets/Observation.rst + +.. include:: snippets/ObservationError.rst + +.. include:: snippets/ObservationOperator.rst + +.. include:: snippets/Observers.rst + +.. include:: snippets/OutputVariables.rst + +.. include:: snippets/StudyName.rst + +.. include:: snippets/StudyRepertory.rst + +.. include:: snippets/UserDataInit.rst + +.. include:: snippets/UserPostAnalysis.rst diff --git a/doc/fr/ref_checking_keywords.rst b/doc/fr/ref_checking_keywords.rst index dbbaaad..a912cea 100644 --- a/doc/fr/ref_checking_keywords.rst +++ b/doc/fr/ref_checking_keywords.rst @@ -27,16 +27,6 @@ Liste des commandes et mots-clés pour un cas de vérification ------------------------------------------------------------ -.. index:: single: Algorithm -.. index:: single: AlgorithmParameters -.. index:: single: Debug -.. index:: single: Observer -.. index:: single: Observers -.. index:: single: Observer Template -.. index:: single: StudyName -.. index:: single: StudyRepertory -.. index:: single: UserDataInit - 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, @@ -44,59 +34,26 @@ sauf le premier, qui décrit le choix entre le calcul ou la vérification. Les différentes commandes sont les suivantes: - **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. - - AlgorithmParameters - *Commande obligatoire*. Elle définit l'algorithme de test choisi par le - mot-clé "*Algorithm*", et ses éventuels paramètres optionnels. Les choix - d'algorithmes sont disponibles à travers l'interface graphique. Il existe - par exemple le "FunctionTest", le "GradientTest"... Chaque algorithme est - défini, plus loin, par une sous-section spécifique. De manière facultative, - la commande permet aussi d'ajouter des paramètres pour contrôler - l'algorithme. Leurs valeurs sont définies explicitement ou dans un objet de - type "*Dict*". On se reportera à la - :ref:`section_ref_options_Algorithm_Parameters` pour l'usage détaillé de - cette partie de la commande. - - .. include:: snippets/CheckingPoint.rst - - .. include:: snippets/BackgroundError.rst - - 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). - - .. include:: snippets/Observation.rst - - .. include:: snippets/ObservationError.rst - - .. include:: snippets/ObservationOperator.rst - - Observers - *Commande optionnelle*. Elle permet de définir des observateurs internes, - qui sont des fonctions liées à une variable particulière, qui sont exécutées - chaque fois que cette variable est modifiée. C'est une manière pratique de - suivre des variables d'intérêt durant le processus d'assimilation de données - ou d'optimisation, en l'affichant ou en la traçant, etc. Des exemples - courants (squelettes) sont fournis pour aider l'utilisateur ou pour - faciliter l'élaboration d'un cas. - - 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. - - 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. - - 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. +.. include:: snippets/CHECKING_STUDY.rst + +.. include:: snippets/AlgorithmParameters.rst + +.. include:: snippets/CheckingPoint.rst + +.. include:: snippets/BackgroundError.rst + +.. include:: snippets/Debug.rst + +.. include:: snippets/Observation.rst + +.. include:: snippets/ObservationError.rst + +.. include:: snippets/ObservationOperator.rst + +.. include:: snippets/Observers.rst + +.. include:: snippets/StudyName.rst + +.. include:: snippets/StudyRepertory.rst + +.. include:: snippets/UserDataInit.rst diff --git a/doc/fr/ref_covariance_requirements.rst b/doc/fr/ref_covariance_requirements.rst index 6724f0c..23ad49b 100644 --- a/doc/fr/ref_covariance_requirements.rst +++ b/doc/fr/ref_covariance_requirements.rst @@ -26,19 +26,22 @@ Exigences pour décrire les matrices de covariance ------------------------------------------------- +.. index:: single: setBackgroundError +.. index:: single: setObservationError +.. index:: single: setEvolutionError .. index:: single: matrice de covariance .. index:: single: covariances d'erreurs d'ébauche .. index:: single: covariances d'erreurs d'observation .. index:: single: covariances -De manière générale, une matrice de covariance (ou une matrice de -variance-covariance) doit être carrée, symétrique, semi-définie positive. Chacun -de ses termes décrit la covariance des deux variables aléatoires correspondantes -à sa position dans la matrice. La forme normalisée de la covariance est la -corrélation linéaire. On peut écrire la relation suivante, entre une matrice de -covariance :math:`\mathbf{M}` et ses matrices correspondantes de corrélation -:math:`\mathbf{C}` (matrice pleine) et d'écart-type :math:`\mathbf{\Sigma}` -(matrice diagonale): +De manière générale, une matrice de variances-covariances, généralement appelée +matrice de covariance, doit être carrée, symétrique et semi-définie positive. +Chacun de ses termes décrit la covariance des deux variables aléatoires +correspondantes à sa position dans la matrice. La forme normalisée de la +covariance est la corrélation linéaire. On peut écrire la relation suivante, +entre une matrice de covariance :math:`\mathbf{M}` et ses matrices +correspondantes de corrélation :math:`\mathbf{C}` (matrice pleine) et +d'écart-type :math:`\mathbf{\Sigma}` (matrice diagonale): .. math:: \mathbf{M} = \mathbf{\Sigma} * \mathbf{C} * \mathbf{\Sigma} @@ -47,9 +50,10 @@ procédures d'assimilation de données ou d'optimisation. Les principales sont l matrice de covariance des erreurs d'ébauche, notée :math:`\mathbf{B}`, et la matrice de covariance des erreurs d'observation, notée :math:`\mathbf{R}`. -Il y a 3 méthodes pratiques pour l'utilisateur pour fournir une matrice de -covariance. La méthode est choisie à l'aide du mot-clé "*INPUT_TYPE*" de chaque -matrice de covariance, comme montré dans la figure qui suit : +Dans l'interface graphique EFICAS d'ADAO, il y a 3 méthodes pratiques pour +l'utilisateur pour fournir une matrice de covariance. La méthode est choisie à +l'aide du mot-clé "*INPUT_TYPE*" de chaque matrice de covariance, comme montré +dans la figure qui suit : .. eficas_covariance_matrix: .. image:: images/eficas_covariance_matrix.png @@ -58,6 +62,15 @@ matrice de covariance, comme montré dans la figure qui suit : .. centered:: **Choisir la représentation d'une matrice de covariance** +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 adéquate +"*setBackgroundError*", "*setObservationError*" ou "*setEvolutionError*" selon +la grandeur physique à définir. Les autres arguments "*Matrix*", +"*ScalarSparseMatrix*" et "*DiagonalSparseMatrix*" de la commande permettent de +la définir comme décrit dans les sous-parties qui suivent. Ces informations +peuvent aussi être fournies dans un script contenu en fichier externe (argument +"*Script*"). + Première forme matricielle : utiliser la représentation "*Matrix*" ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -69,7 +82,7 @@ Première forme matricielle : utiliser la représentation "*Matrix*" La première forme est le défaut, et c'est la plus générale. La matrice de covariance :math:`\mathbf{M}` doit être entièrement spécifiée. Même si la matrice est symétrique par nature, la totalité de la matrice :math:`\mathbf{M}` -doit être donnée. +doit être fournie. .. math:: \mathbf{M} = \begin{pmatrix} m_{11} & m_{12} & \cdots & m_{1n} \\ @@ -117,7 +130,8 @@ décrite dans un fichier de script Python par:: BackgroundError = 1. -ou, mieux, par un "*String*" directement dans le cas ADAO. +ou, mieux, par un argument "*String*" directement dans le cas graphique ou +textuel ADAO. Troisième forme matricielle : utiliser la représentation "*DiagonalSparseMatrix*" +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -153,3 +167,6 @@ script Python par:: ou:: BackgroundError = numpy.ones(...) + +De la même manière que précédemment, on peut aussi définir cette matrice par +un "*String*" directement dans le cas graphique ou textuel ADAO. diff --git a/doc/fr/ref_observers_requirements.rst b/doc/fr/ref_observers_requirements.rst index a969e43..de44198 100644 --- a/doc/fr/ref_observers_requirements.rst +++ b/doc/fr/ref_observers_requirements.rst @@ -21,24 +21,26 @@ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D -.. _ref_observers_requirements: +.. _section_ref_observers_requirements: Exigences pour les fonctions décrivant un "*observer*" ------------------------------------------------------ .. index:: single: Observer +.. index:: single: setObserver .. index:: single: Observer Template -Certaines variables spéciales, internes à l'optimisation, utilisées au cours des -calculs, peuvent être surveillées durant un calcul ADAO. Ces variables peuvent -être affichées, tracées, enregistrées, etc. C'est réalisable en utilisant des -"*observer*", parfois aussi appelés des "callback". Ce sont des scripts Python, -qui sont chacun associés à une variable donnée. Ils sont activés à chaque -modification de la variable. +Certaines variables spéciales, internes à l'optimisation et utilisées au cours +des calculs, peuvent être surveillées durant un calcul ADAO. Ces variables +peuvent être affichées, tracées, enregistrées, etc. par l'utilisateur. C'est +réalisable en utilisant des "*observer*", parfois aussi appelés des "callback". +Ce sont des scripts Python, qui sont chacun associés à une variable donnée, et +qui sont automatiquement activés à chaque modification de la variable. -Il y a 3 méthodes pratiques pour intégrer un "*observer*" dans un cas ADAO. La -méthode est choisie à l'aide du mot-clé "*NodeType*" de chaque entrée de type -"*observer*", comme montré dans la figure qui suit : +Dans l'interface graphique EFICAS d'ADAO, il y a 3 méthodes pratiques pour +intégrer un "*observer*" dans un cas ADAO. La méthode est choisie à l'aide du +mot-clé "*NodeType*" de chaque entrée de type "*observer*", comme montré dans +la figure qui suit : .. eficas_observer_nodetype: .. image:: images/eficas_observer_nodetype.png @@ -50,11 +52,21 @@ méthode est choisie à l'aide du mot-clé "*NodeType*" de chaque entrée de typ 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. 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, 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 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. + +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 +"*setObserver*" appliquée pour une variable données indiquée dans l'argument +"*Variable*". Les autres arguments de cette commande permettent de le définir +soit comme un template (argument "*Template*") désignant l'un des scripts +détaillés dans la partie :ref:`section_ref_observers_templates`, soit comme un +script explicite (argument "*String*"), soit comme un script contenu dans un +fichier externe (argument "*Script*"). Forme générale d'un script permettant de définir un *observer* ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -81,6 +93,8 @@ de traitement complexe, d'analyse statistique, etc. On donne ci-après l'identifiant et le contenu de chaque modèle disponible. +.. _section_ref_observers_templates: + Inventaire des modèles d'*observer* disponibles ("*Template*") ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -164,7 +178,7 @@ Enregistre la série des valeurs de la variable dans un fichier du répertoire ' Modèle **ValuePrinterAndSaver** : .................................. -Imprime sur la sortie standard et, en même temps enregistre dans un fichier, la valeur courante de la variable. +Imprime sur la sortie standard et, en même temps enregistre dans un fichier du répertoire '/tmp', la valeur courante de la variable. :: @@ -186,7 +200,7 @@ Imprime sur la sortie standard et, en même temps enregistre dans un fichier, la Modèle **ValueIndexPrinterAndSaver** : ....................................... -Imprime sur la sortie standard et, en même temps enregistre dans un fichier, la valeur courante de la variable, en ajoutant son index. +Imprime sur la sortie standard et, en même temps enregistre dans un fichier du répertoire '/tmp', la valeur courante de la variable, en ajoutant son index. :: @@ -208,7 +222,7 @@ Imprime sur la sortie standard et, en même temps enregistre dans un fichier, la Modèle **ValueSeriePrinterAndSaver** : ....................................... -Imprime sur la sortie standard et, en même temps, enregistre dans un fichier la série des valeurs de la variable. +Imprime sur la sortie standard et, en même temps, enregistre dans un fichier du répertoire '/tmp', la série des valeurs de la variable. :: @@ -320,7 +334,7 @@ Imprime sur la sortie standard et, en même temps, affiche graphiquement avec Gn Modèle **ValuePrinterSaverAndGnuPlotter** : ............................................ -Imprime sur la sortie standard et, en même temps, enregistre dans un fichier et affiche graphiquement la valeur courante de la variable . +Imprime sur la sortie standard et, en même temps, enregistre dans un fichier du répertoire '/tmp' et affiche graphiquement la valeur courante de la variable . :: @@ -353,7 +367,7 @@ Imprime sur la sortie standard et, en même temps, enregistre dans un fichier et Modèle **ValueSeriePrinterSaverAndGnuPlotter** : ................................................. -Imprime sur la sortie standard et, en même temps, enregistre dans un fichier et affiche graphiquement la série des valeurs de la variable. +Imprime sur la sortie standard et, en même temps, enregistre dans un fichier du répertoire '/tmp' et affiche graphiquement la série des valeurs de la variable. :: diff --git a/doc/fr/ref_operator_requirements.rst b/doc/fr/ref_operator_requirements.rst index e7c14e0..d7c64ea 100644 --- a/doc/fr/ref_operator_requirements.rst +++ b/doc/fr/ref_operator_requirements.rst @@ -26,6 +26,10 @@ Exigences pour les fonctions décrivant un opérateur --------------------------------------------------- +.. index:: single: setObservationOperator +.. index:: single: setEvolutionModel +.. index:: single: setControlModel + Les opérateurs d'observation et d'évolution sont nécessaires pour mettre en oeuvre les procédures d'assimilation de données ou d'optimisation. Ils comprennent la simulation physique par des calculs numériques, mais aussi le @@ -34,62 +38,79 @@ L'opérateur d'évolution est ici considéré dans sa forme incrémentale, qui représente la transition entre deux états successifs, et il est alors similaire à l'opérateur d'observation. -Schématiquement, un opérateur doit donner une solution étant donné les -paramètres d'entrée. Une partie des paramètres d'entrée peut être modifiée au -cours de la procédure d'optimisation. Ainsi, la représentation mathématique d'un -tel processus est une fonction. Il a été brièvement décrit dans la section -:ref:`section_theory` et il est généralisée ici par la relation: +Schématiquement, un opérateur :math:`O` a pour objet de restituer une solution +pour des paramètres d'entrée spécifiés. Une partie des paramètres d'entrée peut +être modifiée au cours de la procédure d'optimisation. Ainsi, la représentation +mathématique d'un tel processus est une fonction. Il a été brièvement décrit +dans la section :ref:`section_theory` et il est généralisé ici par la relation: .. math:: \mathbf{y} = O( \mathbf{x} ) -entre les pseudo-observations :math:`\mathbf{y}` et les paramètres -:math:`\mathbf{x}` en utilisant l'opérateur d'observation ou d'évolution -:math:`O`. La même représentation fonctionnelle peut être utilisée pour le -modèle linéaire tangent :math:`\mathbf{O}` de :math:`O` et son adjoint -:math:`\mathbf{O}^*`, qui sont aussi requis par certains algorithmes +entre les pseudo-observations en sortie :math:`\mathbf{y}` et les paramètres +d'entrée :math:`\mathbf{x}` en utilisant l'opérateur d'observation ou +d'évolution :math:`O`. La même représentation fonctionnelle peut être utilisée +pour le modèle linéaire tangent :math:`\mathbf{O}` de :math:`O` et son adjoint +:math:`\mathbf{O}^*` qui sont aussi requis par certains algorithmes d'assimilation de données ou d'optimisation. En entrée et en sortie de ces opérateurs, les variables :math:`\mathbf{x}` et -:math:`\mathbf{y}` ou leurs incréments sont mathématiquement des vecteurs, et -ils sont donc passés comme des vecteurs non-orientés (de type liste ou vecteur -Numpy) ou orientés (de type matrice Numpy). - -Ensuite, **pour décrire complètement un opérateur, l'utilisateur n'a qu'à -fournir une fonction qui réalise uniquement l'opération fonctionnelle de manière -complète**. - -Cette fonction est généralement donnée comme un script qui peut être exécuté -dans un noeud YACS. Ce script peut aussi, sans différences, lancer des codes -externes ou utiliser des appels et des méthodes internes SALOME. Si l'algorithme -nécessite les 3 aspects de l'opérateur (forme directe, forme tangente et forme -adjointe), l'utilisateur doit donner les 3 fonctions ou les approximer. - -Il existe 3 méthodes effectives pour l'utilisateur de fournir une représentation -fonctionnelle de l'opérateur. Ces méthodes sont choisies dans le champ "*FROM*" -de chaque opérateur ayant une valeur "*Function*" comme "*INPUT_TYPE*", comme le -montre la figure suivante: +:math:`\mathbf{y}`, ou leurs incréments, sont mathématiquement des vecteurs, et +ils peuvent donc être donnés par l'utilisateur comme des vecteurs non-orientés +(de type liste ou vecteur Numpy) ou orientés (de type matrice Numpy). + +Ainsi, **pour décrire de manière complète un opérateur, l'utilisateur n'a qu'à +fournir une fonction qui réalise complètement et uniquement l'opération +fonctionnelle**. + +Cette fonction est généralement donnée comme une fonction ou un script Python, +qui peuvent en particulier être exécuté comme une fonction Python indépendante +ou dans un noeud YACS. Cette fonction ou ce script peuvent, sans différences, +lancer des codes externes ou utiliser des appels et des méthodes internes +Python ou SALOME. Si l'algorithme nécessite les 3 aspects de l'opérateur (forme +directe, forme tangente et forme adjointe), l'utilisateur doit donner les 3 +fonctions ou les approximer grâce à ADAO. + +Il existe pour l'utilisateur 3 méthodes effectives de fournir une représentation +fonctionnelle de l'opérateur, qui diffèrent selon le type d'argument choisi: + +- :ref:`section_ref_operator_one` +- :ref:`section_ref_operator_funcs` +- :ref:`section_ref_operator_switch` + +Dans le cas de l'interface textuelle d'ADAO (TUI), seules les deux premières +sont nécessaires car la troisième est incluse dans la seconde. Dans le cas de +l'interface graphique EFICAS d'ADAO, ces méthodes sont choisies dans le champ +"*FROM*" de chaque opérateur ayant une valeur "*Function*" comme +"*INPUT_TYPE*", comme le montre la figure suivante: .. eficas_operator_function: .. image:: images/eficas_operator_function.png :align: center :width: 100% .. centered:: - **Choisir une représentation fonctionnelle de l'opérateur** + **Choisir graphiquement une représentation fonctionnelle de l'opérateur** -Première forme fonctionnelle : utiliser "*ScriptWithOneFunction*" -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. _section_ref_operator_one: +Première forme fonctionnelle : un seul opérateur direct ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: OneFunction .. index:: single: ScriptWithOneFunction .. index:: single: DirectOperator .. index:: single: DifferentialIncrement .. index:: single: CenteredFiniteDifference -La première consiste à ne fournir qu'une seule fonction potentiellement non -linéaire, et d'approximer les opérateurs tangent et adjoint. Ceci est fait en -utilisant le mot-clé "*ScriptWithOneFunction*" pour la description de -l'opérateur choisi dans l'interface graphique ADAO. L'utilisateur doit fournir -la fonction dans un script, avec un nom obligatoire "*DirectOperator*". Par -exemple, le script peut suivre le modèle suivant:: +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 +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 +fonction qui porte le nom obligatoire "*DirectOperator*". Par exemple, un +script externe peut suivre le modèle générique suivant:: def DirectOperator( X ): """ Opérateur direct de simulation non-linéaire """ @@ -100,18 +121,19 @@ exemple, le script peut suivre le modèle suivant:: Dans ce cas, l'utilisateur doit aussi fournir une valeur pour l'incrément différentiel (ou conserver la valeur par défaut), en utilisant dans l'interface -graphique (GUI) le mot-clé "*DifferentialIncrement*", qui a une valeur par -défaut de 1%. Ce coefficient est utilisé dans l'approximation différences finies -pour construire les opérateurs tangent et adjoint. L'ordre de l'approximation -différences finies peut aussi être choisi à travers l'interface, en utilisant le -mot-clé "*CenteredFiniteDifference*", avec 0 pour un schéma non centré du -premier ordre (qui est la valeur par défaut), et avec 1 pour un schéma centré du -second ordre (qui coûte numériquement deux fois plus cher que le premier ordre). -Si nécessaire et si possible, on peut :ref:`subsection_ref_parallel_df`. Dans -tous les cas, un mécanisme de cache interne permet de limiter le nombre -d'évaluations de l'opérateur au minimum possible du point de vue de l'exécution -séquentielle ou parallèle des approximations numériques des opérateurs tangent -et adjoint, pour éviter des calculs redondants. +graphique (GUI) ou textuelle (TUI) le mot-clé "*DifferentialIncrement*" comme +paramètre, qui a une valeur par défaut de 1%. Ce coefficient est utilisé dans +l'approximation différences finies pour construire les opérateurs tangent et +adjoint. L'ordre de l'approximation différences finies peut aussi être choisi à +travers l'interface, en utilisant le mot-clé "*CenteredFiniteDifference*", avec +0 pour un schéma non centré du premier ordre (qui est la valeur par défaut), et +avec 1 pour un schéma centré du second ordre (et qui coûte numériquement deux +fois plus cher que le premier ordre). Si nécessaire et si possible, on peut +:ref:`subsection_ref_parallel_df`. Dans tous les cas, un mécanisme de cache +interne permet de limiter le nombre d'évaluations de l'opérateur au minimum +possible du point de vue de l'exécution séquentielle ou parallèle des +approximations numériques des opérateurs tangent et adjoint, pour éviter des +calculs redondants. Cette première forme de définition de l'opérateur permet aisément de tester la forme fonctionnelle avant son usage dans un cas ADAO, réduisant notablement la @@ -120,29 +142,37 @@ l'algorithme ADAO de vérification "*FunctionTest*" (voir la section sur l':ref:`section_ref_algorithm_FunctionTest`) pour ce test. **Avertissement important :** le nom "*DirectOperator*" est obligatoire, et le -type de l'argument ``X`` peut être une liste, un vecteur ou une matrice Numpy. -La fonction utilisateur doit accepter et traiter tous ces cas. +type de l'argument ``X`` peut être une liste de valeur réelles, un vecteur +Numpy ou une matrice Numpy. La fonction utilisateur doit accepter et traiter +tous ces cas. + +.. _section_ref_operator_funcs: -Seconde forme fonctionnelle : utiliser "*ScriptWithFunctions*" -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +Seconde forme fonctionnelle : trois opérateurs direct, tangent et adjoint ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. index:: single: ThreeFunctions .. index:: single: ScriptWithFunctions .. index:: single: DirectOperator .. index:: single: TangentOperator .. index:: single: AdjointOperator -**En général, il est recommandé d'utiliser la première forme fonctionnelle -plutôt que la seconde. Un petit accroissement de performances n'est pas une -bonne raison pour utiliser l'implémentation détaillée de cette seconde forme -fonctionnelle.** +.. warning:: + + en général, il est recommandé d'utiliser la première forme fonctionnelle + plutôt que la seconde. Un petit accroissement de performances n'est pas une + bonne raison pour utiliser l'implémentation détaillée de cette seconde forme + fonctionnelle. La seconde consiste à fournir directement les trois opérateurs liés :math:`O`, :math:`\mathbf{O}` et :math:`\mathbf{O}^*`. C'est effectué en utilisant le mot-clé "*ScriptWithFunctions*" pour la description de l'opérateur choisi dans -l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir trois fonctions -dans un script, avec trois noms obligatoires "*DirectOperator*", -"*TangentOperator*" et "*AdjointOperator*". Par exemple, le script peut suivre -le squelette suivant:: +l'interface graphique EFICAS d'ADAO. Dans l'interface textuelle, c'est le +mot-clé "*ThreeFunctions*", éventuellement combiné avec le mot-clé "*Script*" +selon que c'est une fonction ou un script. L'utilisateur doit fournir dans un +script trois fonctions, avec les trois noms obligatoires "*DirectOperator*", +"*TangentOperator*" et "*AdjointOperator*". Par exemple, le script externe peut +suivre le squelette suivant:: def DirectOperator( X ): """ Opérateur direct de simulation non-linéaire """ @@ -151,15 +181,17 @@ le squelette suivant:: ... return quelque chose comme Y - def TangentOperator( (X, dX) ): + def TangentOperator( paire = (X, dX) ): """ Opérateur linéaire tangent, autour de X, appliqué à dX """ + X, dX = paire ... ... ... return quelque chose comme Y - def AdjointOperator( (X, Y) ): + def AdjointOperator( paire = (X, Y) ): """ Opérateur adjoint, autour de X, appliqué à Y """ + X, Y = paire ... ... ... @@ -169,46 +201,53 @@ Un nouvelle fois, cette seconde définition d'opérateur permet aisément de tes les formes fonctionnelles avant de les utiliser dans le cas ADAO, réduisant la complexité de l'implémentation de l'opérateur. -Pour certains algorithmes, il faut que les fonctions tangente et adjointe puisse -renvoyer les matrices équivalentes à l'opérateur linéaire. Dans ce cas, lorsque, -respectivement, les arguments ``dX`` ou ``Y`` valent ``None``, l'utilisateur -doit renvoyer la matrice associée. +Pour certains algorithmes, il faut que les fonctions tangente et adjointe +puisse renvoyer les matrices équivalentes à l'opérateur linéaire. Dans ce cas, +lorsque, respectivement, les arguments ``dX`` ou ``Y`` valent ``None``, le +script de l'utilisateur doit renvoyer la matrice associée. **Avertissement important :** les noms "*DirectOperator*", "*TangentOperator*" et "*AdjointOperator*" sont obligatoires, et le type des arguments ``X``, -``Y``, ``dX`` peut être une liste, un vecteur ou une matrice Numpy. -La fonction utilisateur doit accepter et traiter tous ces cas. +``Y``, ``dX`` peut être une liste de valeur réelles, un vecteur Numpy ou une +matrice Numpy. La fonction utilisateur doit accepter et traiter tous ces cas. + +.. _section_ref_operator_switch: -Troisième forme fonctionnelle : utiliser "*ScriptWithSwitch*" -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +Troisième forme fonctionnelle : trois opérateurs avec un branchement +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. index:: single: ScriptWithSwitch .. index:: single: DirectOperator .. index:: single: TangentOperator .. index:: single: AdjointOperator -**Il est recommandé de ne pas utiliser cette troisième forme fonctionnelle sans -une solide raison numérique ou physique. Un accroissement de performances n'est -pas une bonne raison pour utiliser la complexité de cette troisième forme -fonctionnelle. Seule une impossibilité à utiliser les première ou seconde formes -justifie l'usage de la troisième.** - -La troisième forme donne de plus grandes possibilités de contrôle de l'exécution -des trois fonctions représentant l'opérateur, permettant un usage et un contrôle -avancés sur chaque exécution du code de simulation. C'est réalisable en -utilisant le mot-clé "*ScriptWithSwitch*" pour la description de l'opérateur à -travers l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir un script -unique aiguillant, selon un contrôle, l'exécution des formes directe, tangente -et adjointe du code de simulation. L'utilisateur peut alors, par exemple, -utiliser des approximations pour les codes tangent et adjoint, ou introduire une -plus grande complexité du traitement des arguments des fonctions. Mais cette -démarche sera plus difficile à implémenter et à déboguer. - -Toutefois, si vous souhaitez utiliser cette troisième forme, on recommande de se -baser sur le modèle suivant pour le script d'aiguillage. Il nécessite un fichier -script ou un code externe nommé ici "*Physical_simulation_functions.py*", -contenant trois fonctions nommées "*DirectOperator*", "*TangentOperator*" et -"*AdjointOperator*" comme précédemment. Voici le squelette d'aiguillage:: +.. warning:: + + il est recommandé de ne pas utiliser cette troisième forme fonctionnelle sans + une solide raison numérique ou physique. Un accroissement de performances + n'est pas une bonne raison pour utiliser la complexité de cette troisième + forme fonctionnelle. Seule une impossibilité à utiliser les première ou + seconde formes justifie l'usage de la troisième. + +La troisième forme donne de plus grandes possibilités de contrôle de +l'exécution des trois fonctions représentant l'opérateur, permettant un usage +et un contrôle avancés sur chaque exécution du code de simulation. C'est +réalisable en utilisant le mot-clé "*ScriptWithSwitch*" pour la description de +l'opérateur à travers l'interface graphique EFICAS d'ADAO. Dans l'interface +textuelle, il suffit d'utiliser le mot-clé "*ThreeFunctions*" précédent pour +définir aussi ce cas, en indiquant les fonctions adéquates. L'utilisateur doit +fournir un script unique aiguillant, selon un contrôle, l'exécution des formes +directe, tangente et adjointe du code de simulation. L'utilisateur peut alors, +par exemple, utiliser des approximations pour les codes tangent et adjoint, ou +introduire une plus grande complexité du traitement des arguments des +fonctions. Mais cette démarche sera plus difficile à implémenter et à déboguer. + +Toutefois, si vous souhaitez utiliser cette troisième forme, on recommande de +se baser sur le modèle suivant pour le script d'aiguillage. Il nécessite un +fichier script ou un code externe nommé ici +"*Physical_simulation_functions.py*", contenant trois fonctions nommées +"*DirectOperator*", "*TangentOperator*" et "*AdjointOperator*" comme +précédemment. Voici le squelette d'aiguillage:: import Physical_simulation_functions import numpy, logging, codecs, pickle @@ -267,16 +306,19 @@ Cas spécial d'un opérateur d'évolution avec contrôle Dans certains cas, l'opérateur d'évolution ou d'observation doit être contrôlé par un contrôle d'entrée externe, qui est donné *a priori*. Dans ce cas, la -forme générique du modèle incrémental est légèrement modifié comme suit: +forme générique du modèle incrémental :math:`O` est légèrement modifiée comme +suit: .. math:: \mathbf{y} = O( \mathbf{x}, \mathbf{u}) où :math:`\mathbf{u}` est le contrôle sur l'incrément d'état. En effet, l'opérateur direct doit être appliqué à une paire de variables :math:`(X,U)`. -Schématiquement, l'opérateur doit être construit comme suit:: +Schématiquement, l'opérateur :math:`O` doit être construit comme une fonction +applicable sur une paire:math:`\mathbf{(X, U)}` suit:: - def DirectOperator( (X, U) ): + def DirectOperator( paire = (X, U) ): """ Opérateur direct de simulation non-linéaire """ + X, U = paire ... ... ... @@ -285,8 +327,10 @@ Schématiquement, l'opérateur doit être construit comme suit:: Les opérateurs tangent et adjoint ont la même signature que précédemment, en notant que les dérivées doivent être faites seulement partiellement par rapport à :math:`\mathbf{x}`. Dans un tel cas de contrôle explicite, seule la deuxième -forme fonctionnelle (en utilisant "*ScriptWithFunctions*") et la troisième forme -fonctionnelle (en utilisant "*ScriptWithSwitch*") peuvent être utilisées. +forme fonctionnelle (en utilisant "*ScriptWithFunctions*") et la troisième +forme fonctionnelle (en utilisant "*ScriptWithSwitch*") peuvent être utilisées. + +.. _section_ref_operator_dimensionless: Remarques complémentaires sur l'adimensionnement des opérateurs +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -296,28 +340,75 @@ Remarques complémentaires sur l'adimensionnement des opérateurs Il est fréquent que les grandeurs physiques, en entrée ou en sortie des opérateurs, présentent des différences notables d'ordre de grandeur ou de taux -de variation. Une manière d'éviter des difficultés numériques est d'utiliser, ou -d'établir, un adimensionnement des calculs menés dans les opérateurs +de variation. Une manière d'éviter des difficultés numériques est d'utiliser, +ou d'établir, un adimensionnement des calculs menés dans les opérateurs [WikipediaND]_. Par principe, dans la mesure où la simulation de la physique devrait être la plus adimensionnée possible, il est en premier lieu recommandé d'utiliser les capacités existantes d'adimensionnement du code de calcul. -Néanmoins, dans le cas courant où l'on ne peut en disposer, il est souvent utile -d'environner le calcul pour l'adimensionner en entrée ou en sortie. Une manière -simple de faire cela en entrée consiste à transformer les paramètres +Néanmoins, dans le cas courant où l'on ne peut en disposer, il est souvent +utile d'environner le calcul pour l'adimensionner en entrée ou en sortie. Une +manière simple de faire cela en entrée consiste à transformer les paramètres :math:`\mathbf{x}` en argument d'une fonction comme "*DirectOperator*". On -utilise le plus souvent les valeurs par défaut :math:`\mathbf{x}^b` (ébauche, ou -valeur nominale). Pourvu que chaque composante de :math:`\mathbf{x}^b` soit non -nulle, on peut en effet poser: +utilise le plus souvent comme référence les valeurs par défaut +:math:`\mathbf{x}^b` (ébauche, ou valeur nominale). Pourvu que chaque +composante de :math:`\mathbf{x}^b` soit non nulle, on peut ensuite procéder par +correction multiplicative. Pour cela, on peut par exemple poser: .. math:: \mathbf{x} = \mathbf{\alpha}\mathbf{x}^b et optimiser ensuite le paramètre multiplicatif :math:`\mathbf{\alpha}`. Ce -paramètre a pour valeur par défaut (ou pour ébauche) un vecteur de 1. Attention, -l'application d'une démarche d'adimensionnement nécessite aussi la modification -des covariances d'erreurs associées dans la formulation ADAO du problème -d'optimisation. +paramètre a pour valeur par défaut (ou pour ébauche) un vecteur de 1. De +manière similaire, on peut procéder par correction additive si c'est plus +judicieux pour la physique sous-jacente. Ainsi, dans ce cas, on peut poser: + +.. math:: \mathbf{x} =\mathbf{x}^b + \mathbf{\alpha} + +et optimiser ensuite le paramètre additif :math:`\mathbf{\alpha}`. Cette fois, +ce paramètre a pour valeur d'ébauche un vecteur de 0. + +Attention, l'application d'une démarche d'adimensionnement nécessite aussi la +modification des covariances d'erreurs associées dans la formulation globale du +problème d'optimisation. Une telle démarche suffit rarement à éviter tous les problèmes numériques, mais permet souvent d'améliorer beaucoup le conditionnement numérique de l'optimisation. + +Gestion explicite de fonctions "multiples" +++++++++++++++++++++++++++++++++++++++++++ + +.. warning:: + + il est fortement recommandé de ne pas utiliser cette gestion explicite de + fonctions "multiples" sans une très solide raison informatique pour le faire. + Cette gestion est déjà effectuée par défaut dans ADAO pour l'amélioration des + performances. Seul l'utilisateur très averti, cherchant à gérer des cas + particulièrement difficiles, peut s'intéresser à cette extension. En dépit de + sa simplicité, c'est au risque explicite de dégrader notablement les + performances. + +Il est possible, lorsque l'on fournit des fonctions d'opérateurs, de les +définir comme des fonctions qui traitent non pas un seul argument, mais une +série d'arguments, pour restituer en sortie la série des valeurs +correspondantes. En pseudo-code, la fonction "multiple", ici nommée +``MultiFunctionO``, représentant l'opérateur classique :math:`O` nommé +"*DirectOperator*", effectue:: + + def MultiFunctionO( Inputs ): + """ Multiple ! """ + Outputs = [] + for X in Inputs: + Y = DirectOperator( X ) + Outputs.append( Y ) + return Outputs + +La longueur de la sortie (c'est-à-dire le nombre de valeurs calculées) est +égale à la longueur de l'entrée (c'est-à-dire le nombre d'états dont on veut +calculer la valeur par l'opérateur). + +Cette possibilité n'est disponible que dans l'interface textuelle d'ADAO. Pour +cela, lors de la définition d'une fonction d'opérateur, en même temps que l'on +définit de manière habituelle la fonction ou le script externe, il suffit +d'indiquer en plus en argument par un booléen "*InputFunctionAsMulti*" que la +définition est celle d'une fonction "multiple". diff --git a/doc/fr/ref_output_variables.rst b/doc/fr/ref_output_variables.rst index b75595c..a918f63 100644 --- a/doc/fr/ref_output_variables.rst +++ b/doc/fr/ref_output_variables.rst @@ -133,7 +133,7 @@ représentation graphique avec le module PARAVIS [#]_ ou d'autres modules, des actions de calcul pilotés par YACS [#]_ ou un autre module, etc. D'autres exemples d'utilisation sont aussi donnés en :ref:`section_u_step4` de -la partie :ref:`section_using`, ou en partie :ref:`section_examples`. +la partie :ref:`section_gui_in_salome`, ou en partie :ref:`section_tutorials_in_salome`. Conditionnalité des informations disponibles en sortie ++++++++++++++++++++++++++++++++++++++++++++++++++++++ diff --git a/doc/fr/reference.rst b/doc/fr/reference.rst index ef1e9e9..9e1373c 100644 --- a/doc/fr/reference.rst +++ b/doc/fr/reference.rst @@ -28,20 +28,20 @@ ================================================================================ Les sections suivantes présentent la description de référence des commandes et -mots-clés ADAO disponibles à travers l'interface graphique (GUI) ou à travers -des scripts. Les deux premières sections communes présentent les -:ref:`section_reference_entry` et les :ref:`section_reference_special_entry`. -Ensuite, on décrit successivement les :ref:`section_reference_assimilation` et -les :ref:`section_reference_checking`. - -Chaque commande ou mot-clé à définir par l'interface graphique (GUI) a des -propriétés particulières. La première propriété est d'être *requise*, -*optionnelle* ou simplement utile, décrivant un type d'entrée. La seconde -propriété est d'être une variable "ouverte" avec un type fixé mais avec -n'importe quelle valeur autorisée par le type, ou une variable "fermée", limitée -à des valeurs spécifiées. L'éditeur graphique intégré disposant de capacités -intrinsèques de validation, les propriétés des commandes ou mots-clés données à -l'aide de l'interface graphique sont automatiquement correctes. +mots-clés ADAO disponibles à travers l'interface textuelle (TUI), graphique +(GUI) ou à travers des scripts. Les deux premières sections communes présentent +les :ref:`section_reference_entry` et les +:ref:`section_reference_special_entry`. Ensuite, on décrit successivement les +:ref:`section_reference_assimilation` et les :ref:`section_reference_checking`. + +Chaque commande ou mot-clé à définir par la TUI ou la GUI a des propriétés +particulières. La première propriété est d'être *requise*, *optionnelle* ou +simplement utile, décrivant un type d'entrée. La seconde propriété est d'être +une variable "ouverte" avec un type fixé mais avec n'importe quelle valeur +autorisée par le type, ou une variable "fermée", limitée à des valeurs +spécifiées. L'éditeur graphique GUI intégré disposant de capacités intrinsèques +de validation, les propriétés des commandes ou mots-clés données à l'aide de +l'interface graphique sont automatiquement correctes. .. _section_reference_entry: @@ -83,19 +83,19 @@ 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 d'utilisation et leurs -options. +Cette section décrit les algorithmes d'assimilation de données ou +d'optimisation 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 -:ref:`section_examples` et dans les fichiers d'exemple installés avec le module -ADAO. Les notations mathématiques utilisées sont expliquées dans la section -:ref:`section_theory`. +:ref:`section_tutorials_in_salome`, dans la section +:ref:`section_tutorials_in_python` et dans les fichiers d'exemple installés +avec ADAO. Les notations mathématiques utilisées sont expliquées dans la +section :ref:`section_theory`. .. toctree:: :maxdepth: 1 - ref_assimilation_keywords ref_algorithm_3DVAR ref_algorithm_4DVAR ref_algorithm_Blue @@ -110,7 +110,9 @@ ADAO. Les notations mathématiques utilisées sont expliquées dans la section ref_algorithm_NonLinearLeastSquares ref_algorithm_ParticleSwarmOptimization ref_algorithm_QuantileRegression + ref_algorithm_TabuSearch ref_algorithm_UnscentedKalmanFilter + ref_assimilation_keywords .. _section_reference_checking: @@ -122,18 +124,20 @@ Cette section décrit les algorithmes de vérification 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 -:ref:`section_examples` et dans les fichiers d'exemple installés avec le module -ADAO. Les notations mathématiques utilisées sont expliquées dans la section -:ref:`section_theory`. +:ref:`section_tutorials_in_salome`, dans la section +:ref:`section_tutorials_in_python` et dans les fichiers d'exemple installés +avec ADAO. Les notations mathématiques utilisées sont expliquées dans la +section :ref:`section_theory`. .. toctree:: :maxdepth: 1 - ref_checking_keywords ref_algorithm_AdjointTest ref_algorithm_FunctionTest ref_algorithm_GradientTest ref_algorithm_LinearityTest + ref_algorithm_LocalSensitivityTest ref_algorithm_ObserverTest ref_algorithm_SamplingTest ref_algorithm_TangentTest + ref_checking_keywords diff --git a/doc/fr/snippets/AlphaBeta.rst b/doc/fr/snippets/AlphaBeta.rst new file mode 100644 index 0000000..b6302f7 --- /dev/null +++ b/doc/fr/snippets/AlphaBeta.rst @@ -0,0 +1,15 @@ +.. index:: single: Alpha +.. index:: single: Beta +.. index:: single: Kappa +.. index:: single: Reconditioner + +Alpha, Beta, Kappa, Reconditioner + Ces clés sont des paramètres de mise à l'échelle interne. "Alpha" requiert + une valeur comprise entre 1.e-4 et 1. "Beta" a une valeur optimale de 2 pour + une distribution *a priori* gaussienne. "Kappa" requiert une valeur entière, + dont la bonne valeur par défaut est obtenue en la mettant à 0. + "Reconditioner" requiert une valeur comprise entre 1.e-3 et 10, son défaut + étant 1. + + Exemple : + ``{"Alpha":1,"Beta":2,"Kappa":0,"Reconditioner":1}`` diff --git a/doc/fr/snippets/CrossOverProbability_CR.rst b/doc/fr/snippets/CrossOverProbability_CR.rst index e815cb5..207a459 100644 --- a/doc/fr/snippets/CrossOverProbability_CR.rst +++ b/doc/fr/snippets/CrossOverProbability_CR.rst @@ -3,8 +3,9 @@ CrossOverProbability_CR Cette clé permet de définir la probabilité de recombinaison ou de croisement lors de l'évolution différentielle. Cette variable est usuellement notée - ``CR`` dans la littérature. La valeur par défaut est 0.7, et il est conseillé - de la changer si nécessaire. + ``CR`` dans la littérature, et elle est obligatoirement comprise entre 0 et + 1. La valeur par défaut est 0.7, et il est conseillé de la changer si + nécessaire. Exemple : ``{"CrossOverProbability_CR":0.7}`` diff --git a/doc/fr/snippets/Header2Algo03AdOp.rst b/doc/fr/snippets/Header2Algo03AdOp.rst new file mode 100644 index 0000000..234637a --- /dev/null +++ b/doc/fr/snippets/Header2Algo03AdOp.rst @@ -0,0 +1,9 @@ +Les commandes optionnelles générales, disponibles en édition dans l'interface +graphique ou textuelle, sont indiquées dans la +:ref:`section_ref_assimilation_keywords`. De plus, les paramètres de la +commande "*AlgorithmParameters*" permettent d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes : diff --git a/doc/fr/snippets/Header2Algo03Chck.rst b/doc/fr/snippets/Header2Algo03Chck.rst new file mode 100644 index 0000000..0fdd785 --- /dev/null +++ b/doc/fr/snippets/Header2Algo03Chck.rst @@ -0,0 +1,9 @@ +Les commandes optionnelles générales, disponibles en édition dans l'interface +graphique ou textuelle, sont indiquées dans la +:ref:`section_ref_checking_keywords`. De plus, les paramètres de la commande +"*AlgorithmParameters*" permettent d'indiquer les options particulières, +décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes : diff --git a/doc/fr/snippets/JacobianMatrixAtBackground.rst b/doc/fr/snippets/JacobianMatrixAtBackground.rst new file mode 100644 index 0000000..998177f --- /dev/null +++ b/doc/fr/snippets/JacobianMatrixAtBackground.rst @@ -0,0 +1,10 @@ +.. index:: single: JacobianMatrixAtBackground + +JacobianMatrixAtBackground + *Liste de matrices*. Chaque élément est une matrice jacobienne de dérivées + partielles de la sortie de l'opérateur d'observation par rapport aux + paramètres d'entrée, une colonne de dérivées par paramètre. Le calcul est + effectué à l'état initial. + + Exemple: + ``GradH = ADD.get("JacobianMatrixAtBackground")[-1]`` diff --git a/doc/fr/snippets/JacobianMatrixAtCurrentState.rst b/doc/fr/snippets/JacobianMatrixAtCurrentState.rst new file mode 100644 index 0000000..86f52cd --- /dev/null +++ b/doc/fr/snippets/JacobianMatrixAtCurrentState.rst @@ -0,0 +1,10 @@ +.. index:: single: JacobianMatrixAtCurrentState + +JacobianMatrixAtCurrentState + *Liste de matrices*. Chaque élément est une matrice jacobienne de dérivées + partielles de la sortie de l'opérateur d'observation par rapport aux + paramètres d'entrée, une colonne de dérivées par paramètre. Le calcul est + effectué à l'état courant. + + Exemple: + ``GradH = ADD.get("JacobianMatrixAtCurrentState")[-1]`` diff --git a/doc/fr/snippets/JacobianMatrixAtOptimum.rst b/doc/fr/snippets/JacobianMatrixAtOptimum.rst new file mode 100644 index 0000000..b741945 --- /dev/null +++ b/doc/fr/snippets/JacobianMatrixAtOptimum.rst @@ -0,0 +1,10 @@ +.. index:: single: JacobianMatrixAtOptimum + +JacobianMatrixAtOptimum + *Liste de matrices*. Chaque élément est une matrice jacobienne de dérivées + partielles de la sortie de l'opérateur d'observation par rapport aux + paramètres d'entrée, une colonne de dérivées par paramètre. Le calcul est + effectué à l'état optimal. + + Exemple: + ``GradH = ADD.get("JacobianMatrixAtOptimum")[-1]`` diff --git a/doc/fr/snippets/KalmanGainAtOptimum.rst b/doc/fr/snippets/KalmanGainAtOptimum.rst new file mode 100644 index 0000000..7c946f5 --- /dev/null +++ b/doc/fr/snippets/KalmanGainAtOptimum.rst @@ -0,0 +1,9 @@ +.. index:: single: KalmanGainAtOptimum + +KalmanGainAtOptimum + *Liste de matrices*. Chaque élément est une matrice de gain de Kalman + standard, évaluée à l'aide de l'opérateur d'observation linéarisé. Le calcul + est effectué à l'état optimal. + + Exemple: + ``KG = ADD.get("KalmanGainAtOptimum")[-1]`` diff --git a/doc/fr/snippets/LengthOfTabuList.rst b/doc/fr/snippets/LengthOfTabuList.rst new file mode 100644 index 0000000..72ce3e6 --- /dev/null +++ b/doc/fr/snippets/LengthOfTabuList.rst @@ -0,0 +1,10 @@ +.. index:: single: LengthOfTabuList + +LengthOfTabuList + Cette clé indique la longueur de la liste taboue, c'est-à-dire le nombre + maximal de perturbations antérieurement réalisées et conservées pour mémoire. + Le défaut est 50, et il est recommandé de l'adapter aux besoins pour des + problèmes réels. + + Exemple : + ``{"LengthOfTabuList":50}`` diff --git a/doc/fr/snippets/NoiseAddingProbability.rst b/doc/fr/snippets/NoiseAddingProbability.rst new file mode 100644 index 0000000..0cabad9 --- /dev/null +++ b/doc/fr/snippets/NoiseAddingProbability.rst @@ -0,0 +1,9 @@ +.. index:: single: NoiseAddingProbability + +NoiseAddingProbability + Cette clé indique la probabilité de perturbation d'une composante de l'état. + C'est une valeur obligatoirement comprise entre 0 et 1. La valeur par défaut + est 1, et il n'est pas recommandé de la changer. + + Exemple : + ``{"NoiseAddingProbability":1.}`` diff --git a/doc/fr/snippets/NoiseDistribution.rst b/doc/fr/snippets/NoiseDistribution.rst new file mode 100644 index 0000000..377eb5d --- /dev/null +++ b/doc/fr/snippets/NoiseDistribution.rst @@ -0,0 +1,10 @@ +.. index:: single: NoiseDistribution + +NoiseDistribution + Cette clé indique le type de la distribution utilisée pour générer les + perturbations d'état. Cette distribution peut être de type "Uniform" ou + "Gaussian". Le défaut est une distribution de type "Uniform", et il est + recommandé de l'adapter aux besoins pour des problèmes réels. + + Exemple : + ``{"NoiseDistribution":"Uniform"}`` diff --git a/doc/fr/snippets/NoiseHalfRange.rst b/doc/fr/snippets/NoiseHalfRange.rst new file mode 100644 index 0000000..9d26bc1 --- /dev/null +++ b/doc/fr/snippets/NoiseHalfRange.rst @@ -0,0 +1,15 @@ +.. index:: single: NoiseHalfRange + +NoiseHalfRange + Cette clé indique, uniquement dans le cas d'une distribution de type + "Uniform" demandée par le mot-clé "*NoiseDistribution*", la demi-amplitude + des perturbations uniformes centrées d'état pour chaque composante de l'état. + Le défaut est une liste vide, cette clé doit donc obligatoirement être + renseignée dans le cas d'une distribution "Uniform". Une manière simple de le + faire est de donner une liste de la longueur de l'état recherché et de + demi-amplitudes identiques, comme dans l'exemple ci-dessous avec des + demi-amplitudes de 3%. Il est conseillé de prendre des demi-amplitudes de + quelques pourcents au maximum. + + Exemple : + ``{"NoiseHalfRange":*[0.03]}`` diff --git a/doc/fr/snippets/NumberOfElementaryPerturbations.rst b/doc/fr/snippets/NumberOfElementaryPerturbations.rst new file mode 100644 index 0000000..9ba0eae --- /dev/null +++ b/doc/fr/snippets/NumberOfElementaryPerturbations.rst @@ -0,0 +1,11 @@ +.. index:: single: NumberOfElementaryPerturbations + +NumberOfElementaryPerturbations + Cette clé indique le nombre de perturbations élémentaires qui seront + réalisées pour choisir une perturbation complète d'état. Le défaut est de 1, + et il est recommandé de l'adapter avec prudence aux besoins pour des + problèmes réels, sans choisir un trop grand nombre de perturbations + élémentaires. + + Exemple : + ``{"NumberOfElementaryPerturbations":1}`` diff --git a/doc/fr/snippets/OutputVariables.rst b/doc/fr/snippets/OutputVariables.rst new file mode 100644 index 0000000..9ccae77 --- /dev/null +++ b/doc/fr/snippets/OutputVariables.rst @@ -0,0 +1,7 @@ +.. index:: single: OutputVariables + +OutputVariables + *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des + variables physiques qui sont rassemblées dans le vecteur d'observation. Cette + information est destinée à être utilisée dans le traitement algorithmique + interne des données. diff --git a/doc/fr/snippets/SampleAsExplicitHyperCube.rst b/doc/fr/snippets/SampleAsExplicitHyperCube.rst new file mode 100644 index 0000000..3c29c60 --- /dev/null +++ b/doc/fr/snippets/SampleAsExplicitHyperCube.rst @@ -0,0 +1,9 @@ +.. index:: single: SampleAsExplicitHyperCube + +SampleAsExplicitHyperCube + Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont on + donne la liste des échantillonnages explicites de chaque variable comme une + liste. C'est donc une liste de listes, chacune étant de taille + potentiellement différente. + + Exemple : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` pour un espace d'état de dimension 2 diff --git a/doc/fr/snippets/SampleAsIndependantRandomVariables.rst b/doc/fr/snippets/SampleAsIndependantRandomVariables.rst new file mode 100644 index 0000000..f370cd1 --- /dev/null +++ b/doc/fr/snippets/SampleAsIndependantRandomVariables.rst @@ -0,0 +1,14 @@ +.. index:: single: SampleAsIndependantRandomVariables + +SampleAsIndependantRandomVariables + Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont les + points sur chaque axe proviennent de l'échantillonnage aléatoire indépendant + de la variable d'axe, selon la spécification de la distribution, de ses + paramètres et du nombre de points de l'échantillon, sous la forme d'une liste + ``['distribution', [parametres], nombre]`` pour chaque axe. Les distributions + possibles sont 'normal' de paramètres (mean,std), 'lognormal' de paramètres + (mean,sigma), 'uniform' de paramètres (low,high), ou 'weibull' de paramètre + (shape). C'est donc une liste de la même taille que celle de l'état. + + Exemple : + ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` pour un espace d'état de dimension 2 diff --git a/doc/fr/snippets/SampleAsMinMaxStepHyperCube.rst b/doc/fr/snippets/SampleAsMinMaxStepHyperCube.rst new file mode 100644 index 0000000..6c67568 --- /dev/null +++ b/doc/fr/snippets/SampleAsMinMaxStepHyperCube.rst @@ -0,0 +1,10 @@ +.. index:: single: SampleAsMinMaxStepHyperCube + +SampleAsMinMaxStepHyperCube + Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont on + donne la liste des échantillonnages implicites de chaque variable par un + triplet *[min,max,step]*. C'est donc une liste de la même taille que celle + de l'état. Les bornes sont incluses. + + Exemple : + ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` pour un espace d'état de dimension 2 diff --git a/doc/fr/snippets/SampleAsnUplet.rst b/doc/fr/snippets/SampleAsnUplet.rst new file mode 100644 index 0000000..de33101 --- /dev/null +++ b/doc/fr/snippets/SampleAsnUplet.rst @@ -0,0 +1,8 @@ +.. index:: single: SampleAsnUplet + +SampleAsnUplet + Cette clé décrit les points de calcul sous la forme d'une liste de n-uplets, + chaque n-uplet étant un état. + + Exemple : + ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` pour 3 points dans un espace d'état de dimension 4 diff --git a/doc/fr/snippets/StandardDeviation.rst b/doc/fr/snippets/StandardDeviation.rst new file mode 100644 index 0000000..2498d72 --- /dev/null +++ b/doc/fr/snippets/StandardDeviation.rst @@ -0,0 +1,14 @@ +.. index:: single: StandardDeviation + +StandardDeviation + Cette clé indique, uniquement dans le cas d'une distribution de type + "Gaussian" demandée par le mot-clé "*NoiseDistribution*", l'écart-type des + perturbations gaussiennes d'état pour chaque composante de l'état. Le défaut + est une liste vide, cette clé doit donc obligatoirement être renseignée dans + le cas d'une distribution "Gaussian". Une manière simple de le faire est de + donner une liste de la longueur de l'état recherché avec des écart-types + identiques, comme dans l'exemple ci-dessous avec des demi-amplitudes de 5%. + Il est conseillé de prendre des écart-types de quelques pourcents au maximum. + + Exemple : + ``{"StandardDeviation":*[0.05]}`` diff --git a/doc/fr/tutorials_in_python.rst b/doc/fr/tutorials_in_python.rst new file mode 100644 index 0000000..96054a8 --- /dev/null +++ b/doc/fr/tutorials_in_python.rst @@ -0,0 +1,41 @@ +.. + Copyright (C) 2008-2019 EDF R&D + + This file is part of SALOME ADAO module. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com + + Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D + +.. _section_tutorials_in_python: + +================================================================================ +**[DocU]** Tutoriaux sur l'utilisation du module ADAO dans Python +================================================================================ + +Cette section présente quelques exemples d'utilisation du module ADAO en Python +SALOME. Le premier montre comment construire un cas simple d'assimilation de +données définissant explicitement toutes les données d'entrée requises à +travers l'interface utilisateur textuelle (TUI). Le second montre, sur le même +cas, comment définir les données d'entrée à partir de sources externes à +travers des scripts. + +Les notations mathématiques utilisées ci-dessous sont expliquées dans la +section :ref:`section_theory`. + +Construire un cas d'estimation avec une définition explicite des données +------------------------------------------------------------------------ diff --git a/doc/fr/examples.rst b/doc/fr/tutorials_in_salome.rst similarity index 98% rename from doc/fr/examples.rst rename to doc/fr/tutorials_in_salome.rst index 49ae08b..e0e5f88 100644 --- a/doc/fr/examples.rst +++ b/doc/fr/tutorials_in_salome.rst @@ -21,10 +21,10 @@ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D -.. _section_examples: +.. _section_tutorials_in_salome: ================================================================================ -**[DocU]** Tutoriaux sur l'utilisation du module ADAO +**[DocU]** Tutoriaux sur l'utilisation du module ADAO dans SALOME ================================================================================ .. |eficas_new| image:: images/eficas_new.png @@ -42,12 +42,12 @@ Cette section présente quelques exemples d'utilisation du module ADAO dans SALOME. Le premier montre comment construire un cas simple d'assimilation de -données définissant explicitement toutes les données d'entrée requises à travers -l'interface graphique d'édition (GUI). Le second montre, sur le même cas, -comment définir les données d'entrée à partir de sources externes à travers des -scripts. On présente ici toujours des scripts Python car ils sont directement -insérables dans les noeuds de script de YACS, mais les fichiers externes peuvent -utiliser d'autres langages. +données définissant explicitement toutes les données d'entrée requises à +travers l'interface utilisateur graphique EFICAS (GUI). Le second montre, sur +le même cas, comment définir les données d'entrée à partir de sources externes +à travers des scripts. On présente ici toujours des scripts Python car ils sont +directement insérables dans les noeuds de script de YACS, mais les fichiers +externes peuvent utiliser d'autres langages. Les notations mathématiques utilisées ci-dessous sont expliquées dans la section :ref:`section_theory`. diff --git a/src/daComposant/daAlgorithms/TabuSearch.py b/src/daComposant/daAlgorithms/TabuSearch.py index 8fb07c3..0287a52 100644 --- a/src/daComposant/daAlgorithms/TabuSearch.py +++ b/src/daComposant/daAlgorithms/TabuSearch.py @@ -103,7 +103,19 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): default = [], typecast = tuple, message = "Liste de calculs supplémentaires à stocker et/ou effectuer", - listval = ["BMA", "OMA", "OMB", "CurrentState", "CostFunctionJ", "CostFunctionJb", "CostFunctionJo", "Innovation", "SimulatedObservationAtBackground", "SimulatedObservationAtCurrentState", "SimulatedObservationAtOptimum"] + listval = [ + "BMA", + "OMA", + "OMB", + "CurrentState", + "CostFunctionJ", + "CostFunctionJb", + "CostFunctionJo", + "Innovation", + "SimulatedObservationAtBackground", + "SimulatedObservationAtCurrentState", + "SimulatedObservationAtOptimum", + ] ) self.defineRequiredParameter( # Pas de type name = "Bounds", diff --git a/src/daComposant/daCore/BasicObjects.py b/src/daComposant/daCore/BasicObjects.py index 6b37224..0099c21 100644 --- a/src/daComposant/daCore/BasicObjects.py +++ b/src/daComposant/daCore/BasicObjects.py @@ -1249,7 +1249,7 @@ class RegulationAndParameters(object): self.__P.update( dict(__Dict) ) # if __Algo is not None: - self.__P.update( {"Algorithm":self.__A} ) + self.__P.update( {"Algorithm":__Algo} ) def get(self, key = None): "Vérifie l'existence d'une clé de variable ou de paramètres" -- 2.39.2