doc/reference.rst

   1 .. _section_reference:
   2
   3 ================================================================================
   4 Reference description of the ADAO commands and keywords
   5 ================================================================================
   6
   7 This section presents the reference description of the ADAO commands and
   8 keywords available through the GUI or through scripts.
   9
  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.
  17
  18 The mathematical notations used afterward are explained in the section
  19 :ref:`section_theory`.
  20
  21 Examples of using these commands are available in the section
  22 :ref:`section_examples` and in example files installed with ADAO module.
  23
  24 List of possible input types
  25 ----------------------------
  26
  27 .. index:: single: Dict
  28 .. index:: single: Function
  29 .. index:: single: Matrix
  30 .. index:: single: String
  31 .. index:: single: Script
  32 .. index:: single: Vector
  33
  34 Each ADAO variable has a pseudo-type to help filling it and validation. The
  35 different pseudo-types are:
  36
  37 **Dict**
  38     This indicates a variable that has to be filled by a dictionary, usually
  39     given as a script.
  40
  41 **Function**
  42     This indicates a variable that has to be filled by a function, usually given
  43     as a script or a component method.
  44
  45 **Matrix**
  46     This indicates a variable that has to be filled by a matrix, usually given
  47     either as a string or as a script.
  48
  49 **String**
  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.
  52
  53 **Script**
  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.
  56
  57 **Vector**
  58     This indicates a variable that has to be filled by a vector, usually given
  59     either as a string or as a script.
  60
  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.
  63
  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.
  68
  69 List of commands and keywords for an ADAO calculation case
  70 ----------------------------------------------------------
  71
  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
  91
  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
  96 following:
  97
  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
 101     commands.
 102
 103 **Algorithm**
 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`_.
 109
 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`_.
 116
 117 **Background**
 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.
 121
 122 **BackgroundError**
 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.
 126
 127 **ControlInput**
 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
 132     void string ''.
 133
 134 **Debug**
 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
 137     True).
 138
 139 **EvolutionError**
 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.
 143
 144 **EvolutionModel**
 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)`.
 151
 152 **InputVariables**
 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.
 156
 157 **Observation**
 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.
 162
 163 **ObservationError**
 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.
 167
 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
 175     operator`_.
 176
 177 **Observers**
 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
 182     or plotting it, etc.
 183
 184 **OutputVariables**
 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.
 188
 189 **Study_name**
 190     *Required command*. This is an open string to describe the study by a name
 191     or a sentence.
 192
 193 **Study_repertory**
 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.
 196
 197 **UserDataInit**
 198     *Optional command*. This commands allows to initialize some parameters or
 199     data automatically before data assimilation algorithm processing.
 200
 201 **UserPostAnalysis**
 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
 205     the ADAO case.
 206
 207 List of commands and keywords for an ADAO checking case
 208 -------------------------------------------------------
 209
 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
 219
 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:
 225
 226 **CHECKING_STUDY**
 227     *Required command*. This is the general command describing the checking
 228     case. It hierarchically contains all the other commands.
 229
 230 **Algorithm**
 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`_.
 236
 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`_.
 243
 244 **CheckingPoint**
 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.
 248
 249 **Debug**
 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
 252     True).
 253
 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
 261     operator`_.
 262
 263 **Study_name**
 264     *Required command*. This is an open string to describe the study by a name
 265     or a sentence.
 266
 267 **Study_repertory**
 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.
 270
 271 **UserDataInit**
 272     *Optional command*. This commands allows to initialize some parameters or
 273     data automatically before data assimilation algorithm processing.
 274
 275 Options and required commands for algorithms
 276 --------------------------------------------
 277
 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
 287
 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
 303
 304 Each algorithm can be controlled using some generic or specific options given
 305 through the "*AlgorithmParameters*" optional command, as follows for example::
 306
 307     AlgorithmParameters = {
 308         "Minimizer" : "LBFGSB",
 309         "MaximumNumberOfSteps" : 25,
 310         "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"],
 311         }
 312
 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`_.
 319
 320 **"Blue"**
 321
 322   *Required commands*
 323     *"Background", "BackgroundError",
 324     "Observation", "ObservationError",
 325     "ObservationOperator"*
 326
 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"].
 334
 335 **"LinearLeastSquares"**
 336
 337   *Required commands*
 338     *"Observation", "ObservationError",
 339     "ObservationOperator"*
 340
 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
 346     list: ["OMA"].
 347
 348 **"3DVAR"**
 349
 350   *Required commands*
 351     *"Background", "BackgroundError",
 352     "Observation", "ObservationError",
 353     "ObservationOperator"*
 354
 355   Minimizer
 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).
 361
 362   Bounds
 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.
 368
 369   MaximumNumberOfSteps
 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.
 375
 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.
 381
 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.
 388
 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.
 394
 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
 399     "False".
 400
 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"].
 408
 409 **"NonLinearLeastSquares"**
 410
 411   *Required commands*
 412     *"Background",
 413     "Observation", "ObservationError",
 414     "ObservationOperator"*
 415
 416   Minimizer
 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).
 422
 423   Bounds
 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.
 429
 430   MaximumNumberOfSteps
 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.
 436
 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.
 442
 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.
 449
 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.
 455
 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
 460     "False".
 461
 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"].
 468
 469 **"EnsembleBlue"**
 470
 471   *Required commands*
 472     *"Background", "BackgroundError",
 473     "Observation", "ObservationError",
 474     "ObservationOperator"*
 475
 476   SetSeed
 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.
 481
 482 **"KalmanFilter"**
 483
 484   *Required commands*
 485     *"Background", "BackgroundError",
 486     "Observation", "ObservationError",
 487     "ObservationOperator",
 488     "EvolutionModel", "EvolutionError"*
 489
 490   EstimationType
 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".
 494
 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"].
 501
 502 **"ExtendedKalmanFilter"**
 503
 504   *Required commands*
 505     *"Background", "BackgroundError",
 506     "Observation", "ObservationError",
 507     "ObservationOperator",
 508     "EvolutionModel", "EvolutionError",
 509     "ControlInput"*
 510
 511   EstimationType
 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".
 515
 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"].
 522
 523 **"ParticleSwarmOptimization"**
 524
 525   *Required commands*
 526     *"Background", "BackgroundError",
 527     "Observation", "ObservationError",
 528     "ObservationOperator"*
 529
 530   MaximumNumberOfSteps
 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.
 534
 535   NumberOfInsects
 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.
 538
 539   SwarmVelocity
 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.
 542
 543   GroupRecallRate
 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.
 546
 547   QualityCriterion
 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"]
 555
 556   SetSeed
 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.
 561
 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
 566     "False".
 567
 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"].
 574
 575 **"QuantileRegression"**
 576
 577   *Required commands*
 578     *"Background",
 579     "Observation",
 580     "ObservationOperator"*
 581
 582   Quantile
 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.
 585
 586   Minimizer
 587     This key allows to choose the optimization minimizer. The default choice
 588     and only available choice is "MMQR" (Majorize-Minimize for Quantile
 589     Regression).
 590
 591   MaximumNumberOfSteps
 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
 595     real problems.
 596
 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.
 602
 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
 607     "False".
 608
 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"].
 615
 616 Requirements for functions describing an operator
 617 -------------------------------------------------
 618
 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.
 625
 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:
 631
 632 .. math:: \mathbf{y} = H( \mathbf{x} )
 633
 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.
 639
 640 Then, **to describe completely an operator, the user has only to provide a
 641 function that fully and only realize the functional operation**.
 642
 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.
 648
 649 There are 3 practical methods for the user to provide the operator functional
 650 representation.
 651
 652 First functional form: using "*ScriptWithOneFunction*"
 653 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 654
 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
 660 template::
 661
 662     def DirectOperator( X ):
 663         """ Direct non-linear simulation operator """
 664         ...
 665         ...
 666         ...
 667         return Y=H(X)
 668
 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.
 673
 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.
 676
 677 Second functional form: using "*ScriptWithFunctions*"
 678 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 679
 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::
 686
 687     def DirectOperator( X ):
 688         """ Direct non-linear simulation operator """
 689         ...
 690         ...
 691         ...
 692         return something like Y
 693
 694     def TangentOperator( (X, dX) ):
 695         """ Tangent linear operator, around X, applied to dX """
 696         ...
 697         ...
 698         ...
 699         return something like Y
 700
 701     def AdjointOperator( (X, Y) ):
 702         """ Adjoint operator, around X, applied to Y """
 703         ...
 704         ...
 705         ...
 706         return something like X
 707
 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
 710 implementation.
 711
 712 Third functional form: using "*ScriptWithSwitch*"
 713 +++++++++++++++++++++++++++++++++++++++++++++++++
 714
 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.
 724
 725 **It is recommended not to use this third functional form without a solid
 726 numerical or physical reason.**
 727
 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::
 733
 734     import Physical_simulation_functions
 735     import numpy, logging
 736     #
 737     method = ""
 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)
 744     #
 745     logging.info("Loading operator functions")
 746     FunctionH = Physical_simulation_functions.DirectOperator
 747     TangentH  = Physical_simulation_functions.TangentOperator
 748     AdjointH  = Physical_simulation_functions.AdjointOperator
 749     #
 750     logging.info("Executing the possible computations")
 751     data = []
 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))
 766     #
 767     logging.info("Formatting the output")
 768     it = numpy.ravel(data)
 769     outputValues = [[[[]]]]
 770     for val in it:
 771       outputValues[0][0][0].append(val)
 772     #
 773     result = {}
 774     result["outputValues"]        = outputValues
 775     result["specificOutputInfos"] = []
 776     result["returnCode"]          = 0
 777     result["errorMessage"]        = ""
 778
 779 All various modifications could be done from this template hypothesis.
 780
 781 Special case of controled evolution operator
 782 ++++++++++++++++++++++++++++++++++++++++++++
 783
 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:
 787
 788 .. math:: \mathbf{y} = H( \mathbf{x}, \mathbf{u})
 789
 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::
 793
 794     def DirectOperator( (X, U) ):
 795         """ Direct non-linear simulation operator """
 796         ...
 797         ...
 798         ...
 799         return something like X(n+1)
 800
 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*")
 805 can be used.