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