..
- 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
order to make the reading easier. The whole set of commands is the following
one::
- from numpy import array
- import adaoBuilder
+ from numpy import array, matrix
+ from adao import adaoBuilder
case = adaoBuilder.New()
case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
case.set( 'Background', Vector=[0, 1, 2] )
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
- import adaoBuilder
+ from numpy import array, matrix
+ from adao import adaoBuilder
case = adaoBuilder.New()
It is recommended to import by default the ``numpy`` module or some of its
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`.
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 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, matrix
+ 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 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`.
+ :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
the file must contain the two variables "*Algorithm*" and "*Parameters*" (or
"*AlgorithmParameters*" equivalently).
+.. index:: single: setName
+
+**setName** (*String*)
+ This command allows to set a short title for the calculation case.
+
+.. index:: single: setDirectory
+
+**setDirectory** (*String*)
+ This command allows to set the execution standard directory.
+
.. 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.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
++++++++++++++++++++++++++++++++++++++
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.
+Saving, loading or converting calculation case commands
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The saving or loading of a calculation case deals with quantities and actions
+that are linked by the previous commands, excepted case external operations
+(such as, for example, post-processing that can be developped after the
+calculation cas). The registered or loaded commands remain fully compatible
+with these Python external case operations.
+
+.. index:: single: load
+.. index:: single: FileName
+.. index:: single: Content
+.. index:: single: Object
+.. index:: single: Formater
+
+**load** (*FileName, Content, Object, Formater*)
+ This command allows to read or load a calculation case, from a file named
+ "*FileName*" or a content in memory by "*Content*" or "*Object*". The
+ "*Formater*" keyword can indicate "*TUI*" for commands of textual
+ application programming interface, and "*COM*" for commands of COMM type
+ coming from EFICAS interface for ADAO.
+
+.. index:: single: dump
+
+**dump** (*FileName, Formater*)
+ This command allows to save, in a file named "*FileName*", the commands of
+ the current calculation case. The "*Formater*" keyword can indicate "*TUI*"
+ for commands of textual application programming interface, and "*YACS*" for
+ commands of type YACS.
+
+.. index:: single: convert
+.. index:: single: FileNameFrom
+.. index:: single: ContentFrom
+.. index:: single: ObjectFrom
+.. index:: single: FormaterFrom
+.. index:: single: FileNameTo
+.. index:: single: FormaterTo
+
+**convert** (*FileNameFrom, ContentFrom, ObjectFrom, FormaterFrom, FileNameTo, FormaterTo*)
+ This command allows to convert directly from a known format to an another
+ one the commands establishing the current calculation case. Some formats
+ are only available as input or as output.
+
+.. _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
The set of commands that can be used is the following::
import numpy
- import adaoBuilder
+ from adao import adaoBuilder
#
# Formatting entries
# ------------------
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.
