Metadata-Version: 2.1
Name: cmaes
Version: 0.5.1
Summary: Lightweight Covariance Matrix Adaptation Evolution Strategy (CMA-ES) implementation for Python 3.
Home-page: https://github.com/CyberAgent/cmaes
Author: Masashi Shibata
Author-email: shibata_masashi@cyberagent.co.jp
License: MIT License
Keywords: cma-es evolution-strategy optuna
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Intended Audience :: Science/Research
Description-Content-Type: text/markdown
Requires-Dist: numpy
Provides-Extra: benchmark
Requires-Dist: kurobako ; extra == 'benchmark'
Requires-Dist: cma ; extra == 'benchmark'
Requires-Dist: optuna ; extra == 'benchmark'
Provides-Extra: lint
Requires-Dist: mypy ; extra == 'lint'
Requires-Dist: flake8 ; extra == 'lint'
Requires-Dist: black ; extra == 'lint'
Requires-Dist: optuna ; extra == 'lint'
Provides-Extra: release
Requires-Dist: wheel ; extra == 'release'
Requires-Dist: twine ; extra == 'release'
Provides-Extra: test
Requires-Dist: optuna ; extra == 'test'
Provides-Extra: visualization
Requires-Dist: matplotlib ; extra == 'visualization'
Requires-Dist: scipy ; extra == 'visualization'

# CMA-ES

Lightweight Covariance Matrix Adaptation Evolution Strategy (CMA-ES) [1] implementation.

![visualize-six-hump-camel](https://user-images.githubusercontent.com/5564044/73486622-db5cff00-43e8-11ea-98fb-8246dbacab6d.gif)

<details>
<summary>Himmelblau function.</summary>

![visualize-himmelblau](https://user-images.githubusercontent.com/5564044/73486618-dac46880-43e8-11ea-8a2e-69d745f008b5.gif)

</details>

<details>
<summary>Rosenbrock function.</summary>

![visualize-rosenbrock](https://user-images.githubusercontent.com/5564044/73486620-dac46880-43e8-11ea-9295-ec0bfa774655.gif)

</details>

<details>
<summary>Quadratic function.</summary>

![visualize-quadratic](https://user-images.githubusercontent.com/5564044/73486619-dac46880-43e8-11ea-859d-5f8358ac8be9.gif)

</details>

These GIF animations are generated by [visualizer.py](./visualizer/visualizer.py).


## Installation

Supported Python versions are 3.5 or later.

```
$ pip install cmaes
```

Or you can install via [conda-forge](https://anaconda.org/conda-forge/cmaes).

```
$ conda install -c conda-forge cmaes
```

## Usage

This library provides two interfaces that an Optuna's sampler interface and a low-level interface.
I recommend you to use this library via Optuna.

### Optuna's sampler interface

[Optuna](https://github.com/optuna/optuna) [2] is an automatic hyperparameter optimization framework.
A sampler based on this library is available from [Optuna v1.3.0](https://github.com/optuna/optuna/releases/tag/v1.3.0).
Usage is like this:

```python
import optuna

def objective(trial: optuna.Trial):
    x1 = trial.suggest_uniform("x1", -4, 4)
    x2 = trial.suggest_uniform("x2", -4, 4)
    return (x1 - 3) ** 2 + (10 * (x2 + 2)) ** 2

if __name__ == "__main__":
    sampler = optuna.samplers.CmaEsSampler()
    study = optuna.create_study(sampler=sampler)
    study.optimize(objective, n_trials=250)
```

See [the documentation](https://optuna.readthedocs.io/en/stable/reference/samplers.html#optuna.samplers.CmaEsSampler) for more details.

<details>

<summary>Monkeypatch for faster CMA-ES sampler of Optuna v1.3.x.</summary>

If you are using Optuna v1.3.x, you can make `optuna.samplers.CmaEsSampler` faster.

```python
import optuna
from cmaes.monkeypatch import patch_fast_intersection_search_space

patch_fast_intersection_search_space()

def objective(trial: optuna.Trial):
    x1 = trial.suggest_float("x1", -4, 4)
    x2 = trial.suggest_float("x2", -4, 4)
    return (x1 - 3) ** 2 + (10 * (x2 + 2)) ** 2

if __name__ == "__main__":
    sampler = optuna.samplers.CmaEsSampler()
    study = optuna.create_study(sampler=sampler)
    study.optimize(objective, n_trials=250)
```

</details>

<details>

<summary>For older versions (Optuna v1.2.0 or older)</summary>

If you are using older versions, please use `cmaes.samlper.CMASampler`.

```python
import optuna
from cmaes.sampler import CMASampler

def objective(trial: optuna.Trial):
    x1 = trial.suggest_uniform("x1", -4, 4)
    x2 = trial.suggest_uniform("x2", -4, 4)
    return (x1 - 3) ** 2 + (10 * (x2 + 2)) ** 2

if __name__ == "__main__":
    sampler = CMASampler()
    study = optuna.create_study(sampler=sampler)
    study.optimize(objective, n_trials=250)
```

</details>

Note that CmaEsSampler doesn't support categorical distributions.
If your search space contains a categorical distribution, please use [TPESampler](https://optuna.readthedocs.io/en/latest/reference/samplers.html#optuna.samplers.TPESampler).

### Low-level interface

This library also provides an "ask-and-tell" style interface.

```python
import numpy as np
from cmaes import CMA

def quadratic(x1, x2):
    return (x1 - 3) ** 2 + (10 * (x2 + 2)) ** 2

if __name__ == "__main__":
    cma_es = CMA(mean=np.zeros(2), sigma=1.3)

    for generation in range(50):
        solutions = []
        for _ in range(cma_es.population_size):
            x = cma_es.ask()
            value = quadratic(x[0], x[1])
            solutions.append((x, value))
            print(f"#{generation} {value} (x1={x[0]}, x2 = {x[1]})")
        cma_es.tell(solutions)
```

## Benchmark results

| [Rosenbrock function](https://www.sfu.ca/~ssurjano/rosen.html) | [Six-Hump Camel function](https://www.sfu.ca/~ssurjano/camel6.html) |
| ------------------- | ----------------------- |
| ![rosenbrock](https://user-images.githubusercontent.com/5564044/73486735-0cd5ca80-43e9-11ea-9e6e-35028edf4ee8.png) | ![six-hump-camel](https://user-images.githubusercontent.com/5564044/73486738-0e9f8e00-43e9-11ea-8e65-d60fd5853b8d.png) |

This implementation (green) stands comparison with [pycma](https://github.com/CMA-ES/pycma) (blue).
See [benchmark](./benchmark) for details.

## Links

**Other libraries:**

I respect all libraries involved in CMA-ES.

* [pycma](https://github.com/CMA-ES/pycma) : Most famous CMA-ES implementation by Nikolaus Hansen.
* [libcmaes](https://github.com/beniz/libcmaes): Multithreaded C++11 library with Python bindings.
* [cma-es](https://github.com/srom/cma-es) : A Tensorflow v2 implementation.

**References:**

* [1] [N. Hansen, The CMA Evolution Strategy: A Tutorial. arXiv:1604.00772, 2016.](https://arxiv.org/abs/1604.00772)
* [2] [Takuya Akiba, Shotaro Sano, Toshihiko Yanase, Takeru Ohta, Masanori Koyama. 2019. Optuna: A Next-generation Hyperparameter Optimization Framework. In The 25th ACM SIGKDD Conference on Knowledge Discovery and Data Mining (KDD ’19), August 4–8, 2019.](https://dl.acm.org/citation.cfm?id=3330701)



