..
- Copyright (C) 2008-2015 EDF R&D
+ Copyright (C) 2008-2018 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 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::
- from numpy import array
+ from numpy import array, matrix
import adaoBuilder
case = adaoBuilder.New()
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.
+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.
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
simple present case of a linear operator, we use the following syntax for an
operator from :math:`\mathbf{R}^3` into itself::
- case.ObservationOperator(Matrix = "1 0 0;0 2 0;0 0 3")
+ 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,
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::
- print
- print " Number of iterations :", len(case.get("CostFunctionJ"))
+ print("")
+ print(" Number of iterations : %i"%len(case.get("CostFunctionJ")))
Xa = case.get("Analysis")
- print " Optimal analysis :", Xa[-1]
- print " Size of the analysis :", len(Xa[-1])
- print
+ 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`.
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 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)::
+
+ 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
+++++++++++++++++++++++++++++
.. 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`.
+ :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*". 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`. The "*Info*" variable contains an
+ information string or can be void.
Perform the calculation
+++++++++++++++++++++++
-.. index:: single: executePythonScheme
-
-**executePythonScheme** ()
- This command launches the complete calculation in the environment of the
- 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.
-
.. index:: single: execute
-
-**execute** ()
- This command is a user shorthand for "*executePythonScheme*".
+.. index:: single: Executor
+.. index:: single: SaveCaseInFile
+
+**execute** (*Executor, SaveCaseInFile*)
+ This command launches the complete calculation in the execution environment
+ chosen by the keyword *Executor*. This environment can be the current
+ Python interpreter, without interaction with YACS (using the value
+ "*Python*"), or the one of YACS (using the value "*YACS*" [YACS]_). If a
+ file is given in the keyword *SaveCaseInFile*, it will be used to save the
+ associated version of commands file for the given execution environment.
+ During the execution, the usual outputs (standard and error) are the one of
+ the chosen environment. If necessary (and if possible), the ADAO algorithms
+ internal parallelism, the parallelism of YACS, and the internal parallelism
+ of the simulation code(s) used, are available.
Get the calculation results separately
++++++++++++++++++++++++++++++++++++++
:ref:`section_ref_output_variables` and to the individual documentations of
the algorithms.
+.. _subsection_tui_advanced:
+
More advanced examples of ADAO TUI calculation case
---------------------------------------------------
Xoptimum = case.get("Analysis")[-1]
FX_at_optimum = case.get("SimulatedObservationAtOptimum")[-1]
J_values = case.get("CostFunctionJ")[:]
- print
- print "Number of internal iterations...: %i"%len(J_values)
- print "Initial state...................:",numpy.ravel(Xbackground)
- print "Optimal state...................:",numpy.ravel(Xoptimum)
- print "Simulation at optimal state.....:",numpy.ravel(FX_at_optimum)
- print
+ print("")
+ print("Number of internal iterations...: %i"%len(J_values))
+ print("Initial state...................: %s"%(numpy.ravel(Xbackground),))
+ print("Optimal state...................: %s"%(numpy.ravel(Xoptimum),))
+ print("Simulation at optimal state.....: %s"%(numpy.ravel(FX_at_optimum),))
+ print("")
The command set execution gives the following result::
Optimal state...................: [ 2. 3. 4.]
Simulation at optimal state.....: [ 2. 6. 12. 20.]
-As it should be in twin experiments, it is found that we get correctly the
-parameters that were used to artificially build the observations.
+As it should be in twin experiments, when we trust mainly in observations, it
+is found that we get correctly the parameters that were used to artificially
+build the observations.
+
+.. Reconciliation de courbes a l'aide de MedCoupling
+.. +++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. Utilisation de fonctions de surveillance de type "observer"
+.. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. 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.
