.. _section_advanced:
================================================================================
-**[DocU]** Advanced usage of the ADAO module
+**[DocU]** Advanced usage of the ADAO module and interoperability
================================================================================
This section presents advanced methods to use the ADAO module, how to get more
implement, and it is favorable to try them (in twin experiments or not) because
they solve many problems encountered in practice.
-
-.. _subsection_version_compatibility:
-.. index::
- pair: Version ; SALOME
- pair: Version ; EFICAS
- pair: Version ; Python
- pair: Version ; Numpy
- pair: Version ; Scipy
- pair: Version ; MatplotLib
- pair: Version ; Gnuplot
- pair: Version ; NLopt
-
-Versions of ADAO compatibility with support tools
--------------------------------------------------
-
-.. include:: snippets/ModuleValidation.rst
-
-.. include:: snippets/ModuleCompatibility.rst
-
-.. _subsection_new_adao_version:
-.. index::
- pair: Version of ADAO ; Switching
-
-Switching from a version of ADAO to a newer one
------------------------------------------------
-
-The ADAO module and its ".comm" case files are identified by versions, with
-"Major", "Minor", "Revision" and optionally "Installation" characteristics. A
-particular version is numbered as "Major.Minor.Revision", with strong link with
-the numbering of the SALOME platform. The optional indication of a fourth
-number indicates a difference in the installation method, not in the content of
-the version.
-
-Each version "Major.Minor.Revision" of the ADAO module can read ADAO case files
-of the previous minor version "Major.Minor-1.*". In general, it can also read
-ADAO case files of all the previous minor versions for one major branch, but it
-is not guaranteed for all the commands or keywords. In general also, an ADAO
-case file for one version can not be read by a previous minor or major version
-of the ADAO module.
-
-Switching from 9.x to 9.y with y > x
-++++++++++++++++++++++++++++++++++++
-
-There is no known incompatibility for the ADAO case files. The upgrade procedure
-is to read the old ADAO case file with the new SALOME/ADAO module, and save it
-with a new name.
-
-However, there may be incompatibilities from user cases written directly in TUI
-interface. It is advisable to review the syntax and arguments in the TUI
-scripts at each version change. In particular, it is advisable to check that
-the algorithm parameters are still adequate and active, knowing that it has
-been explicitly chosen that there is no message when a parameter becomes
-inactive (for the example, we quote the parameter "*MaximumNumberOfSteps*" as
-having changed its name to "*MaximumNumberOfIterations*", for homogeneity with
-the variables that can be displayed).
-
-Switching from 8.5 to 9.2
-+++++++++++++++++++++++++
-
-There is no known incompatibility for the ADAO case files. The upgrade procedure
-is to read the old ADAO case file with the new SALOME/ADAO module, and save it
-with a new name.
-
-However, there may be incompatibilities from user script files that would not
-have a syntax compatible with Python 3. The most immediate error is the use of
-printing "*print*" with "*command*" syntax instead of functional syntax
-"*print(...)*". In this case, it is suggested to correct the syntax of user
-files in environment 8 before switching to environment 9.
-
-Switching from 8.x to 8.y with y > x
-++++++++++++++++++++++++++++++++++++
-
-There is no known incompatibility for the ADAO case files. The upgrade procedure
-is to read the old ADAO case file with the new SALOME/ADAO module, and save it
-with a new name.
-
-To make future developments easier, it is strongly recommended to ensure that
-your user scripts files use a Python 2 and a Python 3 compatible syntax. In
-particular, it is recommended to use the functional syntax for "*print*" and not
-the "*command*" syntax, for example::
-
- # Python 2 & 3
- x, unit = 1., "cm"
- print( "x = %s %s"%(str(x),str(unit)) )
-
-or::
-
- # Python 2 & 3
- x, unit = 1., "cm"
- print( "x = {0} {1}".format(str(x),str(unit)) )
-
-rather than::
-
- # Python 2 only
- x, unit = 1., "cm"
- print "x =", x, unit
-
-Switching from 7.8 to 8.1
-+++++++++++++++++++++++++
-
-There is no known incompatibility for the ADAO case files. The upgrade procedure
-is to read the old ADAO case file with the new SALOME/ADAO module, and save it
-with a new name.
-
-Switching from 7.x to 7.y with y > x
-++++++++++++++++++++++++++++++++++++
-
-There is no known incompatibility for the ADAO case files. The upgrade procedure
-is to read the old ADAO case file with the new SALOME/ADAO module, and save it
-with a new name.
-
-Switching from 6.6 to 7.2
-+++++++++++++++++++++++++
-
-There is no known incompatibility for the ADAO case files. The upgrade procedure
-is to read the old ADAO case file with the new SALOME/ADAO module, and save it
-with a new name.
-
-There is one incompatibility introduced for the post-processing or observer
-script files. The old syntax to call a result object, such as the "*Analysis*"
-one (in a script provided through the "*UserPostAnalysis*" keyword), was for
-example::
-
- Analysis = ADD.get("Analysis").valueserie(-1)
- Analysis = ADD.get("Analysis").valueserie()
-
-The new syntax is entirely similar to the (classical) one of a list or tuple
-object::
-
- Analysis = ADD.get("Analysis")[-1]
- Analysis = ADD.get("Analysis")[:]
-
-The post-processing scripts has to be modified.
-
-Switching from 6.x to 6.y with y > x
-++++++++++++++++++++++++++++++++++++
-
-There is no known incompatibility for the ADAO case file. The upgrade procedure
-is to read the old ADAO case file with the new SALOME/ADAO module, and save it
-with a new name.
-
-There is one incompatibility introduced for the operator script files, in the
-naming of operators used to for the observation operator. The new mandatory
-names are "*DirectOperator*", "*TangentOperator*" and "*AdjointOperator*", as
-described in the last subsection of the chapter :ref:`section_reference`. The
-operator script files has to be modified.
-
.. [#] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform.
detailed :ref:`section_reference`, with three essential main sub-parts
describing the details of commands and options of the algorithms. A
:ref:`section_glossary`, some :ref:`section_notations`, a
-:ref:`section_bibliography` and an extensive index are included in the
-document. And, to comply with the module requirements, be sure to read the part
-:ref:`section_license`.
+:ref:`section_bibliography`, some elements about :ref:`section_versions`, and
+an extensive index are included in the document. And, to comply with the module
+requirements, be sure to read the part :ref:`section_license`.
.. toctree::
:caption: Table of contents
gui_in_salome
tui
reference
+ versions
+ notations
license
bibliography
- notations
glossary
genindex
It applies to non-linear observation and incremental evolution (process)
operators with excellent robustness and performance qualities. It can be
+interpreted as an order reduction of the classical Kalman filter, with a
+remarkable assimilation quality of this filtering for large problems. It can be
compared to the :ref:`section_ref_algorithm_UnscentedKalmanFilter`, whose
qualities are similar for non-linear systems.
to evaluate on small systems. One can verify the linearity of the operators
with the help of the :ref:`section_ref_algorithm_LinearityTest`.
-There exists a lot of variants of this algorithm. The following stable and
-robust formulations are proposed here:
+There are many deterministic or stochastic variants of this algorithm, allowing
+in particular to perform size reduction of algebraic problems at different
+levels (by using reduced rank methods, dimension reduction, changes of
+computational space, leading to schemes of type Ensemble Square Root Kalman
+Filters (EnSRKF) or Reduced-Rank Square Root Filters (RRSQRT), to deterministic
+transformations...). We do not go into the complex details of classifications
+and algorithmic equivalences, which are available in the literature. The
+following stable and robust formulations are proposed here:
.. index::
pair: Variant ; EnKF
pair: Variant ; IEnKF
pair: Variant ; E3DVAR
pair: Variant ; EnKS
+ pair: Variant ; EnSRKF
+ pair: Variant ; RRSQRT
- "EnKF" (Ensemble Kalman Filter, see [Evensen94]_), original stochastic algorithm, allowing consistent treatment of non-linear evolution operator,
- "ETKF" (Ensemble-Transform Kalman Filter), deterministic EnKF algorithm, allowing treatment of non-linear evolution operator with a lot less members (one recommends to use a number of members on the order of 10 or even sometimes less),
- "EnKS" (Ensemble Kalman Smoother), smoothing algorithm with a fixed time lag L.
Without being a universal recommandation, one recommend to use "EnKF"
-formulation as a reference algorithm, "ETKF-N" ou "IEnKF" formulation for
-robust performance, and the other algorithms (in this order) as means to obtain
-a less costly data assimilation with (hopefully) the same quality.
+formulation as a reference algorithm, **"ETKF-N" ou "IEnKF" formulation for
+robust performance**, and the other algorithms (in this order) as means to
+obtain a less costly data assimilation with (hopefully) the same quality.
.. ------------------------------------ ..
.. include:: snippets/Header2Algo02.rst
.. include:: snippets/InitialDirection.rst
+.. include:: snippets/NumberOfPrintedDigits.rst
+
.. include:: snippets/ResiduFormula_GradientTest.rst
.. include:: snippets/SetSeed.rst
.. include:: snippets/InitialDirection.rst
+.. include:: snippets/NumberOfPrintedDigits.rst
+
.. include:: snippets/ResiduFormula_LinearityTest.rst
.. include:: snippets/SetSeed.rst
12 1e-12 2.236e+00 1.910e+01 3.536e-12 0.000e+00
-------------------------------------------------------------
- End of the verification by "ScalarProduct" formula
+ End of the "ADJOINTTEST" verification by the "ScalarProduct" formula.
---------------------------------------------------------------------------
---------------------------------------------------------------------------
+ End of the "CONTROLEDFUNCTIONTEST" verification
+
+ ---------------------------------------------------------------------------
+
---------------------------------------------------------------------------
+ End of the "CONTROLEDFUNCTIONTEST" verification
+
+ ---------------------------------------------------------------------------
+
---------------------------------------------------------------------------
+ End of the "FUNCTIONTEST" verification
+
+ ---------------------------------------------------------------------------
+
---------------------------------------------------------------------------
+ End of the "FUNCTIONTEST" verification
+
+ ---------------------------------------------------------------------------
+
for i in range(51):
Yobs.append([random.normal(Xtrue, 0.1, size=(1,)),])
#
-print("Estimation of a constant variable by filtering")
-print("----------------------------------------------")
+print("Estimation by filtering of a time trajectory")
+print("--------------------------------------------")
print(" Noisy measurements acquired on %i time steps"%(len(Yobs)-1,))
print("")
from adao import adaoBuilder
-Estimation of a constant variable by filtering
-----------------------------------------------
+Estimation by filtering of a time trajectory
+--------------------------------------------
Noisy measurements acquired on 50 time steps
Analyzed state at current observation: [0.]
for i in range(51):
Yobs.append([random.normal(Xtrue, 0.1, size=(1,)),])
#
-print("Estimation of a constant variable by filtering")
-print("----------------------------------------------")
+print("Estimation by filtering of a time trajectory")
+print("--------------------------------------------")
print(" Noisy measurements acquired on %i time steps"%(len(Yobs)-1,))
print("")
from adao import adaoBuilder
-Estimation of a constant variable by filtering
-----------------------------------------------
+Estimation by filtering of a time trajectory
+--------------------------------------------
Noisy measurements acquired on 50 time steps
Analyzed state at final observation: [-0.37725236]
---------------------------------------------------------------------------
+ End of the "PARALLELFUNCTIONTEST" verification
+
+ ---------------------------------------------------------------------------
+
--- /dev/null
+..
+ Copyright (C) 2008-2023 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_versions:
+
+================================================================================
+Versions of ADAO and external compatibility
+================================================================================
+
+.. _subsection_new_adao_version:
+.. index::
+ pair: Version ; ADAO
+ pair: Version of ADAO ; Switching
+
+Switching from a version of ADAO to a newer one
+-----------------------------------------------
+
+The ADAO module and its ".comm" case files are identified by versions, with
+"Major", "Minor", "Revision" and optionally "Installation" characteristics. A
+particular version is numbered as "Major.Minor.Revision", with strong link with
+the numbering of the SALOME platform. The optional indication of a fourth
+number indicates a difference in the installation method, not in the content of
+the version.
+
+Each version "Major.Minor.Revision" of the ADAO module can read ADAO case files
+of the previous minor version "Major.Minor-1.*". In general, it can also read
+ADAO case files of all the previous minor versions for one major branch, but it
+is not guaranteed for all the commands or keywords. In general also, an ADAO
+case file for one version can not be read by a previous minor or major version
+of the ADAO module.
+
+Switching from 9.x to 9.y with y > x
+++++++++++++++++++++++++++++++++++++
+
+There is no known incompatibility for the ADAO case files. The upgrade procedure
+is to read the old ADAO case file with the new SALOME/ADAO module, and save it
+with a new name.
+
+However, there may be incompatibilities from user cases written directly in TUI
+interface. It is advisable to review the syntax and arguments in the TUI
+scripts at each version change. In particular, it is advisable to check that
+the algorithm parameters are still adequate and active, knowing that it has
+been explicitly chosen that there is no message when a parameter becomes
+inactive (for the example, we quote the parameter "*MaximumNumberOfSteps*" as
+having changed its name to "*MaximumNumberOfIterations*", for homogeneity with
+the variables that can be displayed).
+
+Switching from 8.5 to 9.2
++++++++++++++++++++++++++
+
+There is no known incompatibility for the ADAO case files. The upgrade procedure
+is to read the old ADAO case file with the new SALOME/ADAO module, and save it
+with a new name.
+
+However, there may be incompatibilities from user script files that would not
+have a syntax compatible with Python 3. The most immediate error is the use of
+printing "*print*" with "*command*" syntax instead of functional syntax
+"*print(...)*". In this case, it is suggested to correct the syntax of user
+files in environment 8 before switching to environment 9.
+
+Switching from 8.x to 8.y with y > x
+++++++++++++++++++++++++++++++++++++
+
+There is no known incompatibility for the ADAO case files. The upgrade procedure
+is to read the old ADAO case file with the new SALOME/ADAO module, and save it
+with a new name.
+
+To make future developments easier, it is strongly recommended to ensure that
+your user scripts files use a Python 2 and a Python 3 compatible syntax. In
+particular, it is recommended to use the functional syntax for "*print*" and not
+the "*command*" syntax, for example::
+
+ # Python 2 & 3
+ x, unit = 1., "cm"
+ print( "x = %s %s"%(str(x),str(unit)) )
+
+or::
+
+ # Python 2 & 3
+ x, unit = 1., "cm"
+ print( "x = {0} {1}".format(str(x),str(unit)) )
+
+rather than::
+
+ # Python 2 only
+ x, unit = 1., "cm"
+ print "x =", x, unit
+
+Switching from 7.8 to 8.1
++++++++++++++++++++++++++
+
+There is no known incompatibility for the ADAO case files. The upgrade procedure
+is to read the old ADAO case file with the new SALOME/ADAO module, and save it
+with a new name.
+
+Switching from 7.x to 7.y with y > x
+++++++++++++++++++++++++++++++++++++
+
+There is no known incompatibility for the ADAO case files. The upgrade procedure
+is to read the old ADAO case file with the new SALOME/ADAO module, and save it
+with a new name.
+
+Switching from 6.6 to 7.2
++++++++++++++++++++++++++
+
+There is no known incompatibility for the ADAO case files. The upgrade procedure
+is to read the old ADAO case file with the new SALOME/ADAO module, and save it
+with a new name.
+
+There is one incompatibility introduced for the post-processing or observer
+script files. The old syntax to call a result object, such as the "*Analysis*"
+one (in a script provided through the "*UserPostAnalysis*" keyword), was for
+example::
+
+ Analysis = ADD.get("Analysis").valueserie(-1)
+ Analysis = ADD.get("Analysis").valueserie()
+
+The new syntax is entirely similar to the (classical) one of a list or tuple
+object::
+
+ Analysis = ADD.get("Analysis")[-1]
+ Analysis = ADD.get("Analysis")[:]
+
+The post-processing scripts has to be modified.
+
+Switching from 6.x to 6.y with y > x
+++++++++++++++++++++++++++++++++++++
+
+There is no known incompatibility for the ADAO case file. The upgrade procedure
+is to read the old ADAO case file with the new SALOME/ADAO module, and save it
+with a new name.
+
+There is one incompatibility introduced for the operator script files, in the
+naming of operators used to for the observation operator. The new mandatory
+names are "*DirectOperator*", "*TangentOperator*" and "*AdjointOperator*", as
+described in the last subsection of the chapter :ref:`section_reference`. The
+operator script files has to be modified.
+
+.. _subsection_version_compatibility:
+.. index::
+ pair: Version ; ADAO
+ pair: Version ; SALOME
+ pair: Version ; EFICAS
+ pair: Version ; Python
+ pair: Version ; Numpy
+ pair: Version ; Scipy
+ pair: Version ; MatplotLib
+ pair: Version ; Gnuplot
+ pair: Version ; NLopt
+
+Versions of ADAO compatibility with support tools
+-------------------------------------------------
+
+.. include:: snippets/ModuleValidation.rst
+
+.. include:: snippets/ModuleCompatibility.rst
.. _section_advanced:
================================================================================
-**[DocU]** Usages avancés du module ADAO
+**[DocU]** Usages avancés du module ADAO et interopérabilité
================================================================================
Cette section présente des méthodes avancées d'usage du module ADAO, comment
expériences jumelles ou pas) car ils résolvent de nombreux problèmes rencontrés
en pratique.
-.. _subsection_version_compatibility:
-.. index::
- pair: Version ; SALOME
- pair: Version ; EFICAS
- pair: Version ; Python
- pair: Version ; Numpy
- pair: Version ; Scipy
- pair: Version ; MatplotLib
- pair: Version ; Gnuplot
- pair: Version ; NLopt
-
-Versions de compatibilité d'ADAO avec les outils support
---------------------------------------------------------
-
-.. include:: snippets/ModuleValidation.rst
-
-.. include:: snippets/ModuleCompatibility.rst
-
-.. _subsection_new_adao_version:
-.. index::
- pair: Version d'ADAO ; Changement de
-
-Passer d'une version d'ADAO à une nouvelle
-------------------------------------------
-
-Le module ADAO et ses fichiers de cas ".comm" sont identifiés par des versions,
-avec des caractéristiques "Major", "Minor", "Revision" et optionnellement
-"Installation". Une version particulière est numérotée "Major.Minor.Revision",
-avec un lien fort avec la numérotation de la plateforme SALOME. L'indication
-optionnelle d'un quatrième numéro désigne une différence dans le mode
-d'installation, pas dans le contenu de la version.
-
-Chaque version "Major.Minor.Revision" du module ADAO peut lire les fichiers de
-cas ADAO de la précédente version mineure "Major.Minor-1.*". En général, elle
-peut aussi lire les fichiers de cas de toutes les versions mineures "Major.*.*"
-d'une branche majeure, mais ce n'est pas obligatoirement vrai pour toutes les
-commandes ou tous les mots-clés. En général aussi, un fichier de cas ADAO d'une
-version ne peut pas être lu par une précédente version mineure ou majeure du
-module ADAO.
-
-Passer de la version 9.x à la 9.y avec y > x
-++++++++++++++++++++++++++++++++++++++++++++
-
-Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
-procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
-avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
-
-Cependant, il peut se présenter des incompatibilités provenant de cas
-utilisateurs écrits directement en interface TUI. Il est conseillé de revoir la
-syntaxe et les arguments dans les scripts TUI à chaque changement de version.
-En particulier, il convient de vérifier que les paramètres d'algorithme sont
-toujours adéquats et actifs, sachant qu'il a été explicitement choisi qu'il n'y
-ait pas de message lorsqu'un paramètre devient inactif (pour l'exemple, on cite
-le paramètre "*MaximumNumberOfSteps*" comme ayant changé de nom pour devenir
-"*MaximumNumberOfIterations*", par homogénéité avec les variables pouvant être
-affichées).
-
-Passer de la version 8.5 à la 9.2
-+++++++++++++++++++++++++++++++++
-
-Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
-procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
-avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
-
-Cependant, il peut se présenter des incompatibilités provenant de fichiers
-scripts utilisateurs qui n'auraient pas une syntaxe compatible avec Python 3.
-L'erreur la plus immédiate est l'usage de l'impression "*print*" avec la
-syntaxe "*commande*" au lieu de la syntaxe fonctionnelle "*print(...)*". Dans
-ce cas, il est suggéré de corriger la syntaxe des fichiers utilisateurs dans
-l'environnement 8 avant de passer en environnement 9.
-
-Passer de la version 8.x à la 8.y avec y > x
-++++++++++++++++++++++++++++++++++++++++++++
-
-Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
-procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
-avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
-
-Pour faciliter les futures évolutions, il est fortement recommandé de veiller à
-ce que vos fichiers scripts utilisateurs utilisent une syntaxe compatible avec
-Python 2 et avec Python 3. En particulier, on recommande d'utiliser la syntaxe
-fonctionnelle pour les "*print*" et non pas la syntaxe "*commande*", comme par
-exemple :
-::
-
- # Python 2 & 3
- x, unit = 1., "cm"
- print( "x = %s %s"%(str(x),str(unit)) )
-
-ou :
-::
-
- # Python 2 & 3
- x, unit = 1., "cm"
- print( "x = {0} {1}".format(str(x),str(unit)) )
-
-plutôt que :
-::
-
- # Python 2 uniquement
- x, unit = 1., "cm"
- print "x =", x, unit
-
-Passer de la version 7.8 à la 8.1
-+++++++++++++++++++++++++++++++++
-
-Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
-procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
-avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
-
-Passer de la version 7.x à la 7.y avec y > x
-++++++++++++++++++++++++++++++++++++++++++++
-
-Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
-procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
-avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
-
-Passer de la version 6.6 à la 7.2
-+++++++++++++++++++++++++++++++++
-
-Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
-procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
-le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
-
-Il y a une incompatibilité introduite dans les fichiers de script de
-post-processing ou d'observers. L'ancienne syntaxe pour interroger un objet
-résultat, comme celui d'analyse "*Analysis*" (fourni dans un script à travers le
-mot-clé "*UserPostAnalysis*"), était par exemple :
-::
-
- Analysis = ADD.get("Analysis").valueserie(-1)
- Analysis = ADD.get("Analysis").valueserie()
-
-La nouvelle syntaxe est entièrement compatible avec celle (classique) pour les
-objets de type liste ou tuple :
-::
-
- Analysis = ADD.get("Analysis")[-1]
- Analysis = ADD.get("Analysis")[:]
-
-Les scripts de post-processing doivent être modifiés.
-
-Passer de la version 6.x à la 6.y avec y > x
-++++++++++++++++++++++++++++++++++++++++++++
-
-Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
-procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
-le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
-
-Il y a une incompatibilité introduite dans les fichiers de script d'opérateur,
-lors de la dénomination des opérateurs élémentaires utilisés pour l'opérateur
-d'observation par script. Les nouveaux noms requis sont "*DirectOperator*",
-"*TangentOperator*" et "*AdjointOperator*", comme décrit dans la quatrième
-partie du chapitre :ref:`section_reference`. Les fichiers de script d'opérateur
-doivent être modifiés.
-
.. [#] Pour de plus amples informations sur YACS, voir le *module YACS* et son aide intégrée disponible dans le menu principal *Aide* de l'environnement SALOME.
dernière grande partie détaille la :ref:`section_reference`, avec trois
sous-parties essentielles qui la composent et qui décrivent les commandes et
des options d'algorithmes. Un :ref:`section_glossary`, des
-:ref:`section_notations`, une :ref:`section_bibliography` et un index développé
-complètent le document. Enfin, pour respecter les exigences de licence du
-module, n'oubliez pas de lire la partie :ref:`section_license`.
+:ref:`section_notations`, une :ref:`section_bibliography`, des éléments de
+changement des :ref:`section_versions`, et un index développé complètent le
+document. Enfin, pour respecter les exigences de licence du module, n'oubliez
+pas de lire la partie :ref:`section_license`.
.. toctree::
:caption: Table des matières
gui_in_salome
tui
reference
+ versions
+ notations
license
bibliography
- notations
glossary
genindex
Notations et conventions communes
=================================
+.. index:: single: Fichier (nommage)
+.. index:: single: Fichier (type)
+
Dans cette documentation, on utilise les notations standards de l'algèbre
linéaire, de l'assimilation de données (comme décrit dans [Ide97]_) et de
l'optimisation.
-Pour les formulations algébriques, les vecteurs sont écrits horizontalement ou
-verticalement sans faire la différence. Les matrices sont écrites soit
-normalement, ou avec une notation condensée, consistant à utiliser un espace
-pour séparer les valeurs, et un "``;``" pour séparer les lignes de la matrice,
-de façon continue sur une ligne.
+Pour les formulations algébriques, les **vecteurs** sont écrits horizontalement
+ou verticalement sans faire la différence. Les **matrices** peuvent s'écrire
+soit normalement comme une série de série de chiffres, soit en notation
+condensée en texte, consistant à utiliser un espace pour séparer les valeurs,
+et un "``;``" pour séparer les lignes de la matrice, de façon continue sur une
+ligne.
-Les fichiers peuvent être indiqués grâce à un chemin absolu ou relatif. Pour
-certains systèmes de fichiers anciens ou partagés, le nom complet avec le
-chemin ne doit pas contenir plus de 256 caractères. Dans le cas où ce sont des
-fichiers de type Python, il est judicieux de ne pas utiliser de points dans le
-nom à part pour l'extension, pour éviter des difficultés d'utilisation
-compliquées à diagnostiquer.
+Les **fichiers** peuvent être indiqués grâce à un chemin absolu ou relatif.
+Pour certains systèmes de fichiers anciens ou partagés, le nom complet, y
+compris le chemin, ne doit pas contenir plus de 256 caractères. Dans le cas où
+ce sont des fichiers de type Python, il est judicieux de ne pas utiliser de
+points dans le nom à part pour l'extension, pour éviter des difficultés
+d'utilisation qui sont ensuite compliquées à diagnostiquer.
-Les conventions de type et de nommage des fichiers s'appuient fortement sur les
-extensions des fichiers eux-mêmes. On en précise brièvement certaines ici, sans
-être exhaustifs :
+Les **conventions de type et de nommage des fichiers** s'appuient fortement sur
+les extensions des fichiers eux-mêmes. On en précise brièvement certaines ici,
+sans être exhaustifs :
-- extension ``.py`` : fichier texte de données ou commandes de type source Python
+- extension ``.py`` : fichier texte de données ou de commandes de type Python
- extension ``.comm`` : fichier texte de données de commandes EFICAS d'ADAO
- extension ``.xml`` : fichier texte de données de type XML (pour YACS, non exclusif)
- extension ``.txt`` : fichier texte de données à séparateur espace
- extension ``.npz`` : fichier binaire de données de type Numpy multi-variables
- extension ``.sdf`` : fichier binaire de données de type Scientific Data Format
+Pour l'usage de certains de ces fichiers, on pourra se reporter au mot-clé
+"*DataFile*" comme :ref:`section_ref_entry_types_info`.
+
.. ------------------------------------ ..
.. include:: snippets/Header2Algo07.rst
Il s'applique aux cas d'opérateurs d'observation et d'évolution incrémentale
(processus) non-linéaires et présente d'excellentes qualités de robustesse et
-de performances. Il peut être rapproché de
+de performances. Il peut être interprété comme une réduction d'ordre du filtre
+de Kalman classique, avec une remarquable qualité d'assimilation de ce
+filtrage pour les problèmes de grande taille. Il peut être rapproché de
l':ref:`section_ref_algorithm_UnscentedKalmanFilter` dont les qualités sont
similaires pour les systèmes non-linéaires.
coûteux en évaluations sur de petits systèmes. On peut vérifier la linéarité
des opérateurs à l'aide de l':ref:`section_ref_algorithm_LinearityTest`.
-Il existe de nombreuses variantes de cet algorithme. On propose ici des
-formulations stables et robustes suivantes :
+Il existe de nombreuses variantes déterministes ou stochastiques de cet
+algorithme, permettant en particulier d'effectuer de la réduction de taille des
+problèmes algébriques à différents niveaux (en utilisant des méthodes de rang
+réduit, de la réduction de dimension, des changements d'espace de calcul,
+conduisant à des schémas de type Ensemble Square Root Kalman Filters (EnSRKF)
+ou Reduced-Rank Square Root Filters (RRSQRT), à des transformations
+déterministes...). On ne rentre pas ici dans le détail complexe des
+classifications et des équivalences algorithmiques, qui sont disponibles dans
+la littérature. On propose ici les formulations stables et robustes suivantes :
.. index::
pair: Variant ; EnKF
pair: Variant ; IEnKF
pair: Variant ; E3DVAR
pair: Variant ; EnKS
+ pair: Variant ; EnSRKF
+ pair: Variant ; RRSQRT
- "EnKF" (Ensemble Kalman Filter, voir [Evensen94]_), algorithme stochastique original, permettant de traiter de manière consistante un opérateur d'évolution non-linéaire,
- "ETKF" (Ensemble-Transform Kalman Filter), algorithme déterministe d'EnKF, permettant de traiter un opérateur d'évolution non-linéaire avec beaucoup moins de membres (on recommande d'utiliser un nombre de membres de l'ordre de 10 ou même parfois moins),
- "EnKS" (Ensemble Kalman Smoother), algorithme de lissage avec un décalage fixe.
Sans pouvoir prétendre à l'universalité, on recommande d'utiliser la
-formulation "EnKF" comme référence, la formulation "ETKF-N" ou "IEnKF" pour une
-performance robuste, et les autres algorithmes (dans l'ordre) comme des moyens
-pour obtenir une assimilation de données plus économique et de qualité
+formulation "EnKF" comme référence, **la formulation "ETKF-N" ou "IEnKF" pour
+une performance robuste**, et les autres algorithmes (dans l'ordre) comme des
+moyens pour obtenir une assimilation de données plus économique et de qualité
(éventuellement) similaire.
.. ------------------------------------ ..
.. include:: snippets/InitialDirection.rst
+.. include:: snippets/NumberOfPrintedDigits.rst
+
.. include:: snippets/ResiduFormula_GradientTest.rst
.. include:: snippets/SetSeed.rst
.. include:: snippets/InitialDirection.rst
+.. include:: snippets/NumberOfPrintedDigits.rst
+
.. include:: snippets/ResiduFormula_LinearityTest.rst
.. include:: snippets/SetSeed.rst
12 1e-12 2.236e+00 1.910e+01 3.536e-12 0.000e+00
-------------------------------------------------------------
- End of the verification by "ScalarProduct" formula
+ End of the "ADJOINTTEST" verification by the "ScalarProduct" formula.
---------------------------------------------------------------------------
---------------------------------------------------------------------------
+ End of the "CONTROLEDFUNCTIONTEST" verification
+
+ ---------------------------------------------------------------------------
+
---------------------------------------------------------------------------
+ End of the "CONTROLEDFUNCTIONTEST" verification
+
+ ---------------------------------------------------------------------------
+
---------------------------------------------------------------------------
+ End of the "FUNCTIONTEST" verification
+
+ ---------------------------------------------------------------------------
+
---------------------------------------------------------------------------
+ End of the "FUNCTIONTEST" verification
+
+ ---------------------------------------------------------------------------
+
for i in range(51):
Yobs.append([random.normal(Xtrue, 0.1, size=(1,)),])
#
-print("Estimation par filtrage d'une variable constante")
-print("------------------------------------------------")
+print("Estimation par filtrage d'une trajectoire temporelle")
+print("----------------------------------------------------")
print(" Observations bruitées acquises sur %i pas de temps"%(len(Yobs)-1,))
print("")
from adao import adaoBuilder
-Estimation par filtrage d'une variable constante
-------------------------------------------------
+Estimation par filtrage d'une trajectoire temporelle
+----------------------------------------------------
Observations bruitées acquises sur 50 pas de temps
État analysé à l'observation courante : [0.]
for i in range(51):
Yobs.append([random.normal(Xtrue, 0.1, size=(1,)),])
#
-print("Estimation par filtrage d'une variable constante")
-print("------------------------------------------------")
+print("Estimation par filtrage d'une trajectoire temporelle")
+print("----------------------------------------------------")
print(" Observations bruitées acquises sur %i pas de temps"%(len(Yobs)-1,))
print("")
from adao import adaoBuilder
-Estimation par filtrage d'une variable constante
-------------------------------------------------
+Estimation par filtrage d'une trajectoire temporelle
+----------------------------------------------------
Observations bruitées acquises sur 50 pas de temps
État analysé à l'observation finale : [-0.37725236]
---------------------------------------------------------------------------
+ End of the "PARALLELFUNCTIONTEST" verification
+
+ ---------------------------------------------------------------------------
+
--- /dev/null
+..
+ Copyright (C) 2008-2023 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_versions:
+
+================================================================================
+Versions d'ADAO et compatibilités externes
+================================================================================
+
+.. _subsection_new_adao_version:
+.. index::
+ pair: Version ; ADAO
+ pair: Version d'ADAO ; Changement de
+
+Passer d'une version d'ADAO à une nouvelle
+------------------------------------------
+
+Le module ADAO et ses fichiers de cas ".comm" sont identifiés par des versions,
+avec des caractéristiques "Major", "Minor", "Revision" et optionnellement
+"Installation". Une version particulière est numérotée "Major.Minor.Revision",
+avec un lien fort avec la numérotation de la plateforme SALOME. L'indication
+optionnelle d'un quatrième numéro désigne une différence dans le mode
+d'installation, pas dans le contenu de la version.
+
+Chaque version "Major.Minor.Revision" du module ADAO peut lire les fichiers de
+cas ADAO de la précédente version mineure "Major.Minor-1.*". En général, elle
+peut aussi lire les fichiers de cas de toutes les versions mineures "Major.*.*"
+d'une branche majeure, mais ce n'est pas obligatoirement vrai pour toutes les
+commandes ou tous les mots-clés. En général aussi, un fichier de cas ADAO d'une
+version ne peut pas être lu par une précédente version mineure ou majeure du
+module ADAO.
+
+Passer de la version 9.x à la 9.y avec y > x
+++++++++++++++++++++++++++++++++++++++++++++
+
+Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
+procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
+avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
+
+Cependant, il peut se présenter des incompatibilités provenant de cas
+utilisateurs écrits directement en interface TUI. Il est conseillé de revoir la
+syntaxe et les arguments dans les scripts TUI à chaque changement de version.
+En particulier, il convient de vérifier que les paramètres d'algorithme sont
+toujours adéquats et actifs, sachant qu'il a été explicitement choisi qu'il n'y
+ait pas de message lorsqu'un paramètre devient inactif (pour l'exemple, on cite
+le paramètre "*MaximumNumberOfSteps*" comme ayant changé de nom pour devenir
+"*MaximumNumberOfIterations*", par homogénéité avec les variables pouvant être
+affichées).
+
+Passer de la version 8.5 à la 9.2
++++++++++++++++++++++++++++++++++
+
+Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
+procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
+avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
+
+Cependant, il peut se présenter des incompatibilités provenant de fichiers
+scripts utilisateurs qui n'auraient pas une syntaxe compatible avec Python 3.
+L'erreur la plus immédiate est l'usage de l'impression "*print*" avec la
+syntaxe "*commande*" au lieu de la syntaxe fonctionnelle "*print(...)*". Dans
+ce cas, il est suggéré de corriger la syntaxe des fichiers utilisateurs dans
+l'environnement 8 avant de passer en environnement 9.
+
+Passer de la version 8.x à la 8.y avec y > x
+++++++++++++++++++++++++++++++++++++++++++++
+
+Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
+procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
+avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
+
+Pour faciliter les futures évolutions, il est fortement recommandé de veiller à
+ce que vos fichiers scripts utilisateurs utilisent une syntaxe compatible avec
+Python 2 et avec Python 3. En particulier, on recommande d'utiliser la syntaxe
+fonctionnelle pour les "*print*" et non pas la syntaxe "*commande*", comme par
+exemple :
+::
+
+ # Python 2 & 3
+ x, unit = 1., "cm"
+ print( "x = %s %s"%(str(x),str(unit)) )
+
+ou :
+::
+
+ # Python 2 & 3
+ x, unit = 1., "cm"
+ print( "x = {0} {1}".format(str(x),str(unit)) )
+
+plutôt que :
+::
+
+ # Python 2 uniquement
+ x, unit = 1., "cm"
+ print "x =", x, unit
+
+Passer de la version 7.8 à la 8.1
++++++++++++++++++++++++++++++++++
+
+Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
+procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
+avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
+
+Passer de la version 7.x à la 7.y avec y > x
+++++++++++++++++++++++++++++++++++++++++++++
+
+Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
+procédure de montée en version consiste à lire l'ancien fichier de cas ADAO
+avec le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
+
+Passer de la version 6.6 à la 7.2
++++++++++++++++++++++++++++++++++
+
+Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
+procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
+le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
+
+Il y a une incompatibilité introduite dans les fichiers de script de
+post-processing ou d'observers. L'ancienne syntaxe pour interroger un objet
+résultat, comme celui d'analyse "*Analysis*" (fourni dans un script à travers le
+mot-clé "*UserPostAnalysis*"), était par exemple :
+::
+
+ Analysis = ADD.get("Analysis").valueserie(-1)
+ Analysis = ADD.get("Analysis").valueserie()
+
+La nouvelle syntaxe est entièrement compatible avec celle (classique) pour les
+objets de type liste ou tuple :
+::
+
+ Analysis = ADD.get("Analysis")[-1]
+ Analysis = ADD.get("Analysis")[:]
+
+Les scripts de post-processing doivent être modifiés.
+
+Passer de la version 6.x à la 6.y avec y > x
+++++++++++++++++++++++++++++++++++++++++++++
+
+Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La
+procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec
+le nouveau module SALOME/ADAO, et à l'enregistrer avec un nouveau nom.
+
+Il y a une incompatibilité introduite dans les fichiers de script d'opérateur,
+lors de la dénomination des opérateurs élémentaires utilisés pour l'opérateur
+d'observation par script. Les nouveaux noms requis sont "*DirectOperator*",
+"*TangentOperator*" et "*AdjointOperator*", comme décrit dans la quatrième
+partie du chapitre :ref:`section_reference`. Les fichiers de script d'opérateur
+doivent être modifiés.
+
+.. _subsection_version_compatibility:
+.. index::
+ pair: Version ; ADAO
+ pair: Version ; SALOME
+ pair: Version ; EFICAS
+ pair: Version ; Python
+ pair: Version ; Numpy
+ pair: Version ; Scipy
+ pair: Version ; MatplotLib
+ pair: Version ; Gnuplot
+ pair: Version ; NLopt
+
+Versions de compatibilité d'ADAO avec les outils support
+--------------------------------------------------------
+
+.. include:: snippets/ModuleValidation.rst
+
+.. include:: snippets/ModuleCompatibility.rst
