:caption: Table of contents
:name: mastertoc
:maxdepth: 2
- :numbered: 2
+ :numbered: 4
intro
theory
are given through the "*Parameters*" optional command included in the mandatory
command "*AlgorithmParameters*".
-There are 3 practical methods for the user of the EFICAS graphical user
-interface of ADAO (GUI) to provide these options. The method is determined as
-follows in the ADAO EFICAS graphical user interface:
-
-#. firstly using the "*Parameters*" keyword in the "*AlgorithmParameters*"
- command, which allows to choose between "*Defaults*" (use of explicit
- pre-filled keywords by default parameters values) and "*Dict*" (use of a
- dictionary to fill the necessary keywords),
-#. then secondly or thirdly, only in the "*Dict*" case of "*Parameters*", by
- the included keyword "*FROM*" which allows to choose between a string entry
- and a Python script file entry.
-
-These two last options can be also used in the ADAO textual interface (TUI),
-through the keywords "*Parameters*" and "*Script*" of the corresponding command
-"*AlgorithmParameters*" (see the :ref:`section_tui` part for detailed
-description).
+There are several convenient methods for providing these options, either using
+the ADAO EFICAS graphical interface (GUI) or the textual interface (TUI). The
+method is determined as follows:
+
+#. First, in the graphical user interface (GUI), using the "*Parameters*"
+ keyword in the "*AlgorithmParameters*" command, which allows you to choose
+ between "*Defaults*" (use of explicit keywords pre-populated by the default
+ values of the parameters) and "*Dict*" (use of a dictionary to fill in the
+ necessary keywords),
+#. Then secondly or thirdly, in the graphical user interface (GUI), only in the
+ case "*Dict*" of "*Parameters*", by the included keyword "*FROM*" which
+ allows to choose between an entry by string or an entry by Python script
+ file.
+#. Fourth, in textual interface (TUI), using the "*Parameters*" keyword in the
+ "*AlgorithmParameters*" command, in a similar way to the graphical
+ interface, by filling in the explicit keywords described in the
+ documentation of each algorithm.
+#. Fifth, in textual interface (TUI), using the keyword "*Parameters*" in the
+ command "*AlgorithmParameters*", providing a script containing a dictionary
+ similar to methods two and three and compatible with these GUI entries.
+
+These last two options are the ones that can be used in the textual interface
+(TUI) in a similar and compatible way to the two previous ones based on the
+graphical interface (GUI).
If an option or a parameter is specified by the user for an algorithm that does
not support it, the option is simply ignored (left unused) and don't stop the
treatment. The meaning of the acronyms or particular names can be found in the
index or the :ref:`section_glossary`.
-First method : using explicit pre-filled keywords
-+++++++++++++++++++++++++++++++++++++++++++++++++
+First method (GUI): using explicit pre-filled keywords
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
To give the parameters values by explicit pre-filled keywords, directly in the
graphical interface, the user selects the type "*Defaults*" in the keyword
This method is naturally not usable in TUI interface.
-Second method : using a string in the graphical interface
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Second method(GUI): using a string in the graphical interface
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
To give the parameters values as a string, directly in the graphical interface,
the user selects the type "*Dict*" in the keyword "*Parameters*", then the type
currently used one. It is then easier to change of algorithm or to keep default
values different of the standard defaults.
-In the textual interface TUI, the dictionary has only to be given as argument
-of the "*Parameters*" keyword.
-
-Third method : using an external Python script file
+Third method (GUI): using an external Python script file
+++++++++++++++++++++++++++++++++++++++++++++++++++
To give the parameters values as an external Python script file, the user
.. centered::
**Using an external file for algorithmic parameters**
-This external Python script file has then to define a variable with the required
-name "*AlgorithmParameters*", as in the following example::
+This external Python script file, named for example here ``myParameters.py``,
+must define a dictionary variable with the imposed name "*Parameters*" or
+"*AlgorithmParameters*", like the following example:
+
+.. code-block:: python
+ :caption: myParameters.py: parameters file
AlgorithmParameters = {
"MaximumNumberOfIterations" : 25,
- "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"],
+ "StoreSupplementaryCalculations" : [
+ "CurrentState",
+ "APosterioriCovariance",
+ "OMA",
+ ],
+ }
+
+Moreover, the file can contain other Python commands. This method also allows,
+like the previous one, to keep externally options or parameters for other
+algorithms than the one we are using.
+
+Fourth method (TUI): use explicit documented keywords
++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+In the textual interface (TUI), the control of the algorithms is done by using
+the command "*setAlgorithmParameters*". It allows to fill in or define the
+keywords described in the documentation of each ADAO calculation case. Just to
+remind you, these keywords are the same as the ones presented in the graphical
+interface.
+
+To do this, a dictionary of "keyword/value" pairs can be given as an argument
+to the "*Parameters*" keyword of the command. For a TUI calculation case named
+for example ``case``, the syntax looks like the following code:
+
+.. code-block:: python
+
+ [...]
+ case.setAlgorithmParameters(
+ Algorithm='3DVAR',
+ Parameters={
+ "MaximumNumberOfIterations" : 25,
+ "StoreSupplementaryCalculations" : [
+ "CurrentState",
+ "APosterioriCovariance",
+ "OMA",
+ ],
+ },
+ )
+ [...]
+
+The argument values can obviously come from Python evaluations or previously
+defined variables, making it easy to insert ADAO commands into the Python
+scripting flow of a study.
+
+Fifth method (TUI): use an external Python script file
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+In the textual interface (TUI), a file can be given as argument in the same and
+compatible way as the third method dedicated to the graphical interface (GUI).
+An external Python script file named ``myParameters.py``, and containing for
+example the information already mentioned for the third method, is the
+following:
+
+.. code-block:: python
+ :caption: Simple version of myParameters.py
+
+ AlgorithmParameters = {
+ "MaximumNumberOfIterations" : 25,
+ "StoreSupplementaryCalculations" : [
+ "CurrentState",
+ "APosterioriCovariance",
+ "OMA",
+ ],
+ }
+
+For a TUI computation case named for example ``case``, which has to read this
+file, the textual interface command uses the argument "*Script*" in the
+following form:
+
+.. code-block:: python
+
+ [...]
+ case.setAlgorithmParameters( Algorithm = "3DVAR", Script = "myParameters.py" )
+ [...]
+
+Alternatively and completely equivalently, to comply with the definition
+required by the "*setAlgorithmParameters*" command, one can use in the external
+Python script ``myParameters.py`` the name "*Parameters*" instead of
+"*AlgorithmParameters*" in the form:
+
+.. code-block:: python
+ :caption: Simple version of myParameters.py
+
+ Parameters = {
+ "MaximumNumberOfIterations" : 25,
+ "StoreSupplementaryCalculations" : [
+ "CurrentState",
+ "APosterioriCovariance",
+ "OMA",
+ ],
}
-The file can also contain other Python commands. This method also allows, as
-the previous one, to keep options or parameters for other algorithms than the
-currently used one.
+The loading command in the textual interface remains the same. One can also add
+in the external script the name of the algorithm with its own keyword
+"*Algorithm*" (which in this case is required, and cannot be included as an
+option in "*AlgorithmParameters*"):
+
+.. code-block:: python
+ :caption: Full version of myParameters.py
+ :name: myParameters.py
+
+ Algorithm='3DVAR'
+ Parameters = {
+ "MaximumNumberOfIterations" : 25,
+ "StoreSupplementaryCalculations" : [
+ "CurrentState",
+ "APosterioriCovariance",
+ "OMA",
+ ],
+ }
+
+The textual interface loading command is then simplified to a single argument:
+
+.. code-block:: python
+
+ [...]
+ case.setAlgorithmParameters(Script = "myParameters.py")
+ [...]
-In the textual interface TUI, the file name has only to be given as argument of
-the "*Script*" keyword.
+This last form is the simplest way to fully parameterize algorithm inputs in an
+external Python script, which can then be controlled or generated by a wider
+process of study building including the ADAO commands.
More details are given here on the successive steps of the setup of an ADAO TUI
calculation case. The commands themselves are detailed just after in the
-:ref:`subsection_tui_commands`.
+:ref:`subsection_tui_commands`. We keep the indication ``[...]`` of preceding
+or following lines to emphasize that these commands can be inserted in the
+middle of a complete stream of Python scripting for a real study.
The creation and initialization of a study are done using the following
commands, the ``case`` object name of the ADAO TUI calculation case being let
-free to the user choice::
+free to the user choice:
+.. code-block:: python
+
+ [...]
from numpy import array
from adao import adaoBuilder
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
:math:`\mathbf{x}^b` (named ``Background``) and its errors covariance
:math:`\mathbf{B}` (named ``BackgroundError``), and after that, the observation
:math:`\mathbf{y}^o` (named ``Observation``) and its errors covariance
-:math:`\mathbf{R}` (named ``ObservationError``)::
+:math:`\mathbf{R}` (named ``ObservationError``):
+
+.. code-block:: python
+ [...]
case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
#
case.set( 'Background', Vector=[0, 1, 2] )
#
case.set( 'Observation', Vector=array([0.5, 1.5, 2.5]) )
case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
+ [...]
As a remark, vector or matrix inputs can be given as objects of type ``str``,
``list`` or ``tuple`` of Python, or of type ``array`` or ``matrix`` of Numpy.
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::
+operator from :math:`\mathbf{R}^3` into itself:
+
+.. code-block:: python
+ [...]
case.set( 'ObservationOperator', Matrix = "1 0 0;0 2 0;0 0 3")
+ [...]
In the most frequent case of a non-linear operator of :math:`\mathbf{R}^n` into
:math:`\mathbf{R}^p`, it has to be previously available as a Python function,
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::
+case:
+.. code-block:: python
+
+ [...]
import numpy
def simulation(x):
"Simulation function H to perform Y=H(X)"
OneFunction = simulation,
Parameters = {"DifferentialIncrement":0.01},
)
+ [...]
To obtain intermediary or final results of the case, one can add some
"*observer*", that link a script to execute with an intermediate or final
:ref:`section_advanced_observer`, and to the :ref:`section_reference` in order
to know what are the observable quantities. This link between an "*observer*"
and an observable quantity is done in a similar way than the calculation data
-definition::
+definition:
+
+.. code-block:: python
+ [...]
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::
+environment of the Python interpreter:
+.. code-block:: python
+
+ [...]
case.execute()
+ [...]
At the end, we get a very compact script previously proposed in
:ref:`subsection_tui_example`.
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::
+``someTable``, the registering of the observations in the ADAO TUI calculation
+case can be done by the following operations:
+
+.. code-block:: python
- from observations import table
- case.set( 'Observation', Vector=table )
+ [...]
+ from observations import someTable
+ case.set( 'Observation', Vector=someTable )
+ [...]
-The first line imports the ``table`` variable from the external file, and the
-second one register directly this table as the "*Observation*" data.
+The first line imports the ``someTable`` variable from the external file, and
+the 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
for a detailed description on this subject.
For instance, we give some script lines that allow to get the number of
-iterations of the optimization and the optimal value, and its size::
+iterations of the optimization and the optimal value, and its size:
+.. code-block:: python
+
+ [...]
print("")
print(" Number of iterations : %i"%len(case.get("CostFunctionJ")))
Xa = case.get("Analysis")
print(" Optimal analysis : %s"%(Xa[-1],))
print(" Size of the analysis : %i"%len(Xa[-1]))
print("")
+ [...]
These lines can be very simply added to the initial example of ADAO TUI
calculation case given in :ref:`subsection_tui_example`.
The creation and the initialization of a calculation case in TUI text interface
are done by importing the interface module "*adaoBuilder*" and by by invoking
its method "*New()*" as illustrated in the following lines (the ``case`` object
-name being let free to the user choice)::
+name being let free to the user choice):
+
+.. code-block:: python
+ [...]
from numpy import array
from adao import adaoBuilder
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
:caption: Table des matières
:name: mastertoc
:maxdepth: 2
- :numbered: 2
+ :numbered: 4
intro
theory
particuliers. Ils sont donnés à travers la commande optionnelle "*Parameters*"
incluse dans la commande obligatoire "*AlgorithmParameters*".
-Il y a 3 méthodes pratiques pour l'utilisateur de l'interface graphique EFICAS
-d'ADAO (GUI) pour fournir ces options. La méthode est déterminée de la manière
-suivante dans l'interface graphique EFICAS d'ADAO :
-
-#. premièrement à l'aide du mot-clé "*Parameters*" dans la commande
- "*AlgorithmParameters*", qui permet de choisir entre "*Defaults*"
- (utilisation de mots-clés explicites pré-remplis par les valeurs par défaut
- des paramètres) et "*Dict*" (utilisation d'un dictionnaire pour renseigner
- les mots-clés nécessaires),
-#. puis deuxièmement ou troisièmement, uniquement dans le cas "*Dict*" de
- "*Parameters*", par le mot-clé "*FROM*" inclus qui permet de choisir entre
- une entrée par chaîne de caractères ou une entrée par fichier de script
- Python.
-
-Ces deux dernières options sont celles que l'on peut aussi utiliser dans
-l'interface textuelle d'ADAO (TUI), par les mot-clés "*Parameters*" et
-"*Script*" dans la commande correspondante "*AlgorithmParameters*" (voir la
-partie :ref:`section_tui` pour une description détaillée).
+Il existe plusieurs méthodes pratiques pour fournir ces options, que ce soit en
+utilisant l'interface graphique EFICAS d'ADAO (GUI) ou l'interface textuelle
+(TUI). La méthode est déterminée de la manière suivante :
+
+#. Premièrement, en interface graphique (GUI), à l'aide du mot-clé
+ "*Parameters*" dans la commande "*AlgorithmParameters*", qui permet de
+ choisir entre "*Defaults*" (utilisation de mots-clés explicites pré-remplis
+ par les valeurs par défaut des paramètres) et "*Dict*" (utilisation d'un
+ dictionnaire pour renseigner les mots-clés nécessaires),
+#. Puis deuxièmement ou troisièmement, en interface graphique (GUI), uniquement
+ dans le cas "*Dict*" de "*Parameters*", par le mot-clé "*FROM*" inclus qui
+ permet de choisir entre une entrée par chaîne de caractères ou une entrée par
+ fichier de script Python.
+#. Quatrièmement, en interface textuelle (TUI), à l'aide du mot-clé
+ "*Parameters*" dans la commande "*AlgorithmParameters*", de manière
+ semblable à l'interface graphique, en renseignant les mots-clés explicites
+ décrits dans la documentation de chaque algorithme.
+#. Cinquièmement, en interface textuelle (TUI), à l'aide du mot-clé
+ "*Parameters*" dans la commande "*AlgorithmParameters*", en fournissant un
+ script contenant un dictionnaire similaire aux méthodes deux et trois et
+ compatibles avec ces entrées en GUI.
+
+Ces deux dernières options sont celles que l'on peut utiliser dans l'interface
+textuelle (TUI) de manière similaire et compatible aux deux précédentes basées
+sur l'interface graphique (GUI).
Si une option ou un paramètre est spécifié par l'utilisateur pour un algorithme
qui ne la supporte pas, cette option est simplement ignorée (laissée
des noms particuliers peut être trouvée dans l'index ou dans le
:ref:`section_glossary`.
-Première méthode : utiliser les mots-clés explicites pré-remplis
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Première méthode (GUI) : utiliser les mots-clés explicites pré-remplis
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Pour donner les valeurs des paramètres par les mots-clés explicites pré-remplis,
directement dans l'interface graphique, l'utilisateur sélectionne le type
Cette méthode n'est naturellement pas utilisable en interface TUI.
-Seconde méthode : utiliser une chaîne de caractères dans l'interface graphique
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Deuxième méthode (GUI) : utiliser une chaîne de caractères dans l'interface graphique
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Pour donner les valeurs des paramètres par une chaîne de caractères, directement
dans l'interface graphique, l'utilisateur sélectionne le type "*Dict*" dans le
facilite le changement d'algorithme ou la conservation de valeurs par défaut
différentes des défauts standards.
-Dans l'interface textuelle TUI, le dictionnaire peut être simplement donné
-comme argument du mot-clé "*Parameters*".
-
-Troisième méthode : utiliser un fichier de script Python externe
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Troisième méthode (GUI) : utiliser un fichier externe de script Python
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Pour donner les valeurs des paramètres par un fichier de script Python externe,
l'utilisateur sélectionne dans l'interface graphique le type "*Dict*" dans le
.. centered::
**Utiliser un fichier externe pour les paramètres algorithmiques**
-Ce fichier script Python externe doit définir alors une variable au nom imposé
-"*AlgorithmParameters*", à la manière de l'exemple qui suit::
+Ce fichier script Python externe, nommé par exemple ici ``myParameters.py``,
+doit définir une variable de type dictionnaire au nom imposé "*Parameters*" ou
+"*AlgorithmParameters*", à la manière de l'exemple qui suit :
+
+.. code-block:: python
+ :caption: myParameters.py : fichier de paramètres
AlgorithmParameters = {
"MaximumNumberOfIterations" : 25,
- "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"],
+ "StoreSupplementaryCalculations" : [
+ "CurrentState",
+ "APosterioriCovariance",
+ "OMA",
+ ],
+ }
+
+De plus, le fichier peut contenir d'autres commandes Python. Cette méthode
+permet aussi, comme la précédente, de conserver de manière externe des options
+ou des paramètres pour d'autres algorithmes que celui que l'on utilise.
+
+Quatrième méthode (TUI) : utiliser les mots-clés explicites documentés
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Dans l'interface textuelle (TUI), le contrôle des algorithmes se fait en
+utilisant la commande "*setAlgorithmParameters*". Elle permet de renseigner ou
+de définir les mots-clés décrits dans la documentation de chaque cas de calcul
+ADAO. Pour mémoire, ces mots-clés sont les mêmes que ceux qui sont présentés
+dans l'interface graphique.
+
+Pour cela, un dictionnaire des couples "mot-clé/valeurs" peut être donné comme
+argument du mot-clé "*Parameters*" de la commande. Pour un cas de calcul TUI
+nommé par exemple ``case``, la syntaxe ressemble au code suivant :
+
+.. code-block:: python
+
+ [...]
+ case.setAlgorithmParameters(
+ Algorithm='3DVAR',
+ Parameters={
+ "MaximumNumberOfIterations" : 25,
+ "StoreSupplementaryCalculations" : [
+ "CurrentState",
+ "APosterioriCovariance",
+ "OMA",
+ ],
+ },
+ )
+ [...]
+
+Les valeurs des arguments peuvent évidemment provenir d'évaluations Python ou
+de variables précédemment définies, facilitant l'insertion des commandes ADAO
+dans le flot du scripting Python d'une étude.
+
+Cinquième méthode (TUI) : utiliser un fichier externe de script Python
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Dans l'interface textuelle (TUI), un fichier peut être donné comme argument de
+manière identique et compatible avec la troisième méthode dédiée à l'interface
+graphique (GUI). Un fichier externe de script Python nommé ``myParameters.py``,
+et contenant par exemple les informations déjà mentionnées pour la troisième
+méthode, est le suivant :
+
+.. code-block:: python
+ :caption: Version simple de myParameters.py
+
+ AlgorithmParameters = {
+ "MaximumNumberOfIterations" : 25,
+ "StoreSupplementaryCalculations" : [
+ "CurrentState",
+ "APosterioriCovariance",
+ "OMA",
+ ],
+ }
+
+Pour un cas de calcul TUI nommé par exemple ``case``, qui doit lire ce
+fichier, la commande en interface textuelle utilise l'argument "*Script*" sous
+la forme suivante :
+
+.. code-block:: python
+
+ [...]
+ case.setAlgorithmParameters( Algorithm = "3DVAR", Script = "myParameters.py" )
+ [...]
+
+De manière alternative et complètement équivalente, pour être conforme à la
+définition requise par la commande "*setAlgorithmParameters*", on peut utiliser
+dans le script Python externe ``myParameters.py`` la dénomination
+"*Parameters*" à la place de "*AlgorithmParameters*" sous la forme :
+
+.. code-block:: python
+ :caption: Version simple de myParameters.py
+
+ Parameters = {
+ "MaximumNumberOfIterations" : 25,
+ "StoreSupplementaryCalculations" : [
+ "CurrentState",
+ "APosterioriCovariance",
+ "OMA",
+ ],
}
-Le fichier peut aussi contenir d'autres commandes Python. Cette méthode permet
-aussi, comme la précédente, de conserver des options ou des paramètres pour
-d'autres algorithmes que celui que l'on utilise.
+La commande de chargement en interface textuelle reste identique. On peut aussi
+rajouter dans le script externe le nom de l'algorithme avec son propre mot-clé
+"*Algorithm*" (qui dans ce cas est requis, et qui ne peut pas être inclus comme
+une option dans "*AlgorithmParameters*") :
+
+.. code-block:: python
+ :caption: Version complète de myParameters.py
+ :name: myParameters.py
+
+ Algorithm='3DVAR'
+ Parameters = {
+ "MaximumNumberOfIterations" : 25,
+ "StoreSupplementaryCalculations" : [
+ "CurrentState",
+ "APosterioriCovariance",
+ "OMA",
+ ],
+ }
+
+La commande de chargement en interface textuelle se simplifie alors pour ne
+plus comporter qu'un seul argument :
+
+.. code-block:: python
+
+ [...]
+ case.setAlgorithmParameters(Script = "myParameters.py")
+ [...]
-Dans l'interface textuelle TUI, le fichier peut être donné comme argument du
-mot-clé "*Script*".
+Cette dernière forme est la plus simple pour paramétrer entièrement les entrées
+d'algorithmes dans un script Python externe, qui peut ainsi être contrôlé ou
+généré par un processus plus vaste de construction d'étude incluant les
+commandes ADAO.
On décrit ici plus en détail les différentes étapes de création d'un cas de
calcul TUI ADAO. Les commandes elles-mêmes sont détaillées juste après dans
-l':ref:`subsection_tui_commands`.
+l':ref:`subsection_tui_commands`. On maintient l'indication ``[...]`` de lignes
+précédentes ou suivantes pour insister sur le fait que ces commandes peuvent
+être insérées au milieu d'un flot complet de scripting Python pour une étude
+réelle.
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::
+quelconque, au choix de l'utilisateur :
+.. code-block:: python
+
+ [...]
from numpy import array
from adao import adaoBuilder
case = adaoBuilder.New()
+ [...]
Il est recommandé d'importer par principe le module ``numpy`` ou ses
constructeurs particuliers comme celui d'``array``, pour faciliter ensuite son
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``)::
+d'erreurs :math:`\mathbf{R}` (nommée ``ObservationError``) :
+
+.. code-block:: python
+ [...]
case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
#
case.set( 'Background', Vector=[0, 1, 2] )
#
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 ou
matricielles, des objets de type ``str``, ``list`` ou ``tuple`` de Python, ou
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::
+:math:`\mathbf{R}^3` sur lui-même :
+
+.. code-block:: python
+ [...]
case.set( 'ObservationOperator', Matrix = "1 0 0;0 2 0;0 0 3")
+ [...]
Dans le cas beaucoup plus courant d'un opérateur non-linéaire de
:math:`\mathbf{R}^n` dans :math:`\mathbf{R}^p`, il doit être préalablement
"*OneFunction*", son adjoint est directement établi de manière numérique et il
est paramétrable par l'argument "*Parameters*". L'exemple suivant montre une
fonction ``simulation`` (qui réalise ici le même opérateur linéaire que
-ci-dessus) et l'enregistre dans le cas ADAO::
+ci-dessus) et l'enregistre dans le cas ADAO :
+.. code-block:: python
+
+ [...]
import numpy
def simulation(x):
"Fonction de simulation H pour effectuer Y=H(X)"
OneFunction = simulation,
Parameters = {"DifferentialIncrement":0.01},
)
+ [...]
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 à
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::
+similaire à la définition des données du calcul :
+
+.. code-block:: python
+ [...]
case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
+ [...]
Enfin, lorsque toutes les informations requises sont disponibles dans le cas
``case`` de calcul ADAO, on peut en demander l'exécution de manière très
-simple dans l'environnement de l'interpréteur Python::
+simple dans l'environnement de l'interpréteur Python :
+.. code-block:: python
+
+ [...]
case.execute()
+ [...]
Au final, on obtient le script très compact proposé précédemment dans
:ref:`subsection_tui_example`.
dans l'espace de nommage du script. Il est donc aisé d'utiliser des variables
calculées préalablement ou obtenues par l'import de scripts "utilisateur". Si
par exemple les observations sont disponibles sous la forme d'une liste dans un
-fichier Python externe nommé ``observations.py`` sous le nom ``table``, il
+fichier Python externe nommé ``observations.py`` sous le nom ``someTable``, il
suffit de réaliser les opérations suivantes pour enregistrer les observations
-dans le cas de calcul TUI ADAO::
+dans le cas de calcul TUI ADAO :
+
+.. code-block:: python
- from observations import table
- case.set( 'Observation', Vector=table )
+ [...]
+ from observations import someTable
+ case.set( 'Observation', Vector=someTable )
+ [...]
-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 ``someTable`` 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
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
-taille::
+taille :
+.. code-block:: python
+
+ [...]
print("")
print(" Nombre d'iterations : %i"%len(case.get("CostFunctionJ")))
Xa = case.get("Analysis")
print(" Analyse optimale : %s"%(Xa[-1],))
print(" Taille de l'analyse : %i"%len(Xa[-1]))
print("")
+ [...]
Ces lignes peuvent être très simplement additionnées à l'exemple initial de cas
de calcul TUI ADAO proposé dans :ref:`subsection_tui_example`.
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)::
+``case`` de l'objet étant quelconque, au choix de l'utilisateur) :
+
+.. code-block:: python
+ [...]
from numpy import array
from adao 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
