2 Copyright (C) 2008-2024 EDF R&D
4 This file is part of SALOME ADAO module.
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.
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.
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
20 See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
22 Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
24 .. index:: single: TUI
25 .. index:: single: API/TUI
26 .. index:: single: adaoBuilder
29 ================================================================================
30 **[DocR]** Textual User Interface for ADAO (TUI/API)
31 ================================================================================
33 .. |eficas_totui| image:: images/eficas_totui.png
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
51 .. _subsection_tui_creating:
53 Creation of ADAO TUI calculation case and examples
54 --------------------------------------------------
56 .. _subsection_tui_example:
58 A simple setup example of an ADAO TUI calculation case
59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
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
66 .. literalinclude:: scripts/tui_example_01.py
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:
73 .. literalinclude:: scripts/tui_example_01.res
75 Detailed setup of an ADAO TUI calculation case
76 +++++++++++++++++++++++++++++++++++++++++++++++
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.
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:
88 .. code-block:: python
91 from numpy import array
92 from adao import adaoBuilder
93 case = adaoBuilder.New()
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
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``):
111 .. code-block:: python
114 case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
116 case.set( 'Background', Vector=[0, 1, 2] )
117 case.set( 'BackgroundError', ScalarSparseMatrix=1.0 )
119 case.set( 'Observation', Vector=array([0.5, 1.5, 2.5]) )
120 case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
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.
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:
134 .. code-block:: python
137 case.set( 'ObservationOperator', Matrix = "1 0 0;0 2 0;0 0 3")
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
151 .. code-block:: python
156 "Simulation function H to perform Y=H(X)"
159 __H = numpy.diag([1.,2.,3.])
160 return numpy.dot(__H, __x)
162 case.set( 'ObservationOperator',
163 OneFunction = simulation,
164 Parameters = {"DifferentialIncrement":0.01},
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
176 .. code-block:: python
179 case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
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:
186 .. code-block:: python
192 At the end, we get a very compact script previously proposed in
193 :ref:`subsection_tui_example`.
195 Using more complex calculation data or information
196 ++++++++++++++++++++++++++++++++++++++++++++++++++
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.
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:
209 .. code-block:: python
212 from observations import someTable
213 case.set( 'Observation', Vector=someTable )
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.
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
225 Obtain and use the results of calculation in a richer way
226 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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.
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.
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:
240 .. code-block:: python
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]))
251 These lines can be very simply added to the initial example of ADAO TUI
252 calculation case given in :ref:`subsection_tui_example`.
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.
259 .. _subsection_tui_commands:
261 Set of available commands in text user interface TUI
262 ----------------------------------------------------
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.
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
281 Equivalent syntax calls for commands
282 ++++++++++++++++++++++++++++++++++++
284 The definition of data during the ADAO TUI calculation case creation supports
285 **two completely equivalent syntaxes**. One can:
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
292 To illustrate this equivalence, we take the example of two commands that lead
295 case.set( 'Background', Vector=[0, 1, 2] )
299 case.setBackground( Vector=[0, 1, 2] )
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.
305 Creating a calculation case in TUI text interface
306 +++++++++++++++++++++++++++++++++++++++++++++++++
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):
313 .. code-block:: python
316 from numpy import array
317 from adao import adaoBuilder
318 case = adaoBuilder.New()
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.
325 Defining the calculation data
326 +++++++++++++++++++++++++++++
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.
335 .. index:: single: Stored
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.
343 The available commands are:
345 .. index:: single: set
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=...*").
355 .. index:: single: Background
356 .. index:: single: setBackground
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
369 .. index:: single: BackgroundError
370 .. index:: single: setBackgroundError
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*".
383 .. index:: single: CheckingPoint
384 .. index:: single: setCheckingPoint
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*".
397 .. index:: single: ControlModel
398 .. index:: single: setControlModel
399 .. index:: single: ExtraArguments
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.
419 .. index:: single: ControlInput
420 .. index:: single: setControlInput
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
433 .. index:: single: EvolutionError
434 .. index:: single: setEvolutionError
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*".
447 .. index:: single: EvolutionModel
448 .. index:: single: setEvolutionModel
449 .. index:: single: ExtraArguments
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*",
464 "*EnableWiseParallelism*", "*NumberOfProcesses*" (similar to the one of
465 graphical interface). If the operator requires some complementary fixed
466 arguments in addition to the state :math:`\mathbf{x}`, they can be given
467 through the variable "*ExtraArguments*" as a named parameters dictionary.
469 .. index:: single: Observation
470 .. index:: single: setObservation
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*".
483 .. index:: single: ObservationError
484 .. index:: single: setObservationError
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*".
497 .. index:: single: ObservationOperator
498 .. index:: single: setObservationOperator
499 .. index:: single: ExtraArguments
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 "*EnableWiseParallelism*", "*NumberOfProcesses*" (similar to the one of
518 graphical interface). If the operator requires some complementary fixed
519 arguments in addition to the state :math:`\mathbf{x}`, they can be given
520 through the variable "*ExtraArguments*" as a named parameters dictionary.
522 Setting the calculation, outputs, etc.
523 ++++++++++++++++++++++++++++++++++++++
525 .. index:: single: AlgorithmParameters
526 .. index:: single: setAlgorithmParameters
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).
537 .. index:: single: setName
539 **setName** (*String*)
540 This command allows to set a short title for the calculation case.
542 .. index:: single: setDirectory
544 **setDirectory** (*String*)
545 This command allows to set the execution standard directory.
547 .. index:: single: setDebug
550 This command enables the detailed information mode when running.
552 .. index:: single: setNoDebug
555 This command disables the detailed information mode when running.
557 .. index:: single: Observer
558 .. index:: single: Observer Template
559 .. index:: single: setObserver
560 .. index:: single: setObserver Template
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.
574 .. index:: single: UserPostAnalysis
575 .. index:: single: UserPostAnalysis Template
576 .. index:: single: setUserPostAnalysis
577 .. index:: single: setUserPostAnalysis Template
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.
593 Perform the calculation
594 +++++++++++++++++++++++
596 .. index:: single: execute
597 .. index:: single: Executor
598 .. index:: single: SaveCaseInFile
599 .. index:: single: nextStep
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
617 Get the calculation results separately
618 ++++++++++++++++++++++++++++++++++++++
620 .. index:: single: get
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
632 Saving, loading or converting calculation case commands
633 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
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.
641 .. index:: single: load
642 .. index:: single: FileName
643 .. index:: single: Content
644 .. index:: single: Object
645 .. index:: single: Formater
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.
654 .. index:: single: dump
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.
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
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.
675 Obtain information on the case, the computation or the system
676 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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:
682 .. literalinclude:: scripts/tui_example_07.py
685 which result is here:
687 .. literalinclude:: scripts/tui_example_07.res
689 .. index:: single: callinfo
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:
699 from adao import adaoBuilder
700 case = adaoBuilder.New()
703 print(case.callinfo())
705 .. index:: single: sysinfo
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
713 from adao import adaoBuilder
714 case = adaoBuilder.New()
715 print(case.sysinfo())
717 .. _subsection_tui_advanced:
719 More advanced examples of ADAO TUI calculation case
720 ---------------------------------------------------
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.
725 Independent holding of the results of a calculation case
726 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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).
733 The hypothesis of the user case are the following ones. It is assumed:
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.
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:
747 .. literalinclude:: scripts/tui_example_11.py
750 The command set execution gives the following results:
752 .. literalinclude:: scripts/tui_example_11.res
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.
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.
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.
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.