errors. Parts of the framework are also known under the names of
*parameter estimation*, *inverse problems*, *Bayesian estimation*,
*optimal interpolation*, etc. More details can be found in the full
-ADAO documentation (see http://www.salome-platform.org/).
+ADAO documentation (see https://www.salome-platform.org/).
Only the use of ADAO text programming interface (API/TUI) is introduced
here. This interface gives ability to create a calculation object in a
More advanced examples of ADAO TUI calculation case
---------------------------------------------------
-Real cases involves observations loaded from files, operators
-explicitly defined as generic functions including physical simulators,
-time dependant information in order to deal with forecast analysis in
-addition to calibration or re-analysis. More details can be found in
-the full ADAO documentation (see http://www.salome-platform.org/).
+Real cases involve observations loaded from files, operators explicitly
+defined as generic functions including physical simulators, time dependant
+information in order to deal with forecast analysis in addition to calibration
+or re-analysis. More details can be found in the full ADAO documentation (see
+documentation on the reference site https://www.salome-platform.org/, with
+https://docs.salome-platform.org/latest/gui/ADAO/en/index.html for english or
+https://docs.salome-platform.org/latest/gui/ADAO/fr/index.html for french, both
+being equivalents).
License and requirements
------------------------
case = adaoBuilder.New()
It is recommended to import by default the ``numpy`` module or some of its
-embedded constructors such as the ``array`` one, to make easier its upcoming use
-in the commands.
+embedded constructors such as the ``array`` one, to make easier its upcoming
+use in the commands.
Thereafter, the case has to be build by preparing and storing the data that
define the study. The commands order does not matter, it is sufficient that all
-the concepts, required by the algorithm used, are present. The user can refer to
-the :ref:`section_reference` and its subparts to get details about commands by
-algorithm. Here, we define successively the chosen data assimilation or
+the concepts, required by the algorithm used, are present. The user can refer
+to the :ref:`section_reference` and its subparts to get details about commands
+by algorithm. Here, we define successively the chosen data assimilation or
optimization algorithm and its parameters, then the *a priori* state
:math:`\mathbf{x}^b` (named ``Background``) and its errors covariance
:math:`\mathbf{B}` (named ``BackgroundError``), and after that, the observation
For these last two cases, one has only to import Numpy module before.
After that, one has to define the operators :math:`H` of observation and
-possibly :math:`M` of evolution. In all cases, linear or non-linear, they can be
-defined as functions. In the simple case of a linear operator, one can also
+possibly :math:`M` of evolution. In all cases, linear or non-linear, they can
+be defined as functions. In the simple case of a linear operator, one can also
define it using the matrix that corresponds to the linear operator. In the most
simple present case of a linear operator, we use the following syntax for an
operator from :math:`\mathbf{R}^3` into itself::
:math:`\mathbf{R}^p`, it has to be previously available as a Python function,
known in the current name space, which takes a ``numpy`` vector (or an ordered
list) of size :math:`n` as input and which returns as output a ``numpy`` vector
-of size :math:`p`. When the non-linear operator is the only one to be defined by
-the keyword "*OneFunction*", its adjoint is directly established by numerical
-calculations and it can be parametrized by the keyword "*Parameters*". The
-following example shows a ``simulation`` function (which realizes here the same
-linear operator than above) and record it in the ADAO case::
+of size :math:`p`. When the non-linear operator is the only one to be defined
+by the keyword "*OneFunction*", its adjoint is directly established by
+numerical calculations and it can be parametrized by the keyword
+"*Parameters*". The following example shows a ``simulation`` function (which
+realizes here the same linear operator than above) and record it in the ADAO
+case::
import numpy
def simulation(x):
case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
-Finally, when all the required information are available in the ADAO calculation
-case named ``case``, it can be executed in a very simple way in the environment
-of the Python interpreter::
+Finally, when all the required information are available in the ADAO
+calculation case named ``case``, it can be executed in a very simple way in the
+environment of the Python interpreter::
case.execute()
of the language to enter more complex data than explicit declaration.
The registering of input data supports various variable types, but in addition,
-these inputs can come from variables currently available in the name space of the
-script. It is then easy to use previously calculated variables or obtained by
-importing "user" scripts. If for example the observations are available as a
+these inputs can come from variables currently available in the name space of
+the script. It is then easy to use previously calculated variables or obtained
+by importing "user" scripts. If for example the observations are available as a
list in an external Python file named ``observations.py`` under the name
-``table``, the registering of the observations in the ADAO TUI calculation
-case can be done by the following operations::
+``table``, the registering of the observations in the ADAO TUI calculation case
+can be done by the following operations::
from observations import table
case.set( 'Observation', Vector=table )
second one register directly this table as the "*Observation*" data.
The simplicity of this recording demonstrates the ease of obtaining
-computational data from external sources, files or computing flows achievable in
-Python. As usual, it is recommended to the user to check its data before saving
-them in the ADAO TUI calculation case to avoid errors complicated to correct.
+computational data from external sources, files or computing flows achievable
+in Python. As usual, it is recommended to the user to check its data before
+saving them in the ADAO TUI calculation case to avoid errors complicated to
+correct.
Obtain and use the results of calculation in a richer way
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
recommendations to make the distinction between public objects, and private or
reserved ones because of implementation details. In practice, every object or
function name beginning with at least one "**_**" sign is private in the usual
-programming sense ("*private*"). Nevertheless, the absence of such a sign at the
-beginning of a name does not designate it as public. In general, in Python, and
-unlike other languages, you can access private objects or functions. This can
-sometimes be useful, but such use in your codes will lead to crashes without
-warning in future versions. It is strongly recommended not to do so.
+programming sense ("*private*"). Nevertheless, the absence of such a sign at
+the beginning of a name does not designate it as public. In general, in Python,
+and unlike other languages, you can access private objects or functions. This
+can sometimes be useful, but such use in your codes will lead to crashes
+without warning in future versions. It is strongly recommended not to do so.
To clarify and facilitate the use of the module for scripting, **this section
therefore defines the application programming interface (API) for textual user
interface (TUI) by a comprehensive and restricted manner**. Use in scripts of
-ADAO objects or functions other than those defined here is strongly discouraged,
-as this will likely lead to crashes without warning in future versions.
+ADAO objects or functions other than those defined here is strongly
+discouraged, as this will likely lead to crashes without warning in future
+versions.
Equivalent syntax calls for commands
++++++++++++++++++++++++++++++++++++
- or use the command ``setXXXXX`` containing the arguments of the command to
apply.
-To illustrate this equivalence, we take the example of two commands that lead to
-the same result::
+To illustrate this equivalence, we take the example of two commands that lead
+to the same result::
case.set( 'Background', Vector=[0, 1, 2] )
case.setBackground( Vector=[0, 1, 2] )
-The choice of one or the other syntaxes is freely left to the user, according to
-its context of use. In the following, for clarity, we define the controls
+The choice of one or the other syntaxes is freely left to the user, according
+to its context of use. In the following, for clarity, we define the controls
according to the second syntax.
Creating a calculation case in TUI text interface
case = adaoBuilder.New()
It is recommended by default to always import the ``numpy`` module (or some of
-its embedded constructors such as the ``array`` one) to make easier its upcoming
-use in the commands.
+its embedded constructors such as the ``array`` one) to make easier its
+upcoming use in the commands.
Defining the calculation data
+++++++++++++++++++++++++++++
case. The pseudo-type of the arguments is similar and consistent with those of
the inputs in GUI interface, as described in section of
:ref:`section_reference_entry` and in particular by the
-:ref:`section_ref_entry_types`. The verification of the adequacy of variables is
-done either on their definition, or at runtime.
+:ref:`section_ref_entry_types`. The verification of the adequacy of variables
+is done either on their definition, or at runtime.
.. index:: single: Stored
-In each command, the boolean keyword "*Stored*" indicates whether you optionally
-want to store the quantity defined, for disposal during calculation or at the
-output. The default is not to store, and it is recommended to keep this default.
-Indeed, for a TUI calculation case, the quantity given in entries are often
-available in the current name space of the case.
+In each command, the boolean keyword "*Stored*" indicates whether you
+optionally want to store the quantity defined, for disposal during calculation
+or at the output. The default is not to store, and it is recommended to keep
+this default. Indeed, for a TUI calculation case, the quantity given in entries
+are often available in the current name space of the case.
The available commands are:
+.. index:: single: Background
.. index:: single: setBackground
**setBackground** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
default or those from the list "*ColNames*"), the vector is of type
"*Vector*".
+.. index:: single: BackgroundError
.. index:: single: setBackgroundError
**setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
- This command allows to set the matrix :math:`\mathbf{B}` of background error
- covariance. The matrix may be completely defined by the "*Matrix*" keyword,
- or in a sparse way, by a diagonal matrix whose unique variance is given on
- the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix which one
- gives the vector of variances located on the diagonal by
+ This command allows to set the matrix :math:`\mathbf{B}` of background
+ error covariance. The matrix may be completely defined by the "*Matrix*"
+ keyword, or in a sparse way, by a diagonal matrix whose unique variance is
+ given on the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix
+ which one gives the vector of variances located on the diagonal by
"*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
"*DiagonalSparseMatrix*" according to whether one of these variables is
positioned to "*True*".
+.. index:: single: CheckingPoint
.. index:: single: setCheckingPoint
**setCheckingPoint** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
"*ColMajor*", all the variables by default or those from the list
"*ColNames*"), the vector is of type "*Vector*".
+.. index:: single: ControlModel
.. index:: single: setControlModel
+.. index:: single: ExtraArguments
-**setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArgs, Stored*)
+**setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArguments, Stored*)
This command allows to set the control operator :math:`O`, which represents
an external linear input control of the evolution or observation operator.
One can refer to the :ref:`section_ref_operator_control`. Its value is
defined as an object of type function or of type "*Matrix*". For the
function case, various functional forms may be used, as described in the
:ref:`section_ref_operator_requirements`, and entered by "*OneFunction*" or
- "*ThreeFunctions*" keywords. If it is defined by a script in the "*Script*"
- keyword, the operator is of type "*Matrix*", "*OneFunction*" or
- "*ThreeFunctions*" according to whether one of these variables is positioned
- to "*True*". The control parameters of the adjoint numerical approximation,
- in the "*OneFunction*"case, can be given by a dictionary through the
- "*Parameters*" keyword. Potential entries of this dictionary are
- "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similar to the one
- of graphical interface).
-
+ "*ThreeFunctions*" keywords. If it is defined by a script in the
+ "*Script*" keyword, the operator is of type "*Matrix*", "*OneFunction*" or
+ "*ThreeFunctions*" according to whether one of these variables is
+ positioned to "*True*". The control parameters of the adjoint numerical
+ approximation, in the "*OneFunction*"case, can be given by a dictionary
+ through the "*Parameters*" keyword. Potential entries of this dictionary
+ are "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similar to the
+ one of graphical interface). If the operator requires some complementary
+ fixed arguments, they can be given through the variable "*ExtraArguments*"
+ as a named parameters dictionary.
+
+.. index:: single: ControlInput
.. index:: single: setControlInput
**setControlInput** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
default or those from the list "*ColNames*"), the vector is of type
"*Vector*".
+.. index:: single: EvolutionError
.. index:: single: setEvolutionError
**setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
"*DiagonalSparseMatrix*" according to whether one of these variables is
positioned to "*True*".
+.. index:: single: EvolutionModel
.. index:: single: setEvolutionModel
+.. index:: single: ExtraArguments
-**setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArgs, Stored*)
- This command allows to set the evolution operator :math:`M`, which describes
- an elementary evolution step. Its value is defined as an object of type
- function or of type "*Matrix*". For the function case, various functional
- forms may be used, as described in the
+**setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArguments, Stored*)
+ This command allows to set the evolution operator :math:`M`, which
+ describes an elementary evolution step. Its value is defined as an object
+ of type function or of type "*Matrix*". For the function case, various
+ functional forms may be used, as described in the
:ref:`section_ref_operator_requirements`, and entered by "*OneFunction*" or
- "*ThreeFunctions*" keywords. If it is defined by a script in the "*Script*"
- keyword, the operator is of type "*Matrix*", "*OneFunction*" or
- "*ThreeFunctions*" according to whether one of these variables is positioned
- to "*True*". The control parameters of the adjoint numerical approximation,
- in the "*OneFunction*"case, can be given by a dictionary through the
- "*Parameters*" keyword. Potential entries of this dictionary are
- "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similar to the one
- of graphical interface).
-
+ "*ThreeFunctions*" keywords. If it is defined by a script in the
+ "*Script*" keyword, the operator is of type "*Matrix*", "*OneFunction*" or
+ "*ThreeFunctions*" according to whether one of these variables is
+ positioned to "*True*". The control parameters of the adjoint numerical
+ approximation, in the "*OneFunction*"case, can be given by a dictionary
+ through the "*Parameters*" keyword. Potential entries of this dictionary
+ are "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similar to the
+ one of graphical interface). If the operator requires some complementary
+ fixed arguments in addition to the state :math:`\mathbf{x}`, they can be
+ given through the variable "*ExtraArguments*" as a named parameters
+ dictionary.
+
+.. index:: single: Observation
.. index:: single: setObservation
**setObservation** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
the variables by default or those from the list "*ColNames*"), the vector
is of type "*Vector*".
+.. index:: single: ObservationError
.. index:: single: setObservationError
**setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
"*DiagonalSparseMatrix*" according to whether one of these variables is
positioned to "*True*".
+.. index:: single: ObservationOperator
.. index:: single: setObservationOperator
+.. index:: single: ExtraArguments
-**setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, AppliedInXb, Parameters, Script, ExtraArgs, Stored*)
+**setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, AppliedInXb, Parameters, Script, ExtraArguments, Stored*)
This command allows to set the evolution operator :math:`H`, which
transforms the input parameters :math:`\mathbf{x}` in results
:math:`\mathbf{y}` that are compared to observations :math:`\mathbf{y}^o`.
Its value is defined as an object of type function or of type "*Matrix*".
- For the function case, various functional forms may be used, as described in
- the :ref:`section_ref_operator_requirements`, and entered by "*OneFunction*"
- or "*ThreeFunctions*" keywords. If it is defined by a script in the
- "*Script*" keyword, the operator is of type "*Matrix*", "*OneFunction*" or
- "*ThreeFunctions*" according to whether one of these variables is positioned
- to "*True*". When the :math:`H` operator evaluated in :math:`\mathbf{x}^b`
- is available, it can be given using "*AppliedInXb*" and will be considered
- as a vector. The control parameters of the adjoint numerical approximation,
- in the "*OneFunction*"case, can be given by a dictionary through the
- "*Parameters*" keyword. Potential entries of this dictionary are
- "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similar to the one
- of graphical interface).
+ For the function case, various functional forms may be used, as described
+ in the :ref:`section_ref_operator_requirements`, and entered by
+ "*OneFunction*" or "*ThreeFunctions*" keywords. If it is defined by a
+ script in the "*Script*" keyword, the operator is of type "*Matrix*",
+ "*OneFunction*" or "*ThreeFunctions*" according to whether one of these
+ variables is positioned to "*True*". When the :math:`H` operator evaluated
+ in :math:`\mathbf{x}^b` is available, it can be given using "*AppliedInXb*"
+ and will be considered as a vector. The control parameters of the adjoint
+ numerical approximation, in the "*OneFunction*"case, can be given by a
+ dictionary through the "*Parameters*" keyword. Potential entries of this
+ dictionary are "*DifferentialIncrement*", "*CenteredFiniteDifference*"
+ (similar to the one of graphical interface). If the operator requires some
+ complementary fixed arguments in addition to the state :math:`\mathbf{x}`,
+ they can be given through the variable "*ExtraArguments*" as a named
+ parameters dictionary.
.. index:: single: set
Setting the calculation, outputs, etc.
++++++++++++++++++++++++++++++++++++++
+.. index:: single: AlgorithmParameters
.. index:: single: setAlgorithmParameters
**setAlgorithmParameters** (*Algorithm, Parameters, Script*)
This command allows to choose the calculation or the verification algorithm
- by the argument "*Algorithm*" in the form of an algorithm name (it is useful
- to refer to the :ref:`section_reference_assimilation` and to the
+ by the argument "*Algorithm*" in the form of an algorithm name (it is
+ useful to refer to the :ref:`section_reference_assimilation` and to the
:ref:`section_reference_checking`) and to define the calculation parameters
by the argument "*Parameters*". In the case of a definition by "*Script*",
- the file must contain the two variables "*Algorithm*" and "*Parameters*" (or
- "*AlgorithmParameters*" equivalently).
+ the file must contain the two variables "*Algorithm*" and "*Parameters*"
+ (or "*AlgorithmParameters*" equivalently).
.. index:: single: setName
**setNoDebug** ()
This command disables the detailed information mode when running.
+.. index:: single: Observer
.. index:: single: setObserver
**setObserver** (*Variable, Template, String, Script, Info*)
:ref:`section_ref_observers_requirements`. The "*Info*" variable contains
an information string or can be void.
+.. index:: single: UserPostAnalysis
+.. index:: single: setUserPostAnalysis
+.. index:: single: setUserPostAnalysis Template
+
+**setUserPostAnalysis** (*Template, String, Script*)
+ This command allows to define the treatment of parameters or results after
+ the calculation algorithm has been performed. Its value is defined as a
+ predefined pattern name, a script file or a string. This allows to produce
+ directly post-processing code in an ADAO case. It is possible to use
+ patterns available by argument "*Template*" (which can be
+ "*AnalysisPrinter*", "*AnalysisSaver*" and "*AnalysisPrinterAndSaver*"). In
+ the case of a definition by "*Script*", the specified file must contain
+ only the commands that could have been put after the execution of the
+ calculation.
+
Perform the calculation
+++++++++++++++++++++++
calcul TUI ADAO. Les commandes elles-mêmes sont détaillées juste après dans
l':ref:`subsection_tui_commands`.
-La création et l'initialisation d'une étude se font par les commandes suivantes,
-le nom ``case`` de l'objet du cas de calcul TUI ADAO étant quelconque, au choix
-de l'utilisateur::
+La création et l'initialisation d'une étude se font par les commandes
+suivantes, le nom ``case`` de l'objet du cas de calcul TUI ADAO étant
+quelconque, au choix de l'utilisateur::
from numpy import array, matrix
from adao import adaoBuilder
constructeurs particuliers comme celui d'``array``, pour faciliter ensuite son
usage dans les commandes elle-mêmes.
-Ensuite, le cas doit être construit par une préparation et un enregistrement des
-données définissant l'étude. L'ordre de ces commande n'a pas d'importance, il
-suffit que les concepts requis par l'algorithme utilisé soient présentes. On se
-reportera à :ref:`section_reference` et à ses sous-parties pour avoir le détail
-des commandes par algorithme. Ici, on définit successivement l'algorithme
-d'assimilation de données ou d'optimisation choisi et ses paramètres, puis
-l'ébauche :math:`\mathbf{x}^b` (nommée ``Background``) et sa covariance
-d'erreurs :math:`\mathbf{B}` (nommée ``BackgroundError``), et enfin
+Ensuite, le cas doit être construit par une préparation et un enregistrement
+des données définissant l'étude. L'ordre de ces commande n'a pas d'importance,
+il suffit que les concepts requis par l'algorithme utilisé soient présentes. On
+se reportera à :ref:`section_reference` et à ses sous-parties pour avoir le
+détail des commandes par algorithme. Ici, on définit successivement
+l'algorithme d'assimilation de données ou d'optimisation choisi et ses
+paramètres, puis l'ébauche :math:`\mathbf{x}^b` (nommée ``Background``) et sa
+covariance d'erreurs :math:`\mathbf{B}` (nommée ``BackgroundError``), et enfin
l'observation :math:`\mathbf{y}^o` (nommée ``Observation``) et sa covariance
d'erreurs :math:`\mathbf{R}` (nommée ``ObservationError``)::
case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
On remarque que l'on peut donner, en entrée des quantités vectorielles ou
-matricielles, des objets de type ``str``, ``list`` ou ``tuple`` de Python, ou de
-type ``array`` ou ``matrix`` de Numpy. Dans ces deux derniers cas, il faut
+matricielles, des objets de type ``str``, ``list`` ou ``tuple`` de Python, ou
+de type ``array`` ou ``matrix`` de Numpy. Dans ces deux derniers cas, il faut
simplement importer le module Numpy avant.
-On doit ensuite définir les opérateurs :math:`H` d'observation et éventuellement
-:math:`M` d'évolution. Dans tous les cas, linéaire ou non-linéaire, on peut les
-définir comme des fonctions. Dans le cas simple d'un opérateur linéaire, on peut
-aussi le définir à l'aide de la matrice qui correspond à l'opérateur linéaire.
-Dans le cas présent le plus simple d'opérateur linéaire, on utilise la syntaxe
-suivante pour un opérateur de :math:`\mathbf{R}^3` sur lui-même::
+On doit ensuite définir les opérateurs :math:`H` d'observation et
+éventuellement :math:`M` d'évolution. Dans tous les cas, linéaire ou
+non-linéaire, on peut les définir comme des fonctions. Dans le cas simple d'un
+opérateur linéaire, on peut aussi le définir à l'aide de la matrice qui
+correspond à l'opérateur linéaire. Dans le cas présent le plus simple
+d'opérateur linéaire, on utilise la syntaxe suivante pour un opérateur de
+:math:`\mathbf{R}^3` sur lui-même::
case.set( 'ObservationOperator', Matrix = "1 0 0;0 2 0;0 0 3")
Pour connaître les résultats intermédiaire ou finaux du calcul du cas, on peut
ajouter des "*observer*", qui permettent d'associer l'exécution d'un script à
-une variable intermédiaire ou finale du calcul. On se reportera à la description
-de la manière d':ref:`section_advanced_observer`, et à la :ref:`section_reference`
-pour savoir quelles sont les quantités observables. Cette association
-d'"*observer*" avec une quantité existante se fait de manière similaire à la
-définition des données du calcul::
+une variable intermédiaire ou finale du calcul. On se reportera à la
+description de la manière d':ref:`section_advanced_observer`, et à la
+:ref:`section_reference` pour savoir quelles sont les quantités observables.
+Cette association d'"*observer*" avec une quantité existante se fait de manière
+similaire à la définition des données du calcul::
case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
from observations import table
case.set( 'Observation', Vector=table )
-La première ligne importe la variable ``table`` depuis le fichier externe, et la
-seconde enregistre directement cette table comme la donnée "*Observation*".
+La première ligne importe la variable ``table`` depuis le fichier externe, et
+la seconde enregistre directement cette table comme la donnée "*Observation*".
La simplicité de cet enregistrement montre bien la facilité d'obtenir les
données de calcul depuis des sources externes, fichiers ou flux informatiques
Obtenir et utiliser les résultats de calcul de manière plus riche
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-De la même manière, il est possible d'obtenir et traiter les résultats de calcul
-de manière plus riche, pour enchaîner sur des post-traitements après le calcul
-en TUI.
+De la même manière, il est possible d'obtenir et traiter les résultats de
+calcul de manière plus riche, pour enchaîner sur des post-traitements après le
+calcul en TUI.
Les variables de résultats de calcul, ou les variables internes issues de
l'optimisation ou de l'assimilation de données, sont disponibles à travers la
-méthode ``get`` du cas de calcul TUI ADAO, qui renvoie un objet de type liste de
-la variable demandée. On se reportera aux :ref:`section_ref_output_variables`
-pour une description détaillée sur ce sujet.
+méthode ``get`` du cas de calcul TUI ADAO, qui renvoie un objet de type liste
+de la variable demandée. On se reportera aux
+:ref:`section_ref_output_variables` pour une description détaillée sur ce
+sujet.
A titre d'exemple, on donne quelques lignes de script qui permettent d'obtenir
le nombre d'itérations de l'optimisation et la valeur optimale ainsi que sa
De même que pour l'entrée des données, la simplicité de récupération des
résultats permet d'envisager aisément des post-traitements enchaînés dans
-SALOME, pour utiliser par exemple de la visualisation avec MatPlotLib ou PARAVIS
-[PARAVIS]_, de l'adaptation de maillage avec HOMARD [HOMARD]_, ou pour d'autres
-calculs.
+SALOME, pour utiliser par exemple de la visualisation avec MatPlotLib ou
+PARAVIS [PARAVIS]_, de l'adaptation de maillage avec HOMARD [HOMARD]_, ou pour
+d'autres calculs.
.. _subsection_tui_commands:
Dans l'interface TUI du module ADAO, on suit les conventions et recommandations
courantes en Python pour la distinction entre ce qui est public, et ce qui est
-privé ou réservé car relevant des détails d'implémentation. De manière pratique,
-tout nom d'objet ou de fonction commençant par au moins un signe "_" est privé
-au sens courant de programmation ("*private*"). Néanmoins, l'absence d'un tel
-signe au début d'un nom ne le désigne pas comme public. De manière générale, en
-Python, et contrairement à d'autres langages, on peut accéder aux objets ou aux
-fonction privés. Cela peut parfois être utile, mais un tel usage dans vos codes
-conduira à des plantages sans avertissement lors de futures versions. Il est
-donc fortement recommandé de ne pas le faire.
+privé ou réservé car relevant des détails d'implémentation. De manière
+pratique, tout nom d'objet ou de fonction commençant par au moins un signe "_"
+est privé au sens courant de programmation ("*private*"). Néanmoins, l'absence
+d'un tel signe au début d'un nom ne le désigne pas comme public. De manière
+générale, en Python, et contrairement à d'autres langages, on peut accéder aux
+objets ou aux fonction privés. Cela peut parfois être utile, mais un tel usage
+dans vos codes conduira à des plantages sans avertissement lors de futures
+versions. Il est donc fortement recommandé de ne pas le faire.
Pour clarifier et faciliter l'utilisation du module pour du script, **cette
section définit donc l'interface de programmation (API) textuelle publique pour
Syntaxes d'appel équivalentes pour les commandes TUI
++++++++++++++++++++++++++++++++++++++++++++++++++++
-La définition des données lors de la création de cas de calcul TUI ADAO supporte
-**deux syntaxes entièrement équivalentes**. On peut :
+La définition des données lors de la création de cas de calcul TUI ADAO
+supporte **deux syntaxes entièrement équivalentes**. On peut :
- soit utiliser la commande ``set`` et comme premier argument le concept
``XXXXX`` sur lequel appliquer la commande dont les arguments suivent,
Création d'un cas de calcul en interface textuelle TUI
++++++++++++++++++++++++++++++++++++++++++++++++++++++
-La création et l'initialisation d'un cas de calcul en interface textuelle TUI se
-font en important le module d'interface "*adaoBuilder*" et en invoquant sa
+La création et l'initialisation d'un cas de calcul en interface textuelle TUI
+se font en important le module d'interface "*adaoBuilder*" et en invoquant sa
méthode "*New()*" comme illustré dans les quelques lignes suivantes (le nom
``case`` de l'objet étant quelconque, au choix de l'utilisateur)::
+++++++++++++++++++++++++++++
Les commandes qui suivent permettent de définir les données d'un cas de calcul
-TUI ADAO. Le pseudo-type des arguments est similaire et compatible avec ceux des
-entrées en interface GUI, décrits dans la section des
+TUI ADAO. Le pseudo-type des arguments est similaire et compatible avec ceux
+des entrées en interface GUI, décrits dans la section des
:ref:`section_reference_entry` et en particulier par la
-:ref:`section_ref_entry_types`. La vérification de l'adéquation des grandeurs se
-fait soit lors de leur définition, soit lors de l'exécution.
+:ref:`section_ref_entry_types`. La vérification de l'adéquation des grandeurs
+se fait soit lors de leur définition, soit lors de l'exécution.
.. index:: single: Stored
Dans chaque commande, le mot-clé booléen "*Stored*" permet d'indiquer si l'on
veut éventuellement stocker la grandeur définie, pour en disposer en cours de
calcul ou en sortie. Le choix par défaut est de ne pas stocker, et il est
-recommandé de conserver cette valeur par défaut. En effet, pour un cas de calcul
-TUI, on dispose déjà souvent des grandeurs données en entrées qui sont présentes
-dans l'espace de nommage courant du cas.
+recommandé de conserver cette valeur par défaut. En effet, pour un cas de
+calcul TUI, on dispose déjà souvent des grandeurs données en entrées qui sont
+présentes dans l'espace de nommage courant du cas.
Les commandes disponibles sont les suivantes :
+.. index:: single: Background
.. index:: single: setBackground
**setBackground** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
défaut ou celles de la liste "*ColNames*"), le vecteur est de type
"*Vector*".
+.. index:: single: BackgroundError
.. index:: single: setBackgroundError
**setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
"*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
selon que l'une de ces variables est placée à "*True*".
+.. index:: single: CheckingPoint
.. index:: single: setCheckingPoint
**setCheckingPoint** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
défaut ou celles de la liste "*ColNames*"), le vecteur est de type
"*Vector*".
+.. index:: single: ControlModel
.. index:: single: setControlModel
+.. index:: single: ExtraArguments
-**setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArgs, Stored*)
+**setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArguments, Stored*)
Cette commande permet de définir l'opérateur de contrôle :math:`O`, qui
décrit un contrôle d'entrée linéaire externe de l'opérateur d'évolution ou
d'observation. On se reportera :ref:`section_ref_operator_control`. Sa
adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
dictionnaire à travers le mot-clé "*Parameters*". Les entrées potentielles
de ce dictionnaire de paramètres sont "*DifferentialIncrement*",
- "*CenteredFiniteDifference*" (similaires à celles de l'interface graphique).
+ "*CenteredFiniteDifference*" (similaires à celles de l'interface
+ graphique). Si l'opérateur nécessite des arguments fixes complémentaires,
+ ils peuvent être fournis par la variable "*ExtraArguments*" sous la forme
+ d'un dictionnaire de paramètres nommés.
+.. index:: single: ControlInput
.. index:: single: setControlInput
**setControlInput** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
les variables par défaut ou celles de la liste "*ColNames*"), le vecteur
est de type "*Vector*".
+.. index:: single: EvolutionError
.. index:: single: setEvolutionError
**setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
"*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
selon que l'une de ces variables est placée à "*True*".
+.. index:: single: EvolutionModel
.. index:: single: setEvolutionModel
+.. index:: single: ExtraArguments
-**setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArgs, Stored*)
+**setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArguments, Stored*)
Cette commande permet de définir l'opérateur d'evolution :math:`M`, qui
- décrit un pas élémentaire d'évolution. Sa valeur est définie comme un objet
- de type fonction ou de type "*Matrix*". Dans le cas d'une fonction,
- différentes formes fonctionnelles peuvent être utilisées, comme décrit dans
- la section :ref:`section_ref_operator_requirements`, et entrées par les
- mots-clés "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une
- définition par "*Script*", l'opérateur est de type "*Matrix*",
- "*OneFunction*" ou "*ThreeFunctions*" selon que l'une de ces variables est
- placée à "*True*". Les paramètres de contrôle de l'approximation numérique
- de l'opérateur adjoint, dans le cas "*OneFunction*", peuvent être renseignés
- par un dictionnaire dans "*Parameters*". Les entrées potentielles de ce
+ décrit un pas élémentaire d'évolution de l'état :math:`\mathbf{x}`. Sa
+ valeur est définie comme un objet de type fonction ou de type "*Matrix*".
+ Dans le cas d'une fonction, différentes formes fonctionnelles peuvent être
+ utilisées, comme décrit dans la section
+ :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
+ "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
+ "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
+ "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
+ Les paramètres de contrôle de l'approximation numérique de l'opérateur
+ adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
+ dictionnaire dans "*Parameters*". Les entrées potentielles de ce
dictionnaire de paramètres sont "*DifferentialIncrement*",
"*CenteredFiniteDifference*", "*EnableMultiProcessing*",
- "*NumberOfProcesses*" (similaires à celles de l'interface graphique).
+ "*NumberOfProcesses*" (similaires à celles de l'interface graphique). Si
+ l'opérateur nécessite des paramètres fixes complémentaires en plus de
+ l'état :math:`\mathbf{x}`, ils peuvent être fournis par la variable
+ "*ExtraArguments*" sous la forme d'un dictionnaire de paramètres nommés.
+.. index:: single: Observation
.. index:: single: setObservation
**setObservation** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
"*ColMajor*", toutes les variables par défaut ou celles de la liste
"*ColNames*"), le vecteur est de type "*Vector*".
+.. index:: single: ObservationError
.. index:: single: setObservationError
**setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
covariance des erreurs d'observation. La matrice peut être définie de
manière complète par le mot-clé "*Matrix*", ou de manière parcimonieuse,
comme une matrice diagonale dont on donne la variance unique sur la
- diagonale par "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on
- donne le vecteur des variances situé sur la diagonale par
- "*DiagonalSparseMatrix*". Si on la définit par un script dans "*Script*", la
- matrice est de type "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou
+ diagonale par "*ScalarSparseMatrix*", ou comme une matrice diagonale dont
+ on donne le vecteur des variances situé sur la diagonale par
+ "*DiagonalSparseMatrix*". Si on la définit par un script dans "*Script*",
+ la matrice est de type "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou
"*DiagonalSparseMatrix*" selon que l'une de ces variables est placée à
"*True*".
+.. index:: single: ObservationOperator
.. index:: single: setObservationOperator
+.. index:: single: ExtraArguments
-**setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, AppliedInXb, Parameters, Script, ExtraArgs, Stored*)
+**setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, AppliedInXb, Parameters, Script, ExtraArguments, Stored*)
Cette commande permet de définir l'opérateur d'observation :math:`H`, qui
transforme les paramètres d'entrée :math:`\mathbf{x}` en résultats
:math:`\mathbf{y}` qui sont à comparer aux observations
disponible, il peut être donné en utilisant "*AppliedInXb*" et sera
considéré comme un vecteur. Les paramètres de contrôle de l'approximation
numérique de l'opérateur adjoint, dans le cas "*OneFunction*", peuvent être
- renseignés par un dictionnaire dans "*Parameters*". Les entrées potentielles
- de ce dictionnaire de paramètres sont "*DifferentialIncrement*",
- "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
- "*NumberOfProcesses*" (similaires à celles de l'interface graphique).
+ renseignés par un dictionnaire dans "*Parameters*". Les entrées
+ potentielles de ce dictionnaire de paramètres sont
+ "*DifferentialIncrement*", "*CenteredFiniteDifference*",
+ "*EnableMultiProcessing*", "*NumberOfProcesses*" (similaires à celles de
+ l'interface graphique). Si l'opérateur nécessite des paramètres fixes
+ complémentaires en plus de l'état :math:`\mathbf{x}`, ils peuvent être
+ fournis par la variable "*ExtraArguments*" sous la forme d'un dictionnaire
+ de paramètres nommés.
.. index:: single: set
Paramétrer le calcul, les sorties, etc.
+++++++++++++++++++++++++++++++++++++++
+.. index:: single: AlgorithmParameters
.. index:: single: setAlgorithmParameters
**setAlgorithmParameters** (*Algorithm, Parameters, Script*)
Cette commande permet de désactiver le mode d'information détaillé lors de
l'exécution.
+.. index:: single: Observer
.. index:: single: setObserver
**setObserver** (*Variable, Template, String, Script, Info*)
décrit dans les :ref:`section_ref_observers_requirements`. La variable
"*Info*" contient une chaîne de caractère d'information ou une chaine vide.
+.. index:: single: UserPostAnalysis
+.. index:: single: setUserPostAnalysis
+.. index:: single: setUserPostAnalysis Template
+
+**setUserPostAnalysis** (*Template, String, Script*)
+ Cette commande permet de définir le traitement des paramètres ou des
+ résultats après le déroulement de l'algorithme de calcul. Sa valeur est
+ définie comme nom de patron prédéfini, un fichier script ou une chaîne de
+ caractères. Cela permet de produire directement du code de post-processing
+ dans un cas ADAO. On peut d'utiliser les patrons disponibles par l'argument
+ "*Template*" (qui peut valoir "*AnalysisPrinter*", "*AnalysisSaver*" et
+ "*AnalysisPrinterAndSaver*"). Dans le cas d'une définition par "*Script*",
+ le fichier indiqué doit contenir uniquement les commandes que l'on aurait
+ pu mettre à la suite de l'exécution du calcul.
+
Effectuer le calcul
+++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
L'objectif est d'effectuer en TUI la mise en données d'un cas de calcul ADAO,
-son exécution, puis la récupération des résultats pour ensuite enchaîner sur une
-exploitation indépendante de ces résultats (cette dernière n'étant pas décrite
-ici, puisque dépendante de l'utilisateur).
+son exécution, puis la récupération des résultats pour ensuite enchaîner sur
+une exploitation indépendante de ces résultats (cette dernière n'étant pas
+décrite ici, puisque dépendante de l'utilisateur).
Les hypothèses du cas utilisateur sont les suivantes. On suppose :
centeredDF = __Function["CenteredFiniteDifference"],
increment = __Function["DifferentialIncrement"],
dX = __Function["withdX"],
+ extraArguments = self.__extraArgs,
avoidingRedundancy = __Function["withAvoidingRedundancy"],
toleranceInRedundancy = __Function["withToleranceInRedundancy"],
lenghtOfRedundancy = __Function["withLenghtOfRedundancy"],
#
# Calculs effectifs
if __mpEnabled:
- _jobs = []
- if _extraArguments is None:
- _jobs = __xserie
- elif _extraArguments is not None and isinstance(_extraArguments, (list, tuple, map)):
- for __xvalue in __xserie:
- _jobs.append( [__xvalue, ] + list(_extraArguments) )
- else:
- raise TypeError("MultiFonction extra arguments unkown input type: %s"%(type(_extraArguments),))
+ _jobs = __xserie
# logging.debug("MULTF Internal multiprocessing calculations begin : evaluation of %i point(s)"%(len(_jobs),))
import multiprocessing
with multiprocessing.Pool(__mpWorkers) as pool:
# logging.getLogger().setLevel(logging.DEBUG)
# ==============================================================================
-def ExecuteFunction( paire ):
- assert len(paire) == 2, "Incorrect number of arguments"
- X, funcrepr = paire
+def ExecuteFunction( triplet ):
+ assert len(triplet) == 3, "Incorrect number of arguments"
+ X, xArgs, funcrepr = triplet
__X = numpy.asmatrix(numpy.ravel( X )).T
__sys_path_tmp = sys.path ; sys.path.insert(0,funcrepr["__userFunction__path"])
__module = __import__(funcrepr["__userFunction__modl"], globals(), locals(), [])
__fonction = getattr(__module,funcrepr["__userFunction__name"])
sys.path = __sys_path_tmp ; del __sys_path_tmp
- __HX = __fonction( __X )
+ if isinstance(xArgs, dict):
+ __HX = __fonction( __X, **xArgs )
+ else:
+ __HX = __fonction( __X )
return numpy.ravel( __HX )
# ==============================================================================
centeredDF = False,
increment = 0.01,
dX = None,
+ extraArguments = None,
avoidingRedundancy = True,
toleranceInRedundancy = 1.e-18,
lenghtOfRedundancy = -1,
mfEnabled = False,
):
self.__name = str(name)
+ self.__extraArgs = extraArguments
if mpEnabled:
try:
import multiprocessing
self.__userFunction__modl = os.path.basename(mod).replace('.pyc','').replace('.pyo','').replace('.py','')
self.__userFunction__path = os.path.dirname(mod)
del mod
- self.__userOperator = Operator( name = self.__name, fromMethod = Function, avoidingRedundancy = self.__avoidRC, inputAsMultiFunction = self.__mfEnabled )
+ self.__userOperator = Operator( name = self.__name, fromMethod = Function, avoidingRedundancy = self.__avoidRC, inputAsMultiFunction = self.__mfEnabled, extraArguments = self.__extraArgs )
self.__userFunction = self.__userOperator.appliedTo # Pour le calcul Direct
elif isinstance(Function,types.MethodType):
logging.debug("FDA Calculs en multiprocessing : MethodType")
self.__userFunction__modl = os.path.basename(mod).replace('.pyc','').replace('.pyo','').replace('.py','')
self.__userFunction__path = os.path.dirname(mod)
del mod
- self.__userOperator = Operator( name = self.__name, fromMethod = Function, avoidingRedundancy = self.__avoidRC, inputAsMultiFunction = self.__mfEnabled )
+ self.__userOperator = Operator( name = self.__name, fromMethod = Function, avoidingRedundancy = self.__avoidRC, inputAsMultiFunction = self.__mfEnabled, extraArguments = self.__extraArgs )
self.__userFunction = self.__userOperator.appliedTo # Pour le calcul Direct
else:
raise TypeError("User defined function or method has to be provided for finite differences approximation.")
else:
- self.__userOperator = Operator( name = self.__name, fromMethod = Function, avoidingRedundancy = self.__avoidRC, inputAsMultiFunction = self.__mfEnabled )
+ self.__userOperator = Operator( name = self.__name, fromMethod = Function, avoidingRedundancy = self.__avoidRC, inputAsMultiFunction = self.__mfEnabled, extraArguments = self.__extraArgs )
self.__userFunction = self.__userOperator.appliedTo
#
self.__centeredDF = bool(centeredDF)
return __ac, __iac
# ---------------------------------------------------------
- def DirectOperator(self, X ):
+ def DirectOperator(self, X, **extraArgs ):
"""
Calcul du direct à l'aide de la fonction fournie.
+
+ NB : les extraArgs sont là pour assurer la compatibilité d'appel, mais
+ ne doivent pas être données ici à la fonction utilisateur.
"""
logging.debug("FDA Calcul DirectOperator (explicite)")
if self.__mfEnabled:
_X_moins_dXi = numpy.array( _X.A1, dtype=float )
_X_moins_dXi[i] = _X[i] - _dXi
#
- _jobs.append( (_X_plus_dXi, funcrepr) )
- _jobs.append( (_X_moins_dXi, funcrepr) )
+ _jobs.append( (_X_plus_dXi, self.__extraArgs, funcrepr) )
+ _jobs.append( (_X_moins_dXi, self.__extraArgs, funcrepr) )
#
import multiprocessing
self.__pool = multiprocessing.Pool(self.__mpWorkers)
"__userFunction__name" : self.__userFunction__name,
}
_jobs = []
- _jobs.append( (_X.A1, funcrepr) )
+ _jobs.append( (_X.A1, self.__extraArgs, funcrepr) )
for i in range( len(_dX) ):
_X_plus_dXi = numpy.array( _X.A1, dtype=float )
_X_plus_dXi[i] = _X[i] + _dX[i]
#
- _jobs.append( (_X_plus_dXi, funcrepr) )
+ _jobs.append( (_X_plus_dXi, self.__extraArgs, funcrepr) )
#
import multiprocessing
self.__pool = multiprocessing.Pool(self.__mpWorkers)
return _Jacobienne
# ---------------------------------------------------------
- def TangentOperator(self, paire ):
+ def TangentOperator(self, paire, **extraArgs ):
"""
Calcul du tangent à l'aide de la Jacobienne.
+
+ NB : les extraArgs sont là pour assurer la compatibilité d'appel, mais
+ ne doivent pas être données ici à la fonction utilisateur.
"""
if self.__mfEnabled:
assert len(paire) == 1, "Incorrect lenght of arguments"
else: return _HtX.A1
# ---------------------------------------------------------
- def AdjointOperator(self, paire ):
+ def AdjointOperator(self, paire, **extraArgs ):
"""
Calcul de l'adjoint à l'aide de la Jacobienne.
+
+ NB : les extraArgs sont là pour assurer la compatibilité d'appel, mais
+ ne doivent pas être données ici à la fonction utilisateur.
"""
if self.__mfEnabled:
assert len(paire) == 1, "Incorrect lenght of arguments"
