cpprb is a python (CPython) module providing replay buffer classes for reinforcement learning.
Major target users are researchers and library developers.
You can build your own reinforcement learning algorithms together with your favorite deep learning library (e.g. TensorFlow, PyTorch).
cpprb forcuses speed, flexibility, and memory efficiency.
By utilizing Cython, complicated calculations (e.g. segment tree for prioritized experience replay) are offloaded onto C++. (The name cpprb comes from "C++ Replay Buffer".)
In terms of API, initially cpprb referred to OpenAI Baselines' implementation. The current version of cpprb has much more flexibility. Any NumPy compatible types of any numbers of values can be stored (as long as memory capacity is sufficient). For example, you can store the next action and the next next observation, too.
cpprb requires following softwares before installation.
Additionally, here are user's good feedbacks for installation at Ubuntu. (Thanks!)
The following command installs cpprb together with other dependencies.
pip install cpprb
Depending on your environment, you might need sudo or --user flag
for installation.
On supported platflorms (Linux x86-64, Windows amd64, and macOS x8664), binary packages hosted on PyPI can be used, so that you don't need C++ compiler. On the other platforms, such as 32bit or arm-architectured Linux and Windows, you cannot install from binary, and you need to compile by yourself. Please be patient, we plan to support wider platforms in future.
If you have any troubles to install from binary, you can fall back to
source installation by passing --no-binary option to the above pip
command. (In order to avoid NumPy source installation, it is better to
install NumPy beforehand.)
pip install numpy
pip install --no-binary cpprb
First, download source code manually or clone the repository;
git clone https://gitlab.com/ymd_h/cpprb.git
Then you can install in the same way;
cd cpprb
pip install .
For this installation, you need to convert extended Python (.pyx) to C++ (.cpp) during installation, it takes longer time than installation from PyPI.
Basic usage is following step;
ReplayBuffer.__init__)ReplayBuffer.add)
ReplayBuffer.on_episode_end)ReplayBuffer.sample)Here is a simple example for storing standard environment (aka. obs,
act, rew, next_obs, and done).
from cpprb import ReplayBuffer
buffer_size = 256
obs_shape = 3
act_dim = 1
rb = ReplayBuffer(buffer_size,
env_dict ={"obs": {"shape": obs_shape},
"act": {"shape": act_dim},
"rew": {},
"next_obs": {"shape": obs_shape},
"done": {}})
obs = np.ones(shape=(obs_shape))
act = np.ones(shape=(act_dim))
rew = 0
next_obs = np.ones(shape=(obs_shape))
done = 0
for i in range(500):
rb.add(obs=obs,act=act,rew=rew,next_obs=next_obs,done=done)
if done:
# Together with resetting environment, call ReplayBuffer.on_episode_end()
rb.on_episode_end()
batch_size = 32
sample = rb.sample(batch_size)
# sample is a dictionary whose keys are 'obs', 'act', 'rew', 'next_obs', and 'done'
(See also API reference)
| Name | Type | Optional | Discription |
|---|---|---|---|
size | int | No | Buffer size |
env_dict | dict | Yes (but unusable) | Environment definition (See here) |
next_of | str or array-like of str | Yes | Memory compression (See here) |
stack_compress | str or array-like of str | Yes | Memory compression (See here) |
default_dtype | numpy.dtype | Yes | Fall back data type |
Nstep | dict | Yes | Nstep configuration (See here) |
mmap_prefix | str | Yes | mmap file prefix (See here) |
Flexible environment values are defined by env_dict when buffer
creation. The detail is described at document.
Since stored values have flexible name, you have to pass to
ReplayBuffer.add member by keyword.
cpprb provides buffer classes for building following algorithms.
| Algorithms | cpprb class | Paper |
|---|---|---|
| Experience Replay | ReplayBuffer | L. J. Lin |
| Prioritized Experience Replay | PrioritizedReplayBuffer | T. Schaul et. al. |
| Multi-step (Nstep) Learning | ReplayBuffer, PrioritizedReplayBuffer | |
| Multiprocess Learning (Ape-X) | MPReplayBuffer MPPrioritizedReplayBuffer | D. Horgan et. al. |
| Large Batch Experience Replay (LaBER) | LaBERmean, LaBERlazy, LaBERmax | T. Lahire et al. |
| Reverse Experience Replay (RER) | ReverseReplayBuffer | E. Rotinov |
| Hindsight Experience Replay (HER) | HindsightReplayBuffer | M. Andrychowicz et al. |
cpprb features and its usage are described at following pages:
One of the most distinctive design of cpprb is column-oriented flexibly defined transitions. As far as we know, other replay buffer implementations adopt row-oriented flexible transitions (aka. array of transition class) or column-oriented non-flexible transitions.
In deep reinforcement learning, sampled batch is divided into
variables (i.e. obs, act, etc.). If the sampled batch is
row-oriented, users (or library) need to convert it into
column-oriented one. (See doc, too)
cpprb can accept addition of multiple transitions simultaneously. This
design is convenient when batch transitions are moved from local
buffers to a global buffer. Moreover it is more efficient because of
not only removing pure-Python for loop but also suppressing
unnecessary priority updates for PER. (See doc, too)
We try to minimize dependency. Only NumPy is required during its execution. Small dependency is always preferable to avoid dependency hell.
Any contribution are very welcome!
Bigger commumity makes development more active and improve cpprb.
When you have any problems or requests, you can check Discussions on GitHub.com. If you still cannot find any information, you can post your own.
We keep issues on GitLab.com and users are still allowed to open issues, however, we mainly use the place as development issue tracker.
cpprb follows local rules:
python -m unittest <Your Test Code> command.gitlab-ci.yamlStep by step instruction for beginners is described at here.
cpprb is available under MIT license.
MIT License
Copyright (c) 2019 Yamada Hiroyuki
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
We would be very happy if you cite cpprb in your papers.
@misc{Yamada_cpprb_2019,
author = {Yamada, Hiroyuki},
month = {1},
title = {{cpprb}},
url = {https://gitlab.com/ymd_h/cpprb},
year = {2019}
}
FAQs
ReplayBuffer for Reinforcement Learning written by C++ and Cython
We found that cpprb demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.