..
- Copyright (C) 2008-2014 EDF R&D
+ Copyright (C) 2008-2018 EDF R&D
This file is part of SALOME ADAO module.
+++++++++++
This algorithm realizes an estimation of the state of a dynamic system by a
-extended Kalman Filter, using a non-linear calculation of the state.
+extended Kalman Filter, using a non-linear calculation of the state and the
+incremental evolution (process).
+
+In case of really non-linear operators, one can easily use the
+:ref:`section_ref_algorithm_EnsembleKalmanFilter` or the
+:ref:`section_ref_algorithm_UnscentedKalmanFilter`, which are often far more
+adapted to non-linear behavior but more costly. One can verify the linearity of
+the operators with the help of the :ref:`section_ref_algorithm_LinearityTest`.
Optional and required commands
++++++++++++++++++++++++++++++
-.. index:: single: Background
-.. index:: single: BackgroundError
-.. index:: single: Observation
-.. index:: single: ObservationError
-.. index:: single: ObservationOperator
-.. index:: single: Bounds
-.. index:: single: ConstrainedBy
-.. index:: single: EstimationOf
-.. index:: single: StoreInternalVariables
-.. index:: single: StoreSupplementaryCalculations
-
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)`.
+ .. include:: snippets/Background.rst
+
+ .. include:: snippets/BackgroundError.rst
+
+ .. include:: snippets/EvolutionError.rst
+
+ .. include:: snippets/EvolutionModel.rst
+
+ .. include:: snippets/Observation.rst
+
+ .. include:: snippets/ObservationError.rst
+
+ .. include:: snippets/ObservationOperator.rst
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,
+indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters
+of the 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.
+:ref:`section_ref_options_Algorithm_Parameters` for the good use of this
+command.
The options of the algorithm are the following:
- Bounds
- This key allows to define upper and lower bounds for every state variable
- being optimized. Bounds have to be given by a list of list of pairs of
- lower/upper bounds for each variable, with extreme values every time there
- is no bound (``None`` is not allowed when there is no bound).
-
- ConstrainedBy
- This key allows to define the method to take bounds into account. The
- possible methods are in the following list: ["EstimateProjection"].
+ .. include:: snippets/BoundsWithExtremes.rst
- EstimationOf
- This key allows to choose the type of estimation to be performed. It can be
- either state-estimation, with a value of "State", or parameter-estimation,
- with a value of "Parameters". The default choice is "State".
+ .. include:: snippets/ConstrainedBy.rst
- 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".
+ .. include:: snippets/EstimationOf.rst
StoreSupplementaryCalculations
+ .. index:: single: 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. 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", "Innovation"].
+ 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: ["APosterioriCorrelations",
+ "APosterioriCovariance", "APosterioriStandardDeviations",
+ "APosterioriVariances", "BMA", "CostFunctionJ", "CostFunctionJb",
+ "CostFunctionJo", "CurrentState", "Innovation"].
+
+ Example :
+ ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}``
+
+Information and variables available at the end of the algorithm
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+At the output, after executing the algorithm, there are variables and
+information originating from the calculation. The description of
+:ref:`section_ref_output_variables` show the way to obtain them by the method
+named ``get`` of the variable "*ADD*" of the post-processing. The input
+variables, available to the user at the output in order to facilitate the
+writing of post-processing procedures, are described in the
+:ref:`subsection_r_o_v_Inventaire`.
+
+The unconditional outputs of the algorithm are the following:
+
+ .. include:: snippets/Analysis.rst
+
+The conditional outputs of the algorithm are the following:
+
+ .. 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/CostFunctionJb.rst
+
+ .. include:: snippets/CostFunctionJo.rst
+
+ .. include:: snippets/CurrentState.rst
+
+ .. include:: snippets/Innovation.rst
See also
++++++++
References to other sections:
- :ref:`section_ref_algorithm_KalmanFilter`
+ - :ref:`section_ref_algorithm_EnsembleKalmanFilter`
- :ref:`section_ref_algorithm_UnscentedKalmanFilter`