..
- Copyright (C) 2008-2014 EDF R&D
+ Copyright (C) 2008-2018 EDF R&D
This file is part of SALOME ADAO module.
Description
+++++++++++
-This algorithm realizes an estimation of the state of a dynamic system by a
-particle swarm.
+This algorithm realizes an estimation of the state of a system by minimization
+of a cost function :math:`J` by using an evolutionary strategy of particle
+swarm. It is a method that does not use the derivatives of the cost function.
+It falls in the same category than the
+:ref:`section_ref_algorithm_DerivativeFreeOptimization` or the
+:ref:`section_ref_algorithm_DifferentialEvolution`.
This is an optimization method allowing for global minimum search of a general
-function of type :math:`L^1`, :math:`L^2` or :math:`L^{\infty}`, with or without
-weights.
+error function :math:`J` of type :math:`L^1`, :math:`L^2` or :math:`L^{\infty}`,
+with or without weights. The default error function is the augmented weighted
+least squares function, classically used in data assimilation.
Optional and required commands
++++++++++++++++++++++++++++++
-.. index:: single: Background
-.. index:: single: BackgroundError
-.. index:: single: Observation
-.. index:: single: ObservationError
-.. index:: single: ObservationOperator
-.. index:: single: MaximumNumberOfSteps
-.. index:: single: NumberOfInsects
-.. index:: single: SwarmVelocity
-.. index:: single: GroupRecallRate
-.. index:: single: QualityCriterion
-.. index:: single: BoxBounds
-.. index:: single: SetSeed
-.. 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/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:
+.. index:: single: NumberOfInsects
+.. index:: single: SwarmVelocity
+.. index:: single: GroupRecallRate
+.. index:: single: QualityCriterion
+.. index:: single: BoxBounds
- MaximumNumberOfSteps
- This key indicates the maximum number of iterations allowed for iterative
- optimization. The default is 50, which is an arbitrary limit. It is then
- recommended to adapt this parameter to the needs on real problems.
+ .. include:: snippets/MaximumNumberOfSteps_50.rst
+
+ .. include:: snippets/MaximumNumberOfFunctionEvaluations.rst
+
+ .. include:: snippets/QualityCriterion.rst
NumberOfInsects
This key indicates the number of insects or particles in the swarm. The
default is 100, which is a usual default for this algorithm.
+ Example :
+ ``{"NumberOfInsects":100}``
+
SwarmVelocity
- This key indicates the part of the insect velocity which is imposed by the
+ This key indicates the part of the insect velocity which is imposed by the
swarm. It is a positive floating point value. The default value is 1.
+ Example :
+ ``{"SwarmVelocity":1.}``
+
GroupRecallRate
This key indicates the recall rate at the best swarm insect. It is a
floating point value between 0 and 1. The default value is 0.5.
- QualityCriterion
- This key indicates the quality criterion, minimized to find the optimal
- state estimate. The default is the usual data assimilation criterion named
- "DA", the augmented weighted least squares. The possible criteria has to be
- in the following list, where the equivalent names are indicated by the sign
- "=": ["AugmentedWeightedLeastSquares"="AWLS"="DA",
- "WeightedLeastSquares"="WLS", "LeastSquares"="LS"="L2",
- "AbsoluteValue"="L1", "MaximumError"="ME"]
-
+ Example :
+ ``{"GroupRecallRate":0.5}``
+
BoxBounds
This key allows to define upper and lower bounds for *increments* on every
state variable being optimized (and not on state variables themselves).
(``None`` is not allowed when there is no bound). This key is required and
there is no default values.
- 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 :
+ ``{"BoxBounds":[[-0.5,0.5], [0.01,2.], [0.,1.e99], [-1.e99,1.e99]]}``
- 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/SetSeed.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 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: ["BMA", "OMA", "OMB", "Innovation"].
+ are in the following list: ["BMA", "CostFunctionJ", "CostFunctionJb",
+ "CostFunctionJo", "CurrentState", "OMA", "OMB", "Innovation",
+ "SimulatedObservationAtBackground", "SimulatedObservationAtCurrentState",
+ "SimulatedObservationAtOptimum"].
+
+ 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
+
+ .. include:: snippets/CostFunctionJ.rst
+
+ .. include:: snippets/CostFunctionJb.rst
+
+ .. include:: snippets/CostFunctionJo.rst
+
+The conditional outputs of the algorithm are the following:
+
+ .. include:: snippets/BMA.rst
+
+ .. include:: snippets/CurrentState.rst
+
+ .. include:: snippets/Innovation.rst
+
+ .. include:: snippets/OMA.rst
+
+ .. include:: snippets/OMB.rst
+
+ .. include:: snippets/SimulatedObservationAtBackground.rst
+
+ .. include:: snippets/SimulatedObservationAtCurrentState.rst
+
+ .. include:: snippets/SimulatedObservationAtOptimum.rst
See also
++++++++
References to other sections:
+ - :ref:`section_ref_algorithm_DerivativeFreeOptimization`
+ - :ref:`section_ref_algorithm_DifferentialEvolution`
+
+Bibliographical references:
- [WikipediaPSO]_
