ribs 0.4.0

A bare-bones Python library for quality diversity optimization.

pyribs

Website	Source	PyPI	Conda	CI/CD	Docs	Docs Status	Twitter
pyribs.org	GitHub				docs.pyribs.org

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.

• Bryon Tjanaka
• Matt Fontaine
• Yulun Zhang
• Sam Sommerer
• Nathan Dennler
• Nikitas Klapsis
• Stefanos Nikolaidis

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.

History

0.4.0 (2021-07-19)

To learn about this release, see our blog post: https://pyribs.org/blog/0-4-0

Changelog

API

• Add ribs.visualize.parallel_axes_plot for analyzing archives with high-dimensional BCs (#92)
• Backwards-incompatible: Reduce attributes and parameters in EmitterBase to make it easier to extend (#101)
• In Optimizer, support emitters that return any number of solutions in ask() (#101)
• Backwards-incompatible: Store metadata in archives as described in #87 (#103, #114, #115, #119)
• Backwards-incompatible: Rename "index" to "index_0" in CVTArchive.as_pandas for API consistency (#113)
• Backwards-incompatible: Make get_index() public in archives to emphasize each index's meaning (#128)
• Backwards-incompatible: Add index to get_random_elite() and elite_with_behavior() in archives (#129)
• Add clear() method to archive (#140, #146)
• Represent archive elites with an Elite namedtuple (#142)
• Add len and iter methods to archives (#151, #152)
• Add statistics to archives (#100, #157)
• Improve manipulation of elites by modifying as_pandas (#123, #149, #153, #158, #168)
• Add checks for optimizer array and list shapes (#166)

Documentation

• Add bibtex citations for tutorials (#122)
• Remove network training from Fooling MNIST tutorial (#161)
• Fix video display for lunar lander in Colab (#163)
• Fix Colab links in stable docs (#164)

Improvements

• Add support for Python 3.9 (#84)
• Test with pinned versions (#110)
• Increase minimum required versions for scipy and numba (#110)
• Refactor as_pandas tests (#114)
• Expand CI/CD to test examples and tutorials (#117)
• Tidy up existing tests (#120, #127)
• Fix vocab in various areas (#138)
• Fix dependency issues in tests (#139)
• Remove tox from CI (#143)
• Replace "entry" with "elite" in tests (#144)
• Use new archive API in ribs.visualize implementation (#155)

0.3.1 (2021-03-05)

This release features various bug fixes and improvements. In particular, we have added tests for SlidingBoundariesArchive and believe it is ready for more rigorous use.

Changelog

• Move SlidingBoundariesArchive out of experimental by adding tests and fixing bugs (#93)
• Added nicer figures to the Sphere example with grid_archive_heatmap (#86)
• Added testing for Windows and MacOS (#83)
• Fixed package metadata e.g. description

0.3.0 (2021-02-05)

pyribs is now in beta. Since our alpha release (0.2.0), we have polished the library and added new tutorials and examples to our documentation.

Changelog

• Added a Lunar Lander example that extends the lunar lander tutorial (#70)
• Added New Tutorial: Illuminating the Latent Space of an MNIST GAN (#78)
• GridArchive: Added a boundaries attribute with the upper and lower bounds of each dimension's bins (#76)
• Fixed a bug where CMA-ME emitters do not work with float32 archives (#74)
• Fixed a bug where Optimizer is able to take in non-unique emitter instances (#75)
• Fixed a bug where GridArchive failed for float32 due to a small epsilon (#81)
• Fix issues with bounds in the SlidingBoundaryArchive (#77)
• Added clearer error messages for archives (#82)
• Modified the Python requirements to allow any version above 3.6.0 (#68)
• The wheel is now fixed so that it only supports py3 rather than py2 and py3 (#68)
• Miscellaneous documentation fixes (#71)

0.2.0 (2021-01-29)

• Alpha release

0.2.1 (2021-01-29)

• Package metadata fixes (author, email, url)
• Miscellaneous documentation improvements

0.1.1 (2021-01-29)

• Test release (now removed)

0.1.0 (2020-09-11)

• Test release (now removed)

0.0.0 (2020-09-11)

• pyribs begins