Metadata-Version: 2.2
Name: cma
Version: 4.0.0
Summary: CMA-ES, Covariance Matrix Adaptation Evolution Strategy for non-linear numerical optimization in Python
Home-page: https://github.com/CMA-ES/pycma
Author: Nikolaus Hansen
Author-email: authors_firstname.lastname@inria.fr
Maintainer: Nikolaus Hansen
Maintainer-email: authors_firstname.lastname@inria.fr
License: BSD
Keywords: optimization,CMA-ES,cmaes
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Other Audience
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Framework :: IPython
Classifier: Framework :: Jupyter
Classifier: License :: OSI Approved :: BSD License
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy
Provides-Extra: plotting
Requires-Dist: matplotlib; extra == "plotting"
Provides-Extra: constrained-solution-tracking
Requires-Dist: moarchiving; extra == "constrained-solution-tracking"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: summary

Package `cma` implements the CMA-ES (Covariance Matrix Adaptation
Evolution Strategy).

CMA-ES is a stochastic optimizer for robust non-linear non-convex
derivative- and function-value-free numerical optimization.

This implementation can be used with Python versions >= 2.7, namely,
it was tested with 2.7, 3.5, 3.6, 3.7, 3.8.

CMA-ES searches for a minimizer (a solution x in :math:`R^n`) of an
objective function f (cost function), such that f(x) is minimal.
Regarding f, only a passably reliable ranking of the candidate
solutions in each iteration is necessary. Neither the function values
itself, nor the gradient of f need to be available or do matter (like
in the downhill simplex Nelder-Mead algorithm). Some termination
criteria however depend on actual f-values.

The `cma` module provides two independent implementations of the
CMA-ES algorithm in the classes `cma.CMAEvolutionStrategy` and
`cma.purecma.CMAES`.

In each implementation two interfaces are provided:

- functions `fmin2` and `purecma.fmin`:
    run a complete minimization of the passed objective function with
    CMA-ES. `fmin` also provides optional restarts and noise handling.

- class `CMAEvolutionStrategy` and `purecma.CMAES`:
    allow for minimization such that the control of the iteration
    loop remains with the user.

The `cma` package root provides shortcuts to these and other classes and
functions.

Used external packages are `numpy` (only `purecma` does not depend on
`numpy`) and `matplotlib.pyplot` (for `plot` etc., optional but highly
recommended).

Install
=======

To install the package from `PyPI`_ with `pip`_, type::

    pip install cma

from the command line.

To install the package from a ``cma`` folder::

    pip install -e cma

To upgrade the currently installed version use additionally the ``-U``
option.

To use the package `from source`_, only the source folder ``cma`` needs to
be visible in the python path, e.g. in the current working directory.


.. _PyPI: https://pypi.org/project/cma
.. _pip: https://pip.pypa.io
.. _from source: https://github.com/CMA-ES/pycma

Testing
=======
From the system shell::

    python -m cma.test -h
    python -m cma.test
    python -c "import cma.test; cma.test.main()"  # the same

or from any (i)python shell::

    import cma.test
    cma.test.main()

should run without complaints in about between 20 and 100 seconds.

Example
=======
From a python shell::

    import cma
    help(cma)  # "this" help message, use cma? in ipython
    help(cma.fmin)
    help(cma.CMAEvolutionStrategy)
    help(cma.CMAOptions)
    cma.CMAOptions('tol')  # display 'tolerance' termination options
    cma.CMAOptions('verb') # display verbosity options
    x, es = cma.fmin2(cma.ff.tablet, 15 * [1], 1)
    es = cma.CMAEvolutionStrategy(15 * [1], 1).optimize(cma.ff.tablet)
    help(es.result)
    x, es.result[0]  # best evaluated solution
    es.result[5]  # mean solution, presumably better with noise

:See also: `fmin` (), `CMAOptions`, `CMAEvolutionStrategy`

:Author: Nikolaus Hansen, 2008-
:Author: Petr Baudis, 2014
:Author: Youhei Akimoto, 2017-

:License: BSD 3-Clause, see LICENSE file.

