Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/DLR-RM/stable-baselines3

PyTorch version of Stable Baselines, reliable implementations of reinforcement learning algorithms.
https://github.com/DLR-RM/stable-baselines3

baselines gsde gym machine-learning openai python pytorch reinforcement-learning reinforcement-learning-algorithms robotics sb3 sde stable-baselines toolbox

Last synced: about 2 months ago
JSON representation

PyTorch version of Stable Baselines, reliable implementations of reinforcement learning algorithms.

Host: GitHub
URL: https://github.com/DLR-RM/stable-baselines3
Owner: DLR-RM
License: mit
Created: 2020-05-05T05:52:26.000Z (over 4 years ago)
Default Branch: master
Last Pushed: 2024-10-29T11:23:17.000Z (about 2 months ago)
Last Synced: 2024-10-29T12:38:21.690Z (about 2 months ago)
Topics: baselines, gsde, gym, machine-learning, openai, python, pytorch, reinforcement-learning, reinforcement-learning-algorithms, robotics, sb3, sde, stable-baselines, toolbox
Language: Python
Homepage: https://stable-baselines3.readthedocs.io
Size: 4.41 MB
Stars: 9,021
Watchers: 64
Forks: 1,690
Open Issues: 91
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.bib

Awesome Lists containing this project

awesome-rl - [Baselines @ DLR-RM
awesome-list - Stable Baselines3 - A set of reliable implementations of reinforcement learning algorithms in PyTorch. (Reinforcement Learning / Others)
StarryDivineSky - DLR-RM/stable-baselines3
awesome-production-machine-learning - Stable Baselines - RM/stable-baselines3.svg?style=social) - A fork of OpenAI Baselines, implementations of reinforcement learning algorithms. (Industry Strength RL)

README

        
![CI](https://github.com/DLR-RM/stable-baselines3/workflows/CI/badge.svg)

[![Documentation Status](https://readthedocs.org/projects/stable-baselines/badge/?version=master)](https://stable-baselines3.readthedocs.io/en/master/?badge=master) [![coverage report](https://gitlab.com/araffin/stable-baselines3/badges/master/coverage.svg)](https://gitlab.com/araffin/stable-baselines3/-/commits/master)

[![codestyle](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

# Stable Baselines3



Stable Baselines3 (SB3) is a set of reliable 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 Baselines3 in the [v1.0 blog post](https://araffin.github.io/post/sb3/) or our [JMLR paper](https://jmlr.org/papers/volume22/20-1364/20-1364.pdf).

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-baselines3.readthedocs.io/en/master/guide/rl.html) to get started with RL.

## Main Features

**The performance of each algorithm was tested** (see *Results* section in their respective page),

you can take a look at the issues [#48](https://github.com/DLR-RM/stable-baselines3/issues/48) and [#49](https://github.com/DLR-RM/stable-baselines3/issues/49) for more details.

| **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: |

| `Dict` observation space support  | :heavy_check_mark: |

| Ipython / Notebook friendly | :heavy_check_mark: |

| Tensorboard support         | :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: |

### Planned features

Please take a look at the [Roadmap](https://github.com/DLR-RM/stable-baselines3/issues/1) and [Milestones](https://github.com/DLR-RM/stable-baselines3/milestones).

## Migration guide: from Stable-Baselines (SB2) to Stable-Baselines3 (SB3)

A migration guide from SB2 to SB3 can be found in the [documentation](https://stable-baselines3.readthedocs.io/en/master/guide/migration.html).

## Documentation

Documentation is available online: [https://stable-baselines3.readthedocs.io/](https://stable-baselines3.readthedocs.io/)

## Integrations

Stable-Baselines3 has some integration with other libraries/services like Weights & Biases for experiment tracking or Hugging Face for storing/sharing trained models. You can find out more in the [dedicated section](https://stable-baselines3.readthedocs.io/en/master/guide/integrations.html) of the documentation.

## RL Baselines3 Zoo: A Training Framework for Stable Baselines3 Reinforcement Learning Agents

[RL Baselines3 Zoo](https://github.com/DLR-RM/rl-baselines3-zoo) is a training framework for Reinforcement Learning (RL).

It provides scripts for training, evaluating agents, tuning hyperparameters, plotting results and recording videos.

In addition, it includes a collection of tuned hyperparameters for common environments and RL algorithms, and agents trained with those settings.

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

Documentation: https://rl-baselines3-zoo.readthedocs.io/en/master/

## SB3-Contrib: Experimental RL Features

We implement experimental features in a separate contrib repository: [SB3-Contrib](https://github.com/Stable-Baselines-Team/stable-baselines3-contrib)

This allows SB3 to maintain a stable and compact core, while still providing the latest features, like Recurrent PPO (PPO LSTM), Truncated Quantile Critics (TQC), Quantile Regression DQN (QR-DQN) or PPO with invalid action masking (Maskable PPO).

Documentation is available online: [https://sb3-contrib.readthedocs.io/](https://sb3-contrib.readthedocs.io/)

## Stable-Baselines Jax (SBX)

[Stable Baselines Jax (SBX)](https://github.com/araffin/sbx) is a proof of concept version of Stable-Baselines3 in Jax, with recent algorithms like DroQ or CrossQ.

It provides a minimal number of features compared to SB3 but can be much faster (up to 20x times!): https://twitter.com/araffin2/status/1590714558628253698

## Installation

**Note:** Stable-Baselines3 supports PyTorch >= 1.13

### Prerequisites

Stable Baselines3 requires Python 3.8+.

#### Windows 10

To install stable-baselines on Windows, please look at the [documentation](https://stable-baselines3.readthedocs.io/en/master/guide/install.html#prerequisites).

### Install using pip

Install the Stable Baselines3 package:

```

pip install stable-baselines3[extra]

```

**Note:** Some shells such as Zsh require quotation marks around brackets, i.e. `pip install 'stable-baselines3[extra]'` ([More Info](https://stackoverflow.com/a/30539963)).

This includes an optional dependencies like Tensorboard, OpenCV or `ale-py` to train on atari games. If you do not need those, you can use:

```sh

pip install stable-baselines3

```

Please read the [documentation](https://stable-baselines3.readthedocs.io/) for more details and alternatives (from source, using docker).

## Example

Most of the code in 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 gymnasium as gym

from stable_baselines3 import PPO

env = gym.make("CartPole-v1", render_mode="human")

model = PPO("MlpPolicy", env, verbose=1)

model.learn(total_timesteps=10_000)

vec_env = model.get_env()

obs = vec_env.reset()

for i in range(1000):

    action, _states = model.predict(obs, deterministic=True)

    obs, reward, done, info = vec_env.step(action)

    vec_env.render()

    # VecEnv resets automatically

    # if done:

    #   obs = env.reset()

env.close()

```

Or just train a model with a one liner if [the environment is registered in Gymnasium](https://gymnasium.farama.org/tutorials/gymnasium_basics/environment_creation/#registering-envs) and if [the policy is registered](https://stable-baselines3.readthedocs.io/en/master/guide/custom_policy.html):

```python

from stable_baselines3 import PPO

model = PPO("MlpPolicy", "CartPole-v1").learn(10_000)

```

Please read the [documentation](https://stable-baselines3.readthedocs.io/) for more examples.

## Try it online with Colab Notebooks !

All the following examples can be executed online using Google Colab notebooks:

- [Full Tutorial](https://github.com/araffin/rl-tutorial-jnrr19)

- [All Notebooks](https://github.com/Stable-Baselines-Team/rl-colab-notebooks/tree/sb3)

- [Getting Started](https://colab.research.google.com/github/Stable-Baselines-Team/rl-colab-notebooks/blob/sb3/stable_baselines_getting_started.ipynb)

- [Training, Saving, Loading](https://colab.research.google.com/github/Stable-Baselines-Team/rl-colab-notebooks/blob/sb3/saving_loading_dqn.ipynb)

- [Multiprocessing](https://colab.research.google.com/github/Stable-Baselines-Team/rl-colab-notebooks/blob/sb3/multiprocessing_rl.ipynb)

- [Monitor Training and Plotting](https://colab.research.google.com/github/Stable-Baselines-Team/rl-colab-notebooks/blob/sb3/monitor_training.ipynb)

- [Atari Games](https://colab.research.google.com/github/Stable-Baselines-Team/rl-colab-notebooks/blob/sb3/atari_games.ipynb)

- [RL Baselines Zoo](https://colab.research.google.com/github/Stable-Baselines-Team/rl-colab-notebooks/blob/sb3/rl-baselines-zoo.ipynb)

- [PyBullet](https://colab.research.google.com/github/Stable-Baselines-Team/rl-colab-notebooks/blob/sb3/pybullet.ipynb)

## Implemented Algorithms

| **Name**         | **Recurrent**      | `Box`          | `Discrete`     | `MultiDiscrete` | `MultiBinary`  | **Multi Processing**              |

| ------------------- | ------------------ | ------------------ | ------------------ | ------------------- | ------------------ | --------------------------------- |

| ARS^[1](#f1)   | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :heavy_check_mark: |

| A2C   | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |

| DDPG  | :x: | :heavy_check_mark: | :x:                | :x:                 | :x:                | :heavy_check_mark: |

| DQN   | :x: | :x: | :heavy_check_mark: | :x:                 | :x:                | :heavy_check_mark: |

| HER   | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :heavy_check_mark: |

| PPO   | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  | :heavy_check_mark: | :heavy_check_mark: |

| QR-DQN^[1](#f1)  | :x: | :x: | :heavy_check_mark: | :x:                 | :x:                | :heavy_check_mark: |

| RecurrentPPO^[1](#f1)   | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  | :heavy_check_mark: | :heavy_check_mark: |

| SAC   | :x: | :heavy_check_mark: | :x:                | :x:                 | :x:                | :heavy_check_mark: |

| TD3   | :x: | :heavy_check_mark: | :x:                | :x:                 | :x:                | :heavy_check_mark: |

| TQC^[1](#f1)   | :x: | :heavy_check_mark: | :x:                | :x:                 | :x: | :heavy_check_mark: |

| TRPO^[1](#f1)  | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  | :heavy_check_mark: | :heavy_check_mark: |

| Maskable PPO^[1](#f1)   | :x: | :x: | :heavy_check_mark: | :heavy_check_mark:  | :heavy_check_mark: | :heavy_check_mark:  |

1: Implemented in [SB3 Contrib](https://github.com/Stable-Baselines-Team/stable-baselines3-contrib) GitHub repository.

Actions `gym.spaces`:

 * `Box`: A N-dimensional box that contains 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.

## Testing the installation

### Install dependencies

```sh

pip install -e .[docs,tests,extra]

```

### Run tests

All unit tests in stable baselines3 can be run using `pytest` runner:

```sh

make pytest

```

To run a single test file:

```sh

python3 -m pytest -v tests/test_env_checker.py

```

To run a single test:

```sh

python3 -m pytest -v -k 'test_check_env_dict_action'

```

You can also do a static type check using `pytype` and `mypy`:

```sh

pip install pytype mypy

make type

```

Codestyle check with `ruff`:

```sh

pip install ruff

make lint

```

## Projects Using Stable-Baselines3

We try to maintain a list of projects using stable-baselines3 in the [documentation](https://stable-baselines3.readthedocs.io/en/master/misc/projects.html),

please tell us if you want your project to appear on this page ;)

## Citing the Project

To cite this repository in publications:

```bibtex

@article{stable-baselines3,

  author  = {Antonin Raffin and Ashley Hill and Adam Gleave and Anssi Kanervisto and Maximilian Ernestus and Noah Dormann},

  title   = {Stable-Baselines3: Reliable Reinforcement Learning Implementations},

  journal = {Journal of Machine Learning Research},

  year    = {2021},

  volume  = {22},

  number  = {268},

  pages   = {1-8},

  url     = {http://jmlr.org/papers/v22/20-1364.html}

}

```

## 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/ernestum) (aka @ernestum), [Adam Gleave](https://github.com/adamgleave) (@AdamGleave), [Anssi Kanervisto](https://github.com/Miffyli) (@Miffyli) and [Quentin Gallouédec](https://gallouedec.com/) (@qgallouedec).

**Important Note: We do not provide technical support, or consulting** and do not answer personal questions via email.

Please post your question on the [RL Discord](https://discord.com/invite/xhfNqQv), [Reddit](https://www.reddit.com/r/reinforcementlearning/), or [Stack Overflow](https://stackoverflow.com/) in that case.

## 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**](./CONTRIBUTING.md) guide first.

## Acknowledgments

The initial work to develop Stable Baselines3 was partially funded by the project *Reduced Complexity Models* from the *Helmholtz-Gemeinschaft Deutscher Forschungszentren*, and by the EU's Horizon 2020 Research and Innovation Programme under grant number 951992 ([VeriDream](https://www.veridream.eu/)).

The original version, Stable Baselines, was created in the [robotics lab U2IS](http://u2is.ensta-paristech.fr/index.php?lang=en) ([INRIA Flowers](https://flowers.inria.fr/) team) at [ENSTA ParisTech](http://www.ensta-paristech.fr/en).

Logo credits: [L.M. Tenkes](https://www.instagram.com/lucillehue/)