**[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
+graphical interface (GUI). When one wants to elaborate "by hand" the TUI
+calculation case, it is recommended to extensively use all the ADAO module
+documentation, and to go back if necessary to the graphical interface (GUI), to
+get all the elements allowing to correctly set the commands. The general used
+notions and terms are defined in :ref:`section_theory`.
+
+.. _subsection_tui_creating:
+
+Creation of ADAO TUI calculation case and examples
+--------------------------------------------------
+
+.. _subsection_tui_example:
+
+A simple setup example of an ADAO TUI calculation case
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+To introduce the TUI interface, lets begin by a simple but complete example of
+ADAO calculation case. All the data are explicitly defined inside the script in
+order to make the reading easier. The whole set of commands is the following
+one::
+
+ from numpy import array
+ import adaoBuilder
+ case = adaoBuilder.New()
+ case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
+ case.set( 'Background', Vector=[0, 1, 2] )
+ case.set( 'BackgroundError', ScalarSparseMatrix=1.0 )
+ case.set( 'Observation', Vector=array([0.5, 1.5, 2.5]) )
+ case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
+ case.set( 'ObservationOperator', Matrix='1 0 0;0 2 0;0 0 3' )
+ case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
+ case.execute()
+
+The result of running these commands in SALOME (either as a SALOME "*shell*"
+command, in the Python command window of the interface, or by the script
+execution entry of the menu) is the following::
+
+ Analysis [ 0.25000264 0.79999797 0.94999939]
+
+Detailed setup of an ADAO TUI calculation case
++++++++++++++++++++++++++++++++++++++++++++++++
+
+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`.
+
+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::
+
+ from numpy import array
+ 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 use
+in the commands.
+
+Thereafter, the case has to be build by preparing and storing the data that
+define the study. The commands order does not matter, it is sufficient that all
+the concepts, required by the algorithm used, are present. The user can refer to
+the :ref:`section_reference` and its subparts to get details about commands by
+algorithm. Here, we define successively the chosen data assimilation or
+optimization algorithm and its parameters, then the *a priori* state
+: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``)::
+
+ case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
+ #
+ case.set( 'Background', Vector=[0, 1, 2] )
+ case.set( 'BackgroundError', ScalarSparseMatrix=1.0 )
+ #
+ 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.
+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
+possibly :math:`M` of evolution. In all cases, linear or non-linear, they can 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::
+
+ case.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,
+known in the current name space, which takes a ``numpy`` vector (or an ordered
+list) of size :math:`n` as input and which returns as output a ``numpy`` vector
+of size :math:`p`. When the non-linear operator is the only one to be defined by
+the keyword "*OneFunction*", its adjoint is directly established by 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::
+
+ import numpy
+ def simulation(x):
+ "Simulation function H to perform Y=H(X)"
+ __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
+ __H = numpy.matrix("1 0 0;0 2 0;0 0 3")
+ return __H * __x
+ #
+ case.set( 'ObservationOperator',
+ 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
+calculation variable. The reader can go the description of the way of
+: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::
+
+ 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::
+
+ case.execute()
+
+At the end, we get a very compact script previously proposed in
+:ref:`subsection_tui_example`.
+
+Using more complex calculation data or information
+++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Such an interface being written in Python, it is possible to use all the power
+of the language to enter more complex data than explicit declaration.
+
+The registering of input data supports various variable types, but in addition,
+these inputs can come from variables currently available in the name space of 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::
+
+ from observations import table
+ case.set( 'Observation', Vector=table )
+
+The first line imports the ``table`` 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 in
+Python. As usual, it is recommended to the user to check its data before saving
+them in the ADAO TUI calculation case to avoid errors complicated to correct.
+
+Obtain and use the results of calculation in a richer way
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Similarly, it is possible to obtain and process the results of calculation in a
+richer way, following up on post-processing after the TUI calculation.
+
+The variables of calculation results, or the internal variables coming from
+optimization or data assimilation, are available through the ``get`` method of
+the ADAO TUI calculation case, which send back an object of list type of the
+required variable. The reader can go to the :ref:`section_ref_output_variables`
+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::
+
+ print
+ print " Number of iterations :", len(case.get("CostFunctionJ"))
+ Xa = case.get("Analysis")
+ print " Optimal analysis :", Xa[-1]
+ print " Size of the analysis :", 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`.
+
+As well as for data entry, the simplicity of results achievement makes it easy
+to consider post-processing chains in SALOME, to use for example visualization
+with MatPlotLib or PARAVIS [PARAVIS]_, mesh adaptation with HOMARD [HOMARD]_, or
+for other calculations.
+
+.. _subsection_tui_commands:
+
+Set of available commands in text user interface TUI
+----------------------------------------------------
+
+In the TUI interface of ADAO module, we follow usual Python conventions and
+recommendations to make the distinction between public objects, and private or
+reserved ones because of implementation details. In practice, every object or
+function name beginning with at least one "**_**" sign is private in the usual
+programming sense ("*private*"). Nevertheless, the absence of such a sign at the
+beginning of a name does not designate it as public. In general, in Python, and
+unlike other languages, you can access private objects or functions. This can
+sometimes be useful, but such use in your codes will lead to crashes without
+warning in future versions. It is strongly recommended not to do so.
+
+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.
+
+Equivalent syntax calls for commands
+++++++++++++++++++++++++++++++++++++
+
+The definition of data during the ADAO TUI calculation case creation supports
+**two completely equivalent syntaxes**. One can:
+
+- either use the ``set`` command and as the first argument the concept ``XXXXX``
+ on which to apply the command whose arguments follow,
+- or use the command ``setXXXXX`` containing the arguments of the command to
+ apply.
+
+To illustrate this equivalence, we take the example of two commands that lead to
+the same result::
+
+ case.set( 'Background', Vector=[0, 1, 2] )
+
+and::
+
+ case.setBackground( Vector=[0, 1, 2] )
+
+The choice of one or the other syntaxes is freely left to the user, according to
+its context of use. In the following, for clarity, we define the controls
+according to the second syntax.
+
+Defining the calculation data
++++++++++++++++++++++++++++++
+
+The following commands are used to define the data of an ADAO TUI calculation
+case. The pseudo-type of the arguments is similar and consistent with those of
+the inputs in GUI interface, as described in section of
+:ref:`section_reference_entry` and in particular by the
+:ref:`section_ref_entry_types`. The verification of the adequacy of variables is
+done either on their definition, or at runtime.
+
+In each command, the boolean keyword "*Stored*" indicates whether you optionally
+want to store the quantity defined, for disposal during calculation or at the
+output. The default is not to store, and it is recommended to keep this default.
+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::
+
+.. index:: single: setBackground
+
+**setBackground** (*Vector, VectorSerie, Script, Stored*)
+ This command allows to set the background :math:`\mathbf{x}^b`. Depending on
+ the algorithm, it can be defined as a simple vector by "*Vector*", or as a
+ vector list by "*VectorSerie*". If it is defined by a script in the
+ "*Script*" keyword, the vector is of type "*Vector*" (by default) or
+ "*VectorSerie*" according to whether one of these variables is positioned to
+ "*True*".
+
+.. index:: single: setBackgroundError
+
+**setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
+ This command allows to set the matrix :math:`\mathbf{B}` of background error
+ covariance. The matrix may be completely defined by the "*Matrix*" keyword,
+ or in a sparse way, by a diagonal matrix whose unique variance is given on
+ the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix which one
+ gives the vector of variances located on the diagonal by
+ "*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
+ matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
+ "*DiagonalSparseMatrix*" according to whether one of these variables is
+ positioned to "*True*".
+
+.. index:: single: setCheckingPoint
+
+**setCheckingPoint** (*Vector, VectorSerie, Script, Stored*)
+ This command allows to set a current point :math:`\mathbf{x}` used in a
+ checking algorithm. Depending on the algorithm, it can be defined as a
+ simple vector by "*Vector*", or as a vector list by "*VectorSerie*". If it
+ is defined by a script in the "*Script*" keyword, the vector is of type
+ "*Vector*" (by default) or "*VectorSerie*" according to whether one of these
+ variables is positioned to "*True*".
+
+.. index:: single: setControlModel
+
+**setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
+ This command allows to set the control operator :math:`O`, which represents
+ an external linear input control of the evolution or observation operator.
+ One can refer to the :ref:`section_ref_operator_control`. 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,
+ 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
+ of graphical interface).
+
+.. index:: single: setControlInput
+
+**setControlInput** (*Vector, VectorSerie, Script, Stored*)
+ This command allows to set the control vector :math:`\mathbf{u}`. Depending
+ on the algorithm, it can be defined as a simple vector by "*Vector*", or as
+ a vector list by "*VectorSerie*". If it is defined by a script in the
+ "*Script*" keyword, the vector is of type "*Vector*" (by default) or
+ "*VectorSerie*" according to whether one of these variables is positioned to
+ "*True*".
+
+.. index:: single: setEvolutionError
+
+**setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
+ This command allows to set the matrix :math:`\mathbf{Q}` of evolution error
+ covariance. The matrix may be completely defined by the "*Matrix*" keyword,
+ or in a sparse way, by a diagonal matrix whose unique variance is given on
+ the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix which one
+ gives the vector of variances located on the diagonal by
+ "*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
+ matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
+ "*DiagonalSparseMatrix*" according to whether one of these variables is
+ positioned to "*True*".
+
+.. index:: single: setEvolutionModel
+
+**setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
+ This command allows to set the evolution operator :math:`M`, which describes
+ an elementary evolution step. 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,
+ 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
+ of graphical interface).
+
+.. index:: single: setObservation
+
+**setObservation** (*Vector, VectorSerie, Script, Stored*)
+ This command allows to set the observation vector :math:`\mathbf{y}^o`.
+ Depending on the algorithm, it can be defined as a simple vector by
+ "*Vector*", or as a vector list by "*VectorSerie*". If it is defined by a
+ script in the "*Script*" keyword, the vector is of type "*Vector*" (by
+ default) or "*VectorSerie*" according to whether one of these variables is
+ positioned to "*True*".
+
+.. index:: single: setObservationError
+
+**setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
+ This command allows to set the matrix :math:`\mathbf{R}` of observation
+ error covariance. The matrix may be completely defined by the "*Matrix*"
+ keyword, or in a sparse way, by a diagonal matrix whose unique variance is
+ given on the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix
+ which one gives the vector of variances located on the diagonal by
+ "*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
+ matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
+ "*DiagonalSparseMatrix*" according to whether one of these variables is
+ positioned to "*True*".
+
+.. index:: single: setObservationOperator
+
+**setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, 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`.
+ 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,
+ 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
+ of graphical interface).
+
+.. index:: single: set
+
+**set** (*Concept,...*)
+ This command allows to have an equivalent syntax for all the commands of
+ these section. Its first argument is the name of the concept to be defined
+ (for example "*Background*" or "*ObservationOperator*"), on which the
+ following arguments, which are the same as in the individual previous
+ commands, are applied. When using this command, it is required to name the
+ arguments (for example "*Vector=...*").
+
+Setting the calculation, outputs, etc.
+++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: setAlgorithmParameters
+
+**setAlgorithmParameters** (*Algorithm, Parameters, Script*)
+ This command allows to choose the calculation or the verification algorithm
+ by the argument "*Algorithm*" in the form of an algorithm name (it is useful
+ to refer to the :ref:`section_reference_assimilation` and to the
+ :ref:`section_reference_checking`) and to define the calculation parameters
+ by the argument "*Parameters*". In the case of a definition by "*Script*",
+ the file must contain the two variables "*Algorithm*" and "*Parameters*" (or
+ "*AlgorithmParameters*" equivalently).
+
+.. index:: single: setDebug
+
+**setDebug** ()
+ This command enables the detailed information mode when running.
+
+.. index:: single: setNoDebug
+
+**setNoDebug** ()
+ 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`.
+
+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*".
+
+Get the calculation results separately
+++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: get
+
+**get** (*Concept*)
+ This command explicitly extract the variables available at the output of
+ calculation case for use in the rest of the scripting, such as
+ 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
+ :ref:`section_ref_output_variables` and to the individual documentations of
+ the algorithms.
+
+More advanced examples of ADAO TUI calculation case
+---------------------------------------------------
+
+We propose here more comprehensive examples of ADAO TUI calculation, by giving
+the purpose of the example and a set of commands that can achieve this goal.
+
+Independent holding of the results of a calculation case
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The objective is to perform in TUI the setting of data for an ADAO calculation
+case, its execution, and then the retrieving of the results to follow on a
+independent holding of these results (this last step not being described here,
+because it depends on the the user).
+
+The hypothesis of the user case are the following ones. It is assumed:
+
+#. 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 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
+for example the following entries, perfectly arbitrary, by building the
+observations by simulation in order to set a twin experiments case::
+
+ #
+ # Artificial building of an example of user data
+ # ----------------------------------------------
+ alpha = 5.
+ beta = 7
+ gamma = 9.0
+ #
+ alphamin, alphamax = 0., 10.
+ betamin, betamax = 3, 13
+ gammamin, gammamax = 1.5, 15.5
+ #
+ def simulation(x):
+ "Simulation function H to perform Y=H(X)"
+ import numpy
+ __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
+ __H = numpy.matrix("1 0 0;0 2 0;0 0 3; 1 2 3")
+ return __H * __x
+ #
+ # Observations obtained by simulation
+ # -----------------------------------
+ observations = simulation((2, 3, 4))
+
+The set of commands that can be used is the following::
+
+ import numpy
+ import adaoBuilder
+ #
+ # Formatting entries
+ # ------------------
+ Xb = (alpha, beta, gamma)
+ Bounds = (
+ (alphamin, alphamax),
+ (betamin, betamax ),
+ (gammamin, gammamax))
+ #
+ # TUI ADAO
+ # --------
+ case = adaoBuilder.New()
+ case.set(
+ 'AlgorithmParameters',
+ Algorithm = '3DVAR',
+ Parameters = {
+ "Bounds":Bounds,
+ "MaximumNumberOfSteps":100,
+ "StoreSupplementaryCalculations":[
+ "CostFunctionJ",
+ "CurrentState",
+ "SimulatedObservationAtOptimum",
+ ],
+ }
+ )
+ case.set( 'Background', Vector = numpy.array(Xb), Stored = True )
+ case.set( 'Observation', Vector = numpy.array(observations) )
+ case.set( 'BackgroundError', ScalarSparseMatrix = 1.0e10 )
+ case.set( 'ObservationError', ScalarSparseMatrix = 1.0 )
+ case.set(
+ 'ObservationOperator',
+ OneFunction = simulation,
+ Parameters = {"DifferentialIncrement":0.0001},
+ )
+ case.set( 'Observer', Variable="CurrentState", Template="ValuePrinter" )
+ case.execute()
+ #
+ # Independent holding
+ # -------------------
+ Xbackground = case.get("Background")
+ 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
+
+The command set execution gives the following result::
+
+ CurrentState [ 5. 7. 9.]
+ CurrentState [ 0. 3. 1.5]
+ CurrentState [ 1.40006418 3.86705307 3.7061137 ]
+ CurrentState [ 1.42580231 3.68474804 3.81008738]
+ CurrentState [ 1.60220353 3.0677108 4.06146069]
+ CurrentState [ 1.72517855 3.03296953 4.04915706]
+ CurrentState [ 2.00010755 3. 4.00055409]
+ CurrentState [ 1.99995528 3. 3.99996367]
+ CurrentState [ 2.00000007 3. 4.00000011]
+ CurrentState [ 2. 3. 4.]
+
+ Number of internal iterations...: 10
+ Initial state...................: [ 5. 7. 9.]
+ 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.
+
+.. [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.
+
+.. [YACS] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform.
**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.
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
