doc/en/tui.rst

   1 ..
   2    Copyright (C) 2008-2023 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 subparts 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: Background
 346 .. index:: single: setBackground
 347
 348 **setBackground** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
 349     This command allows to set the background :math:`\mathbf{x}^b`. Depending
 350     on the algorithm, it can be defined as a simple vector by "*Vector*", or as
 351     a vector list by "*VectorSerie*". If it is defined by a script in the
 352     "*Script*" keyword, the vector is of type "*Vector*" (by default) or
 353     "*VectorSerie*" according to whether one of these variables is positioned
 354     to "*True*". If there is a data file given by "*DataFile*" (selecting, in
 355     rows by default or in lines as chosen by "*ColMajor*", all the variables by
 356     default or those from the list "*ColNames*"), the vector is of type
 357     "*Vector*".
 358
 359 .. index:: single: BackgroundError
 360 .. index:: single: setBackgroundError
 361
 362 **setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 363     This command allows to set the matrix :math:`\mathbf{B}` of background
 364     error covariance. The matrix may be completely defined by the "*Matrix*"
 365     keyword, or in a sparse way, by a diagonal matrix whose unique variance is
 366     given on the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix
 367     which one gives the vector of variances located on the diagonal by
 368     "*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
 369     matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
 370     "*DiagonalSparseMatrix*" according to whether one of these variables is
 371     positioned to "*True*".
 372
 373 .. index:: single: CheckingPoint
 374 .. index:: single: setCheckingPoint
 375
 376 **setCheckingPoint** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
 377     This command allows to set a current point :math:`\mathbf{x}` used in a
 378     checking algorithm. Depending on the algorithm, it can be defined as a
 379     simple vector by "*Vector*", or as a vector list by "*VectorSerie*". If it
 380     is defined by a script in the "*Script*" keyword, the vector is of type
 381     "*Vector*" (by default) or "*VectorSerie*" according to whether one of
 382     these variables is positioned to "*True*". If there is a data file given by
 383     "*DataFile*" (selecting, in rows by default or in lines as chosen by
 384     "*ColMajor*", all the variables by default or those from the list
 385     "*ColNames*"), the vector is of type "*Vector*".
 386
 387 .. index:: single: ControlModel
 388 .. index:: single: setControlModel
 389 .. index:: single: ExtraArguments
 390
 391 **setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArguments, Stored*)
 392     This command allows to set the control operator :math:`O`, which represents
 393     an external linear input control of the evolution or observation operator.
 394     One can refer to the :ref:`section_ref_operator_control`. Its value is
 395     defined as an object of type function or of type "*Matrix*". For the
 396     function case, various functional forms may be used, as described in the
 397     :ref:`section_ref_operator_requirements`, and entered by "*OneFunction*" or
 398     "*ThreeFunctions*" keywords.  If it is defined by a script in the
 399     "*Script*" keyword, the operator is of type "*Matrix*", "*OneFunction*" or
 400     "*ThreeFunctions*" according to whether one of these variables is
 401     positioned to "*True*". The control parameters of the adjoint numerical
 402     approximation, in the "*OneFunction*"case, can be given by a dictionary
 403     through the "*Parameters*" keyword. Potential entries of this dictionary
 404     are "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similar to the
 405     one of graphical interface). If the operator requires some complementary
 406     fixed arguments, they can be given through the variable "*ExtraArguments*"
 407     as a named parameters dictionary.
 408
 409 .. index:: single: ControlInput
 410 .. index:: single: setControlInput
 411
 412 **setControlInput** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
 413     This command allows to set the control vector :math:`\mathbf{u}`. Depending
 414     on the algorithm, it can be defined as a simple vector by "*Vector*", or as
 415     a vector list by "*VectorSerie*". If it is defined by a script in the
 416     "*Script*" keyword, the vector is of type "*Vector*" (by default) or
 417     "*VectorSerie*" according to whether one of these variables is positioned
 418     to "*True*". If there is a data file given by "*DataFile*" (selecting, in
 419     rows by default or in lines as chosen by "*ColMajor*", all the variables by
 420     default or those from the list "*ColNames*"), the vector is of type
 421     "*Vector*".
 422
 423 .. index:: single: EvolutionError
 424 .. index:: single: setEvolutionError
 425
 426 **setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 427     This command allows to set the matrix :math:`\mathbf{Q}` of evolution error
 428     covariance. The matrix may be completely defined by the "*Matrix*" keyword,
 429     or in a sparse way, by a diagonal matrix whose unique variance is given on
 430     the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix which one
 431     gives the vector of variances located on the diagonal by
 432     "*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
 433     matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
 434     "*DiagonalSparseMatrix*" according to whether one of these variables is
 435     positioned to "*True*".
 436
 437 .. index:: single: EvolutionModel
 438 .. index:: single: setEvolutionModel
 439 .. index:: single: ExtraArguments
 440
 441 **setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArguments, Stored*)
 442     This command allows to set the evolution operator :math:`M`, which
 443     describes an elementary evolution step. Its value is defined as an object
 444     of type function or of type "*Matrix*". For the function case, various
 445     functional forms may be used, as described in the
 446     :ref:`section_ref_operator_requirements`, and entered by "*OneFunction*" or
 447     "*ThreeFunctions*" keywords.  If it is defined by a script in the
 448     "*Script*" keyword, the operator is of type "*Matrix*", "*OneFunction*" or
 449     "*ThreeFunctions*" according to whether one of these variables is
 450     positioned to "*True*". The control parameters of the adjoint numerical
 451     approximation, in the "*OneFunction*"case, can be given by a dictionary
 452     through the "*Parameters*" keyword. Potential entries of this dictionary
 453     are "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similar to the
 454     one of graphical interface). If the operator requires some complementary
 455     fixed arguments in addition to the state :math:`\mathbf{x}`, they can be
 456     given through the variable "*ExtraArguments*" as a named parameters
 457     dictionary.
 458
 459 .. index:: single: Observation
 460 .. index:: single: setObservation
 461
 462 **setObservation** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
 463     This command allows to set the observation vector :math:`\mathbf{y}^o`.
 464     Depending on the algorithm, it can be defined as a simple vector by
 465     "*Vector*", or as a vector list by "*VectorSerie*". If it is defined by a
 466     script in the "*Script*" keyword, the vector is of type "*Vector*" (by
 467     default) or "*VectorSerie*" according to whether one of these variables is
 468     positioned to "*True*". If there is a data file given by "*DataFile*"
 469     (selecting, in rows by default or in lines as chosen by "*ColMajor*", all
 470     the variables by default or those from the list "*ColNames*"), the vector
 471     is of type "*Vector*".
 472
 473 .. index:: single: ObservationError
 474 .. index:: single: setObservationError
 475
 476 **setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 477     This command allows to set the matrix :math:`\mathbf{R}` of observation
 478     error covariance. The matrix may be completely defined by the "*Matrix*"
 479     keyword, or in a sparse way, by a diagonal matrix whose unique variance is
 480     given on the diagonal by "*ScalarSparseMatrix*", or by a diagonal matrix
 481     which one gives the vector of variances located on the diagonal by
 482     "*DiagonalSparseMatrix*". If it is defined by a script in "*Script*", the
 483     matrix is of type "*Matrix*" (by default), "*ScalarSparseMatrix*" or
 484     "*DiagonalSparseMatrix*" according to whether one of these variables is
 485     positioned to "*True*".
 486
 487 .. index:: single: ObservationOperator
 488 .. index:: single: setObservationOperator
 489 .. index:: single: ExtraArguments
 490
 491 **setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, AppliedInXb, Parameters, Script, ExtraArguments, Stored*)
 492     This command allows to set the evolution operator :math:`H`, which
 493     transforms the input parameters :math:`\mathbf{x}` in results
 494     :math:`\mathbf{y}` that are compared to observations :math:`\mathbf{y}^o`.
 495     Its value is defined as an object of type function or of type "*Matrix*".
 496     For the function case, various functional forms may be used, as described
 497     in the :ref:`section_ref_operator_requirements`, and entered by
 498     "*OneFunction*" or "*ThreeFunctions*" keywords.  If it is defined by a
 499     script in the "*Script*" keyword, the operator is of type "*Matrix*",
 500     "*OneFunction*" or "*ThreeFunctions*" according to whether one of these
 501     variables is positioned to "*True*". When the :math:`H` operator evaluated
 502     in :math:`\mathbf{x}^b` is available, it can be given using "*AppliedInXb*"
 503     and will be considered as a vector. The control parameters of the adjoint
 504     numerical approximation, in the "*OneFunction*"case, can be given by a
 505     dictionary through the "*Parameters*" keyword. Potential entries of this
 506     dictionary are "*DifferentialIncrement*", "*CenteredFiniteDifference*"
 507     (similar to the one of graphical interface). If the operator requires some
 508     complementary fixed arguments in addition to the state :math:`\mathbf{x}`,
 509     they can be given through the variable "*ExtraArguments*" as a named
 510     parameters dictionary.
 511
 512 .. index:: single: set
 513
 514 **set** (*Concept,...*)
 515     This command allows to have an equivalent syntax for all the commands of
 516     these section. Its first argument is the name of the concept to be defined
 517     (for example "*Background*" or "*ObservationOperator*"), on which the
 518     following arguments, which are the same as in the individual previous
 519     commands, are applied. When using this command, it is required to name the
 520     arguments (for example "*Vector=...*").
 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 In addition, simple information about the case study as defined by the user can
 676 be obtained by using the Python "*print*" command directly on the case, at any
 677 stage during its design. For example:
 678
 679 .. literalinclude:: scripts/tui_example_07.py
 680     :language: python
 681
 682 which result is here:
 683
 684 .. literalinclude:: scripts/tui_example_07.res
 685
 686 .. _subsection_tui_advanced:
 687
 688 More advanced examples of ADAO TUI calculation case
 689 ---------------------------------------------------
 690
 691 We propose here more comprehensive examples of ADAO TUI calculation, by giving
 692 the purpose of the example and a set of commands that can achieve this goal.
 693
 694 Independent holding of the results of a calculation case
 695 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 696
 697 The objective is to perform in TUI the setting of data for an ADAO calculation
 698 case, its execution, and then the retrieving of the results to follow on a
 699 independent holding of these results (this last step not being described here,
 700 because it depends on the user).
 701
 702 The hypothesis of the user case are the following ones. It is assumed:
 703
 704 #. that we want to adjust 3 parameters ``alpha``, ``beta`` and ``gamma`` in a bounded domain,
 705 #. that we dispose of observations named ``observations``,
 706 #. 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,
 707 #. 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.
 708
 709 In order to try in a simple way this example of TUI calculation case, we set
 710 ourselves in a twin experiments case (for information, see the approach
 711 :ref:`section_methodology_twin`). For that, we choose for example the following
 712 entries, perfectly arbitrary, by building the observations by simulation. Then
 713 we solve the adjustment problem through the command set execution that follows.
 714 Finally, the whole problem is set and solved by the following script:
 715
 716 .. literalinclude:: scripts/tui_example_11.py
 717     :language: python
 718
 719 The command set execution gives the following results:
 720
 721 .. literalinclude:: scripts/tui_example_11.res
 722
 723 As it should be in twin experiments, when we trust mainly in observations, it
 724 is found that we get correctly the parameters that were used to artificially
 725 build the observations.
 726
 727 .. [HOMARD] For more information on HOMARD, see the *HOMARD module* and its integrated help available from the main menu *Help* of the SALOME platform.
 728
 729 .. [PARAVIS] For more information on PARAVIS, see the *PARAVIS module* and its integrated help available from the main menu *Help* of the SALOME platform.
 730
 731 .. [YACS] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform.