Metadata-Version: 2.1
Name: ribs
Version: 0.4.0
Summary: A bare-bones Python library for quality diversity optimization.
Home-page: https://github.com/icaros-usc/pyribs
Author: ICAROS Lab pyribs Team
Author-email: team@pyribs.org
License: MIT license
Keywords: ribs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.7.0
Description-Content-Type: text/markdown
Provides-Extra: visualize
Provides-Extra: examples
Provides-Extra: dev
License-File: LICENSE

# pyribs

|             Website              |                     Source                     |                                                       PyPI                                                        |                                                               Conda                                                                |                                                                                                      CI/CD                                                                                                       |                    Docs                    |                                                                   Docs Status                                                                    |                                                                   Twitter                                                                    |
| :------------------------------: | :--------------------------------------------: | :---------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------: |
| [pyribs.org](https://pyribs.org) | [GitHub](https://github.com/icaros-usc/pyribs) | [![PyPI](https://img.shields.io/pypi/v/ribs.svg?style=flat-square&color=blue)](https://pypi.python.org/pypi/ribs) | [![Conda Recipe](https://img.shields.io/badge/recipe-pyribs-green.svg?style=flat-square)](https://anaconda.org/conda-forge/pyribs) | [![Tests](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Ficaros-usc%2Fpyribs%2Fbadge&style=flat-square)](https://github.com/icaros-usc/pyribs/actions?query=workflow%3A"Tests") | [docs.pyribs.org](https://docs.pyribs.org) | [![Documentation Status](https://readthedocs.org/projects/ribs/badge/?version=stable&style=flat-square)](https://readthedocs.org/projects/ribs/) | [![Twitter](https://img.shields.io/badge/twitter-%231DA1F2.svg?&style=flat-square&logo=twitter&logoColor=white)](https://twitter.com/pyribs) |

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](https://arxiv.org/abs/1912.02400).

## Overview

![Types of Optimization](readme_assets/optimization_types.png)

[Quality diversity (QD) optimization](https://arxiv.org/abs/2012.04322) 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
> "behavior characteristics," "behavior descriptors," or "feature descriptors."

While many QD libraries exist, this particular library aims to be the QD analog
to the [pycma](https://pypi.org/project/cma/) library (a single objective
optimization library). In contrast to other QD libraries, this library is
"bare-bones," meaning pyribs (like [pycma](https://pypi.org/project/cma/))
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 ease of use. Refer to the list of
[additional QD libraries](#additional-qd-libraries) below if you need greater
performance or have additional use cases.

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

- An **Archive** saves the best representatives generated within measure space.
- **Emitters** control how new candidate solutions are generated and affect if
  the algorithm prioritizes quality or diversity.
- A **Scheduler** joins the **Archive** and **Emitters** together and acts as a
  scheduling algorithm for emitters. The **Scheduler** 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](https://www.overleaf.com/learn/latex/Hyperlinks#Linking_web_addresses)
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 David H. Lee and
            Yulun Zhang and Trung Tran Minh Vu 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](https://dl.acm.org/doi/10.1145/3377930.3390232).

```
@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 cells 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.
- A **Scheduler** 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](https://pypi.org/project/cma/) 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.

```python
import numpy as np

from ribs.archives import GridArchive
from ribs.emitters import ImprovementEmitter
from ribs.scheduler import Scheduler

archive = GridArchive(solution_dim=len([0.0] * 10), dims=[20, 20], ranges=[(-1, 1), (-1, 1)])
emitters = [ImprovementEmitter(archive, [0.0] * 10, 0.1)]
scheduler = Scheduler(archive, emitters)

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

    objectives = -np.sum(np.square(solutions), axis=1)
    measures = solutions[:, :2]

    scheduler.tell(objectives, measures)
```

To visualize this archive with matplotlib, we then use the
`grid_archive_heatmap` function from `ribs.visualize`.

```python
import matplotlib.pyplot as plt
from ribs.visualize import grid_archive_heatmap

grid_archive_heatmap(archive)
plt.show()
```

![Sphere heatmap](readme_assets/sphere_heatmap.png)

For more information, refer to the [documentation](https://docs.pyribs.org/).

## Installation

pyribs supports Python 3.7-3.10. 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](https://pyribs.org/#installation) on our website.

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

```bash
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

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

Then run

```bash
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](http://icaros.usc.edu) at
USC.

- [Bryon Tjanaka](https://btjanaka.net)
- [Matt Fontaine](https://scholar.google.com/citations?user=RqSvzikAAAAJ)
- [David Lee](https://github.com/itsdawei)
- [Yulun Zhang](https://github.com/lunjohnzhang)
- [Vincent Vu](https://vuvincent.com/)
- [Sam Sommerer](https://github.com/sam-sommerer)
- [Nathan Dennler](https://ndennler.github.io/)
- Nikitas Klapsis
- [Stefanos Nikolaidis](https://stefanosnikolaidis.net)

We thank [Amy K. Hoover](http://amykhoover.com/) and
[Julian Togelius](http://julian.togelius.com/) for their contributions deriving
the CMA-ME algorithm.

## Additional QD Libraries

- [QDax](https://github.com/adaptive-intelligent-robotics/QDax): Implementations
  of QD algorithms in JAX -- suitable if you want to run entire QD algorithms on
  hardware accelerators in a matter of minutes, and particularly useful if you
  need to interface with Brax environments.
- [qdpy](https://gitlab.com/leo.cazenille/qdpy/): Python implementations of a
  wide variety of QD algorithms.
- [sferes](https://github.com/sferes2/sferes2): Contains C++ implementations of
  QD algorithms; can also handle discrete domains.

## Users

pyribs users include:

<!-- Alphabetical order -->

- [Adam Gaier (Autodesk Research)](https://scholar.google.com/citations?user=GGyARB8AAAAJ)
- [Adaptive & Intelligent Robotics Lab (Imperial College London)](https://www.imperial.ac.uk/adaptive-intelligent-robotics)
- [Chair of Statistical Learning and Data Science (LMU Munich)](https://www.slds.stat.uni-muenchen.de/)
- [Game Innovation Lab (New York University)](https://game.engineering.nyu.edu)
- [Giovanni Iacca (University of Trento)](https://sites.google.com/site/giovanniiacca/)
- [ganyariya (University of Tsukuba)](https://github.com/ganyariya/mario_pytorch)
- [HUAWEI Noah's Ark Lab](https://github.com/huawei-noah)
- [ICAROS Lab (University of Southern California)](http://icaros.usc.edu/)
- [Jacob Schrum (Southwestern University)](https://github.com/schrum2/PyribsForGameGAN)
- [Lenia Research](https://lenia.world)

### Publications

For the list of publications which use pyribs, refer to our
[Google Scholar entry](https://scholar.google.com/scholar?oi=bibs&hl=en&cites=16246392515630874608).

### Software

See the
[GitHub dependency graph](https://github.com/icaros-usc/pyribs/network/dependents)
for the public GitHub repositories which depend on pyribs.

## License

pyribs is released under the
[MIT License](https://github.com/icaros-usc/pyribs/blob/master/LICENSE).

## Credits

The pyribs package was initially created with
[Cookiecutter](https://github.com/audreyr/cookiecutter) and the
[audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage)
project template.


# History

## 0.5.0 (Forthcoming)

### Changelog

#### API

- Allow custom initialization in Gaussian and IsoLine emitters (#259)
- Implement CMA-MAE archive thresholds (#256, #260)
  - 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 `GradientAborescenceEmitter`(#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 `GradientAborescenceEmitter`, which is used to implement CMA-MEGA (#240)
- 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)
  - **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)
- Raise ValueError for incorrect array shapes in archive methods (#219)
- Add elites_with_measures_single method for getting elite for a single
  solution's measures (#215)
- 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 batched
  elites_with_measures method in archives (#213)
- **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

#### Documentation

- Add sphinx-codeautolink to docs (#206)
- 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 and remove 'all' extra (#183,#184)

## 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
