# pyribs¶

Website | Source | PyPI | Conda | CI/CD | Docs | Docs Status | |
---|---|---|---|---|---|---|---|

A *bare-bones* Python library for quality diversity optimization. pyribs is the official implementation of the Covariance Matrix Adaptation MAP-Elites (CMA-ME) algorithm and implements the *Rapid Illumination of Behavior Space (RIBS)* redesign of MAP-Elites detailed in the paper Covariance Matrix Adapation for the Rapid Illumination of Behavior Space.

## Overview¶

Quality diversity (QD) optimization is a subfield of optimization where solutions generated cover every point in a behavior space while simultaneously maximizing (or minimizing) a single objective. QD algorithms within the MAP-Elites family of QD algorithms produce heatmaps (archives) as output where each cell contains the best discovered representative of a region in behavior space.

While many QD libraries exist, this particular library aims to be the QD analog to the pycma library (a single objective optimization library). In contrast to other QD libraries, this library is “bare-bones,” meaning pyribs (like pycma) focuses solely on optimizing fixed-dimensional continuous domains. Focusing solely on this one commonly-occurring problem allows us to optimize the library for performance as well as simplicity of use. For applications of QD on discrete domains, we recommend using qdpy or sferes.

A user of pyribs selects three components that meet the needs of their application:

An

**Archive**saves the best representatives generated within behavior space.**Emitters**control how new candidate solutions are generated and affect if the algorithm prioritizes quality or diversity.An

**Optimizer**joins the**Archive**and**Emitters**together and acts as a scheduling algorithm for emitters. The**Optimizer**provides an interface for requesting new candidate solutions and telling the algorithm how candidates performed.

## Citation¶

If you use pyribs in your research, please cite it as follows. Note that you will need to include the hyperref package in order to use the `\url`

command.

```
@misc{pyribs,
title = {pyribs: A bare-bones Python library for quality diversity
optimization},
author = {Bryon Tjanaka and Matthew C. Fontaine and Yulun Zhang and
Sam Sommerer and Nathan Dennler and Stefanos Nikolaidis},
year = {2021},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/icaros-usc/pyribs}},
}
```

If you use the CMA-ME algorithm, please also cite Fontaine 2020.

```
@inproceedings{10.1145/3377930.3390232,
author = {Fontaine, Matthew C. and Togelius, Julian and Nikolaidis, Stefanos and Hoover, Amy K.},
title = {Covariance Matrix Adaptation for the Rapid Illumination of Behavior Space},
year = {2020},
isbn = {9781450371285},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3377930.3390232},
doi = {10.1145/3377930.3390232},
booktitle = {Proceedings of the 2020 Genetic and Evolutionary Computation Conference},
pages = {94–102},
numpages = {9},
location = {Canc\'{u}n, Mexico},
series = {GECCO '20}
}
```

## Usage¶

Here we show an example application of CMA-ME in pyribs. To initialize the algorithm, we first create:

A 2D

**GridArchive**where each dimension contains 20 bins across the range [-1, 1].An

**ImprovementEmitter**, which starts from the search point**0**in 10 dimensional space and a Gaussian sampling distribution with standard deviation 0.1.An

**Optimizer**that combines the archive and emitter together.

After initializing the components, we optimize (pyribs maximizes) the negative 10-D Sphere function for 1000 iterations. Users of pycma will be familiar with the ask-tell interface (which pyribs adopted). First, the user must `ask`

the optimizer for new candidate solutions. After evaluating the solution, they `tell`

the optimizer the objective value and behavior characteristics (BCs) of each candidate solution. The algorithm then populates the archive and makes decisions on where to sample solutions next. Our toy example uses the first two parameters of the search space as BCs.

```
import numpy as np
from ribs.archives import GridArchive
from ribs.emitters import ImprovementEmitter
from ribs.optimizers import Optimizer
archive = GridArchive([20, 20], [(-1, 1), (-1, 1)])
emitters = [ImprovementEmitter(archive, [0.0] * 10, 0.1)]
optimizer = Optimizer(archive, emitters)
for itr in range(1000):
solutions = optimizer.ask()
objectives = -np.sum(np.square(solutions), axis=1)
bcs = solutions[:, :2]
optimizer.tell(objectives, bcs)
```

To visualize this archive with matplotlib, we then use the `grid_archive_heatmap`

function from `ribs.visualize`

.

```
import matplotlib.pyplot as plt
from ribs.visualize import grid_archive_heatmap
grid_archive_heatmap(archive)
plt.show()
```

For more information, refer to the documentation.

## Installation¶

pyribs supports Python 3.6-3.9. Earlier Python versions may work but are not officially supported.

To install from PyPI, run

```
pip install ribs
```

This command only installs dependencies for the core of pyribs. To install support tools like `ribs.visualize`

, run

```
pip install ribs[all]
```

Equivalently, you can install the base version (equivalent to `ribs`

) from Conda with

```
conda install -c conda-forge pyribs-base
```

The full version (equivalent to `ribs[all]`

) can be installed with

```
conda install -c conda-forge pyribs
```

To test your installation, import it and print the version with:

```
python -c "import ribs; print(ribs.__version__)"
```

You should see a version number like `0.2.0`

in the output.

### From Source¶

To install a version from source, clone the repo

```
git clone https://github.com/icaros-usc/pyribs
```

Then `cd`

into it

```
cd pyribs
```

And run

```
pip install -e .[all]
```

## Documentation¶

See here for the documentation: https://docs.pyribs.org

To serve the documentation locally, clone the repo and install the development requirements with

```
pip install -e .[dev]
```

Then run

```
make servedocs
```

This will open a window in your browser with the documentation automatically loaded. Furthermore, every time you make changes to the documentation, the preview will also reload.

## Contributors¶

pyribs is developed and maintained by the ICAROS Lab at USC.

Nikitas Klapsis

We thank Amy K. Hoover and Julian Togelius for their contributions deriving the CMA-ME algorithm.

## License¶

pyribs is released under the MIT License.

## Credits¶

The pyribs package was initially created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.