..
- Copyright (C) 2008-2015 EDF R&D
+ Copyright (C) 2008-2020 EDF R&D
This file is part of SALOME ADAO module.
Calculation algorithm "*Blue*"
------------------------------
-Description
-+++++++++++
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo01.rst
This algorithm realizes a BLUE (Best Linear Unbiased Estimator) type estimation
of the state of a system. More precisely, it is an Aitken estimator.
linearity of the observation operator with the help of the
:ref:`section_ref_algorithm_LinearityTest`.
-In case of non-linearity, even slightly marked, it will be easily prefered the
+In case of non-linearity, even slightly marked, it will be easily preferred the
:ref:`section_ref_algorithm_ExtendedBlue` or the
:ref:`section_ref_algorithm_3DVAR`.
-Optional and required commands
-++++++++++++++++++++++++++++++
-
-.. index:: single: Background
-.. index:: single: BackgroundError
-.. index:: single: Observation
-.. index:: single: ObservationError
-.. index:: single: ObservationOperator
-.. index:: single: StoreInternalVariables
-.. index:: single: StoreSupplementaryCalculations
-.. index:: single: Quantiles
-.. index:: single: SetSeed
-.. index:: single: NumberOfSamplesForQuantiles
-.. index:: single: SimulationForQuantiles
-
-The general required commands, available in the editing user interface, are the
-following:
-
- Background
- *Required command*. This indicates the background or initial vector used,
- previously noted as :math:`\mathbf{x}^b`. Its value is defined as a
- "*Vector*" or a *VectorSerie*" type object.
-
- BackgroundError
- *Required command*. This indicates the background error covariance matrix,
- previously noted as :math:`\mathbf{B}`. Its value is defined as a "*Matrix*"
- type object, a "*ScalarSparseMatrix*" type object, or a
- "*DiagonalSparseMatrix*" type object.
-
- Observation
- *Required command*. This indicates the observation vector used for data
- assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
- is defined as a "*Vector*" or a *VectorSerie* type object.
-
- ObservationError
- *Required command*. This indicates the observation error covariance matrix,
- previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
- object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
- type object.
-
- ObservationOperator
- *Required command*. This indicates the observation operator, previously
- noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
- results :math:`\mathbf{y}` to be compared to observations
- :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
- a "*Matrix*" type one. In the case of "*Function*" type, different
- functional forms can be used, as described in the section
- :ref:`section_ref_operator_requirements`. If there is some control :math:`U`
- included in the observation, the operator has to be applied to a pair
- :math:`(X,U)`.
-
-The general optional commands, available in the editing user interface, are
-indicated in :ref:`section_ref_assimilation_keywords`. In particular, the
-optional command "*AlgorithmParameters*" allows to choose the specific options,
-described hereafter, of the algorithm. See
-:ref:`section_ref_options_AlgorithmParameters` for the good use of this command.
-
-The options of the algorithm are the following:
-
- StoreInternalVariables
- This Boolean key allows to store default internal variables, mainly the
- current state during iterative optimization process. Be careful, this can be
- a numerically costly choice in certain calculation cases. The default is
- "False".
-
- Example : ``{"StoreInternalVariables":True}``
-
- StoreSupplementaryCalculations
- This list indicates the names of the supplementary variables that can be
- available at the end of the algorithm. It involves potentially costly
- calculations or memory consumptions. The default is a void list, none of
- these variables being calculated and stored by default. The possible names
- are in the following list: ["APosterioriCovariance", "BMA", "OMA", "OMB",
- "Innovation", "SigmaBck2", "SigmaObs2", "MahalanobisConsistency",
- "SimulationQuantiles"].
-
- Example : ``{"StoreSupplementaryCalculations":["BMA","Innovation"]}``
-
- Quantiles
- This list indicates the values of quantile, between 0 and 1, to be estimated
- by simulation around the optimal state. The sampling uses a multivariate
- gaussian random sampling, directed by the *a posteriori* covariance matrix.
- This option is useful only if the supplementary calculation
- "SimulationQuantiles" has been chosen. The default is a void list.
-
- Example : ``{"Quantiles":[0.1,0.9]}``
-
- SetSeed
- This key allow to give an integer in order to fix the seed of the random
- generator used to generate the ensemble. A convenient value is for example
- 1000. By default, the seed is left uninitialized, and so use the default
- initialization from the computer.
-
- Example : ``{"SetSeed":1000}``
-
- NumberOfSamplesForQuantiles
- This key indicates the number of simulation to be done in order to estimate
- the quantiles. This option is useful only if the supplementary calculation
- "SimulationQuantiles" has been chosen. The default is 100, which is often
- sufficient for correct estimation of common quantiles at 5%, 10%, 90% or
- 95%.
-
- Example : ``{"NumberOfSamplesForQuantiles":100}``
-
- SimulationForQuantiles
- This key indicates the type of simulation, linear (with the tangent
- observation operator applied to perturbation increments around the optimal
- state) or non-linear (with standard observation operator applied to
- perturbated states), one want to do for each perturbation. It changes mainly
- the time of each elementary calculation, usually longer in non-linear than
- in linear. This option is useful only if the supplementary calculation
- "SimulationQuantiles" has been chosen. The default value is "Linear", and
- the possible choices are "Linear" and "NonLinear".
-
- Example : ``{"SimulationForQuantiles":"Linear"}``
-
-See also
-++++++++
-
-References to other sections:
- - :ref:`section_ref_algorithm_ExtendedBlue`
- - :ref:`section_ref_algorithm_3DVAR`
- - :ref:`section_ref_algorithm_LinearityTest`
-
-Bibliographical references:
- - [Bouttier99]_
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo02.rst
+
+.. include:: snippets/Background.rst
+
+.. include:: snippets/BackgroundError.rst
+
+.. include:: snippets/Observation.rst
+
+.. include:: snippets/ObservationError.rst
+
+.. include:: snippets/ObservationOperator.rst
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo03AdOp.rst
+
+.. include:: snippets/NumberOfSamplesForQuantiles.rst
+
+.. include:: snippets/Quantiles.rst
+
+.. include:: snippets/SetSeed.rst
+
+.. include:: snippets/SimulationForQuantiles.rst
+
+StoreSupplementaryCalculations
+ .. index:: single: StoreSupplementaryCalculations
+
+ This list indicates the names of the supplementary variables that can be
+ available at the end of the algorithm, if they are initially required by the
+ user. It involves potentially costly calculations or memory consumptions. The
+ default is a void list, none of these variables being calculated and stored
+ by default excepted the unconditionnal variables. The possible names are in
+ the following list: [
+ "Analysis",
+ "APosterioriCorrelations",
+ "APosterioriCovariance",
+ "APosterioriStandardDeviations",
+ "APosterioriVariances",
+ "BMA",
+ "CostFunctionJ",
+ "CostFunctionJAtCurrentOptimum",
+ "CostFunctionJb",
+ "CostFunctionJbAtCurrentOptimum",
+ "CostFunctionJo",
+ "CostFunctionJoAtCurrentOptimum",
+ "CurrentOptimum",
+ "CurrentState",
+ "Innovation",
+ "MahalanobisConsistency",
+ "OMA",
+ "OMB",
+ "SigmaBck2",
+ "SigmaObs2",
+ "SimulatedObservationAtBackground",
+ "SimulatedObservationAtCurrentOptimum",
+ "SimulatedObservationAtCurrentState",
+ "SimulatedObservationAtOptimum",
+ "SimulationQuantiles",
+ ].
+
+ Example :
+ ``{"StoreSupplementaryCalculations":["BMA", "CurrentState"]}``
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo04.rst
+
+.. include:: snippets/Analysis.rst
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo05.rst
+
+.. include:: snippets/Analysis.rst
+
+.. include:: snippets/APosterioriCorrelations.rst
+
+.. include:: snippets/APosterioriCovariance.rst
+
+.. include:: snippets/APosterioriStandardDeviations.rst
+
+.. include:: snippets/APosterioriVariances.rst
+
+.. include:: snippets/BMA.rst
+
+.. include:: snippets/CostFunctionJ.rst
+
+.. include:: snippets/CostFunctionJAtCurrentOptimum.rst
+
+.. include:: snippets/CostFunctionJb.rst
+
+.. include:: snippets/CostFunctionJbAtCurrentOptimum.rst
+
+.. include:: snippets/CostFunctionJo.rst
+
+.. include:: snippets/CostFunctionJoAtCurrentOptimum.rst
+
+.. include:: snippets/CurrentOptimum.rst
+
+.. include:: snippets/CurrentState.rst
+
+.. include:: snippets/Innovation.rst
+
+.. include:: snippets/MahalanobisConsistency.rst
+
+.. include:: snippets/OMA.rst
+
+.. include:: snippets/OMB.rst
+
+.. include:: snippets/SigmaBck2.rst
+
+.. include:: snippets/SigmaObs2.rst
+
+.. include:: snippets/SimulatedObservationAtBackground.rst
+
+.. include:: snippets/SimulatedObservationAtCurrentOptimum.rst
+
+.. include:: snippets/SimulatedObservationAtCurrentState.rst
+
+.. include:: snippets/SimulatedObservationAtOptimum.rst
+
+.. include:: snippets/SimulationQuantiles.rst
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo09.rst
+
+.. literalinclude:: scripts/simple_Blue.py
+
+.. include:: snippets/Header2Algo10.rst
+
+.. literalinclude:: scripts/simple_Blue.res
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo06.rst
+
+- :ref:`section_ref_algorithm_ExtendedBlue`
+- :ref:`section_ref_algorithm_3DVAR`
+- :ref:`section_ref_algorithm_LinearityTest`
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo07.rst
+
+- [Bouttier99]_