doc/en/tui.rst

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