Package: cpprb
Overviewcpprb 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 utilizingCython, 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 toOpenAI Baselines'
implementation. The current version of cpprb has much more
flexibility. AnyNumPycompatible 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.Installationcpprb requires following softwares before installation.C++17 compiler (for installation from source)GCC(maybe 7.2 and newer)Visual Studio(2017 Enterprise is fine)Python 3pipAdditionally, here are user's good feedbacks for installation atUbuntu.
(Thanks!)Install fromPyPI(Recommended)The following command installs cpprb together with other dependencies.pip install cpprbDepending on your environment, you might needsudoor--userflag
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-binaryoption 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 cpprbInstall from source codeFirst, download source code manually or clone the repository;git clone https://gitlab.com/ymd_h/cpprb.gitThen 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.UsageBasic UsageBasic usage is following step;Create replay buffer (ReplayBuffer.__init__)Add transitions (ReplayBuffer.add)Reset at episode end (ReplayBuffer.on_episode_end)Sample transitions (ReplayBuffer.sample)Example CodeHere is a simple example for storing standard environment (aka.obs,act,rew,next_obs, anddone).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'Construction Parameters(See alsoAPI reference)NameTypeOptionalDiscriptionsizeintNoBuffer sizeenv_dictdictYes (but unusable)Environment definition (Seehere)next_ofstror array-like ofstrYesMemory compression (Seehere)stack_compressstror array-like ofstrYesMemory compression (Seehere)default_dtypenumpy.dtypeYesFall back data typeNstepdictYesNstep configuration (Seehere)mmap_prefixstrYesmmap file prefix (Seehere)NotesFlexible environment values are defined byenv_dictwhen buffer
creation. The detail is described atdocument.Since stored values have flexible name, you have to pass toReplayBuffer.addmember by keyword.Featurescpprb provides buffer classes for building following algorithms.Algorithmscpprb classPaperExperience ReplayReplayBufferL. J. LinPrioritized Experience ReplayPrioritizedReplayBufferT. Schaul et. al.Multi-step (Nstep) LearningReplayBuffer,PrioritizedReplayBufferMultiprocess Learning (Ape-X)MPReplayBufferMPPrioritizedReplayBufferD. Horgan et. al.Large Batch Experience Replay (LaBER)LaBERmean,LaBERlazy,LaBERmaxT. Lahire et al.Reverse Experience Replay (RER)ReverseReplayBufferE. RotinovHindsight Experience Replay (HER)HindsightReplayBufferM. Andrychowicz et al.cpprb features and its usage are described at following pages:Flexible EnvironmentMulti-step addPrioritized Experience ReplayNstep Experience ReplayMemory CompressionMap Large Data on FileMultiprocess Learning (Ape-X)Save/Load TransitionsDesignColumn-oriented and FlexibleOne 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. (Seedoc, too)Batch Insertioncpprb 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-Pythonforloop but also suppressing
unnecessary priority updates for PER. (Seedoc, too)Minimum DependencyWe try to minimize dependency. Only NumPy is required during its
execution. Small dependency is always preferable to avoid dependency
hell.Contributing to cpprbAny contribution are very welcome!Making Community LargerBigger commumity makes development more active and improve cpprb.StarGitLab repository(and/orGitHub Mirror)Publish your code using cpprbShare this repository to your friend and/or followers.Q & A at ForumWhen you have any problems or requests, you can checkDiscussions on
GitHub.com. If you still cannot find any information, you can post
your own.We keepissues on GitLab.comand users are still allowed to open
issues, however, we mainly use the place as development issue tracker.Merge Request (Pull Request)cpprb follows local rules:Branch Name"HotFix***" for bug fix"Feature***" for new feature implementationdocstringMust for external APINumpy StyleUnit TestPut test code under "test/" directoryCan test bypython -m unittest <Your Test Code>commandContinuous Integration on GitLab CI configured by.gitlab-ci.yamlOpen an issue and associate it to Merge RequestStep by step instruction for beginners is described athere.Linkscpprb sitesProject SiteClass ReferenceUnit Test CoverageMain RepositoryGitHub Mirrorcpprb on PyPIcpprb users' repositorieskeiohta/TF2RL:TensorFlow2.x Reinforcement LearningExample usage at Kaggle competitionApe-X DQN-LAP: SafeGuard & RewardRedesign|Hungry GeeseJapanese Documents【強化学習】cpprb で Experience Replay を簡単に！| Qiita【強化学習】Ape-X の高速な実装を簡単に！| Qiita【強化学習】自作ライブラリでDQN | Qiita【強化学習】Ape-Xの高速化を実現 | Zenn【強化学習】cpprb に遷移のファイル保存機能を追加 | ZennLicensecpprb 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.CitationWe 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}
}3rd Party Papers citing cpprbE. Aitygulov and A. I. Panov, "Transfer Learning with Demonstration Forgetting for Robotic Manipulator", Proc. Comp. Sci. 186 (2021), 374-380, https://doi.org/10.1016/j.procs.2021.04.159T. Kitamura and R. Yonetani, "ShinRL: A Library for Evaluating RL Algorithms from Theoretical and Practical Perspectives", NeurIPS Deep RL Workshop (2021)(arXiv,code)