3 ================================================================================
4 Reference description of the ADAO commands and keywords
5 ================================================================================
7 This section presents the reference description of the ADAO commands and
8 keywords available through the GUI or through scripts.
10 Each command or keyword to be defined through the ADAO GUI has some properties.
11 The first property is to be *required*, *optional* or only factual, describing a
12 type of input. The second property is to be an "open" variable with a fixed type
13 but with any value allowed by the type, or a "restricted" variable, limited to
14 some specified values. The EFICAS editor GUI having build-in validating
15 capacities, the properties of the commands or keywords given through this GUI
16 are automatically correct.
18 The mathematical notations used afterward are explained in the section
19 :ref:`section_theory`.
21 Examples of using these commands are available in the section
22 :ref:`section_examples` and in example files installed with ADAO module.
24 List of possible input types
25 ----------------------------
27 .. index:: single: Dict
28 .. index:: single: Function
29 .. index:: single: Matrix
30 .. index:: single: String
31 .. index:: single: Script
32 .. index:: single: Vector
34 Each ADAO variable has a pseudo-type to help filling it and validation. The
35 different pseudo-types are:
38 This indicates a variable that has to be filled by a dictionary, usually
42 This indicates a variable that has to be filled by a function, usually given
43 as a script or a component method.
46 This indicates a variable that has to be filled by a matrix, usually given
47 either as a string or as a script.
50 This indicates a string giving a literal representation of a matrix, a
51 vector or a vector serie, such as "1 2 ; 3 4" for a square 2x2 matrix.
54 This indicates a script given as an external file. It can be described by a
55 full absolute path name or only by the file name without path.
58 This indicates a variable that has to be filled by a vector, usually given
59 either as a string or as a script.
61 **VectorSerie** This indicates a variable that has to be filled by a list of
62 vectors, usually given either as a string or as a script.
64 When a command or keyword can be filled by a script file name, the script has to
65 contain a variable or a method that has the same name as the one to be filled.
66 In other words, when importing the script in a YACS Python node, it must create
67 a variable of the good name in the current namespace.
69 List of commands and keywords for an ADAO calculation case
70 ----------------------------------------------------------
72 .. index:: single: ASSIMILATION_STUDY
73 .. index:: single: Algorithm
74 .. index:: single: AlgorithmParameters
75 .. index:: single: Background
76 .. index:: single: BackgroundError
77 .. index:: single: ControlInput
78 .. index:: single: Debug
79 .. index:: single: EvolutionError
80 .. index:: single: EvolutionModel
81 .. index:: single: InputVariables
82 .. index:: single: Observation
83 .. index:: single: ObservationError
84 .. index:: single: ObservationOperator
85 .. index:: single: Observers
86 .. index:: single: OutputVariables
87 .. index:: single: Study_name
88 .. index:: single: Study_repertory
89 .. index:: single: UserDataInit
90 .. index:: single: UserPostAnalysis
92 The first set of commands is related to the description of a calculation case,
93 that is a *Data Assimilation* procedure or an *Optimization* procedure. The
94 terms are ordered in alphabetical order, except the first, which describes
95 choice between calculation or checking. The different commands are the
98 **ASSIMILATION_STUDY**
99 *Required command*. This is the general command describing the data
100 assimilation or optimization case. It hierarchically contains all the other
104 *Required command*. This is a string to indicate the data assimilation or
105 optimization algorithm chosen. The choices are limited and available through
106 the GUI. There exists for example "3DVAR", "Blue"... See below the list of
107 algorithms and associated parameters in the following subsection `Options
108 and required commands for algorithms`_.
110 **AlgorithmParameters**
111 *Optional command*. This command allows to add some optional parameters to
112 control the data assimilation or optimization algorithm. It is defined as a
113 "*Dict*" type object, that is, given as a script. See below the list of
114 algorithms and associated parameters in the following subsection `Options
115 and required commands for algorithms`_.
118 *Required command*. This indicates the background or initial vector used,
119 previously noted as :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type
120 object, that is, given either as a string or as a script.
123 *Required command*. This indicates the background error covariance matrix,
124 previously noted as :math:`\mathbf{B}`. It is defined as a "*Matrix*" type
125 object, that is, given either as a string or as a script.
128 *Optional command*. This indicates the control vector used to force the
129 evolution model at each step, usually noted as :math:`\mathbf{U}`. It is
130 defined as a "*Vector*" or a *VectorSerie* type object, that is, given
131 either as a string or as a script. When there is no control, it has to be a
135 *Required command*. This define the level of trace and intermediary debug
136 information. The choices are limited between 0 (for False) and 1 (for
140 *Optional command*. This indicates the evolution error covariance matrix,
141 usually noted as :math:`\mathbf{Q}`. It is defined as a "*Matrix*" type
142 object, that is, given either as a string or as a script.
145 *Optional command*. This indicates the evolution model operator, usually
146 noted :math:`M`, which describes a step of evolution. It is defined as a
147 "*Function*" type object, that is, given as a script. Different functional
148 forms can be used, as described in the following subsection `Requirements
149 for functions describing an operator`_. If there is some control :math:`U`,
150 the operator has to be applied to a pair :math:`(X,U)`.
153 *Optional command*. This command allows to indicates the name and size of
154 physical variables that are bundled together in the control vector. This
155 information is dedicated to data processed inside an algorithm.
158 *Required command*. This indicates the observation vector used for data
159 assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
160 is defined as a "*Vector*" or a *VectorSerie* type object, that is, given
161 either as a string or as a script.
164 *Required command*. This indicates the observation error covariance matrix,
165 previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
166 object, that is, given either as a string or as a script.
168 **ObservationOperator**
169 *Required command*. This indicates the observation operator, previously
170 noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
171 results :math:`\mathbf{y}` to be compared to observations
172 :math:`\mathbf{y}^o`. It is defined as a "*Function*" type object, that is,
173 given as a script. Different functional forms can be used, as described in
174 the following subsection `Requirements for functions describing an
178 *Optional command*. This command allows to set internal observers, that are
179 functions linked with a particular variable, which will be executed each
180 time this variable is modified. It is a convenient way to monitor interest
181 variables during the data assimilation or optimization process, by printing
185 *Optional command*. This command allows to indicates the name and size of
186 physical variables that are bundled together in the output observation
187 vector. This information is dedicated to data processed inside an algorithm.
190 *Required command*. This is an open string to describe the study by a name
194 *Optional command*. If available, this repertory is used to find all the
195 script files that can be used to define some other commands by scripts.
198 *Optional command*. This commands allows to initialize some parameters or
199 data automatically before data assimilation algorithm processing.
202 *Optional command*. This commands allows to process some parameters or data
203 automatically after data assimilation algorithm processing. It is defined as
204 a script or a string, allowing to put post-processing code directly inside
207 List of commands and keywords for an ADAO checking case
208 -------------------------------------------------------
210 .. index:: single: CHECKING_STUDY
211 .. index:: single: Algorithm
212 .. index:: single: AlgorithmParameters
213 .. index:: single: CheckingPoint
214 .. index:: single: Debug
215 .. index:: single: ObservationOperator
216 .. index:: single: Study_name
217 .. index:: single: Study_repertory
218 .. index:: single: UserDataInit
220 The second set of commands is related to the description of a checking case,
221 that is a procedure to check required properties on information somewhere else
222 by a calculation case. The terms are ordered in alphabetical order, except the
223 first, which describes choice between calculation or checking. The different
224 commands are the following:
227 *Required command*. This is the general command describing the checking
228 case. It hierarchically contains all the other commands.
231 *Required command*. This is a string to indicate the data assimilation or
232 optimization algorithm chosen. The choices are limited and available through
233 the GUI. There exists for example "3DVAR", "Blue"... See below the list of
234 algorithms and associated parameters in the following subsection `Options
235 and required commands for algorithms`_.
237 **AlgorithmParameters**
238 *Optional command*. This command allows to add some optional parameters to
239 control the data assimilation or optimization algorithm. It is defined as a
240 "*Dict*" type object, that is, given as a script. See below the list of
241 algorithms and associated parameters in the following subsection `Options
242 and required commands for algorithms`_.
245 *Required command*. This indicates the vector used,
246 previously noted as :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type
247 object, that is, given either as a string or as a script.
250 *Required command*. This define the level of trace and intermediary debug
251 information. The choices are limited between 0 (for False) and 1 (for
254 **ObservationOperator**
255 *Required command*. This indicates the observation operator, previously
256 noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
257 results :math:`\mathbf{y}` to be compared to observations
258 :math:`\mathbf{y}^o`. It is defined as a "*Function*" type object, that is,
259 given as a script. Different functional forms can be used, as described in
260 the following subsection `Requirements for functions describing an
264 *Required command*. This is an open string to describe the study by a name
268 *Optional command*. If available, this repertory is used to find all the
269 script files that can be used to define some other commands by scripts.
272 *Optional command*. This commands allows to initialize some parameters or
273 data automatically before data assimilation algorithm processing.
275 Options and required commands for algorithms
276 --------------------------------------------
278 .. index:: single: 3DVAR
279 .. index:: single: Blue
280 .. index:: single: EnsembleBlue
281 .. index:: single: KalmanFilter
282 .. index:: single: ExtendedKalmanFilter
283 .. index:: single: LinearLeastSquares
284 .. index:: single: NonLinearLeastSquares
285 .. index:: single: ParticleSwarmOptimization
286 .. index:: single: QuantileRegression
288 .. index:: single: AlgorithmParameters
289 .. index:: single: Bounds
290 .. index:: single: CostDecrementTolerance
291 .. index:: single: GradientNormTolerance
292 .. index:: single: GroupRecallRate
293 .. index:: single: MaximumNumberOfSteps
294 .. index:: single: Minimizer
295 .. index:: single: NumberOfInsects
296 .. index:: single: ProjectedGradientTolerance
297 .. index:: single: QualityCriterion
298 .. index:: single: Quantile
299 .. index:: single: SetSeed
300 .. index:: single: StoreInternalVariables
301 .. index:: single: StoreSupplementaryCalculations
302 .. index:: single: SwarmVelocity
304 Each algorithm can be controlled using some generic or specific options given
305 through the "*AlgorithmParameters*" optional command, as follows for example::
307 AlgorithmParameters = {
308 "Minimizer" : "LBFGSB",
309 "MaximumNumberOfSteps" : 25,
310 "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"],
313 This section describes the available options algorithm by algorithm. If an
314 option is specified for an algorithm that doesn't support it, the option is
315 simply left unused. The meaning of the acronyms or particular names can be found
316 in the :ref:`genindex` or the :ref:`section_glossary`. In addition, for each
317 algorithm, the required commands are given, being described in `List of commands
318 and keywords for an ADAO calculation case`_.
323 *"Background", "BackgroundError",
324 "Observation", "ObservationError",
325 "ObservationOperator"*
327 StoreSupplementaryCalculations
328 This list indicates the names of the supplementary variables that can be
329 available at the end of the algorithm. It involves potentially costly
330 calculations. The default is a void list, none of these variables being
331 calculated and stored by default. The possible names are in the following
332 list: ["APosterioriCovariance", "BMA", "OMA", "OMB", "Innovation",
333 "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"].
335 **"LinearLeastSquares"**
338 *"Observation", "ObservationError",
339 "ObservationOperator"*
341 StoreSupplementaryCalculations
342 This list indicates the names of the supplementary variables that can be
343 available at the end of the algorithm. It involves potentially costly
344 calculations. The default is a void list, none of these variables being
345 calculated and stored by default. The possible names are in the following
351 *"Background", "BackgroundError",
352 "Observation", "ObservationError",
353 "ObservationOperator"*
356 This key allows to choose the optimization minimizer. The default choice
357 is "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
358 minimizer, see [Byrd95]_ and [Zhu97]_), "TNC" (nonlinear constrained
359 minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" (nonlinear
360 unconstrained minimizer), "NCG" (Newton CG minimizer).
363 This key allows to define upper and lower bounds for every control
364 variable being optimized. Bounds can be given by a list of list of pairs
365 of lower/upper bounds for each variable, with possibly ``None`` every time
366 there is no bound. The bounds can always be specified, but they are taken
367 into account only by the constrained minimizers.
370 This key indicates the maximum number of iterations allowed for iterative
371 optimization. The default is 15000, which is very similar to no limit on
372 iterations. It is then recommended to adapt this parameter to the needs on
373 real problems. For some minimizers, the effective stopping step can be
374 slightly different due to algorithm internal control requirements.
376 CostDecrementTolerance
377 This key indicates a limit value, leading to stop successfully the
378 iterative optimization process when the cost function decreases less than
379 this tolerance at the last step. The default is 1.e-7, and it is
380 recommended to adapt it to the needs on real problems.
382 ProjectedGradientTolerance
383 This key indicates a limit value, leading to stop successfully the iterative
384 optimization process when all the components of the projected gradient are
385 under this limit. It is only used for constrained minimizers. The default is
386 -1, that is the internal default of each minimizer (generally 1.e-5), and it
387 is not recommended to change it.
389 GradientNormTolerance
390 This key indicates a limit value, leading to stop successfully the
391 iterative optimization process when the norm of the gradient is under this
392 limit. It is only used for non-constrained minimizers. The default is
393 1.e-5 and it is not recommended to change it.
395 StoreInternalVariables
396 This boolean key allows to store default internal variables, mainly the
397 current state during iterative optimization process. Be careful, this can be
398 a numerically costly choice in certain calculation cases. The default is
401 StoreSupplementaryCalculations
402 This list indicates the names of the supplementary variables that can be
403 available at the end of the algorithm. It involves potentially costly
404 calculations. The default is a void list, none of these variables being
405 calculated and stored by default. The possible names are in the following
406 list: ["APosterioriCovariance", "BMA", "OMA", "OMB", "Innovation",
407 "SigmaObs2", "MahalanobisConsistency"].
409 **"NonLinearLeastSquares"**
413 "Observation", "ObservationError",
414 "ObservationOperator"*
417 This key allows to choose the optimization minimizer. The default choice
418 is "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
419 minimizer, see [Byrd95]_ and [Zhu97]_), "TNC" (nonlinear constrained
420 minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" (nonlinear
421 unconstrained minimizer), "NCG" (Newton CG minimizer).
424 This key allows to define upper and lower bounds for every control
425 variable being optimized. Bounds can be given by a list of list of pairs
426 of lower/upper bounds for each variable, with possibly ``None`` every time
427 there is no bound. The bounds can always be specified, but they are taken
428 into account only by the constrained minimizers.
431 This key indicates the maximum number of iterations allowed for iterative
432 optimization. The default is 15000, which is very similar to no limit on
433 iterations. It is then recommended to adapt this parameter to the needs on
434 real problems. For some minimizers, the effective stopping step can be
435 slightly different due to algorithm internal control requirements.
437 CostDecrementTolerance
438 This key indicates a limit value, leading to stop successfully the
439 iterative optimization process when the cost function decreases less than
440 this tolerance at the last step. The default is 1.e-7, and it is
441 recommended to adapt it to the needs on real problems.
443 ProjectedGradientTolerance
444 This key indicates a limit value, leading to stop successfully the iterative
445 optimization process when all the components of the projected gradient are
446 under this limit. It is only used for constrained minimizers. The default is
447 -1, that is the internal default of each minimizer (generally 1.e-5), and it
448 is not recommended to change it.
450 GradientNormTolerance
451 This key indicates a limit value, leading to stop successfully the
452 iterative optimization process when the norm of the gradient is under this
453 limit. It is only used for non-constrained minimizers. The default is
454 1.e-5 and it is not recommended to change it.
456 StoreInternalVariables
457 This boolean key allows to store default internal variables, mainly the
458 current state during iterative optimization process. Be careful, this can be
459 a numerically costly choice in certain calculation cases. The default is
462 StoreSupplementaryCalculations
463 This list indicates the names of the supplementary variables that can be
464 available at the end of the algorithm. It involves potentially costly
465 calculations. The default is a void list, none of these variables being
466 calculated and stored by default. The possible names are in the following
467 list: ["BMA", "OMA", "OMB", "Innovation"].
472 *"Background", "BackgroundError",
473 "Observation", "ObservationError",
474 "ObservationOperator"*
477 This key allow to give an integer in order to fix the seed of the random
478 generator used to generate the ensemble. A convenient value is for example
479 1000. By default, the seed is left uninitialized, and so use the default
480 initialization from the computer.
485 *"Background", "BackgroundError",
486 "Observation", "ObservationError",
487 "ObservationOperator",
488 "EvolutionModel", "EvolutionError"*
491 This key allows to choose the type of estimation to be performed. It can be
492 either state-estimation, named "State", or parameter-estimation, named
493 "Parameters". The default choice is "Parameters".
495 StoreSupplementaryCalculations
496 This list indicates the names of the supplementary variables that can be
497 available at the end of the algorithm. It involves potentially costly
498 calculations. The default is a void list, none of these variables being
499 calculated and stored by default. The possible names are in the following
500 list: ["APosterioriCovariance", "CostFunctionJ", "Innovation"].
502 **"ExtendedKalmanFilter"**
505 *"Background", "BackgroundError",
506 "Observation", "ObservationError",
507 "ObservationOperator",
508 "EvolutionModel", "EvolutionError",
512 This key allows to choose the type of estimation to be performed. It can be
513 either state-estimation, named "State", or parameter-estimation, named
514 "Parameters". The default choice is "Parameters".
516 StoreSupplementaryCalculations
517 This list indicates the names of the supplementary variables that can be
518 available at the end of the algorithm. It involves potentially costly
519 calculations. The default is a void list, none of these variables being
520 calculated and stored by default. The possible names are in the following
521 list: ["APosterioriCovariance", "CostFunctionJ", "Innovation"].
523 **"ParticleSwarmOptimization"**
526 *"Background", "BackgroundError",
527 "Observation", "ObservationError",
528 "ObservationOperator"*
531 This key indicates the maximum number of iterations allowed for iterative
532 optimization. The default is 50, which is an arbitrary limit. It is then
533 recommended to adapt this parameter to the needs on real problems.
536 This key indicates the number of insects or particles in the swarm. The
537 default is 100, which is a usual default for this algorithm.
540 This key indicates the part of the insect velocity which is imposed by the
541 swarm. It is a positive floating point value. The default value is 1.
544 This key indicates the recall rate at the best swarm insect. It is a
545 floating point value between 0 and 1. The default value is 0.5.
548 This key indicates the quality criterion, minimized to find the optimal
549 state estimate. The default is the usual data assimilation criterion named
550 "DA", the augmented ponderated least squares. The possible criteria has to
551 be in the following list, where the equivalent names are indicated by "=":
552 ["AugmentedPonderatedLeastSquares"="APLS"="DA",
553 "PonderatedLeastSquares"="PLS", "LeastSquares"="LS"="L2",
554 "AbsoluteValue"="L1", "MaximumError"="ME"]
557 This key allow to give an integer in order to fix the seed of the random
558 generator used to generate the ensemble. A convenient value is for example
559 1000. By default, the seed is left uninitialized, and so use the default
560 initialization from the computer.
562 StoreInternalVariables
563 This boolean key allows to store default internal variables, mainly the
564 current state during iterative optimization process. Be careful, this can be
565 a numerically costly choice in certain calculation cases. The default is
568 StoreSupplementaryCalculations
569 This list indicates the names of the supplementary variables that can be
570 available at the end of the algorithm. It involves potentially costly
571 calculations. The default is a void list, none of these variables being
572 calculated and stored by default. The possible names are in the following
573 list: ["BMA", "OMA", "OMB", "Innovation"].
575 **"QuantileRegression"**
580 "ObservationOperator"*
583 This key allows to define the real value of the desired quantile, between
584 0 and 1. The default is 0.5, corresponding to the median.
587 This key allows to choose the optimization minimizer. The default choice
588 and only available choice is "MMQR" (Majorize-Minimize for Quantile
592 This key indicates the maximum number of iterations allowed for iterative
593 optimization. The default is 15000, which is very similar to no limit on
594 iterations. It is then recommended to adapt this parameter to the needs on
597 CostDecrementTolerance
598 This key indicates a limit value, leading to stop successfully the
599 iterative optimization process when the cost function or the surrogate
600 decreases less than this tolerance at the last step. The default is 1.e-6,
601 and it is recommended to adapt it to the needs on real problems.
603 StoreInternalVariables
604 This boolean key allows to store default internal variables, mainly the
605 current state during iterative optimization process. Be careful, this can be
606 a numerically costly choice in certain calculation cases. The default is
609 StoreSupplementaryCalculations
610 This list indicates the names of the supplementary variables that can be
611 available at the end of the algorithm. It involves potentially costly
612 calculations. The default is a void list, none of these variables being
613 calculated and stored by default. The possible names are in the following
614 list: ["BMA", "OMA", "OMB", "Innovation"].
616 Requirements for functions describing an operator
617 -------------------------------------------------
619 The operators for observation and evolution are required to implement the data
620 assimilation or optimization procedures. They include the physical simulation
621 numerical simulations, but also the filtering and restriction to compare the
622 simulation to observation. The evolution operator is considered here in its
623 incremental form, representing the transition between two successive states, and
624 is then similar to the observation operator.
626 Schematically, an operator has to give a output solution given the input
627 parameters. Part of the input parameters can be modified during the optimization
628 procedure. So the mathematical representation of such a process is a function.
629 It was briefly described in the section :ref:`section_theory` and is generalized
630 here by the relation:
632 .. math:: \mathbf{y} = H( \mathbf{x} )
634 between the pseudo-observations :math:`\mathbf{y}` and the parameters
635 :math:`\mathbf{x}` using the observation operator :math:`H`. The same functional
636 representation can be used for the linear tangent model :math:`\mathbf{H}` of
637 :math:`H` and its adjoint :math:`\mathbf{H}^*`, also required by some data
638 assimilation or optimization algorithms.
640 Then, **to describe completely an operator, the user has only to provide a
641 function that fully and only realize the functional operation**.
643 This function is usually given as a script that can be executed in a YACS node.
644 This script can without difference launch external codes or use internal SALOME
645 calls and methods. If the algorithm requires the 3 aspects of the operator
646 (direct form, tangent form and adjoint form), the user has to give the 3
647 functions or to approximate them.
649 There are 3 practical methods for the user to provide the operator functional
652 First functional form: using "*ScriptWithOneFunction*"
653 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
655 The first one consist in providing only one potentially non-linear function, and
656 to approximate the tangent and the adjoint operators. This is done by using the
657 keyword "*ScriptWithOneFunction*" for the description of the chosen operator in
658 the ADAO GUI. The user have to provide the function in a script, with a
659 mandatory name "*DirectOperator*". For example, the script can follow the
662 def DirectOperator( X ):
663 """ Direct non-linear simulation operator """
669 In this case, the user can also provide a value for the differential increment,
670 using through the GUI the keyword "*DifferentialIncrement*", which has a default
671 value of 1%. This coefficient will be used in the finite difference
672 approximation to build the tangent and adjoint operators.
674 This first operator definition allow easily to test the functional form before
675 its use in an ADAO case, reducing the complexity of implementation.
677 Second functional form: using "*ScriptWithFunctions*"
678 +++++++++++++++++++++++++++++++++++++++++++++++++++++
680 The second one consist in providing directly the three associated operators
681 :math:`H`, :math:`\mathbf{H}` and :math:`\mathbf{H}^*`. This is done by using
682 the keyword "*ScriptWithFunctions*" for the description of the chosen operator
683 in the ADAO GUI. The user have to provide three functions in one script, with
684 three mandatory names "*DirectOperator*", "*TangentOperator*" and
685 "*AdjointOperator*". For example, the script can follow the template::
687 def DirectOperator( X ):
688 """ Direct non-linear simulation operator """
692 return something like Y
694 def TangentOperator( (X, dX) ):
695 """ Tangent linear operator, around X, applied to dX """
699 return something like Y
701 def AdjointOperator( (X, Y) ):
702 """ Adjoint operator, around X, applied to Y """
706 return something like X
708 Another time, this second perator definition allow easily to test the functional
709 forms before their use in an ADAO case, greatly reducing the complexity of
712 Third functional form: using "*ScriptWithSwitch*"
713 +++++++++++++++++++++++++++++++++++++++++++++++++
715 This third form give more possibilities to control the execution of the three
716 functions representing the operator, allowing advanced usage and control over
717 each execution of the simulation code. This is done by using the keyword
718 "*ScriptWithSwitch*" for the description of the chosen operator in the ADAO GUI.
719 The user have to provide a switch in one script to control the execution of the
720 direct, tangent and adjoint forms of its simulation code. The user can then, for
721 example, use other approximations for the tangent and adjoint codes, or
722 introduce more complexity in the argument treatment of the functions. But it
723 will be far more complicated to implement and debug.
725 **It is recommended not to use this third functional form without a solid
726 numerical or physical reason.**
728 If, however, you want to use this third form, we recommend using the following
729 template for the switch. It requires an external script or code named
730 "*Physical_simulation_functions.py*", containing three functions named
731 "*DirectOperator*", "*TangentOperator*" and "*AdjointOperator*" as previously.
732 Here is the switch template::
734 import Physical_simulation_functions
735 import numpy, logging
738 for param in computation["specificParameters"]:
739 if param["name"] == "method":
740 method = param["value"]
741 if method not in ["Direct", "Tangent", "Adjoint"]:
742 raise ValueError("No valid computation method is given")
743 logging.info("Found method is \'%s\'"%method)
745 logging.info("Loading operator functions")
746 FunctionH = Physical_simulation_functions.DirectOperator
747 TangentH = Physical_simulation_functions.TangentOperator
748 AdjointH = Physical_simulation_functions.AdjointOperator
750 logging.info("Executing the possible computations")
752 if method == "Direct":
753 logging.info("Direct computation")
754 Xcurrent = computation["inputValues"][0][0][0]
755 data = FunctionH(numpy.matrix( Xcurrent ).T)
756 if method == "Tangent":
757 logging.info("Tangent computation")
758 Xcurrent = computation["inputValues"][0][0][0]
759 dXcurrent = computation["inputValues"][0][0][1]
760 data = TangentH(numpy.matrix(Xcurrent).T, numpy.matrix(dXcurrent).T)
761 if method == "Adjoint":
762 logging.info("Adjoint computation")
763 Xcurrent = computation["inputValues"][0][0][0]
764 Ycurrent = computation["inputValues"][0][0][1]
765 data = AdjointH((numpy.matrix(Xcurrent).T, numpy.matrix(Ycurrent).T))
767 logging.info("Formatting the output")
768 it = numpy.ravel(data)
769 outputValues = [[[[]]]]
771 outputValues[0][0][0].append(val)
774 result["outputValues"] = outputValues
775 result["specificOutputInfos"] = []
776 result["returnCode"] = 0
777 result["errorMessage"] = ""
779 All various modifications could be done from this template hypothesis.
781 Special case of controled evolution operator
782 ++++++++++++++++++++++++++++++++++++++++++++
784 In some cases, the evolution operator is required to be controled by an external
785 input control, given a priori. In this case, the generic form of the incremental
786 evolution model is slightly modified as follows:
788 .. math:: \mathbf{y} = H( \mathbf{x}, \mathbf{u})
790 where :math:`\mathbf{u}` is the control over one state increment. In this case,
791 the direct evolution operator has to be applied to a pair of variables
792 :math:`(X,U)`. Schematically, the evolution operator has to be set as::
794 def DirectOperator( (X, U) ):
795 """ Direct non-linear simulation operator """
799 return something like X(n+1)
801 The tangent and adjoint operators have the same signature as previously, noting
802 that the derivatives has to be done only against :math:`\mathbf{x}` partially.
803 In such a case with explicit control, only the second functional form (using
804 "*ScriptWithFunctions*") and third functional form (using "*ScriptWithSwitch*")