..
- Copyright (C) 2008-2015 EDF R&D
+ Copyright (C) 2008-2016 EDF R&D
This file is part of SALOME ADAO module.
.. index:: single: TUI
.. index:: single: API/TUI
+.. index:: single: adaoBuilder
.. _section_tui:
================================================================================
calcul TUI ADAO. Les commandes elles-mêmes sont détaillées juste après dans
l':ref:`subsection_tui_commands`.
-L'initialisation et la création d'une étude se fait par les commandes suivantes,
+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::
case.set( 'Observation', Vector=array([0.5, 1.5, 2.5]) )
case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
-On remarque que l'on peut donner en entrée des quantités vectorielles des objets
-de type ``list``, ``tuple``, ``array`` ou ``matrix`` de Numpy. Dans ces deux
-derniers cas, il faut simplement importer Numpy avant.
+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
+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
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 interne ou finale du calcul. On se reportera à la description de la
-manière d':ref:`section_advanced_observer`, et à la :ref:`section_reference`
+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::
Au final, on obtient le script très compact proposé précédemment dans
:ref:`subsection_tui_example`.
-Fournir des données de calcul plus complexes
-++++++++++++++++++++++++++++++++++++++++++++
+Fournir des données ou informations de calcul plus complexes
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Une telle interface s'écrivant en Python, il est possible d'utiliser toute la
puissance du langage pour entrer des données plus complexes qu'une déclaration
en TUI.
Les variables de résultats de calcul, ou les variables internes issues de
-l'optimisation 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.
+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.
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
print
print " Nombre d'iterations :", len(case.get("CostFunctionJ"))
Xa = case.get("Analysis")
- print " Analyse optimale :", Xa[-1]
+ print " Analyse optimale :", Xa[-1]
print " Taille de l'analyse :", len(Xa[-1])
print
de calcul TUI ADAO proposé dans :ref:`subsection_tui_example`.
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, 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.
+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.
.. _subsection_tui_commands:
**deux syntaxes entièrement équivalentes**. On peut :
- soit utiliser la commande ``set`` et comme premier argument le concept
- ``XXXXX`` sur laquelle appliquer la commande dont les arguments suivent,
+ ``XXXXX`` sur lequel appliquer la commande dont les arguments suivent,
- soit utiliser la commande ``setXXXXX`` contenant les arguments de la commande
à appliquer.
selon son contexte d'usage. Dans la suite, par souci de clarté, on définit les
commandes selon la seconde syntaxe.
+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
+méthode "*New()*" comme illustré dans les quelques lignes suivantes (le nom
+``case`` de l'objet étant quelconque, au choix de l'utilisateur)::
+
+ from numpy import array
+ import adaoBuilder
+ case = adaoBuilder.New()
+
+Il est recommandé par principe de toujours importer le module ``numpy`` (ou ses
+constructeurs particuliers, comme celui d'``array``) pour faciliter ensuite son
+usage dans les commandes elle-mêmes.
+
Définir les données de calcul
+++++++++++++++++++++++++++++
fait soit lors de leur définition, soit lors de l'exécution.
Dans chaque commande, le mot-clé booléen "*Stored*" permet d'indiquer si l'on
-veut éventuellement la stocker la grandeur définie pour en disposer en en cours
-de calcul ou en sortie. Le choix par défaut est de ne pas stocker, et il est
+veut éventuellement la 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.
**setBackground** (*Vector, VectorSerie, Script, Stored*)
Cette commande permet de définir l'ébauche :math:`\mathbf{x}^b`. Selon les
- algorithmes, on peut le définir comme un vecteur simple par "*Vector*", ou
- comme une liste de vecteurs par "*VectorSerie*". Si on le définit par un
+ algorithmes, on peut la définir comme un vecteur simple par "*Vector*", ou
+ comme une liste de vecteurs par "*VectorSerie*". Si on la définit par un
script dans "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
"*VectorSerie*" selon que l'une de ces variables est placée à "*True*".
.. index:: single: setBackgroundError
**setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
- Cette commande permet de définir la matrice :math:`\mathbf{B}` des
+ Cette commande permet de définir la matrice :math:`\mathbf{B}` de
covariance des erreurs d'ébauche. La matrice peut être définie de manière
- complète par "*Matrix*", ou de manière parcimonieuse comme une matrice
- diagonale dont on donne la variance unique sur la diagonale par
+ 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
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 "*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*" (similaires à
- celles de l'interface graphique).
+ :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 à travers le mot-clé "*Parameters*". Les entrées potentielles
+ de ce dictionnaire de paramètres sont "*DifferentialIncrement*",
+ "*CenteredFiniteDifference*" (similaires à celles de l'interface graphique).
.. index:: single: setControlInput
.. index:: single: setEvolutionError
**setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
- Cette commande permet de définir la matrice :math:`\mathbf{Q}` des
+ Cette commande permet de définir la matrice :math:`\mathbf{Q}` de
covariance des erreurs d'évolution. La matrice peut être définie de manière
- complète par "*Matrix*", ou de manière parcimonieuse comme une matrice
- diagonale dont on donne la variance unique sur la diagonale par
+ 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
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
- "*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
+ 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).
.. index:: single: setObservationError
**setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
- Cette commande permet de définir la matrice :math:`\mathbf{R}` des
+ Cette commande permet de définir la matrice :math:`\mathbf{R}` de
covariance des erreurs d'observation. La matrice peut être définie de
- manière complète par "*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 "*DiagonalSparseMatrix*"
- selon que l'une de ces variables est placée à "*True*".
+ 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
+ "*DiagonalSparseMatrix*" selon que l'une de ces variables est placée à
+ "*True*".
.. index:: single: setObservationOperator
:math:`\mathbf{y}^o`. 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 "*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).
+ :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).
.. index:: single: set
.. index:: single: setObserver
**setObserver** (*Variable, Template, String, Script, Info*)
- Cette commande permet de définir un observer sur une variable courante ou
- finale du calcul. On se reportera à la description de la manière
- d':ref:`section_advanced_observer`, et à la :ref:`section_reference` pour
- savoir quelles sont les quantités observables. On définit par "*String*" le
- corps de l'observer par une chaine de caractères incluant si nécessaire des
- sauts de lignes. On recommande d'utiliser les patrons disponibles par
- l'argument "*Template*". On dispose des patrons simples suivants :
- "*ValuePrinter*", "*ValueSeriePrinter*", "*ValueSaver*",
- "*ValueSerieSaver*", "*ValuePrinterAndSaver*",
- "*ValueSeriePrinterAndSaver*", "*ValueGnuPlotter*",
- "*ValueSerieGnuPlotter*". Dans le cas d'une définition par "*Script*", le
- fichier indiqué doit contenir uniquement le corps de la fonction, comme
- décrit dans la manière d':ref:`section_advanced_observer`.
+ Cette commande permet de définir un *observer* sur une variable courante ou
+ finale du calcul. On se reportera à la description des
+ :ref:`ref_observers_requirements` pour avoir leur liste et leur format, et à
+ la :ref:`section_reference` pour savoir quelles sont les quantités
+ observables. On définit comme un "*String*" le corps de l'*observer*, en
+ utilisant une chaine de caractères incluant si nécessaire des sauts de
+ lignes. On recommande d'utiliser les patrons disponibles par l'argument
+ "*Template*". Dans le cas d'une définition par "*Script*", le fichier
+ indiqué doit contenir uniquement le corps de la fonction, comme décrit dans
+ les :ref:`ref_observers_requirements`.
Effectuer le calcul
+++++++++++++++++++
**executePythonScheme** ()
Cette commande lance le calcul complet dans l'environnement de
- l'interpréteur Python courant, sans interaction avec YACS. Les sorties
- standard et d'erreur sont celles de l'interpréteur Python. On dispose si
- nécessaire du parallélisme interne des algorithmes dans ADAO et du
- parallélisme interne du ou des codes de simulation utilisé.
+ l'interpréteur Python courant, sans interaction avec YACS [YACS]_. Les
+ sorties standard et d'erreur sont celles de l'interpréteur Python. On
+ dispose si nécessaire du parallélisme interne des algorithmes dans ADAO et
+ du parallélisme interne du ou des codes de simulation utilisé.
.. .. index:: single: generateYACSscheme
..
Les hypothèses du cas utilisateur sont les suivantes. On suppose :
-#. que l'on veut recaler 3 paramètres ``alpha``, ``beta`` et ``gamma`` dans un domaine borné,
-#. que l'on dispose d'observations nommées ``observations``,
-#. que l'utilisateur dispose en Python d'une fonction de simulation physique appellée ``simulation`` préalablement testée, qui transforme les 3 paramètres en résultats similaires aux observations,
-#. que l'exploitation indépendante, que l'utilisateur veut faire, est représentée ici par l'affichage simple de l'état initial, de l'état optimal, de la simulation en ce point, des états intermédiaires et du nombre d'itérations d'optimisation.
+#. que l'on veut recaler 3 paramètres ``alpha``, ``beta`` et ``gamma`` dans un domaine borné,
+#. que l'on dispose d'observations nommées ``observations``,
+#. que l'utilisateur dispose en Python d'une fonction de simulation physique appellée ``simulation``, préalablement (bien) testée, qui transforme les 3 paramètres en résultats similaires aux observations,
+#. que l'exploitation indépendante, que l'utilisateur veut faire, est représentée ici par l'affichage simple de l'état initial, de l'état optimal, de la simulation en ce point, des états intermédiaires et du nombre d'itérations d'optimisation.
Pour effectuer de manière simple cet essai de cas de calcul TUI, on se donne par
exemple les entrées suivantes, parfaitement arbitraires, en construisant les
