..
- 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:
================================================================================
**[DocR]** Textual Application Programming Interface for the user (API/TUI)
================================================================================
-.. warning::
-
- in its present version, this text programming interface (TUI) is experimental,
- and so changes can be required in forthcoming versions.
-
This section presents advanced usage of the ADAO module using its text
programming interface (API/TUI). This interface gives ability to create a
calculation object in a similar way than the case building obtained through the
calculation case. The commands themselves are detailed just after in the
:ref:`subsection_tui_commands`.
-The initial creation of a study is done using the following commands, the
-``case`` object name of the ADAO TUI calculation case being let free to the
-user choice::
+The creation and initialisation 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::
from numpy import array
import adaoBuilder
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) 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.
+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.
Equivalent syntax calls for commands
++++++++++++++++++++++++++++++++++++
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
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The creation and the initialisation 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)::
+
+ from numpy import array
+ 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 upcoming
+use in the commands.
+
Defining the calculation data
+++++++++++++++++++++++++++++
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::
+The available commands are:
.. index:: single: setBackground
.. index:: single: setObservationOperator
-**setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
+**setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, AppliedInXb, Parameters, Script, 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`.
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,
+ 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
.. index:: single: setDebug
**setDebug** ()
- This command enables the detailed information mode when running.
+ This command enables the detailed information mode when running.
.. index:: single: setNoDebug
**setNoDebug** ()
- This command disables the detailed information mode when running.
+ This command disables the detailed information mode when running.
.. index:: single: setObserver
**setObserver** (*Variable, Template, String, Script, Info*)
- This command allows to set an *observer* on the current or final
- calculation variable. Reference should be made to the description of the
- way of ':ref:`section_advanced_observer`, and to the
- :ref:`section_reference` to know what are the observable quantities. One
- defines as "*String*" the *observer* body, using a string including if
- necessary line breaks. It is recommended to use the patterns available by
- the argument "*Template*". There exist the following simple patterns:
- "ValuePrinter", "ValueSeriePrinter", "ValueSaver", "ValueSerieSaver",
- "ValuePrinterAndSaver", "ValueSeriePrinterAndSaver", "ValueGnuPlotter",
- "ValueSerieGnuPlotter", "ValuePrinterAndGnuPlotter",
- "ValueSeriePrinterAndGnuPlotter", "ValuePrinterSaverAndGnuPlotter",
- "ValueSeriePrinterSaverAndGnuPlotter". In the case of a definition as
- "*Script*", the file must contain only the body of the function, as
- described in the way of :ref:`section_advanced_observer`.
+ This command allows to set an *observer* on the current or final calculation
+ variable. Reference should be made to the description of the
+ ':ref:`ref_observers_requirements` for their list and content, and to the
+ :ref:`section_reference` to know what are the observable quantities. One
+ defines as "*String*" the *observer* body, using a string including if
+ necessary line breaks. It is recommended to use the patterns available by
+ the argument "*Template*". In the case of a definition as "*Script*", the
+ file must contain only the body of the function, as described in the
+ :ref:`ref_observers_requirements`.
Perform the calculation
+++++++++++++++++++++++
**executePythonScheme** ()
This command launches the complete calculation in the environment of the
- current Python interpreter, without interaction with YACS.The standard
- output and standard error are those of the Python interpreter. If
+ current Python interpreter, without interaction with YACS [YACS]_. The
+ standard output and standard error are those of the Python interpreter. If
necessary, the internal parallelism, of the algorithms in ADAO and of the
simulation code used, is available.
visualization. Its argument the name of a variable "*Concept*" and returns
back the quantity as a list (even if there is only one specimen) of this
base variable. For a list of variables and use them, the user has to refer
- to the ':ref:`subsection_r_o_v_Inventaire` and more generally to the
+ to the :ref:`subsection_r_o_v_Inventaire` and more generally to the
:ref:`section_ref_output_variables` and to the individual documentations of
the algorithms.
+.. _subsection_tui_advanced:
+
More advanced examples of ADAO TUI calculation case
---------------------------------------------------
#. that we want to adjust 3 parameters ``alpha``, ``beta`` and ``gamma`` in a bounded domain,
#. that we dispose of observations named ``observations``,
-#. that the user have a Python function of physical simulation named ``simulation`` previously tested, which transforms the 3 parameters in results similar to the observations,
+#. that the user have a Python function of physical simulation named ``simulation``, previously (well) tested, which transforms the 3 parameters in results similar to the observations,
#. that the independent holding, that the user want to elaborate, is represented here by the simple printing of the initial state, of the optimal state, of the simulation in that point, of the intermediate state and of the number of optimization iteration.
In order to try in a simple way this example of TUI calculation case, we choose
As it should be in twin experiments, it is found that we get correctly the
parameters that were used to artificially build the observations.
+.. Réconciliation de courbes à l'aide de MedCoupling
+.. +++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. Utilisation de fonctions de surveillance de type "observer"
+.. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. Suivre d'un recalage à l'aide de MatPlotLib
+.. +++++++++++++++++++++++++++++++++++++++++++
+
+.. Equivalences entre l'interface graphique (GUI) et l'interface textuelle (TUI)
+.. -----------------------------------------------------------------------------
+
.. [HOMARD] For more information on HOMARD, see the *HOMARD module* and its integrated help available from the main menu *Help* of the SALOME platform.
.. [PARAVIS] For more information on PARAVIS, see the *PARAVIS module* and its integrated help available from the main menu *Help* of the SALOME platform.
