doc/en/tui.rst

   1 ..
   2    Copyright (C) 2008-2024 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 User Interface for ADAO (TUI/API)
  31 ================================================================================
  32
  33 .. |eficas_totui| image:: images/eficas_totui.png
  34    :align: middle
  35    :scale: 50%
  36
  37 This section presents advanced usage of the ADAO module using its text
  38 programming interface (API/TUI). This interface gives user ability to create a
  39 calculation object in a similar way than the case building obtained through the
  40 graphical interface (GUI). A scripted form of a case built in the GUI can be
  41 obtained directly using the TUI export button |eficas_totui| integrated in the
  42 interface, but more complicated or integrated cases can be build only using TUI
  43 approach. When one wants to elaborate directly the TUI calculation case, it is
  44 recommended to extensively use all the ADAO module documentation, and to go
  45 back if necessary to the graphical interface (GUI), to get all the elements
  46 allowing to correctly set the commands. The general used notions and terms are
  47 defined in :ref:`section_theory`. As in the graphical interface, we point out
  48 that the TUI approach is intended to create and manage a single calculation
  49 case.
  50
  51 .. _subsection_tui_creating:
  52
  53 Creation of ADAO TUI calculation case and examples
  54 --------------------------------------------------
  55
  56 .. _subsection_tui_example:
  57
  58 A simple setup example of an ADAO TUI calculation case
  59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
  60
  61 To introduce the TUI interface, lets begin by a simple but complete example of
  62 ADAO calculation case. All the data are explicitly defined inside the script in
  63 order to make the reading easier. The whole set of commands is the following
  64 one:
  65
  66 .. literalinclude:: scripts/tui_example_01.py
  67     :language: python
  68
  69 The result of running these commands in SALOME (either as a SALOME "*shell*"
  70 command, in the SALOME Python command window of the interface, or by the script
  71 execution entry of the menu) is the following:
  72
  73 .. literalinclude:: scripts/tui_example_01.res
  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`. We keep the indication ``[...]`` of preceding
  81 or following lines to emphasize that these commands can be inserted in the
  82 middle of a complete stream of Python scripting for a real study.
  83
  84 The creation and initialization of a study are done using the following
  85 commands, the ``case`` object name of the ADAO TUI calculation case being let
  86 free to the user choice:
  87
  88 .. code-block:: python
  89
  90     [...]
  91     from numpy import array
  92     from adao import adaoBuilder
  93     case = adaoBuilder.New()
  94     [...]
  95
  96 It is recommended to import by default the ``numpy`` module or some of its
  97 embedded constructors such as the ``array`` one, to make easier its upcoming
  98 use in the commands.
  99
 100 Thereafter, the case has to be build by preparing and storing the data that
 101 define the study. The commands order does not matter, it is sufficient that all
 102 the concepts, required by the algorithm used, are present. The user can refer
 103 to the :ref:`section_reference` and its sub-parts to get details about commands
 104 by algorithm. Here, we define successively the chosen data assimilation or
 105 optimization algorithm and its parameters, then the *a priori* state
 106 :math:`\mathbf{x}^b` (named ``Background``) and its errors covariance
 107 :math:`\mathbf{B}` (named ``BackgroundError``), and after that, the observation
 108 :math:`\mathbf{y}^o` (named ``Observation``) and its errors  covariance
 109 :math:`\mathbf{R}` (named ``ObservationError``):
 110
 111 .. code-block:: python
 112
 113     [...]
 114     case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
 115     #
 116     case.set( 'Background',          Vector=[0, 1, 2] )
 117     case.set( 'BackgroundError',     ScalarSparseMatrix=1.0 )
 118     #
 119     case.set( 'Observation',         Vector=array([0.5, 1.5, 2.5]) )
 120     case.set( 'ObservationError',    DiagonalSparseMatrix='1 1 1' )
 121     [...]
 122
 123 As a remark, vector or matrix inputs can be given as objects of type ``str``,
 124 ``list`` or ``tuple`` of Python, or of type ``array`` or ``matrix`` of Numpy.
 125 For these last two cases, one has only to import Numpy module before.
 126
 127 After that, one has to define the operators :math:`H` of observation and
 128 possibly :math:`M` of evolution. In all cases, linear or non-linear, they can
 129 be defined as functions. In the simple case of a linear operator, one can also
 130 define it using the matrix that corresponds to the linear operator. In the most
 131 simple present case of a linear operator, we use the following syntax for an
 132 operator from :math:`\mathbf{R}^3` into itself:
 133
 134 .. code-block:: python
 135
 136     [...]
 137     case.set( 'ObservationOperator', Matrix = "1 0 0;0 2 0;0 0 3")
 138     [...]
 139
 140 In the most frequent case of a non-linear operator of :math:`\mathbf{R}^n` into
 141 :math:`\mathbf{R}^p`, it has to be previously available as a Python function,
 142 known in the current name space, which takes a Numpy vector (or an ordered
 143 list) of size :math:`n` as input and which returns as output a Numpy vector
 144 of size :math:`p`. When the non-linear operator is the only one to be defined
 145 by the keyword "*OneFunction*", its adjoint is directly established by
 146 numerical calculations and it can be parametrized by the keyword
 147 "*Parameters*". The following example shows a ``simulation`` function (which
 148 realizes here the same linear operator than above) and record it in the ADAO
 149 case:
 150
 151 .. code-block:: python
 152
 153     [...]
 154     import numpy
 155     def simulation(x):
 156         "Simulation function H to perform Y=H(X)"
 157         import numpy
 158         __x = numpy.ravel(x)
 159         __H = numpy.diag([1.,2.,3.])
 160         return numpy.dot(__H, __x)
 161     #
 162     case.set( 'ObservationOperator',
 163         OneFunction = simulation,
 164         Parameters  = {"DifferentialIncrement":0.01},
 165         )
 166     [...]
 167
 168 To obtain intermediary or final results of the case, one can add some
 169 "*observer*", that link a script to execute with an intermediate or final
 170 calculation variable. The reader can go the description of the way of
 171 :ref:`section_advanced_observer`, and to the :ref:`section_reference` in order
 172 to know what are the observable quantities. This link between an "*observer*"
 173 and an observable quantity is done in a similar way than the calculation data
 174 definition:
 175
 176 .. code-block:: python
 177
 178     [...]
 179     case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
 180     [...]
 181
 182 Finally, when all the required information are available in the ADAO
 183 calculation case named ``case``, it can be executed in a very simple way in the
 184 environment of the Python interpreter:
 185
 186 .. code-block:: python
 187
 188     [...]
 189     case.execute()
 190     [...]
 191
 192 At the end, we get a very compact script previously proposed in
 193 :ref:`subsection_tui_example`.
 194
 195 Using more complex calculation data or information
 196 ++++++++++++++++++++++++++++++++++++++++++++++++++
 197
 198 Such an interface being written in Python, it is possible to use all the power
 199 of the language to enter more complex data than explicit declaration.
 200
 201 The registering of input data supports various variable types, but in addition,
 202 these inputs can come from variables currently available in the name space of
 203 the script. It is then easy to use previously calculated variables or obtained
 204 by importing "user" scripts. If for example the observations are available as a
 205 list in an external Python file named ``observations.py`` under the name
 206 ``someTable``, the registering of the observations in the ADAO TUI calculation
 207 case can be done by the following operations:
 208
 209 .. code-block:: python
 210
 211     [...]
 212     from observations import someTable
 213     case.set( 'Observation', Vector=someTable )
 214     [...]
 215
 216 The first line imports the ``someTable`` variable from the external file, and
 217 the second one register directly this table as the "*Observation*" data.
 218
 219 The simplicity of this recording demonstrates the ease of obtaining
 220 computational data from external sources, files or computing flows achievable
 221 in Python. As usual, it is recommended to the user to check its data before
 222 saving them in the ADAO TUI calculation case to avoid errors complicated to
 223 correct.
 224
 225 Obtain and use the results of calculation in a richer way
 226 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 227
 228 Similarly, it is possible to obtain and process the results of calculation in a
 229 richer way, following up on post-processing after the TUI calculation.
 230
 231 The variables of calculation results, or the internal variables coming from
 232 optimization or data assimilation, are available through the ``get`` method of
 233 the ADAO TUI calculation case, which send back an object of list type of the
 234 required variable. The reader can go to the :ref:`section_ref_output_variables`
 235 for a detailed description on this subject.
 236
 237 For instance, we give some script lines that allow to get the number of
 238 iterations of the optimization and the optimal value, and its size:
 239
 240 .. code-block:: python
 241
 242     [...]
 243     print("")
 244     print("    Number of iterations : %i"%len(case.get("CostFunctionJ")))
 245     Xa = case.get("Analysis")
 246     print("    Optimal analysis     : %s"%(Xa[-1],))
 247     print("    Size of the analysis : %i"%len(Xa[-1]))
 248     print("")
 249     [...]
 250
 251 These lines can be very simply added to the initial example of ADAO TUI
 252 calculation case given in :ref:`subsection_tui_example`.
 253
 254 As well as for data entry, the simplicity of results achievement makes it easy
 255 to consider post-processing chains in SALOME, to use for example visualization
 256 with MatPlotLib or PARAVIS [PARAVIS]_, mesh adaptation with HOMARD [HOMARD]_, or
 257 for other calculations.
 258
 259 .. _subsection_tui_commands:
 260
 261 Set of available commands in text user interface TUI
 262 ----------------------------------------------------
 263
 264 In the TUI interface of ADAO module, we follow usual Python conventions and
 265 recommendations to make the distinction between public objects, and private or
 266 reserved ones because of implementation details. In practice, every object or
 267 function name beginning with at least one "**_**" sign is private in the usual
 268 programming sense ("*private*"). Nevertheless, the absence of such a sign at
 269 the beginning of a name does not designate it as public. In general, in Python,
 270 and unlike other languages, you can access private objects or functions. This
 271 can sometimes be useful, but such use in your codes will lead to crashes
 272 without warning in future versions. It is strongly recommended not to do so.
 273
 274 To clarify and facilitate the use of the module for scripting, **this section
 275 therefore defines the application programming interface (API) for textual user
 276 interface (TUI) by a comprehensive and restricted manner**. Use in scripts of
 277 ADAO objects or functions other than those defined here is strongly
 278 discouraged, as this will likely lead to crashes without warning in future
 279 versions.
 280
 281 Equivalent syntax calls for commands
 282 ++++++++++++++++++++++++++++++++++++
 283
 284 The definition of data during the ADAO TUI calculation case creation supports
 285 **two completely equivalent syntaxes**. One can:
 286
 287 - either use the ``set`` command and as the first argument the concept ``XXXXX``
 288   on which to apply the command whose arguments follow,
 289 - or use the command ``setXXXXX`` containing the arguments of the command to
 290   apply.
 291
 292 To illustrate this equivalence, we take the example of two commands that lead
 293 to the same result::
 294
 295     case.set( 'Background', Vector=[0, 1, 2] )
 296
 297 and::
 298
 299     case.setBackground( Vector=[0, 1, 2] )
 300
 301 The choice of one or the other syntaxes is freely left to the user, according
 302 to its context of use. In the following, for clarity, we define the controls
 303 according to the second syntax.
 304
 305 Creating a calculation case in TUI text interface
 306 +++++++++++++++++++++++++++++++++++++++++++++++++
 307
 308 The creation and the initialization of a calculation case in TUI text interface
 309 are done by importing the interface module "*adaoBuilder*" and by by invoking
 310 its method "*New()*" as illustrated in the following lines (the ``case`` object
 311 name being let free to the user choice):
 312
 313 .. code-block:: python
 314
 315     [...]
 316     from numpy import array
 317     from adao import adaoBuilder
 318     case = adaoBuilder.New()
 319     [...]
 320
 321 It is recommended by default to always import the ``numpy`` module (or some of
 322 its embedded constructors such as the ``array`` one) to make easier its
 323 upcoming use in the commands.
 324
 325 Defining the calculation data
 326 +++++++++++++++++++++++++++++
 327
 328 The following commands are used to define the data of an ADAO TUI calculation
 329 case. The pseudo-type of the arguments is similar and consistent with those of
 330 the inputs in GUI interface, as described in section of
 331 :ref:`section_reference_entry` and in particular by the
 332 :ref:`section_ref_entry_types`. The verification of the adequacy of variables
 333 is done either on their definition, or at runtime.
 334
 335 .. index:: single: Stored
 336
 337 In each command, the boolean keyword "*Stored*" indicates whether you
 338 optionally want to store the quantity defined, for disposal during calculation
 339 or at the output. The default is not to store, and it is recommended to keep
 340 this default. Indeed, for a TUI calculation case, the quantity given in entries
 341 are often available in the current name space of the case.
 342
 343 The available commands are:
 344
 345 .. index:: single: set
 346
 347 **set** (*Concept,...*)
 348     This command allows to have an equivalent syntax for all the commands of
 349     these section. Its first argument is the name of the concept to be defined
 350     (for example "*Background*" or "*ObservationOperator*"), on which the
 351     following arguments, which are the same as in the individual previous
 352     commands, are applied. When using this command, it is required to name the
 353     arguments (for example "*Vector=...*").
 354
 355 .. index:: single: Background
 356 .. index:: single: setBackground
 357
 358 **setBackground** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
 359     This command allows to set the background :math:`\mathbf{x}^b`. Depending
 360     on the algorithm, it can be defined as a simple vector by "*Vector*", or as
 361     a vector list by "*VectorSerie*". If it is defined by a script in the
 362     "*Script*" keyword, the vector is of type "*Vector*" (by default) or
 363     "*VectorSerie*" according to whether one of these variables is positioned
 364     to "*True*". If there is a data file given by "*DataFile*" (selecting, in
 365     rows by default or in lines as chosen by "*ColMajor*", all the variables by
 366     default or those from the list "*ColNames*"), the vector is of type
 367     "*Vector*".
 368
 369 .. index:: single: BackgroundError
 370 .. index:: single: setBackgroundError
 371
 372 **setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 373     This command allows to set the matrix :math:`\mathbf{B}` of background
 374     error covariance. The matrix may be completely defined by the "*Matrix*"
 375     keyword, or in a sparse way, by a diagonal matrix whose unique variance is
 376     given on the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix
 377     which one gives the vector of variances located on the diagonal by
 378     "*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
 379     matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
 380     "*DiagonalSparseMatrix*" according to whether one of these variables is
 381     positioned to "*True*".
 382
 383 .. index:: single: CheckingPoint
 384 .. index:: single: setCheckingPoint
 385
 386 **setCheckingPoint** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
 387     This command allows to set a current point :math:`\mathbf{x}` used in a
 388     checking algorithm. Depending on the algorithm, it can be defined as a
 389     simple vector by "*Vector*", or as a vector list by "*VectorSerie*". If it
 390     is defined by a script in the "*Script*" keyword, the vector is of type
 391     "*Vector*" (by default) or "*VectorSerie*" according to whether one of
 392     these variables is positioned to "*True*". If there is a data file given by
 393     "*DataFile*" (selecting, in rows by default or in lines as chosen by
 394     "*ColMajor*", all the variables by default or those from the list
 395     "*ColNames*"), the vector is of type "*Vector*".
 396
 397 .. index:: single: ControlModel
 398 .. index:: single: setControlModel
 399 .. index:: single: ExtraArguments
 400
 401 **setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArguments, Stored*)
 402     This command allows to set the control operator :math:`O`, which represents
 403     an external linear input control of the evolution or observation operator.
 404     One can refer to the :ref:`section_ref_operator_control`. Its value is
 405     defined as an object of type function or of type "*Matrix*". For the
 406     function case, various functional forms may be used, as described in the
 407     :ref:`section_ref_operator_requirements`, and entered by "*OneFunction*" or
 408     "*ThreeFunctions*" keywords.  If it is defined by a script in the
 409     "*Script*" keyword, the operator is of type "*Matrix*", "*OneFunction*" or
 410     "*ThreeFunctions*" according to whether one of these variables is
 411     positioned to "*True*". The control parameters of the adjoint numerical
 412     approximation, in the "*OneFunction*"case, can be given by a dictionary
 413     through the "*Parameters*" keyword. Potential entries of this dictionary
 414     are "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similar to the
 415     one of graphical interface). If the operator requires some complementary
 416     fixed arguments, they can be given through the variable "*ExtraArguments*"
 417     as a named parameters dictionary.
 418
 419 .. index:: single: ControlInput
 420 .. index:: single: setControlInput
 421
 422 **setControlInput** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
 423     This command allows to set the control vector :math:`\mathbf{u}`. Depending
 424     on the algorithm, it can be defined as a simple vector by "*Vector*", or as
 425     a vector list by "*VectorSerie*". If it is defined by a script in the
 426     "*Script*" keyword, the vector is of type "*Vector*" (by default) or
 427     "*VectorSerie*" according to whether one of these variables is positioned
 428     to "*True*". If there is a data file given by "*DataFile*" (selecting, in
 429     rows by default or in lines as chosen by "*ColMajor*", all the variables by
 430     default or those from the list "*ColNames*"), the vector is of type
 431     "*Vector*".
 432
 433 .. index:: single: EvolutionError
 434 .. index:: single: setEvolutionError
 435
 436 **setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 437     This command allows to set the matrix :math:`\mathbf{Q}` of evolution error
 438     covariance. The matrix may be completely defined by the "*Matrix*" keyword,
 439     or in a sparse way, by a diagonal matrix whose unique variance is given on
 440     the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix which one
 441     gives the vector of variances located on the diagonal by
 442     "*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
 443     matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
 444     "*DiagonalSparseMatrix*" according to whether one of these variables is
 445     positioned to "*True*".
 446
 447 .. index:: single: EvolutionModel
 448 .. index:: single: setEvolutionModel
 449 .. index:: single: ExtraArguments
 450
 451 **setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArguments, Stored*)
 452     This command allows to set the evolution operator :math:`M`, which
 453     describes an elementary evolution step. Its value is defined as an object
 454     of type function or of type "*Matrix*". For the function case, various
 455     functional forms may be used, as described in the
 456     :ref:`section_ref_operator_requirements`, and entered by "*OneFunction*" or
 457     "*ThreeFunctions*" keywords.  If it is defined by a script in the
 458     "*Script*" keyword, the operator is of type "*Matrix*", "*OneFunction*" or
 459     "*ThreeFunctions*" according to whether one of these variables is
 460     positioned to "*True*". The control parameters of the adjoint numerical
 461     approximation, in the "*OneFunction*"case, can be given by a dictionary
 462     through the "*Parameters*" keyword. Potential entries of this dictionary
 463     are "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similar to the
 464     one of graphical interface). If the operator requires some complementary
 465     fixed arguments in addition to the state :math:`\mathbf{x}`, they can be
 466     given through the variable "*ExtraArguments*" as a named parameters
 467     dictionary.
 468
 469 .. index:: single: Observation
 470 .. index:: single: setObservation
 471
 472 **setObservation** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
 473     This command allows to set the observation vector :math:`\mathbf{y}^o`.
 474     Depending on the algorithm, it can be defined as a simple vector by
 475     "*Vector*", or as a vector list by "*VectorSerie*". If it is defined by a
 476     script in the "*Script*" keyword, the vector is of type "*Vector*" (by
 477     default) or "*VectorSerie*" according to whether one of these variables is
 478     positioned to "*True*". If there is a data file given by "*DataFile*"
 479     (selecting, in rows by default or in lines as chosen by "*ColMajor*", all
 480     the variables by default or those from the list "*ColNames*"), the vector
 481     is of type "*Vector*".
 482
 483 .. index:: single: ObservationError
 484 .. index:: single: setObservationError
 485
 486 **setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 487     This command allows to set the matrix :math:`\mathbf{R}` of observation
 488     error covariance. The matrix may be completely defined by the "*Matrix*"
 489     keyword, or in a sparse way, by a diagonal matrix whose unique variance is
 490     given on the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix
 491     which one gives the vector of variances located on the diagonal by
 492     "*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
 493     matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
 494     "*DiagonalSparseMatrix*" according to whether one of these variables is
 495     positioned to "*True*".
 496
 497 .. index:: single: ObservationOperator
 498 .. index:: single: setObservationOperator
 499 .. index:: single: ExtraArguments
 500
 501 **setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, AppliedInXb, Parameters, Script, ExtraArguments, Stored*)
 502     This command allows to set the evolution operator :math:`H`, which
 503     transforms the input parameters :math:`\mathbf{x}` in results
 504     :math:`\mathbf{y}` that are compared to observations :math:`\mathbf{y}^o`.
 505     Its value is defined as an object of type function or of type "*Matrix*".
 506     For the function case, various functional forms may be used, as described
 507     in the :ref:`section_ref_operator_requirements`, and entered by
 508     "*OneFunction*" or "*ThreeFunctions*" keywords.  If it is defined by a
 509     script in the "*Script*" keyword, the operator is of type "*Matrix*",
 510     "*OneFunction*" or "*ThreeFunctions*" according to whether one of these
 511     variables is positioned to "*True*". When the :math:`H` operator evaluated
 512     in :math:`\mathbf{x}^b` is available, it can be given using "*AppliedInXb*"
 513     and will be considered as a vector. The control parameters of the adjoint
 514     numerical approximation, in the "*OneFunction*"case, can be given by a
 515     dictionary through the "*Parameters*" keyword. Potential entries of this
 516     dictionary are "*DifferentialIncrement*", "*CenteredFiniteDifference*"
 517     (similar to the one of graphical interface). If the operator requires some
 518     complementary fixed arguments in addition to the state :math:`\mathbf{x}`,
 519     they can be given through the variable "*ExtraArguments*" as a named
 520     parameters dictionary.
 521
 522 Setting the calculation, outputs, etc.
 523 ++++++++++++++++++++++++++++++++++++++
 524
 525 .. index:: single: AlgorithmParameters
 526 .. index:: single: setAlgorithmParameters
 527
 528 **setAlgorithmParameters** (*Algorithm, Parameters, Script*)
 529     This command allows to choose the calculation or the verification algorithm
 530     by the argument "*Algorithm*" in the form of an algorithm name (it is
 531     useful to refer to the :ref:`section_reference_assimilation` and to the
 532     :ref:`section_reference_checking`) and to define the calculation parameters
 533     by the argument "*Parameters*". In the case of a definition by "*Script*",
 534     the file must contain the two variables "*Algorithm*" and "*Parameters*"
 535     (or "*AlgorithmParameters*" equivalently).
 536
 537 .. index:: single: setName
 538
 539 **setName** (*String*)
 540     This command allows to set a short title for the calculation case.
 541
 542 .. index:: single: setDirectory
 543
 544 **setDirectory** (*String*)
 545     This command allows to set the execution standard directory.
 546
 547 .. index:: single: setDebug
 548
 549 **setDebug** ()
 550     This command enables the detailed information mode when running.
 551
 552 .. index:: single: setNoDebug
 553
 554 **setNoDebug** ()
 555     This command disables the detailed information mode when running.
 556
 557 .. index:: single: Observer
 558 .. index:: single: Observer Template
 559 .. index:: single: setObserver
 560 .. index:: single: setObserver Template
 561
 562 **setObserver** (*Variable, Template, String, Script, Info*)
 563     This command allows to set an *observer* on the current or final
 564     calculation variable. Reference should be made to the description of the
 565     ':ref:`section_ref_observers_requirements` for their list and content, and
 566     to the :ref:`section_reference` to know what are the observable quantities.
 567     One defines as "*String*" the *observer* body, using a string including if
 568     necessary line breaks. It is recommended to use the patterns available by
 569     the argument "*Template*". In the case of a definition as "*Script*", the
 570     file must contain only the body of the function, as  described in the
 571     :ref:`section_ref_observers_requirements`. The "*Info*" variable contains
 572     an information string or can be void.
 573
 574 .. index:: single: UserPostAnalysis
 575 .. index:: single: UserPostAnalysis Template
 576 .. index:: single: setUserPostAnalysis
 577 .. index:: single: setUserPostAnalysis Template
 578
 579 **setUserPostAnalysis** (*Template, String, Script*)
 580     This command allows to define the treatment of parameters or results after
 581     the calculation algorithm has been performed. Its value is defined either
 582     as a predefined pattern name, or as a script file name, or as a string.
 583     This allows to produce directly post-processing code in an ADAO case. It is
 584     possible to use patterns available by argument "*Template*" (which can be
 585     "*AnalysisPrinter*", "*AnalysisSaver*" and "*AnalysisPrinterAndSaver*"). In
 586     the case of a definition by "*Script*", the specified file must contain
 587     only the commands that could have been put after the execution of the
 588     calculation.  We refer to the description of
 589     :ref:`section_ref_userpostanalysis_requirements` for the list of templates
 590     and their format. Important note: this processing is only performed when
 591     the case is executed in TUI or exported to YACS.
 592
 593 Perform the calculation
 594 +++++++++++++++++++++++
 595
 596 .. index:: single: execute
 597 .. index:: single: Executor
 598 .. index:: single: SaveCaseInFile
 599 .. index:: single: nextStep
 600
 601 **execute** (*Executor, SaveCaseInFile, nextStep*)
 602     This command launches the complete calculation in the execution environment
 603     chosen by the keyword *Executor*, which is defined by default with respect
 604     of the launching environment. This environment can be the current Python
 605     interpreter, without interaction with YACS (using the value "*Python*"), or
 606     the one of YACS (using the value "*YACS*" [YACS]_). If a file is given in
 607     the keyword *SaveCaseInFile*, it will be used to save the associated
 608     version of commands file for the given execution environment. The boolean
 609     keyword "*nextStep*" indicates whether the run starts from the result of
 610     the previous run without storing it (value "*True*") or not (value
 611     "*False*", by default). During the execution, the usual outputs (standard
 612     and error) are the one of the chosen environment. If necessary (and if
 613     possible), the ADAO algorithms internal parallelism, the parallelism of
 614     YACS, and the internal parallelism of the simulation code(s) used, are
 615     available.
 616
 617 Get the calculation results separately
 618 ++++++++++++++++++++++++++++++++++++++
 619
 620 .. index:: single: get
 621
 622 **get** (*Concept*)
 623     This command explicitly extract the variables available at the output of
 624     calculation case for use in the rest of the scripting, such as
 625     visualization. Its argument the name of a variable "*Concept*" and returns
 626     back the quantity as a list (even if there is only one specimen) of this
 627     base variable. For a list of variables and use them, the user has to refer
 628     to the :ref:`subsection_r_o_v_Inventaire` and more generally to the
 629     :ref:`section_ref_output_variables` and to the individual documentations of
 630     the algorithms.
 631
 632 Saving, loading or converting calculation case commands
 633 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 634
 635 The saving or loading of a calculation case deals with quantities and actions
 636 that are linked by the previous commands, excepted case external operations
 637 (such as, for example, post-processing that can be developped after the
 638 calculation cas). The registered or loaded commands remain fully compatible
 639 with these Python external case operations.
 640
 641 .. index:: single: load
 642 .. index:: single: FileName
 643 .. index:: single: Content
 644 .. index:: single: Object
 645 .. index:: single: Formater
 646
 647 **load** (*FileName, Content, Object, Formater*)
 648     This command allows to read or load a calculation case, from a file named
 649     "*FileName*" or a content in memory by "*Content*" or "*Object*". The
 650     "*Formater*" keyword can indicate "*TUI*" for commands of textual
 651     application programming interface (default), and "*COM*" for commands of
 652     COMM type coming from EFICAS interface for ADAO.
 653
 654 .. index:: single: dump
 655
 656 **dump** (*FileName, Formater*)
 657     This command allows to save, in a file named "*FileName*", the commands of
 658     the current calculation case. The "*Formater*" keyword can indicate "*TUI*"
 659     for commands of textual application programming interface (default), and
 660     "*YACS*" for commands of type YACS.
 661
 662 .. index:: single: convert
 663 .. index:: single: FileNameFrom
 664 .. index:: single: ContentFrom
 665 .. index:: single: ObjectFrom
 666 .. index:: single: FormaterFrom
 667 .. index:: single: FileNameTo
 668 .. index:: single: FormaterTo
 669
 670 **convert** (*FileNameFrom, ContentFrom, ObjectFrom, FormaterFrom, FileNameTo, FormaterTo*)
 671     This command allows to convert directly from a known format to an another
 672     one the commands establishing the current calculation case. Some formats
 673     are only available as input or as output.
 674
 675 Obtain information on the case, the computation or the system
 676 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 677
 678 It's easy to obtain **aggregate information on the study case** as defined by
 679 the user, by using Python's "*print*" command directly on the case, at any
 680 stage during its completion. For example:
 681
 682 .. literalinclude:: scripts/tui_example_07.py
 683     :language: python
 684
 685 which result is here:
 686
 687 .. literalinclude:: scripts/tui_example_07.res
 688
 689 .. index:: single: callinfo
 690
 691 **Synthetic information on the number of calls to operator computations** can
 692 be dynamically obtained with the "**callinfo()**" command. These operator
 693 computations are those defined by the user in an ADAO case, for the observation
 694 and evolution operators. It is used after the calculation has been performed in
 695 the ADAO case, bearing in mind that the result of this command is simply empty
 696 when no calculation has been performed:
 697 ::
 698
 699     from adao import adaoBuilder
 700     case = adaoBuilder.New()
 701     ...
 702     case.execute()
 703     print(case.callinfo())
 704
 705 .. index:: single: sysinfo
 706
 707 Synthetic **system information** can be obtained with the "**sysinfo()**"
 708 command, present in every calculation case. It dynamically returns system
 709 information and details of Python modules useful for ADAO. It is used as
 710 follows:
 711 ::
 712
 713     from adao import adaoBuilder
 714     case = adaoBuilder.New()
 715     print(case.sysinfo())
 716
 717 .. _subsection_tui_advanced:
 718
 719 More advanced examples of ADAO TUI calculation case
 720 ---------------------------------------------------
 721
 722 We propose here more comprehensive examples of ADAO TUI calculation, by giving
 723 the purpose of the example and a set of commands that can achieve this goal.
 724
 725 Independent holding of the results of a calculation case
 726 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 727
 728 The objective is to perform in TUI the setting of data for an ADAO calculation
 729 case, its execution, and then the retrieving of the results to follow on a
 730 independent holding of these results (this last step not being described here,
 731 because it depends on the user).
 732
 733 The hypothesis of the user case are the following ones. It is assumed:
 734
 735 #. that we want to adjust 3 parameters ``alpha``, ``beta`` and ``gamma`` in a bounded domain,
 736 #. that we dispose of observations named ``observations``,
 737 #. 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,
 738 #. 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.
 739
 740 In order to try in a simple way this example of TUI calculation case, we set
 741 ourselves in a twin experiments case (for information, see the approach
 742 :ref:`section_methodology_twin`). For that, we choose for example the following
 743 entries, perfectly arbitrary, by building the observations by simulation. Then
 744 we solve the adjustment problem through the command set execution that follows.
 745 Finally, the whole problem is set and solved by the following script:
 746
 747 .. literalinclude:: scripts/tui_example_11.py
 748     :language: python
 749
 750 The command set execution gives the following results:
 751
 752 .. literalinclude:: scripts/tui_example_11.res
 753
 754 As it should be in twin experiments, when we trust mainly in observations, it
 755 is found that we get correctly the parameters that were used to artificially
 756 build the observations.
 757
 758 .. [HOMARD] For more information on HOMARD, see the *HOMARD module* and its integrated help available from the main menu *Help* of the SALOME platform.
 759
 760 .. [PARAVIS] For more information on PARAVIS, see the *PARAVIS module* and its integrated help available from the main menu *Help* of the SALOME platform.
 761
 762 .. [YACS] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform.