A Library for Deep Reinforcement Learning
Project description
Tianshou
Tianshou(天授) is a reinforcement learning platform based on pure PyTorch. Unlike existing reinforcement learning libraries, which are mainly based on TensorFlow, have many nested classes, unfriendly API, or slow-speed, Tianshou provides a fast-speed framework and pythonic API for building the deep reinforcement learning agent. The supported interface algorithms include:
- Policy Gradient (PG)
- Deep Q-Network (DQN)
- Double DQN (DDQN) + n-step returns
- Advantage Actor-Critic (A2C)
- Deep Deterministic Policy Gradient (DDPG)
- Proximal Policy Optimization (PPO)
- Twin Delayed DDPG (TD3)
- Soft Actor-Critic (SAC)
Tianshou supports parallel environment training for all algorithms as well.
Tianshou is still under development. More algorithms are going to be added and we always welcome contributions to help make Tianshou better. If you would like to contribute, please check out the guidelines.
Installation
Tianshou is currently hosted on PyPI. You can simply install Tianshou with the following command:
pip3 install tianshou
Documentation
The tutorials and API documentation are hosted on https://tianshou.readthedocs.io.
The example scripts are under test/discrete (CartPole) and test/continuous (Pendulum).
Why Tianshou?
Fast-speed
Tianshou is a lightweight but high-speed reinforcement learning platform. For example, here is a test on a laptop (i7-8750H + GTX1060). It only uses 3 seconds for training a agent based on vanilla policy gradient on the CartPole-v0 task.
We select some of famous (>1k stars) reinforcement learning platform. Here is the benchmark result for other algorithms and platforms on toy scenarios:
Platform | Tianshou | Baselines | Ray/RLlib | PyTorch DRL | rlpyt |
---|---|---|---|---|---|
GitHub Stars | |||||
Algo \ ML platform | PyTorch | TensorFlow | TF/PyTorch | PyTorch | PyTorch |
PG - CartPole | 9.03±4.18s | None | |||
DQN - CartPole | 20.94±11.38s | 175.55±53.81s | |||
A2C - CartPole | 11.72±3.85s | Error | |||
PPO - CartPole | 35.25±16.47s | 29.16±15.46s | |||
DDPG - Pendulum | 46.95±24.31s | 652.83±471.28s | |||
SAC - Pendulum | 38.92±2.09s | None | 808.21±405.70s | ||
TD3 - Pendulum | 48.39±7.22s | None | 619.33±324.97s |
All of the platforms use at most 10 different seeds for testing. We erase those trials which failed for training. The reward threshold is 195.0 in CartPole and -250.0 in Pendulum over consecutive 100 episodes.
Reproducible
Tianshou has unit tests. Different from other platforms, the unit tests include the full agent training procedure for all of the implemented algorithms. It will be failed once it cannot train an agent to perform well enough on limited epochs on toy scenarios. The unit tests secure the reproducibility of our platform.
Check out the GitHub Actions page for more detail.
Elegant and Flexible
Currently, the overall code of Tianshou platform is less than 1500 lines. It is quite easy to go through the framework and understand how it works. We provide many flexible API as you wish, for instance, if you want to use your policy to interact with environment with n
episodes:
result = collector.collect(n_episode=n)
If you want to train the given policy with a sampled batch:
result = policy.learn(collector.sample(batch_size))
You can check out the documentation for further usage.
Quick Start
This is an example of Policy Gradient. You can also run the full script under test/discrete/test_pg.py.
First, import the relevant packages:
import gym, torch, numpy as np, torch.nn as nn
from torch.utils.tensorboard import SummaryWriter
from tianshou.policy import PGPolicy
from tianshou.env import SubprocVectorEnv
from tianshou.trainer import onpolicy_trainer
from tianshou.data import Collector, ReplayBuffer
Define some hyper-parameters:
task = 'CartPole-v0'
seed = 1626
lr = 3e-4
gamma = 0.9
epoch = 10
step_per_epoch = 1000
collect_per_step = 10
repeat_per_collect = 2
batch_size = 64
train_num = 8
test_num = 100
device = 'cuda' if torch.cuda.is_available() else 'cpu'
writer = SummaryWriter('log') # tensorboard is also supported!
Define the network:
class Net(nn.Module):
def __init__(self, layer_num, state_shape, action_shape=0, device='cpu'):
super().__init__()
self.device = device
self.model = [
nn.Linear(np.prod(state_shape), 128),
nn.ReLU(inplace=True)]
for i in range(layer_num):
self.model += [nn.Linear(128, 128), nn.ReLU(inplace=True)]
if action_shape:
self.model += [nn.Linear(128, np.prod(action_shape))]
self.model = nn.Sequential(*self.model)
def forward(self, s, state=None, info={}):
if not isinstance(s, torch.Tensor):
s = torch.tensor(s, device=self.device, dtype=torch.float)
batch = s.shape[0]
s = s.view(batch, -1)
logits = self.model(s)
return logits, state
Make envs and fix seed:
env = gym.make(task)
state_shape = env.observation_space.shape or env.observation_space.n
action_shape = env.action_space.shape or env.action_space.n
train_envs = SubprocVectorEnv([lambda: gym.make(task) for _ in range(train_num)])
test_envs = SubprocVectorEnv([lambda: gym.make(task) for _ in range(test_num)])
np.random.seed(seed)
torch.manual_seed(seed)
train_envs.seed(seed)
test_envs.seed(seed)
Setup policy and collector:
net = Net(3, state_shape, action_shape, device).to(device)
optim = torch.optim.Adam(net.parameters(), lr=lr)
policy = PGPolicy(net, optim, torch.distributions.Categorical, gamma)
train_collector = Collector(policy, train_envs, ReplayBuffer(20000))
test_collector = Collector(policy, test_envs)
Let's train it:
result = onpolicy_trainer(policy, train_collector, test_collector, epoch, step_per_epoch, collect_per_step, repeat_per_collect, test_num, batch_size, stop_fn=lambda x: x >= env.spec.reward_threshold, writer=writer)
Saving / loading trained policy (it's exactly the same as PyTorch nn.module):
torch.save(policy.state_dict(), 'pg.pth')
policy.load_state_dict(torch.load('pg.pth', map_location=device))
Watch the performance with 35 FPS:
collecter = Collector(policy, env)
collecter.collect(n_episode=1, render=1/35)
Looking at the result saved in tensorboard: (on bash script)
tensorboard --logdir log
Citing Tianshou
If you find Tianshou useful, please cite it in your publications.
@misc{tianshou,
author = {Jiayi Weng},
title = {Tianshou},
year = {2020},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/thu-ml/tianshou}},
}
TODO
- More examples on [mujoco, atari] benchmark
- Prioritized replay buffer
- RNN support
- Multi-agent
- Distributed training
Miscellaneous
Tianshou was previously a reinforcement learning platform based on TensorFlow. You can checkout the branch priv
for more detail.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for tianshou-0.2.0.post1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e3cd3b8ab27f3394a4541933e0ecbe28bad9f70d890b52bc29b11d46f6f03b18 |
|
MD5 | b3863acee74634cd1bda20d3a555c45d |
|
BLAKE2b-256 | 932793f1165946ed530d16b401bcb9bd5b60bb60356a08610903acbb6ee9dc5f |