.. _CMAES:

================================================
CMAES
================================================

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
using the Covariance Matrix Adaptation Evolution Strategy (CMA-ES). This method is suitable
for the global minimization of inexpensive functions without known derivatives.

CMA-ES is an evolutionary algorithm [1]_. It draws its :math:`N` population members from a multivariate normal distribution :math:`\mathcal{N}(\mathbf{\mu}, \Sigma)` with mean vector :math:`\mathbf{\mu} \in \mathbb{R}^d` and covariance matrix :math:`\Sigma\in\mathbb{R}^{d\times d}` where :math:`d` is the dimensionality of the design space. After evaluating the objective value for each population member, it uses a weighted subset of :math:`M < N` members with the lowest objective values to update the mean :math:`\mathbf{\mu}` and covariance matrix :math:`\Sigma` for the next iteration.

Alternative drivers for the global minimization of **inexpensive** functions are :ref:`DifferentialEvolution` and the :ref:`ScipyMinimizer`. The CMA-ES driver is recommended if:

  * No gradient information are available.
  * The minimization is performed w.r.t. discrete and categorial design parameters.
  * The observations are subject to noise. In this case CMA-ES is specifically suitable since
    for the determination of the population mean and covariance, many samples are used such that
    effects of noise can average out.
  * The objective function does not have multiple well-separated local minima.
    Otherwise, the multivariate Gaussian distribution can either only focus on one minimum,
    or the mean vector lies between several local minima such that many samples will have
    bad objective values.

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


.. [1] Hansen N *The CMA evolution strategy: a comparing review*
       Towards a new evolutionary computation: Advances in the estimation of distribution
       algorithms 75-102 (2006).

       



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

   ../tutorials/benchmark



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

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

.. currentmodule:: jcmoptimizer
.. autoclass:: CMAES
   
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);


.. _CMAES.max_iter:


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

   Default: Infinite number of evaluations.

.. _CMAES.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``

.. _CMAES.num_parallel:


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

   Default: ``1``

.. _CMAES.min_val:


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

   Default: ``-inf``

.. _CMAES.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``

.. _CMAES.population_size:


population_size (int)
"""""""""""""""""""""
   The population size. 

   Default: Automatic choice :math:`4 + \lfloor 3 * \log(N)\rfloor` depending on problem dimension :math:`N`.

.. _CMAES.mean0:


mean0 (cell{float})
"""""""""""""""""""
   Initial mean vector of the multi-variate Gaussian  distribution of the population. For each new population this value is updated. If the study is continued, the latest updated value will be used and ``mean0`` is disregarded. 

   Default: Random choice.

.. _CMAES.sigma0:


sigma0 (float)
""""""""""""""
   Initial standard deviation of the population. The problem is internally rescaled such that all variables lie in the interval [0,1]. The standard deviation is defined on these rescaled variables. For each new population this value is updated. If the study is continued, the latest updated value will be used and ``sigma0`` is disregarded. 

   Default: ``0.4``