doc/en/ref_algorithm_ParticleSwarmOptimization.rst

   1 ..
   2    Copyright (C) 2008-2018 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 system by minimization
  34 of a cost function :math:`J` by using an evolutionary strategy of particle
  35 swarm. It is a method that does not use the derivatives of the cost function.
  36 It falls in the same category than the
  37 :ref:`section_ref_algorithm_DerivativeFreeOptimization` or the
  38 :ref:`section_ref_algorithm_DifferentialEvolution`.
  39
  40 This is an optimization method allowing for global minimum search of a general
  41 error function :math:`J` of type :math:`L^1`, :math:`L^2` or :math:`L^{\infty}`,
  42 with or without weights. The default error function is the augmented weighted
  43 least squares function, classically used in data assimilation.
  44
  45 Optional and required commands
  46 ++++++++++++++++++++++++++++++
  47
  48 The general required commands, available in the editing user interface, are the
  49 following:
  50
  51   .. include:: snippets/Background.rst
  52
  53   .. include:: snippets/BackgroundError.rst
  54
  55   .. include:: snippets/Observation.rst
  56
  57   .. include:: snippets/ObservationError.rst
  58
  59   .. include:: snippets/ObservationOperator.rst
  60
  61 The general optional commands, available in the editing user interface, are
  62 indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters
  63 of the command "*AlgorithmParameters*" allows to choose the specific options,
  64 described hereafter, of the algorithm. See
  65 :ref:`section_ref_options_Algorithm_Parameters` for the good use of this
  66 command.
  67
  68 The options of the algorithm are the following:
  69 .. index:: single: NumberOfInsects
  70 .. index:: single: SwarmVelocity
  71 .. index:: single: GroupRecallRate
  72 .. index:: single: QualityCriterion
  73 .. index:: single: BoxBounds
  74
  75   .. include:: snippets/MaximumNumberOfSteps_50.rst
  76
  77   .. include:: snippets/MaximumNumberOfFunctionEvaluations.rst
  78
  79   .. include:: snippets/QualityCriterion.rst
  80
  81   NumberOfInsects
  82     This key indicates the number of insects or particles in the swarm. The
  83     default is 100, which is a usual default for this algorithm.
  84
  85     Example :
  86     ``{"NumberOfInsects":100}``
  87
  88   SwarmVelocity
  89     This key indicates the part of the insect velocity which is imposed by the
  90     swarm. It is a positive floating point value. The default value is 1.
  91
  92     Example :
  93     ``{"SwarmVelocity":1.}``
  94
  95   GroupRecallRate
  96     This key indicates the recall rate at the best swarm insect. It is a
  97     floating point value between 0 and 1. The default value is 0.5.
  98
  99     Example :
 100     ``{"GroupRecallRate":0.5}``
 101
 102   BoxBounds
 103     This key allows to define upper and lower bounds for *increments* on every
 104     state variable being optimized (and not on state variables themselves).
 105     Bounds have to be given by a list of list of pairs of lower/upper bounds for
 106     each increment on variable, with extreme values every time there is no bound
 107     (``None`` is not allowed when there is no bound). This key is required and
 108     there is no default values.
 109
 110     Example :
 111     ``{"BoxBounds":[[-0.5,0.5], [0.01,2.], [0.,1.e99], [-1.e99,1.e99]]}``
 112
 113   .. include:: snippets/SetSeed.rst
 114
 115   StoreSupplementaryCalculations
 116     .. index:: single: StoreSupplementaryCalculations
 117
 118     This list indicates the names of the supplementary variables that can be
 119     available at the end of the algorithm. It involves potentially costly
 120     calculations or memory consumptions. The default is a void list, none of
 121     these variables being calculated and stored by default. The possible names
 122     are in the following list: ["BMA", "CostFunctionJ", "CostFunctionJb",
 123     "CostFunctionJo", "CurrentState", "OMA", "OMB", "Innovation",
 124     "SimulatedObservationAtBackground", "SimulatedObservationAtCurrentState",
 125     "SimulatedObservationAtOptimum"].
 126
 127     Example :
 128     ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}``
 129
 130 Information and variables available at the end of the algorithm
 131 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 132
 133 At the output, after executing the algorithm, there are variables and
 134 information originating from the calculation. The description of
 135 :ref:`section_ref_output_variables` show the way to obtain them by the method
 136 named ``get`` of the variable "*ADD*" of the post-processing. The input
 137 variables, available to the user at the output in order to facilitate the
 138 writing of post-processing procedures, are described in the
 139 :ref:`subsection_r_o_v_Inventaire`.
 140
 141 The unconditional outputs of the algorithm are the following:
 142
 143   .. include:: snippets/Analysis.rst
 144
 145   .. include:: snippets/CostFunctionJ.rst
 146
 147   .. include:: snippets/CostFunctionJb.rst
 148
 149   .. include:: snippets/CostFunctionJo.rst
 150
 151 The conditional outputs of the algorithm are the following:
 152
 153   .. include:: snippets/BMA.rst
 154
 155   .. include:: snippets/CurrentState.rst
 156
 157   .. include:: snippets/Innovation.rst
 158
 159   .. include:: snippets/OMA.rst
 160
 161   .. include:: snippets/OMB.rst
 162
 163   .. include:: snippets/SimulatedObservationAtBackground.rst
 164
 165   .. include:: snippets/SimulatedObservationAtCurrentState.rst
 166
 167   .. include:: snippets/SimulatedObservationAtOptimum.rst
 168
 169 See also
 170 ++++++++
 171
 172 References to other sections:
 173   - :ref:`section_ref_algorithm_DerivativeFreeOptimization`
 174   - :ref:`section_ref_algorithm_DifferentialEvolution`
 175
 176 Bibliographical references:
 177   - [WikipediaPSO]_