.. _DifferentialEvolution:

================================================
DifferentialEvolution
================================================

Contents
=========

:`Purpose`_: The purpose of the driver.
:`Tutorials`_: Tutorials demonstrating the application of this driver.
:`Driver Interface`_: Driver-specific methods of the Matlab interface.
:`Configuration`_: Configuration of the driver.                   


Purpose
=======


The driver minimizes scalar function of one or more variables
based on the Differential Evolution (DE) method. This method is suitable
for the global minimization of inexpensive functions without known derivatives.

Differential Evolution (DE) is an evolutionary optimization algorithm inspired by the mutation, crossover and selection processes occurring in nature [1]_. In the mutation step, for each member :math:`\mathbf{p}_i` of the population, a mutated genome is created as :math:`\mathbf{p}_{\rm mut} = \mathbf{a} + F(\mathbf{b} - \mathbf{c})`, where :math:`F` is the differential weight and :math:`\mathbf{a}, \mathbf{b}, \mathbf{c}` are distinct randomly selected population members. Random entries of :math:`\mathbf{p}_i`, selected according to a crossover probability, are replaced with the mutated genome :math:`\mathbf{p}_{\rm mut}`, forming a new candidate. The candidate replaces :math:`\mathbf{p}_i` in the next population if its objective value is lower.

Alternative drivers for the global minimization of **inexpensive** functions are :ref:`CMAES` and the :ref:`ScipyMinimizer`. The Differential Evolution driver is recommended if:

  * No gradient information are available.
  * The objective function has potentially many well-separated local minima.

For **expensive** objectives with evaluation times larger than a few seconds, the :ref:`ActiveLearning` driver is recommended.


.. [1] Das S and Suganthan P N *Differential evolution: A survey of the state-of-the-art*
       IEEE transactions on evolutionary computation **15** 4-31 (2010).




Tutorials
=========
.. toctree::

   ../tutorials/differential_evolution

   ../tutorials/benchmark



Driver Interface
================

The driver instance can be obtained by :attr:`.Study.driver`.

.. currentmodule:: jcmoptimizer
.. autoclass:: DifferentialEvolution
   
best_sample
"""""""""""""""""""""""""""""""""""
   .. automethod:: Minimizer.best_sample
      :noindex:
		     
   
describe
"""""""""""""""""""""""""""""""""""
   .. automethod:: Driver.describe
      :noindex:
		     
   
get_state
"""""""""""""""""""""""""""""""""""
   .. automethod:: Driver.get_state
      :noindex:
		     
   
historic_parameter_values
"""""""""""""""""""""""""""""""""""
   .. automethod:: Driver.historic_parameter_values
      :noindex:
		     
   
min_objective
"""""""""""""""""""""""""""""""""""
   .. automethod:: Minimizer.min_objective
      :noindex:
		     
   

   



Configuration
=============
The configuration parameters can be set by calling, e.g.


.. code-block:: matlab

   study.configure('example_parameter1',[1,2,3], 'example_parameter2',true);


The driver allows to run :ref:`num_initial<DifferentialEvolution.num_initial>` minimizations starting from multiple :ref:`initial samples <DifferentialEvolution.initial_samples>` in parallel. Only continous design parameters are minimized while discrete and categorial parameters are fixed to the values of the initial samples.

.. _DifferentialEvolution.max_iter:


max_iter (int)
""""""""""""""
   Maximum number of evaluations of the studied system. 

   Default: Infinite number of evaluations.

.. _DifferentialEvolution.max_time:


max_time (float)
""""""""""""""""
   Maximum run time of study in seconds.  The time is counted from the moment, that the parameter is set or reset. 

   Default: ``inf``

.. _DifferentialEvolution.num_parallel:


num_parallel (int)
""""""""""""""""""
   Number of parallel evaluations of the studied system. 

   Default: ``1``

.. _DifferentialEvolution.min_val:


min_val (float)
"""""""""""""""
   The minimization is stopped when the observed objective value is below the specified minimum value. 

   Default: ``-inf``

.. _DifferentialEvolution.min_step:


min_step (float)
""""""""""""""""
   The minimization is stopped when the Eucledian distance between consecutive sampling points in the design parameter space is below the specified value. 

   Default: ``0.0``

.. _DifferentialEvolution.num_initial:


num_initial (int)
"""""""""""""""""
   Number of independent initial optimizers. 

   Default: ``1``

.. _DifferentialEvolution.max_num_optimizers:


max_num_optimizers (int)
""""""""""""""""""""""""
   If an optimizer has converged, it is restarted at another position. If ``max_num_optimizers`` have converged, the optimization is stopped. 

   Default: Infinite number of optimizers.

.. _DifferentialEvolution.initial_samples:


initial_samples (cell{cell})
""""""""""""""""""""""""""""
   List of initial samples each with dimension of the design space. The role of the initial samples is twofold. First, they are regarded as initial guess to the minimization. Once the ``num_initial`` populations have been initialized these samples replace the first (best) member. Second, if the design space contains discrete or categorial parameters, they can be specified for each DE minimizer by the value of the initial samples. If ``num_initial > len(initial_samples)`` the rest of the initial populations is chosen randomly. 

   Default: ``{}``

.. _DifferentialEvolution.sobol_sequence:


sobol_sequence (bool)
"""""""""""""""""""""
   If true, all initial samples are taken from a Sobol sequence. This typically improves the coverage of the parameter space. 

   Default: ``true``

.. _DifferentialEvolution.popsize_multiplier:


popsize_multiplier (int)
""""""""""""""""""""""""
   A multiplier for setting the total population size. The population has popsize * len(x) individuals. 

   Default: ``15``

.. _DifferentialEvolution.tol:


tol (float)
"""""""""""
   The optimizer stops when the mean of the population  energies (objective function values), multiplied by tol is larger than  the standard deviation of the population energies. 

   Default: ``0.0``

.. _DifferentialEvolution.strategy:


strategy (str)
""""""""""""""
   The differential evolution strategy to use. 

   Default: ``"best1bin"``
   Choices: ``"best1bin"``, ``"best1exp"``, ``"rand1exp"``, ``"randtobest1exp"``, ``"best2exp"``, ``"rand2exp"``, ``"randtobest1bin"``, ``"best2bin"``, ``"rand2bin"``, ``"rand1bin"``.

.. _DifferentialEvolution.mutation:


mutation (cell{float})
""""""""""""""""""""""
   Controls the range of the mutation constant also known as differential weight, being denoted by F. The entries should be in the range [0, 2]. The mutation constant is changed randomly on a generation by generation basis. The mutation constant for that generation is taken from U[min, max). This dithering can help speed convergence significantly.  Increasing the mutation constant increases the search radius, but will slow down convergence. 

   Default: ``{0.5,1}``

.. _DifferentialEvolution.recombination:


recombination (float)
"""""""""""""""""""""
   The recombination constant, should be in the range [0, 1].  In the literature this is also known as the crossover probability, being  denoted by CR. Increasing this value allows a larger number of mutants  to progress into the next generation, but at the risk of population  stability. 

   Default: ``0.7``