doc/en/ref_algorithm_ParticleSwarmOptimization.rst

   1 ..
   2    Copyright (C) 2008-2014 EDF R&D
   3
   4    This file is part of SALOME ADAO module.
   5
   6    This library is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Lesser General Public
   8    License as published by the Free Software Foundation; either
   9    version 2.1 of the License, or (at your option) any later version.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with this library; if not, write to the Free Software
  18    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  19
  20    See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21
  22    Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
  23
  24 .. index:: single: ParticleSwarmOptimization
  25 .. _section_ref_algorithm_ParticleSwarmOptimization:
  26
  27 Calculation algorithm "*ParticleSwarmOptimization*"
  28 ---------------------------------------------------
  29
  30 Description
  31 +++++++++++
  32
  33 This algorithm realizes an estimation of the state of a dynamic system by a
  34 particle swarm.
  35
  36 This is an optimization method allowing for global minimum search of a general
  37 error function :math:`J` of type :math:`L^1`, :math:`L^2` or :math:`L^{\infty}`,
  38 with or without weights. The default error function is the augmented weighted
  39 least squares function, classicaly used in data assimilation.
  40
  41 Optional and required commands
  42 ++++++++++++++++++++++++++++++
  43
  44 .. index:: single: Background
  45 .. index:: single: BackgroundError
  46 .. index:: single: Observation
  47 .. index:: single: ObservationError
  48 .. index:: single: ObservationOperator
  49 .. index:: single: MaximumNumberOfSteps
  50 .. index:: single: NumberOfInsects
  51 .. index:: single: SwarmVelocity
  52 .. index:: single: GroupRecallRate
  53 .. index:: single: QualityCriterion
  54 .. index:: single: BoxBounds
  55 .. index:: single: SetSeed
  56 .. index:: single: StoreInternalVariables
  57 .. index:: single: StoreSupplementaryCalculations
  58
  59 The general required commands, available in the editing user interface, are the
  60 following:
  61
  62   Background
  63     *Required command*. This indicates the background or initial vector used,
  64     previously noted as :math:`\mathbf{x}^b`. Its value is defined as a
  65     "*Vector*" or a *VectorSerie*" type object.
  66
  67   BackgroundError
  68     *Required command*. This indicates the background error covariance matrix,
  69     previously noted as :math:`\mathbf{B}`. Its value is defined as a "*Matrix*"
  70     type object, a "*ScalarSparseMatrix*" type object, or a
  71     "*DiagonalSparseMatrix*" type object.
  72
  73   Observation
  74     *Required command*. This indicates the observation vector used for data
  75     assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
  76     is defined as a "*Vector*" or a *VectorSerie* type object.
  77
  78   ObservationError
  79     *Required command*. This indicates the observation error covariance matrix,
  80     previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
  81     object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
  82     type object.
  83
  84   ObservationOperator
  85     *Required command*. This indicates the observation operator, previously
  86     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
  87     results :math:`\mathbf{y}` to be compared to observations
  88     :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
  89     a "*Matrix*" type one. In the case of "*Function*" type, different
  90     functional forms can be used, as described in the section
  91     :ref:`section_ref_operator_requirements`. If there is some control :math:`U`
  92     included in the observation, the operator has to be applied to a pair
  93     :math:`(X,U)`.
  94
  95 The general optional commands, available in the editing user interface, are
  96 indicated in :ref:`section_ref_assimilation_keywords`. In particular, the
  97 optional command "*AlgorithmParameters*" allows to choose the specific options,
  98 described hereafter, of the algorithm. See
  99 :ref:`section_ref_options_AlgorithmParameters` for the good use of this command.
 100
 101 The options of the algorithm are the following:
 102
 103   MaximumNumberOfSteps
 104     This key indicates the maximum number of iterations allowed for iterative
 105     optimization. The default is 50, which is an arbitrary limit. It is then
 106     recommended to adapt this parameter to the needs on real problems.
 107
 108     Example : ``{"MaximumNumberOfSteps":100}``
 109
 110   NumberOfInsects
 111     This key indicates the number of insects or particles in the swarm. The
 112     default is 100, which is a usual default for this algorithm.
 113
 114     Example : ``{"NumberOfInsects":100}``
 115
 116   SwarmVelocity
 117     This key indicates the part of the insect velocity which is imposed by the
 118     swarm. It is a positive floating point value. The default value is 1.
 119
 120     Example : ``{"SwarmVelocity":1.}``
 121
 122   GroupRecallRate
 123     This key indicates the recall rate at the best swarm insect. It is a
 124     floating point value between 0 and 1. The default value is 0.5.
 125
 126     Example : ``{"GroupRecallRate":0.5}``
 127
 128   QualityCriterion
 129     This key indicates the quality criterion, minimized to find the optimal
 130     state estimate. The default is the usual data assimilation criterion named
 131     "DA", the augmented weighted least squares. The possible criteria has to be
 132     in the following list, where the equivalent names are indicated by the sign
 133     "=": ["AugmentedWeightedLeastSquares"="AWLS"="DA",
 134     "WeightedLeastSquares"="WLS", "LeastSquares"="LS"="L2",
 135     "AbsoluteValue"="L1", "MaximumError"="ME"].
 136
 137     Example : ``{"QualityCriterion":"DA"}``
 138
 139   BoxBounds
 140     This key allows to define upper and lower bounds for *increments* on every
 141     state variable being optimized (and not on state variables themselves).
 142     Bounds have to be given by a list of list of pairs of lower/upper bounds for
 143     each increment on variable, with extreme values every time there is no bound
 144     (``None`` is not allowed when there is no bound). This key is required and
 145     there is no default values.
 146
 147     Example : ``{"BoxBounds":[[-0.5,0.5],[0.01,2.],[0.,1.e99],[-1.e99,1.e99]]}``
 148
 149   SetSeed
 150     This key allow to give an integer in order to fix the seed of the random
 151     generator used to generate the ensemble. A convenient value is for example
 152     1000. By default, the seed is left uninitialized, and so use the default
 153     initialization from the computer.
 154
 155     Example : ``{"SetSeed":1000}``
 156
 157   StoreInternalVariables
 158     This Boolean key allows to store default internal variables, mainly the
 159     current state during iterative optimization process. Be careful, this can be
 160     a numerically costly choice in certain calculation cases. The default is
 161     "False".
 162
 163     Example : ``{"StoreInternalVariables":True}``
 164
 165   StoreSupplementaryCalculations
 166     This list indicates the names of the supplementary variables that can be
 167     available at the end of the algorithm. It involves potentially costly
 168     calculations or memory consumptions. The default is a void list, none of
 169     these variables being calculated and stored by default. The possible names
 170     are in the following list: ["BMA", "OMA", "OMB", "Innovation"].
 171
 172     Example : ``{"StoreSupplementaryCalculations":["BMA","Innovation"]}``
 173
 174 See also
 175 ++++++++
 176
 177 References to other sections:
 178   - [WikipediaPSO]_