ribs 0.5.1

A bare-bones Python library for quality diversity optimization.

pyribs

Website	Source	Docs	Paper	Twitter
pyribs.org	GitHub	docs.pyribs.org	pyribs.org/paper

PyPI	Conda	CI/CD	Docs Status

A bare-bones Python library for quality diversity (QD) optimization. Pyribs implements the highly modular Rapid Illumination of Behavior Space (RIBS) framework for QD optimization. Pyribs is also the official implementation of Covariance Matrix Adaptation MAP-Elites (CMA-ME), Covariance Matrix Adaptation MAP-Elites via a Gradient Arborescence (CMA-MEGA), Covariance Matrix Adaptation MAP-Annealing (CMA-MAE), and scalable variants of CMA-MAE.

Overview

Quality diversity (QD) optimization is a subfield of optimization where solutions generated cover every point in a measure 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 measure space.

In the QD literature, measure function outputs have also been referred to as "behavioral characteristics," "behavior descriptors," or "feature descriptors."

Recent years have seen the development of a large number of QD algorithms. To represent these and future algorithms, we have developed the highly modular RIBS framework. RIBS divides a QD algorithm into three components:

• An archive, which saves generated solutions within measure space.
• One or more emitters, where each emitter is an algorithm which generates new candidate solutions and responds to feedback about how the solutions were evaluated and how they were inserted into the archive.
• A scheduler which controls the interaction of the archive and emitters. The scheduler also provides an interface for requesting new candidate solutions and telling the algorithm how candidates performed.

By interchanging these components, a user can compose a large number of QD algorithms.

Pyribs is an implementation of the RIBS framework designed to support a wide range of users, from beginners entering the field to experienced researchers seeking to develop new algorithms. Pyribs achieves these goals by embodying three principles:

• Simple: Centered only on components that are absolutely necessary to run a QD algorithm, allowing users to combine the framework with other software frameworks.
• Flexible: Capable of representing a wide range of current and future QD algorithms, allowing users to easily create or modify components.
• Accessible: Easy to install and learn, particularly for beginners with limited computational resources.

In contrast to other QD libraries, pyribs is "bare-bones." For example, like pycma, pyribs focuses solely on optimizing fixed-dimensional continuous domains. Focusing on this one commonly-occurring problem allows us to optimize the library for performance as well as ease of use. Refer to the list of additional QD libraries below if you need greater performance or have additional use cases.

Following the RIBS framework (shown in the figure below), a standard algorithm in pyribs operates as follows:

1. The user calls the ask() method on the scheduler. The scheduler requests solutions from each emitter by calling the emitter's ask() method.
2. The user evaluates solutions to obtain the objective and measure values.
3. The user passes the evaluations to the scheduler's tell() method. The scheduler adds the solutions into the archive and receives feedback. The scheduler passes this feedback along with the evaluated solutions to each emitter's tell() method, and each emitter then updates its internal state.

Paper

Two years after the initial release of pyribs, we released a paper which elaborates on the RIBS framework and the design decisions behind pyribs! For more information on this paper, see here.

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. Also consider citing any algorithms you use as shown below.

@misc{pyribs,
  title={pyribs: A Bare-Bones Python Library for Quality Diversity Optimization},
  author={Bryon Tjanaka and Matthew C. Fontaine and David H. Lee and Yulun Zhang and Nivedit Reddy Balam and Nathaniel Dennler and Sujay S. Garlanka and Nikitas Dimitri Klapsis and Stefanos Nikolaidis},
  year={2023},
  eprint={2303.00191},
  archivePrefix={arXiv},
  primaryClass={cs.NE}
}

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 cells across the range [-1, 1].
• Three instances of EvolutionStrategyEmitter, all of which start from the search point 0 in 10-dimensional space and a Gaussian sampling distribution with standard deviation 0.1.
• A Scheduler that combines the archive and emitters 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 scheduler for new candidate solutions. After evaluating the solution, they tell the scheduler the objectives and measures 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 measures.

import numpy as np

from ribs.archives import GridArchive
from ribs.emitters import EvolutionStrategyEmitter
from ribs.schedulers import Scheduler

archive = GridArchive(
    solution_dim=10,
    dims=[20, 20],
    ranges=[(-1, 1), (-1, 1)],
)
emitters = [
    EvolutionStrategyEmitter(
        archive,
        x0=[0.0] * 10,
        sigma0=0.1,
    ) for _ in range(3)
]
scheduler = Scheduler(archive, emitters)

for itr in range(1000):
    solutions = scheduler.ask()

    # Optimize the 10D negative Sphere function.
    objective_batch = -np.sum(np.square(solutions), axis=1)

    # Measures: first 2 coordinates of each 10D solution.
    measures_batch = solutions[:, :2]

    scheduler.tell(objective_batch, measures_batch)

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.7 and above. Earlier Python versions may work but are not officially supported. To find the installation command for your system (including for installing from source), visit the installation selector on our website.

To test your installation, import pyribs and print the version with this command:

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

You should see a version number in the output.

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. For information on contributing to the repo, see CONTRIBUTING.

• Bryon Tjanaka
• Matthew C. Fontaine
• David H. Lee
• Yulun Zhang
• Nivedit Reddy Balam
• Nathan Dennler
• Sujay S. Garlanka
• Nikitas Klapsis
• Robby Costales
• Sam Sommerer
• Vincent Vu
• Stefanos Nikolaidis

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

Users

pyribs users include:

• Adam Gaier (Autodesk Research)
• Adaptive & Intelligent Robotics Lab (Imperial College London)
• Chair of Statistical Learning and Data Science (LMU Munich)
• Game Innovation Lab (New York University)
• Giovanni Iacca (University of Trento)
• HUAWEI Noah's Ark Lab
• ICAROS Lab (University of Southern California)
• Jacob Schrum (Southwestern University)
• Lenia Research
• Paul Kent (The University of Warwick)
• Various researchers at the University of Tsukuba

Publications

For the list of publications which use pyribs, refer to our Google Scholar entry.

Software

See the GitHub dependency graph for the public GitHub repositories which depend on pyribs.

Citing Algorithms in pyribs

If you use the following algorithms, please also cite their relevant papers:

• CMA-ME: 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}
  }
  

• CMA-MEGA: Fontaine 2021

  @inproceedings{NEURIPS2021_532923f1,
   author = {Fontaine, Matthew and Nikolaidis, Stefanos},
   booktitle = {Advances in Neural Information Processing Systems},
   editor = {M. Ranzato and A. Beygelzimer and Y. Dauphin and P.S. Liang and J. Wortman Vaughan},
   pages = {10040--10052},
   publisher = {Curran Associates, Inc.},
   title = {Differentiable Quality Diversity},
   url = {https://proceedings.neurips.cc/paper/2021/file/532923f11ac97d3e7cb0130315b067dc-Paper.pdf},
   volume = {34},
   year = {2021}
  }
  

• CMA-MAE: Fontaine 2022

  @misc{cmamae,
    doi = {10.48550/ARXIV.2205.10752},
    url = {https://arxiv.org/abs/2205.10752},
    author = {Fontaine, Matthew C. and Nikolaidis, Stefanos},
    keywords = {Machine Learning (cs.LG), Artificial Intelligence (cs.AI), FOS: Computer and information sciences, FOS: Computer and information sciences},
    title = {Covariance Matrix Adaptation MAP-Annealing},
    publisher = {arXiv},
    year = {2022},
    copyright = {arXiv.org perpetual, non-exclusive license}
  }
  

• Scalable CMA-MAE: Tjanaka 2022

  @misc{scalablecmamae,
        title={Training Diverse High-Dimensional Controllers by Scaling Covariance Matrix Adaptation MAP-Annealing},
        author={Bryon Tjanaka and Matthew C. Fontaine and Aniruddha Kalkar and Stefanos Nikolaidis},
        year={2022},
        eprint={2210.02622},
        archivePrefix={arXiv},
        primaryClass={cs.RO}
  }
  

Additional QD Libraries

• QDax: Implementations of QD algorithms in JAX. QDax is suitable if you want to run entire QD algorithms on hardware accelerators in a matter of minutes, and it is particularly useful if you need to interface with Brax environments.
• qdpy: Python implementations of a wide variety of QD algorithms.
• sferes: Contains C++ implementations of QD algorithms; can also handle discrete domains.

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.5.1

This release contains miscellaneous edits to our documentation from v0.5.0. There were no changes to library functionality in this release.

0.5.0

To learn about this release, see our page on What's New in v0.5.0: https://docs.pyribs.org/en/stable/whats-new.html

Changelog

API

• Schedulers warn if no solutions are inserted into archive (#320)
• Implement BanditScheduler (#299)
• Backwards-incompatible: Implement Scalable CMA-ES Optimizers (#274, #288)
• Make ribs.emitters.opt public (#281)
• Add normalized QD score to ArchiveStats (#276)
• Backwards-incompatible: Make ArchiveStats a dataclass (#275)
• Backwards-incompatible: Add shape checks to tell() and tell_dqd() methods (#269)
• Add method for computing CQD score in archives (#252)
• Backwards-incompatible: Deprecate positional arguments in constructors (#261)
• Backwards-incompatible: Allow custom initialization in Gaussian and IsoLine emitters (#259, #265)
• Implement CMA-MAE archive thresholds (#256, #260, #314)
  • Revive the old implementation of add_single removed in (#221)
  • Add separate tests for add_single and add with single solution
• Fix all examples and tutorials (#253)
• Add restart timer to EvolutionStrategyEmitter and GradientArborescenceEmitter(#255)
• Rename fields and update documentation (#249, #250)
  • Backwards-incompatible: rename Optimizer to Scheduler
  • Backwards-incompatible: rename objective_value to objective
  • Backwards-incompatible: rename behavior_value/bcs to measures
  • Backwards-incompatible: behavior_dim in archives is now measure_dim
  • Rename n_solutions to batch_size in Scheduler.
• Add GradientArborescenceEmitter, which is used to implement CMA-MEGA (#240, #263, #264, #282, #321)
• Update emitter tell() docstrings to no longer say "Inserts entries into archive" (#247)
• Expose emitter.restarts as a property (#248)
• Specify that x0 is 1D for all emitters (#244)
• Add best_elite property for archives (#237)
• Rename methods in ArchiveDataFrame and rename as_pandas behavior columns (#236)
• Re-run CVTArchive benchmarks and update CVTArchive (#235, #329)
  • Backwards-incompatible: use_kd_tree now defaults to True since the k-D tree is always faster than brute force in benchmarks.
• Allow adding solutions one at a time in optimizer (#233)
• Minimize numba usage (#232)
• Backwards-incompatible: Implement batch addition in archives (#221, #242)
  • add now adds a batch of solutions to the archive
  • add_single adds a single solution
• emitter.tell now takes in status_batch and value_batch (#227)
• Make epsilon configurable in archives (#226)
• Backwards-incompatible: Remove ribs.factory (#225, #228)
• Backwards-incompatible: Replaced ImprovementEmitter, RandomDirectionEmitter, and OptimizingEmitter with EvolutionStrategyEmitter (#220, #223, #278)
• Raise ValueError for incorrect array shapes in archive methods (#219)
• Introduced the Ranker object, which is responsible for ranking the solutions based on different objectives (#209, #222, #245)
• Add index_of_single method for getting index of measures for one solution (#214)
• Backwards-incompatible: Replace elite_with_behavior with retrieve and retrieve_single in archives (#213, #215, #295)
• Backwards-incompatible: Replace get_index with batched index_of method in archives (#208)
  • Also added grid_to_int_index and int_to_grid_index methods for GridArchive and SlidingBoundariesArchive
• Backwards-incompatible: Made it such that each archive is initialized fully in its constructor instead of needing a separate .initialize(solution_dim) call (#200)
• Backwards-incompatible: Add sigma, sigma0 options to gaussian_emitter and iso_line_emitter (#199)
  • gaussian_emitter constructor requires sigma; sigma0 is optional.
  • iso_line_emitter constructor takes in optional parameter sigma0.
• Backwards-incompatible: Add cbar, aspect options for cvt_archive_heatmap (#197)
• Backwards-incompatible: Add aspect option to grid_archive_heatmap + support for 1D heatmaps (#196)
  • square option no longer works
• Backwards-incompatible: Add cbar option to grid_archive_heatmap (#193)
• Backwards-incompatible: Replace get_random_elite() with batched sample_elites() method (#192)
• Backwards-incompatible: Add EliteBatch and rename fields in Elite (#191)
• Backwards-incompatible: Rename bins to cells for consistency with literature (#189)
  • Archive constructors now take in cells argument instead of bins
  • Archive now have a cells property rather than a bins property
• Backwards-incompatible: Only use integer indices in archives (#185)
  • ArchiveBase
    • Replaced storage_dims (tuple of int) with storage_dim (int)
    • _occupied_indices is now a fixed-size array with _num_occupied indicating its current usage, and _occupied_indices_cols has been removed
    • index_of must now return an integer

Bugs

• Fix boundary lines in sliding boundaries archive heatmap (#271)
• Fix negative eigenvalue in CMA-ES covariance matrix (#285)

Documentation

• Speed up lunar lander tutorial (#319)
• Add DQDTutorial (#267)
• Remove examples extra in favor of individual example deps (#306)
• Facilitate linking to latest version of documentation (#300)
• Update lunar lander tutorial with v0.5.0 features (#292)
• Improve tutorial and example overviews (#291)
• Move tutorials out of examples folder (#290)
• Update lunar lander to use Gymnasium (#289)
• Add CMA-MAE tutorial (#273, #284)
• Update README (#279)
• Add sphinx-codeautolink to docs (#206, #280)
• Fix documentation rendering issues on ReadTheDocs (#205)
• Fix typos and formatting in docstrings of ribs/visualize.py (#203)
• Add in-comment type hint rich linking (#204)
• Upgrade Sphinx dependencies (#202)

Improvements

• Move threadpoolctl from optimizer to CMA-ES (#241)
• Remove unnecessary emitter benchmarks (#231)
• Build docs during CI/CD workflow (#211)
• Drop Python 3.6 and add Python 3.10 support (#181)
• Add procedure for updating changelog (#182)
• Add 'visualize' extra (#183, #184, #302)

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 index_of() 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