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   StoreSupplementaryCalculations
 491      This list indicates the names of the supplementary variables that can be
 492      available at the end of the algorithm. It involves potentially costly
 493      calculations. The default is a void list, none of these variables being
 494      calculated and stored by default. The possible names are in the following
 495      list: ["APosterioriCovariance", "Innovation"].
 496
 497 **"ExtendedKalmanFilter"**
 498
 499   *Required commands*
 500     *"Background", "BackgroundError",
 501     "Observation", "ObservationError",
 502     "ObservationOperator",
 503     "EvolutionModel", "EvolutionError",
 504     "ControlInput"*
 505
 506   StoreSupplementaryCalculations
 507      This list indicates the names of the supplementary variables that can be
 508      available at the end of the algorithm. It involves potentially costly
 509      calculations. The default is a void list, none of these variables being
 510      calculated and stored by default. The possible names are in the following
 511      list: ["APosterioriCovariance", "Innovation"].
 512
 513 **"ParticleSwarmOptimization"**
 514
 515   *Required commands*
 516     *"Background", "BackgroundError",
 517     "Observation", "ObservationError",
 518     "ObservationOperator"*
 519
 520   MaximumNumberOfSteps
 521     This key indicates the maximum number of iterations allowed for iterative
 522     optimization. The default is 50, which is an arbitrary limit. It is then
 523     recommended to adapt this parameter to the needs on real problems.
 524
 525   NumberOfInsects
 526     This key indicates the number of insects or particles in the swarm. The
 527     default is 100, which is a usual default for this algorithm.
 528
 529   SwarmVelocity
 530     This key indicates the part of the insect velocity which is imposed by the
 531     swarm. It is a positive floating point value. The default value is 1.
 532
 533   GroupRecallRate
 534     This key indicates the recall rate at the best swarm insect. It is a
 535     floating point value between 0 and 1. The default value is 0.5.
 536
 537   QualityCriterion
 538     This key indicates the quality criterion, minimized to find the optimal
 539     state estimate. The default is the usual data assimilation criterion named
 540     "DA", the augmented ponderated least squares. The possible criteria has to
 541     be in the following list, where the equivalent names are indicated by "=":
 542     ["AugmentedPonderatedLeastSquares"="APLS"="DA",
 543     "PonderatedLeastSquares"="PLS", "LeastSquares"="LS"="L2",
 544     "AbsoluteValue"="L1", "MaximumError"="ME"]
 545
 546   SetSeed
 547     This key allow to give an integer in order to fix the seed of the random
 548     generator used to generate the ensemble. A convenient value is for example
 549     1000. By default, the seed is left uninitialized, and so use the default
 550     initialization from the computer.
 551
 552   StoreInternalVariables
 553     This boolean key allows to store default internal variables, mainly the
 554     current state during iterative optimization process. Be careful, this can be
 555     a numerically costly choice in certain calculation cases. The default is
 556     "False".
 557
 558   StoreSupplementaryCalculations
 559      This list indicates the names of the supplementary variables that can be
 560      available at the end of the algorithm. It involves potentially costly
 561      calculations. The default is a void list, none of these variables being
 562      calculated and stored by default. The possible names are in the following
 563      list: ["BMA", "OMA", "OMB", "Innovation"].
 564
 565 **"QuantileRegression"**
 566
 567   *Required commands*
 568     *"Background",
 569     "Observation",
 570     "ObservationOperator"*
 571
 572   Quantile
 573     This key allows to define the real value of the desired quantile, between
 574     0 and 1. The default is 0.5, corresponding to the median.
 575
 576   Minimizer
 577     This key allows to choose the optimization minimizer. The default choice
 578     and only available choice is "MMQR" (Majorize-Minimize for Quantile
 579     Regression).
 580
 581   MaximumNumberOfSteps
 582     This key indicates the maximum number of iterations allowed for iterative
 583     optimization. The default is 15000, which is very similar to no limit on
 584     iterations. It is then recommended to adapt this parameter to the needs on
 585     real problems.
 586
 587   CostDecrementTolerance
 588     This key indicates a limit value, leading to stop successfully the
 589     iterative optimization process when the cost function or the surrogate
 590     decreases less than this tolerance at the last step. The default is 1.e-6,
 591     and it is recommended to adapt it to the needs on real problems.
 592
 593   StoreInternalVariables
 594     This boolean key allows to store default internal variables, mainly the
 595     current state during iterative optimization process. Be careful, this can be
 596     a numerically costly choice in certain calculation cases. The default is
 597     "False".
 598
 599   StoreSupplementaryCalculations
 600      This list indicates the names of the supplementary variables that can be
 601      available at the end of the algorithm. It involves potentially costly
 602      calculations. The default is a void list, none of these variables being
 603      calculated and stored by default. The possible names are in the following
 604      list: ["BMA", "OMA", "OMB", "Innovation"].
 605
 606 Requirements for functions describing an operator
 607 -------------------------------------------------
 608
 609 The operators for observation and evolution are required to implement the data
 610 assimilation or optimization procedures. They include the physical simulation
 611 numerical simulations, but also the filtering and restriction to compare the
 612 simulation to observation. The evolution operator is considered here in its
 613 incremental form, representing the transition between two successive states, and
 614 is then similar to the observation operator.
 615
 616 Schematically, an operator has to give a output solution given the input
 617 parameters. Part of the input parameters can be modified during the optimization
 618 procedure. So the mathematical representation of such a process is a function.
 619 It was briefly described in the section :ref:`section_theory` and is generalized
 620 here by the relation:
 621
 622 .. math:: \mathbf{y} = H( \mathbf{x} )
 623
 624 between the pseudo-observations :math:`\mathbf{y}` and the parameters
 625 :math:`\mathbf{x}` using the observation operator :math:`H`. The same functional
 626 representation can be used for the linear tangent model :math:`\mathbf{H}` of
 627 :math:`H` and its adjoint :math:`\mathbf{H}^*`, also required by some data
 628 assimilation or optimization algorithms.
 629
 630 Then, **to describe completely an operator, the user has only to provide a
 631 function that fully and only realize the functional operation**.
 632
 633 This function is usually given as a script that can be executed in a YACS node.
 634 This script can without difference launch external codes or use internal SALOME
 635 calls and methods. If the algorithm requires the 3 aspects of the operator
 636 (direct form, tangent form and adjoint form), the user has to give the 3
 637 functions or to approximate them.
 638
 639 There are 3 practical methods for the user to provide the operator functional
 640 representation.
 641
 642 First functional form: using "*ScriptWithOneFunction*"
 643 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 644
 645 The first one consist in providing only one potentially non-linear function, and
 646 to approximate the tangent and the adjoint operators. This is done by using the
 647 keyword "*ScriptWithOneFunction*" for the description of the chosen operator in
 648 the ADAO GUI. The user have to provide the function in a script, with a
 649 mandatory name "*DirectOperator*". For example, the script can follow the
 650 template::
 651
 652     def DirectOperator( X ):
 653         """ Direct non-linear simulation operator """
 654         ...
 655         ...
 656         ...
 657         return Y=H(X)
 658
 659 In this case, the user can also provide a value for the differential increment,
 660 using through the GUI the keyword "*DifferentialIncrement*", which has a default
 661 value of 1%. This coefficient will be used in the finite difference
 662 approximation to build the tangent and adjoint operators.
 663
 664 This first operator definition allow easily to test the functional form before
 665 its use in an ADAO case, reducing the complexity of implementation.
 666
 667 Second functional form: using "*ScriptWithFunctions*"
 668 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 669
 670 The second one consist in providing directly the three associated operators
 671 :math:`H`, :math:`\mathbf{H}` and :math:`\mathbf{H}^*`. This is done by using
 672 the keyword "*ScriptWithFunctions*" for the description of the chosen operator
 673 in the ADAO GUI. The user have to provide three functions in one script, with
 674 three mandatory names "*DirectOperator*", "*TangentOperator*" and
 675 "*AdjointOperator*". For example, the script can follow the template::
 676
 677     def DirectOperator( X ):
 678         """ Direct non-linear simulation operator """
 679         ...
 680         ...
 681         ...
 682         return something like Y
 683
 684     def TangentOperator( (X, dX) ):
 685         """ Tangent linear operator, around X, applied to dX """
 686         ...
 687         ...
 688         ...
 689         return something like Y
 690
 691     def AdjointOperator( (X, Y) ):
 692         """ Adjoint operator, around X, applied to Y """
 693         ...
 694         ...
 695         ...
 696         return something like X
 697
 698 Another time, this second perator definition allow easily to test the functional
 699 forms before their use in an ADAO case, greatly reducing the complexity of
 700 implementation.
 701
 702 Third functional form: using "*ScriptWithSwitch*"
 703 +++++++++++++++++++++++++++++++++++++++++++++++++
 704
 705 This third form give more possibilities to control the execution of the three
 706 functions representing the operator, allowing advanced usage and control over
 707 each execution of the simulation code. This is done by using the keyword
 708 "*ScriptWithSwitch*" for the description of the chosen operator in the ADAO GUI.
 709 The user have to provide a switch in one script to control the execution of the
 710 direct, tangent and adjoint forms of its simulation code. The user can then, for
 711 example, use other approximations for the tangent and adjoint codes, or
 712 introduce more complexity in the argument treatment of the functions. But it
 713 will be far more complicated to implement and debug.
 714
 715 **It is recommended not to use this third functional form without a solid
 716 numerical or physical reason.**
 717
 718 If, however, you want to use this third form, we recommend using the following
 719 template for the switch. It requires an external script or code named
 720 "*Physical_simulation_functions.py*", containing three functions named
 721 "*DirectOperator*", "*TangentOperator*" and "*AdjointOperator*" as previously.
 722 Here is the switch template::
 723
 724     import Physical_simulation_functions
 725     import numpy, logging
 726     #
 727     method = ""
 728     for param in computation["specificParameters"]:
 729         if param["name"] == "method":
 730             method = param["value"]
 731     if method not in ["Direct", "Tangent", "Adjoint"]:
 732         raise ValueError("No valid computation method is given")
 733     logging.info("Found method is \'%s\'"%method)
 734     #
 735     logging.info("Loading operator functions")
 736     FunctionH = Physical_simulation_functions.DirectOperator
 737     TangentH  = Physical_simulation_functions.TangentOperator
 738     AdjointH  = Physical_simulation_functions.AdjointOperator
 739     #
 740     logging.info("Executing the possible computations")
 741     data = []
 742     if method == "Direct":
 743         logging.info("Direct computation")
 744         Xcurrent = computation["inputValues"][0][0][0]
 745         data = FunctionH(numpy.matrix( Xcurrent ).T)
 746     if method == "Tangent":
 747         logging.info("Tangent computation")
 748         Xcurrent  = computation["inputValues"][0][0][0]
 749         dXcurrent = computation["inputValues"][0][0][1]
 750         data = TangentH(numpy.matrix(Xcurrent).T, numpy.matrix(dXcurrent).T)
 751     if method == "Adjoint":
 752         logging.info("Adjoint computation")
 753         Xcurrent = computation["inputValues"][0][0][0]
 754         Ycurrent = computation["inputValues"][0][0][1]
 755         data = AdjointH((numpy.matrix(Xcurrent).T, numpy.matrix(Ycurrent).T))
 756     #
 757     logging.info("Formatting the output")
 758     it = numpy.ravel(data)
 759     outputValues = [[[[]]]]
 760     for val in it:
 761       outputValues[0][0][0].append(val)
 762     #
 763     result = {}
 764     result["outputValues"]        = outputValues
 765     result["specificOutputInfos"] = []
 766     result["returnCode"]          = 0
 767     result["errorMessage"]        = ""
 768
 769 All various modifications could be done from this template hypothesis.
 770
 771 Special case of controled evolution operator
 772 ++++++++++++++++++++++++++++++++++++++++++++
 773
 774 In some cases, the evolution operator is required to be controled by an external
 775 input control, given a priori. In this case, the generic form of the incremental
 776 evolution model is slightly modified as follows:
 777
 778 .. math:: \mathbf{y} = H( \mathbf{x}, \mathbf{u})
 779
 780 where :math:`\mathbf{u}` is the control over one state increment. In this case,
 781 the direct evolution operator has to be applied to a pair of variables
 782 :math:`(X,U)`. Schematically, the evolution operator has to be set as::
 783
 784     def DirectOperator( (X, U) ):
 785         """ Direct non-linear simulation operator """
 786         ...
 787         ...
 788         ...
 789         return something like X(n+1)
 790
 791 The tangent and adjoint operators have the same signature as previously, noting
 792 that the derivatives has to be done only against :math:`\mathbf{x}` partially.
 793 In such a case with explicit control, only the second functional form (using
 794 "*ScriptWithFunctions*") and third functional form (using "*ScriptWithSwitch*")
 795 can be used.