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