doc/en/tui.rst

   1 ..
   2    Copyright (C) 2008-2015 EDF R&D
   3
   4    This file is part of SALOME ADAO module.
   5
   6    This library is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Lesser General Public
   8    License as published by the Free Software Foundation; either
   9    version 2.1 of the License, or (at your option) any later version.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with this library; if not, write to the Free Software
  18    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  19
  20    See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21
  22    Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
  23
  24 .. index:: single: TUI
  25 .. index:: single: API/TUI
  26 .. index:: single: adaoBuilder
  27 .. _section_tui:
  28
  29 ================================================================================
  30 **[DocR]** Textual Application Programming Interface for the user (API/TUI)
  31 ================================================================================
  32
  33 .. warning::
  34
  35   in its present version, this text programming interface (TUI) is experimental,
  36   and so changes can be required in forthcoming versions.
  37
  38 This section presents advanced usage of the ADAO module using its text
  39 programming interface (API/TUI). This interface gives ability to create a
  40 calculation object in a similar way than the case building obtained through the
  41 graphical interface (GUI). When one wants to elaborate "by hand" the TUI
  42 calculation case, it is recommended to extensively use all the ADAO module
  43 documentation, and to go back if necessary to the graphical interface (GUI), to
  44 get all the elements allowing to correctly set the commands. The general used
  45 notions and terms are defined in :ref:`section_theory`.
  46
  47 .. _subsection_tui_creating:
  48
  49 Creation of ADAO TUI calculation case and examples
  50 --------------------------------------------------
  51
  52 .. _subsection_tui_example:
  53
  54 A simple setup example of an ADAO TUI calculation case
  55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
  56
  57 To introduce the TUI interface, lets begin by a simple but complete example of
  58 ADAO calculation case. All the data are explicitly defined inside the script in
  59 order to make the reading easier. The whole set of commands is the following
  60 one::
  61
  62     from numpy import array
  63     import adaoBuilder
  64     case = adaoBuilder.New()
  65     case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
  66     case.set( 'Background',          Vector=[0, 1, 2] )
  67     case.set( 'BackgroundError',     ScalarSparseMatrix=1.0 )
  68     case.set( 'Observation',         Vector=array([0.5, 1.5, 2.5]) )
  69     case.set( 'ObservationError',    DiagonalSparseMatrix='1 1 1' )
  70     case.set( 'ObservationOperator', Matrix='1 0 0;0 2 0;0 0 3' )
  71     case.set( 'Observer',            Variable="Analysis", Template="ValuePrinter" )
  72     case.execute()
  73
  74 The result of running these commands in SALOME (either as a SALOME "*shell*"
  75 command, in the Python command window of the interface, or by the script
  76 execution entry of the menu) is the following::
  77
  78     Analysis [ 0.25000264  0.79999797  0.94999939]
  79
  80 Detailed setup of an ADAO TUI calculation case
  81 +++++++++++++++++++++++++++++++++++++++++++++++
  82
  83 More details are given here on the successive steps of the setup of an ADAO TUI
  84 calculation case. The commands themselves are detailed just after in the
  85 :ref:`subsection_tui_commands`.
  86
  87 The creation and initialisation of a study are done using the following
  88 commands, the ``case`` object name of the ADAO TUI calculation case being let
  89 free to the user choice::
  90
  91     from numpy import array
  92     import adaoBuilder
  93     case = adaoBuilder.New()
  94
  95 It is recommended to import by default the ``numpy`` module or some of its
  96 embedded constructors such as the ``array`` one, to make easier its upcoming use
  97 in the commands.
  98
  99 Thereafter, the case has to be build by preparing and storing the data that
 100 define the study. The commands order does not matter, it is sufficient that all
 101 the concepts, required by the algorithm used, are present. The user can refer to
 102 the :ref:`section_reference` and its subparts to get details about commands by
 103 algorithm. Here, we define successively the chosen data assimilation or
 104 optimization algorithm and its parameters, then the *a priori* state
 105 :math:`\mathbf{x}^b` (named ``Background``) and its errors covariance
 106 :math:`\mathbf{B}` (named ``BackgroundError``), and after that, the observation
 107 :math:`\mathbf{y}^o` (named ``Observation``) and its errors  covariance
 108 :math:`\mathbf{R}` (named ``ObservationError``)::
 109
 110     case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
 111     #
 112     case.set( 'Background',          Vector=[0, 1, 2] )
 113     case.set( 'BackgroundError',     ScalarSparseMatrix=1.0 )
 114     #
 115     case.set( 'Observation',         Vector=array([0.5, 1.5, 2.5]) )
 116     case.set( 'ObservationError',    DiagonalSparseMatrix='1 1 1' )
 117
 118 As a remark, vector or matrix inputs can be given as objects of type ``str``,
 119 ``list`` or ``tuple`` of Python, or of type ``array`` or ``matrix`` of Numpy.
 120 For these last two cases, one has only to import Numpy module before.
 121
 122 After that, one has to define the operators :math:`H` of observation and
 123 possibly :math:`M` of evolution. In all cases, linear or non-linear, they can be
 124 defined as functions. In the simple case of a linear operator, one can also
 125 define it using the matrix that corresponds to the linear operator. In the most
 126 simple present case of a linear operator, we use the following syntax for an
 127 operator from :math:`\mathbf{R}^3` into itself::
 128
 129     case.ObservationOperator(Matrix = "1 0 0;0 2 0;0 0 3")
 130
 131 In the most frequent case of a non-linear operator of :math:`\mathbf{R}^n` into
 132 :math:`\mathbf{R}^p`, it has to be previously available as a Python function,
 133 known in the current name space, which takes a ``numpy`` vector (or an ordered
 134 list) of size :math:`n` as input and which returns as output a ``numpy`` vector
 135 of size :math:`p`. When the non-linear operator is the only one to be defined by
 136 the keyword "*OneFunction*", its adjoint is directly established by numerical
 137 calculations and it can be parametrized by the keyword "*Parameters*". The
 138 following example shows a ``simulation`` function (which realizes here the same
 139 linear operator than above) and record it in the ADAO case::
 140
 141     import numpy
 142     def simulation(x):
 143         "Simulation function H to perform Y=H(X)"
 144         __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
 145         __H = numpy.matrix("1 0 0;0 2 0;0 0 3")
 146         return __H * __x
 147     #
 148     case.set( 'ObservationOperator',
 149         OneFunction = simulation,
 150         Parameters  = {"DifferentialIncrement":0.01},
 151         )
 152
 153 To obtain intermediary or final results of the case, one can add some
 154 "*observer*", that link a script to execute with an intermediate or final
 155 calculation variable. The reader can go the description of the way of
 156 :ref:`section_advanced_observer`, and to the :ref:`section_reference` in order
 157 to know what are the observable quantities. This link between an "*observer*"
 158 and an observable quantity is done in a similar way than the calculation data
 159 definition::
 160
 161     case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
 162
 163 Finally, when all the required information are available in the ADAO calculation
 164 case named ``case``, it can be executed in a very simple way in the environment
 165 of the Python interpreter::
 166
 167     case.execute()
 168
 169 At the end, we get a very compact script previously proposed in
 170 :ref:`subsection_tui_example`.
 171
 172 Using more complex calculation data or information
 173 ++++++++++++++++++++++++++++++++++++++++++++++++++
 174
 175 Such an interface being written in Python, it is possible to use all the power
 176 of the language to enter more complex data than explicit declaration.
 177
 178 The registering of input data supports various variable types, but in addition,
 179 these inputs can come from variables currently available in the name space of the
 180 script. It is then easy to use previously calculated variables or obtained by
 181 importing "user" scripts. If for example the observations are available as a
 182 list in an external Python file named ``observations.py`` under the name
 183 ``table``, the registering of the observations in the ADAO TUI calculation
 184 case can be done by the following operations::
 185
 186     from observations import table
 187     case.set( 'Observation', Vector=table )
 188
 189 The first line imports the ``table`` variable from the external file, and the
 190 second one register directly this table as the "*Observation*" data.
 191
 192 The simplicity of this recording demonstrates the ease of obtaining
 193 computational data from external sources, files or computing flows achievable in
 194 Python. As usual, it is recommended to the user to check its data before saving
 195 them in the ADAO TUI calculation case to avoid errors complicated to correct.
 196
 197 Obtain and use the results of calculation in a richer way
 198 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 199
 200 Similarly, it is possible to obtain and process the results of calculation in a
 201 richer way, following up on post-processing after the TUI calculation.
 202
 203 The variables of calculation results, or the internal variables coming from
 204 optimization or data assimilation, are available through the ``get`` method of
 205 the ADAO TUI calculation case, which send back an object of list type of the
 206 required variable. The reader can go to the :ref:`section_ref_output_variables`
 207 for a detailed description on this subject.
 208
 209 For instance, we give some script lines that allow to get the number of
 210 iterations of the optimization and the optimal value, and its size::
 211
 212     print
 213     print "    Number of iterations :", len(case.get("CostFunctionJ"))
 214     Xa = case.get("Analysis")
 215     print "    Optimal analysis     :", Xa[-1]
 216     print "    Size of the analysis :", len(Xa[-1])
 217     print
 218
 219 These lines can be very simply added to the initial example of ADAO TUI
 220 calculation case given in :ref:`subsection_tui_example`.
 221
 222 As well as for data entry, the simplicity of results achievement makes it easy
 223 to consider post-processing chains in SALOME, to use for example visualization
 224 with MatPlotLib or PARAVIS [PARAVIS]_, mesh adaptation with HOMARD [HOMARD]_, or
 225 for other calculations.
 226
 227 .. _subsection_tui_commands:
 228
 229 Set of available commands in text user interface TUI
 230 ----------------------------------------------------
 231
 232 In the TUI interface of ADAO module, we follow usual Python conventions and
 233 recommendations to make the distinction between public objects, and private or
 234 reserved ones because of implementation details. In practice, every object or
 235 function name beginning with at least one "**_**" sign is private in the usual
 236 programming sense ("*private*"). Nevertheless, the absence of such a sign at the
 237 beginning of a name does not designate it as public. In general, in Python, and
 238 unlike other languages, you can access private objects or functions. This can
 239 sometimes be useful, but such use in your codes will lead to crashes without
 240 warning in future versions. It is strongly recommended not to do so.
 241
 242 To clarify and facilitate the use of the module for scripting, **this section
 243 therefore defines the application programming interface (API) for textual user
 244 interface (TUI) by a comprehensive and restricted manner**. Use in scripts of
 245 ADAO objects or functions other than those defined here is strongly discouraged,
 246 as this will likely lead to crashes without warning in future versions.
 247
 248 Equivalent syntax calls for commands
 249 ++++++++++++++++++++++++++++++++++++
 250
 251 The definition of data during the ADAO TUI calculation case creation supports
 252 **two completely equivalent syntaxes**. One can:
 253
 254 - either use the ``set`` command and as the first argument the concept ``XXXXX``
 255   on which to apply the command whose arguments follow,
 256 - or use the command ``setXXXXX`` containing the arguments of the command to
 257   apply.
 258
 259 To illustrate this equivalence, we take the example of two commands that lead to
 260 the same result::
 261
 262     case.set( 'Background', Vector=[0, 1, 2] )
 263
 264 and::
 265
 266     case.setBackground( Vector=[0, 1, 2] )
 267
 268 The choice of one or the other syntaxes is freely left to the user, according to
 269 its context of use. In the following, for clarity, we define the controls
 270 according to the second syntax.
 271
 272 Creating a calculation case in TUI text interface
 273 +++++++++++++++++++++++++++++++++++++++++++++++++
 274
 275 The creation and the initialisation of a calculation case in TUI text interface
 276 are done by importing the interface module "*adaoBuilder*" and by by invoking
 277 its method "*New()*" as illustrated in the following lines (the ``case`` object
 278 name being let free to the user choice)::
 279
 280     from numpy import array
 281     import adaoBuilder
 282     case = adaoBuilder.New()
 283
 284 It is recommended by default to always import the ``numpy`` module (or some of
 285 its embedded constructors such as the ``array`` one) to make easier its upcoming
 286 use in the commands.
 287
 288 Defining the calculation data
 289 +++++++++++++++++++++++++++++
 290
 291 The following commands are used to define the data of an ADAO TUI calculation
 292 case. The pseudo-type of the arguments is similar and consistent with those of
 293 the inputs in GUI interface, as described in section of
 294 :ref:`section_reference_entry` and in particular by the
 295 :ref:`section_ref_entry_types`. The verification of the adequacy of variables is
 296 done either on their definition, or at runtime.
 297
 298 In each command, the boolean keyword "*Stored*" indicates whether you optionally
 299 want to store the quantity defined, for disposal during calculation or at the
 300 output. The default is not to store, and it is recommended to keep this default.
 301 Indeed, for a TUI calculation case, the quantity given in entries are often
 302 available in the current name space of the case.
 303
 304 The available commands are:
 305
 306 .. index:: single: setBackground
 307
 308 **setBackground** (*Vector, VectorSerie, Script, Stored*)
 309     This command allows to set the background :math:`\mathbf{x}^b`. Depending on
 310     the algorithm, it can be defined as a simple vector by "*Vector*", or as a
 311     vector list by "*VectorSerie*". If it is defined by a script in the
 312     "*Script*" keyword, the vector is of type "*Vector*" (by default) or
 313     "*VectorSerie*" according to whether one of these variables is positioned to
 314     "*True*".
 315
 316 .. index:: single: setBackgroundError
 317
 318 **setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 319     This command allows to set the matrix :math:`\mathbf{B}` of background error
 320     covariance. The matrix may be completely defined by the "*Matrix*" keyword,
 321     or in a sparse way, by a diagonal matrix whose unique variance is given on
 322     the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix which one
 323     gives the vector of variances located on the diagonal by
 324     "*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
 325     matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
 326     "*DiagonalSparseMatrix*" according to whether one of these variables is
 327     positioned to "*True*".
 328
 329 .. index:: single: setCheckingPoint
 330
 331 **setCheckingPoint** (*Vector, VectorSerie, Script, Stored*)
 332     This command allows to set a current point :math:`\mathbf{x}` used in a
 333     checking algorithm. Depending on the algorithm, it can be defined as a
 334     simple vector by "*Vector*", or as a vector list by "*VectorSerie*". If it
 335     is defined by a script in the "*Script*" keyword, the vector is of type
 336     "*Vector*" (by default) or "*VectorSerie*" according to whether one of these
 337     variables is positioned to "*True*".
 338
 339 .. index:: single: setControlModel
 340
 341 **setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
 342     This command allows to set the control operator :math:`O`, which represents
 343     an external linear input control of the evolution or observation operator.
 344     One can refer to the :ref:`section_ref_operator_control`. Its value is
 345     defined as an object of type function or of type "*Matrix*". For the
 346     function case, various functional forms may be used, as described in the
 347     :ref:`section_ref_operator_requirements`, and entered by "*OneFunction*" or
 348     "*ThreeFunctions*" keywords.  If it is defined by a script in the "*Script*"
 349     keyword, the operator is of type "*Matrix*", "*OneFunction*" or
 350     "*ThreeFunctions*" according to whether one of these variables is positioned
 351     to "*True*". The control parameters of the adjoint numerical approximation,
 352     in the "*OneFunction*"case, can be given by a dictionary through the
 353     "*Parameters*" keyword. Potential entries of this dictionary are
 354     "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similar to the one
 355     of graphical interface).
 356
 357 .. index:: single: setControlInput
 358
 359 **setControlInput** (*Vector, VectorSerie, Script, Stored*)
 360     This command allows to set the control vector :math:`\mathbf{u}`. Depending
 361     on the algorithm, it can be defined as a simple vector by "*Vector*", or as
 362     a vector list by "*VectorSerie*". If it is defined by a script in the
 363     "*Script*" keyword, the vector is of type "*Vector*" (by default) or
 364     "*VectorSerie*" according to whether one of these variables is positioned to
 365     "*True*".
 366
 367 .. index:: single: setEvolutionError
 368
 369 **setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 370     This command allows to set the matrix :math:`\mathbf{Q}` of evolution error
 371     covariance. The matrix may be completely defined by the "*Matrix*" keyword,
 372     or in a sparse way, by a diagonal matrix whose unique variance is given on
 373     the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix which one
 374     gives the vector of variances located on the diagonal by
 375     "*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
 376     matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
 377     "*DiagonalSparseMatrix*" according to whether one of these variables is
 378     positioned to "*True*".
 379
 380 .. index:: single: setEvolutionModel
 381
 382 **setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
 383     This command allows to set the evolution operator :math:`M`, which describes
 384     an elementary evolution step. Its value is defined as an object of type
 385     function or of type "*Matrix*". For the function case, various functional
 386     forms may be used, as described in the
 387     :ref:`section_ref_operator_requirements`, and entered by "*OneFunction*" or
 388     "*ThreeFunctions*" keywords.  If it is defined by a script in the "*Script*"
 389     keyword, the operator is of type "*Matrix*", "*OneFunction*" or
 390     "*ThreeFunctions*" according to whether one of these variables is positioned
 391     to "*True*". The control parameters of the adjoint numerical approximation,
 392     in the "*OneFunction*"case, can be given by a dictionary through the
 393     "*Parameters*" keyword. Potential entries of this dictionary are
 394     "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similar to the one
 395     of graphical interface).
 396
 397 .. index:: single: setObservation
 398
 399 **setObservation** (*Vector, VectorSerie, Script, Stored*)
 400     This command allows to set the observation vector :math:`\mathbf{y}^o`.
 401     Depending on the algorithm, it can be defined as a simple vector by
 402     "*Vector*", or as a vector list by "*VectorSerie*". If it is defined by a
 403     script in the "*Script*" keyword, the vector is of type "*Vector*" (by
 404     default) or "*VectorSerie*" according to whether one of these variables is
 405     positioned to "*True*".
 406
 407 .. index:: single: setObservationError
 408
 409 **setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 410     This command allows to set the matrix :math:`\mathbf{R}` of observation
 411     error covariance. The matrix may be completely defined by the "*Matrix*"
 412     keyword, or in a sparse way, by a diagonal matrix whose unique variance is
 413     given on the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix
 414     which one gives the vector of variances located on the diagonal by
 415     "*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
 416     matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
 417     "*DiagonalSparseMatrix*" according to whether one of these variables is
 418     positioned to "*True*".
 419
 420 .. index:: single: setObservationOperator
 421
 422 **setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
 423     This command allows to set the evolution operator :math:`H`, which
 424     transforms the input parameters :math:`\mathbf{x}` in results
 425     :math:`\mathbf{y}` that are compared to observations :math:`\mathbf{y}^o`.
 426     Its value is defined as an object of type function or of type "*Matrix*".
 427     For the function case, various functional forms may be used, as described in
 428     the :ref:`section_ref_operator_requirements`, and entered by "*OneFunction*"
 429     or "*ThreeFunctions*" keywords.  If it is defined by a script in the
 430     "*Script*" keyword, the operator is of type "*Matrix*", "*OneFunction*" or
 431     "*ThreeFunctions*" according to whether one of these variables is positioned
 432     to "*True*". The control parameters of the adjoint numerical approximation,
 433     in the "*OneFunction*"case, can be given by a dictionary through the
 434     "*Parameters*" keyword. Potential entries of this dictionary are
 435     "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similar to the one
 436     of graphical interface).
 437
 438 .. index:: single: set
 439
 440 **set** (*Concept,...*)
 441     This command allows to have an equivalent syntax for all the commands of
 442     these section. Its first argument is the name of the concept to be defined
 443     (for example "*Background*" or "*ObservationOperator*"), on which the
 444     following arguments, which are the same as in the individual previous
 445     commands, are applied. When using this command, it is required to name the
 446     arguments (for example "*Vector=...*").
 447
 448 Setting the calculation, outputs, etc.
 449 ++++++++++++++++++++++++++++++++++++++
 450
 451 .. index:: single: setAlgorithmParameters
 452
 453 **setAlgorithmParameters** (*Algorithm, Parameters, Script*)
 454     This command allows to choose the calculation or the verification algorithm
 455     by the argument "*Algorithm*" in the form of an algorithm name (it is useful
 456     to refer to the :ref:`section_reference_assimilation` and to the
 457     :ref:`section_reference_checking`) and to define the calculation parameters
 458     by the argument "*Parameters*". In the case of a definition by "*Script*",
 459     the file must contain the two variables "*Algorithm*" and "*Parameters*" (or
 460     "*AlgorithmParameters*" equivalently).
 461
 462 .. index:: single: setDebug
 463
 464 **setDebug** ()
 465     This command enables the detailed information mode when running.
 466
 467 .. index:: single: setNoDebug
 468
 469 **setNoDebug** ()
 470     This command disables the detailed information mode when running.
 471
 472 .. index:: single: setObserver
 473
 474 **setObserver** (*Variable, Template, String, Script, Info*)
 475     This command allows to set an *observer* on the current or final calculation
 476     variable. Reference should be made to the description of the
 477     ':ref:`ref_observers_requirements` for their list and content, and to the
 478     :ref:`section_reference` to know what are the observable quantities. One
 479     defines as "*String*" the *observer* body, using a string including if
 480     necessary line breaks. It is recommended to use the patterns available by
 481     the argument "*Template*". In the case of a definition as "*Script*", the
 482     file must contain only the body of the function, as  described in the
 483     :ref:`ref_observers_requirements`.
 484
 485 Perform the calculation
 486 +++++++++++++++++++++++
 487
 488 .. index:: single: executePythonScheme
 489
 490 **executePythonScheme** ()
 491     This command launches the complete calculation in the environment of the
 492     current Python interpreter, without interaction with YACS [YACS]_. The
 493     standard output and standard error are those of the Python interpreter. If
 494     necessary, the internal parallelism, of the algorithms in ADAO and of the
 495     simulation code used, is available.
 496
 497 .. index:: single: execute
 498
 499 **execute** ()
 500     This command is a user shorthand for "*executePythonScheme*".
 501
 502 Get the calculation results separately
 503 ++++++++++++++++++++++++++++++++++++++
 504
 505 .. index:: single: get
 506
 507 **get** (*Concept*)
 508     This command explicitly extract the variables available at the output of
 509     calculation case for use in the rest of the scripting, such as
 510     visualization. Its argument the name of a variable "*Concept*" and returns
 511     back the quantity as a list (even if there is only one specimen) of this
 512     base variable. For a list of variables and use them, the user has to refer
 513     to the :ref:`subsection_r_o_v_Inventaire` and more generally to the
 514     :ref:`section_ref_output_variables` and to the individual documentations of
 515     the algorithms.
 516
 517 More advanced examples of ADAO TUI calculation case
 518 ---------------------------------------------------
 519
 520 We propose here more comprehensive examples of ADAO TUI calculation, by giving
 521 the purpose of the example and a set of commands that can achieve this goal.
 522
 523 Independent holding of the results of a calculation case
 524 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 525
 526 The objective is to perform in TUI the setting of data for an ADAO calculation
 527 case, its execution, and then the retrieving of the results to follow on a
 528 independent holding of these results (this last step not being described here,
 529 because it depends on the the user).
 530
 531 The hypothesis of the user case are the following ones. It is assumed:
 532
 533 #. that we want to adjust 3 parameters ``alpha``, ``beta`` and ``gamma`` in a bounded domain,
 534 #. that we dispose of observations named ``observations``,
 535 #. 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,
 536 #. 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.
 537
 538 In order to try in a simple way this example of TUI calculation case, we choose
 539 for example the following entries, perfectly arbitrary, by building the
 540 observations by simulation in order to set a twin experiments case::
 541
 542     #
 543     # Artificial building of an example of user data
 544     # ----------------------------------------------
 545     alpha = 5.
 546     beta = 7
 547     gamma = 9.0
 548     #
 549     alphamin, alphamax = 0., 10.
 550     betamin,  betamax  = 3, 13
 551     gammamin, gammamax = 1.5, 15.5
 552     #
 553     def simulation(x):
 554         "Simulation function H to perform Y=H(X)"
 555         import numpy
 556         __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
 557         __H = numpy.matrix("1 0 0;0 2 0;0 0 3; 1 2 3")
 558         return __H * __x
 559     #
 560     # Observations obtained by simulation
 561     # -----------------------------------
 562     observations = simulation((2, 3, 4))
 563
 564 The set of commands that can be used is the following::
 565
 566     import numpy
 567     import adaoBuilder
 568     #
 569     # Formatting entries
 570     # ------------------
 571     Xb = (alpha, beta, gamma)
 572     Bounds = (
 573         (alphamin, alphamax),
 574         (betamin,  betamax ),
 575         (gammamin, gammamax))
 576     #
 577     # TUI ADAO
 578     # --------
 579     case = adaoBuilder.New()
 580     case.set(
 581         'AlgorithmParameters',
 582         Algorithm = '3DVAR',
 583         Parameters = {
 584             "Bounds":Bounds,
 585             "MaximumNumberOfSteps":100,
 586             "StoreSupplementaryCalculations":[
 587                 "CostFunctionJ",
 588                 "CurrentState",
 589                 "SimulatedObservationAtOptimum",
 590                 ],
 591             }
 592         )
 593     case.set( 'Background', Vector = numpy.array(Xb), Stored = True )
 594     case.set( 'Observation', Vector = numpy.array(observations) )
 595     case.set( 'BackgroundError', ScalarSparseMatrix = 1.0e10 )
 596     case.set( 'ObservationError', ScalarSparseMatrix = 1.0 )
 597     case.set(
 598         'ObservationOperator',
 599         OneFunction = simulation,
 600         Parameters  = {"DifferentialIncrement":0.0001},
 601         )
 602     case.set( 'Observer', Variable="CurrentState", Template="ValuePrinter" )
 603     case.execute()
 604     #
 605     # Independent holding
 606     # -------------------
 607     Xbackground   = case.get("Background")
 608     Xoptimum      = case.get("Analysis")[-1]
 609     FX_at_optimum = case.get("SimulatedObservationAtOptimum")[-1]
 610     J_values      = case.get("CostFunctionJ")[:]
 611     print
 612     print "Number of internal iterations...: %i"%len(J_values)
 613     print "Initial state...................:",numpy.ravel(Xbackground)
 614     print "Optimal state...................:",numpy.ravel(Xoptimum)
 615     print "Simulation at optimal state.....:",numpy.ravel(FX_at_optimum)
 616     print
 617
 618 The command set execution gives the following result::
 619
 620     CurrentState [ 5.  7.  9.]
 621     CurrentState [ 0.   3.   1.5]
 622     CurrentState [ 1.40006418  3.86705307  3.7061137 ]
 623     CurrentState [ 1.42580231  3.68474804  3.81008738]
 624     CurrentState [ 1.60220353  3.0677108   4.06146069]
 625     CurrentState [ 1.72517855  3.03296953  4.04915706]
 626     CurrentState [ 2.00010755  3.          4.00055409]
 627     CurrentState [ 1.99995528  3.          3.99996367]
 628     CurrentState [ 2.00000007  3.          4.00000011]
 629     CurrentState [ 2.  3.  4.]
 630
 631     Number of internal iterations...: 10
 632     Initial state...................: [ 5.  7.  9.]
 633     Optimal state...................: [ 2.  3.  4.]
 634     Simulation at optimal state.....: [  2.   6.  12.  20.]
 635
 636 As it should be in twin experiments, it is found that we get correctly the
 637 parameters that were used to artificially build the observations.
 638
 639 .. Réconciliation de courbes à l'aide de MedCoupling
 640 .. +++++++++++++++++++++++++++++++++++++++++++++++++
 641
 642 .. Utilisation de fonctions de surveillance de type "observer"
 643 .. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 644
 645 .. Suivre d'un recalage à l'aide de MatPlotLib
 646 .. +++++++++++++++++++++++++++++++++++++++++++
 647
 648 .. Equivalences entre l'interface graphique (GUI) et l'interface textuelle (TUI)
 649 .. -----------------------------------------------------------------------------
 650
 651 .. [HOMARD] For more information on HOMARD, see the *HOMARD module* and its integrated help available from the main menu *Help* of the SALOME platform.
 652
 653 .. [PARAVIS] For more information on PARAVIS, see the *PARAVIS module* and its integrated help available from the main menu *Help* of the SALOME platform.
 654
 655 .. [YACS] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform.