diff --git a/README.md b/README.md index bc0efa7..644edbc 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,173 @@ -[![Build Status](https://travis-ci.com/hill-a/stable-baselines.svg?branch=master)](https://travis-ci.com/hill-a/stable-baselines) [![Documentation Status](https://readthedocs.org/projects/stable-baselines/badge/?version=master)](https://stable-baselines.readthedocs.io/en/master/?badge=master) + + +**WARNING: Stable Baselines3 is currently in a beta version, breaking changes may occur before 1.0 is released** + +Note: most of the documentation of [Stable Baselines](https://github.com/hill-a/stable-baselines) should be still valid though. # Stable Baselines3 -PyTorch version of [Stable Baselines](https://github.com/hill-a/stable-baselines), a set of improved implementations of reinforcement learning algorithms. +Stable Baselines3 is a set of improved implementations of reinforcement learning algorithms in PyTorch. It is the next major version of [Stable Baselines](https://github.com/hill-a/stable-baselines). + +You can read a detailed presentation of Stable Baselines in the [Medium article](https://medium.com/@araffin/stable-baselines-a-fork-of-openai-baselines-reinforcement-learning-made-easy-df87c4b2fc82). + + +These algorithms will make it easier for the research community and industry to replicate, refine, and identify new ideas, and will create good baselines to build projects on top of. We expect these tools will be used as a base around which new ideas can be added, and as a tool for comparing a new approach against existing ones. We also hope that the simplicity of these tools will allow beginners to experiment with a more advanced toolset, without being buried in implementation details. + +**Note: despite its simplicity of use, Stable Baselines3 (SB3) assumes you have some knowledge about Reinforcement Learning (RL).** You should not utilize this library without some practice. To that extent, we provide good resources in the [documentation](https://stable-baselines.readthedocs.io/en/master/guide/rl.html) to get started with RL. + +## Main Features + + +| **Features** | **Stable-Baselines3** | +| --------------------------- | ----------------------| +| State of the art RL methods | :heavy_check_mark: | +| Documentation | :heavy_check_mark: | +| Custom environments | :heavy_check_mark: | +| Custom policies | :heavy_check_mark: | +| Common interface | :heavy_check_mark: | +| Ipython / Notebook friendly | :heavy_check_mark: | +| PEP8 code style | :heavy_check_mark: | +| Custom callback | :heavy_check_mark: | +| High code coverage | :heavy_check_mark: | +| Type hints | :heavy_check_mark: | + + + +## Documentation + +Documentation is available online: [https://stable-baselines.readthedocs.io/](https://stable-baselines.readthedocs.io/) + + +## RL Baselines3 Zoo: A Collection of Trained RL Agents + +[RL Baselines3 Zoo](https://github.com/DLR-RM/rl-baselines3-zoo). is a collection of pre-trained Reinforcement Learning agents using Stable-Baselines3. + +It also provides basic scripts for training, evaluating agents, tuning hyperparameters, plotting results and recording videos. + +Goals of this repository: + +1. Provide a simple interface to train and enjoy RL agents +2. Benchmark the different Reinforcement Learning algorithms +3. Provide tuned hyperparameters for each environment and RL algorithm +4. Have fun with the trained agents! + +Github repo: https://github.com/DLR-RM/rl-baselines3-zoo + + + +## Installation + +**Note:** Stable-Baselines3 supports PyTorch 1.4+. + +### Prerequisites +Stable Baselines3 requires python 3.6+. + + + + +### Install using pip +Install the Stable Baselines3 package: +``` +pip install stable-baselines3[extra] +``` + +This includes an optional dependency OpenCV to display the environments when using `SubprocVecEnv`. If you do not need it, you can install without OpenCV: +``` +pip install stable-baselines3 +``` + +Please read the [documentation](https://stable-baselines.readthedocs.io/) for more details and alternatives (from source, using docker). + + +## Example + +Most of the library tries to follow a sklearn-like syntax for the Reinforcement Learning algorithms. + +Here is a quick example of how to train and run PPO on a cartpole environment: +```python +import gym + +from stable_baselines3 import PPO +from stable_baselines3.ppo import MlpPolicy + +env = gym.make('CartPole-v1') + +model = PPO('MlpPolicy', env, verbose=1) +model.learn(total_timesteps=10000) + +obs = env.reset() +for i in range(1000): + action, _states = model.predict(obs, deterministic=True) + obs, rewards, dones, info = env.step(action) + env.render() + +env.close() +``` + +Or just train a model with a one liner if [the environment is registered in Gym](https://github.com/openai/gym/wiki/Environments) and if [the policy is registered](https://stable-baselines.readthedocs.io/en/master/guide/custom_policy.html): + +```python +from stable_baselines3 import PPO + +model = PPO('MlpPolicy', 'CartPole-v1').learn(10000) +``` + +Please read the [documentation](https://stable-baselines.readthedocs.io/) for more examples. + + + -NOTE: Python 3.6 is required! ## Implemented Algorithms -- A2C -- PPO -- SAC -- TD3 - -- SDE support for A2C, PPO, SAC and TD3. +| **Name** | **Recurrent** | `Box` | `Discrete` | `MultiDiscrete` | `MultiBinary` | **Multi Processing** | +| ------------------- | ------------------ | ------------------ | ------------------ | ------------------- | ------------------ | --------------------------------- | +| A2C | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :heavy_check_mark: | +| PPO | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :heavy_check_mark: | +| SAC | :x: | :heavy_check_mark: | :x: | :x: | :x: | :x: | +| TD3 | :x: | :heavy_check_mark: | :x: | :x: | :x: | :x: | -## Roadmap - -- cf github Roadmap +Actions `gym.spaces`: + * `Box`: A N-dimensional box that containes every point in the action space. + * `Discrete`: A list of possible actions, where each timestep only one of the actions can be used. + * `MultiDiscrete`: A list of possible actions, where each timestep only one action of each discrete set can be used. + * `MultiBinary`: A list of possible actions, where each timestep any of the actions can be used in any combination. -## Run the Tests +## Testing the installation +All unit tests in stable baselines3 can be run using pytest runner: ``` -pip install -e .[tests] +pip install pytest pytest-cov make pytest ``` -## Type check - +You can also do a static type check using pytype: ``` -pip install -e .[tests] +pip install pytype make type ``` -## Build the Documentation - -``` -pip install -e .[docs] -make doc -``` - -Spell check for the documentation: - -``` -make spelling -``` + ## Citing the Project @@ -65,3 +183,18 @@ To cite this repository in publications: howpublished = {\url{https://github.com/DLR-RM/stable-baselines3}}, } ``` + +## Maintainers + +Stable-Baselines3 is currently maintained by [Ashley Hill](https://github.com/hill-a) (aka @hill-a), [Antonin Raffin](https://araffin.github.io/) (aka [@araffin](https://github.com/araffin)), [Maximilian Ernestus](https://github.com/erniejunior) (aka @erniejunior), [Adam Gleave](https://github.com/adamgleave) (@AdamGleave) and [Anssi Kanervisto](https://github.com/Miffyli) (@Miffyli). + +**Important Note: We do not do technical support, nor consulting** and don't answer personal questions per email. + + +## How To Contribute + +To any interested in making the baselines better, there is still some documentation that needs to be done. +If you want to contribute, please read **CONTRIBUTING.md** guide first. + + +Logo credits: [L.M. Tenkes](https://www.instagram.com/lucillehue/)