Awesome

Reinforcement Learning Zoo

RLzoo is a collection of the most practical reinforcement learning algorithms, frameworks and applications. It is implemented with Tensorflow 2.0 and API of neural network layers in TensorLayer2.0+, to provide a hands-on fast-developing approach for reinforcement learning practices and benchmarks. It supports basic toy-tests like OpenAI Gym and DeepMind Control Suite with very simple configurations. Moreover, RLzoo supports robot learning benchmark environment RLBench based on Vrep/Pyrep simulator. Other large-scale distributed training framework for more realistic scenarios with Unity 3D, Mujoco, Bullet Physics, etc, will be supported in the future. A Springer textbook is also provided, you can get the free PDF if your institute has Springer license.

Different from RLzoo for simple usage with high-level APIs, we also have a RL tutorial that aims to make the reinforcement learning tutorial simple, transparent and straight-forward with low-level APIs, as this would not only benefits new learners of reinforcement learning, but also provide convenience for senior researchers to testify their new ideas quickly.

<img src="https://github.com/tensorlayer/RLzoo/blob/master/gif/atari.gif" height=250 width=205 > <img src="https://github.com/tensorlayer/RLzoo/blob/master/gif/box2d.gif" height=250 width=205 ><img src="https://github.com/tensorlayer/RLzoo/blob/master/gif/classic.gif" height=250 width=205 > <img src="https://github.com/tensorlayer/RLzoo/blob/master/gif/mujoco.gif" height=250 width=205 >

<img src="https://github.com/tensorlayer/RLzoo/blob/master/gif/robotics.gif" height=250 width=205 > <img src="https://github.com/tensorlayer/RLzoo/blob/master/gif/dmcontrol.gif" height=250 width=205 > <img src="https://github.com/tensorlayer/RLzoo/blob/master/gif/rlbench.gif" height=250 width=205 > <img src="https://github.com/tensorlayer/tensorlayer/blob/master/img/tl_transparent_logo.png" height=180 width=200 >

Please check our Online Documentation for detailed usage and the Arxiv paper for the high-level description of design choices plus comparisons with other RL libraries. We suggest users to report bugs using Github issues. Users can also discuss how to use RLzoo in the following slack channel.

[News] RLzoo's paper is accepted at ACM Multimedia 2021 Open Source Software Competition! See a simple presentation slide describing the key characteristics of RLzoo.

Table of contents:

• Status
• Installation
• Prerequisites
• Usage
• Contents
  • Algorithms
  • Environments
  • Configurations
• Properties
• Troubleshooting
• Credits
• Citing

Status: Release

• 1.0.4 (Current version)

  Changes:

  • Add distributed training for DPPO algorithm, using Kungfu

• 1.0.3

  Changes:

  • Fix bugs in SAC algorithm

• 1.0.1

  Changes:

  • Add interactive training configuration;
  • Better support RLBench environment, with multi-head network architectures to support dictionary as observation type;
  • Make the code cleaner.

• 0.0.1

Installation

Ensure that you have Python >=3.5 (Python 3.6 is needed if using DeepMind Control Suite).

Direct installation:

pip3 install rlzoo --upgrade

Install RLzoo from Git:

git clone https://github.com/tensorlayer/RLzoo.git
cd RLzoo
pip3 install .

Prerequisites

pip3 install -r requirements.txt

• tensorflow >= 2.0.0 or tensorflow-gpu >= 2.0.0a0
• tensorlayer >= 2.0.1
• tensorflow-probability
• tf-nightly-2.0-preview
• Mujoco 2.0, dm_control, dm2gym (if using DeepMind Control Suite environments)
• Vrep, PyRep, RLBench (if using RLBench environments, follows here, here and here)

Usage

For detailed usage, please check our online documentation.

Quick Start

Choose whatever environments with whatever RL algorithms supported in RLzoo, and enjoy the game by running following example in the root file of installed package:

# in the root folder of RLzoo package
cd rlzoo
python run_rlzoo.py

What's in run_rlzoo.py?

from rlzoo.common.env_wrappers import build_env
from rlzoo.common.utils import call_default_params
from rlzoo.algorithms import TD3  # import the algorithm to use
# choose an algorithm
AlgName = 'TD3'
# chose an environment
EnvName = 'Pendulum-v0'  
# select a corresponding environment type
EnvType = 'classic_control'
# build an environment with wrappers
env = build_env(EnvName, EnvType)  
# call default parameters for the algorithm and learning process
alg_params, learn_params = call_default_params(env, EnvType, AlgName)  
# instantiate the algorithm
alg = eval(AlgName+'(**alg_params)')
# start the training
alg.learn(env=env, mode='train', render=False, **learn_params)  
# test after training 
alg.learn(env=env, mode='test', render=True, **learn_params)  

The main script run_rlzoo.py follows (almost) the same structure for all algorithms on all environments, see the full list of examples.

General Descriptions: RLzoo provides at least two types of interfaces for running the learning algorithms, with (1) implicit configurations or (2) explicit configurations. Both of them start learning program through running a python script, instead of running a long command line with all configurations shortened to be arguments of it (e.g. in Openai Baseline). Our approaches are found to be more interpretable, flexible and convenient to apply in practice. According to the level of explicitness of learning configurations, we provided two different ways of setting learning configurations in python scripts: the first one with implicit configurations uses a default.py script to record all configurations for each algorithm, while the second one with explicit configurations exposes all configurations to the running scripts. Both of them can run any RL algorithms on any environments supported in our repository with a simple command line.

RLzoo with implicit configurations means the configurations for learning are not explicitly contained in the main script for running (i.e. run_rlzoo.py), but in the default.py file in each algorithm folder (for example, rlzoo/algorithms/sac/default.py is the default parameters configuration for SAC algorithm). All configurations include (1) parameter values for the algorithm and learning process, (2) the network structures, (3) the optimizers, etc, are divided into configurations for the algorithm (stored in alg_params) and configurations for the learning process (stored in learn_params). Whenever you want to change the configurations for the algorithm or learning process, you can either go to the folder of each algorithm and modify parameters in default.py, or change the values in alg_params (a dictionary of configurations for the algorithm) and learn_params (a dictionary of configurations for the learning process) in run_rlzoo.py according to the keys.

Common Interface:

from rlzoo.common.env_wrappers import build_env
from rlzoo.common.utils import call_default_params
from rlzoo.algorithms import *
# choose an algorithm
AlgName = 'TD3'
# chose an environment
EnvName = 'Pendulum-v0'  
# select a corresponding environment type
EnvType = ['classic_control', 'atari', 'box2d', 'mujoco', 'robotics', 'dm_control', 'rlbench'][0] 
# build an environment with wrappers
env = build_env(EnvName, EnvType)  
# call default parameters for the algorithm and learning process
alg_params, learn_params = call_default_params(env, EnvType, AlgName)  
# instantiate the algorithm
alg = eval(AlgName+'(**alg_params)')
# start the training
alg.learn(env=env, mode='train', render=False, **learn_params)  
# test after training 
alg.learn(env=env, mode='test', render=True, **learn_params)  

# in the root folder of rlzoo package
cd rlzoo
python run_rlzoo.py

RLzoo with explicit configurations means the configurations for learning, including parameter values for the algorithm and the learning process, the network structures used in the algorithms and the optimizers etc, are explicitly displayed in the main script for running. And the main scripts for demonstration are under the folder of each algorithm, for example, ./rlzoo/algorithms/sac/run_sac.py can be called with python algorithms/sac/run_sac.py from the file ./rlzoo to run the learning process same as in above implicit configurations.

A Quick Example

import gym
from rlzoo.common.utils import make_env, set_seed
from rlzoo.algorithms import AC
from rlzoo.common.value_networks import ValueNetwork
from rlzoo.common.policy_networks import StochasticPolicyNetwork

''' load environment '''
env = gym.make('CartPole-v0').unwrapped
obs_space = env.observation_space
act_space = env.action_space
# reproducible
seed = 2
set_seed(seed, env)

''' build networks for the algorithm '''
num_hidden_layer = 4 #number of hidden layers for the networks
hidden_dim = 64 # dimension of hidden layers for the networks
with tf.name_scope('AC'):
        with tf.name_scope('Critic'):
            	# choose the critic network, can be replaced with customized network
                critic = ValueNetwork(obs_space, hidden_dim_list=num_hidden_layer * [hidden_dim])
        with tf.name_scope('Actor'):
            	# choose the actor network, can be replaced with customized network
                actor = StochasticPolicyNetwork(obs_space, act_space, hidden_dim_list=num_hidden_layer * [hidden_dim], output_activation=tf.nn.tanh)
net_list = [actor, critic] # list of the networks

''' choose optimizers '''
a_lr, c_lr = 1e-4, 1e-2  # a_lr: learning rate of the actor; c_lr: learning rate of the critic
a_optimizer = tf.optimizers.Adam(a_lr)
c_optimizer = tf.optimizers.Adam(c_lr)
optimizers_list=[a_optimizer, c_optimizer]  # list of optimizers

# intialize the algorithm model, with algorithm parameters passed in
model = AC(net_list, optimizers_list)
''' 
full list of arguments for the algorithm
----------------------------------------
net_list: a list of networks (value and policy) used in the algorithm, from common functions or customization
optimizers_list: a list of optimizers for all networks and differentiable variables
gamma: discounted factor of reward
action_range: scale of action values
'''

# start the training process, with learning parameters passed in
model.learn(env, train_episodes=500,  max_steps=200,
            save_interval=50, mode='train', render=False)
''' 
full list of parameters for training
---------------------------------------
env: learning environment
train_episodes:  total number of episodes for training
test_episodes:  total number of episodes for testing
max_steps:  maximum number of steps for one episode
save_interval: time steps for saving the weights and plotting the results
mode: 'train' or 'test'
render:  if true, visualize the environment
'''

# test after training
model.learn(env, test_episodes=100, max_steps=200,  mode='test', render=True)

In the package folder, we provides examples with explicit configurations for each algorithm.

# in the root folder of rlzoo package
cd rlzoo
python algorithms/<ALGORITHM_NAME>/run_<ALGORITHM_NAME>.py 
# for example: run actor-critic
python algorithms/ac/run_ac.py

Interactive Configurations

We also provide an interactive learning configuration with Jupyter Notebook and ipywidgets, where you can select the algorithm, environment, and general learning settings with simple clicking on dropdown lists and sliders! A video demonstrating the usage is as following. The interactive mode can be used with rlzoo/interactive/main.ipynb by running $ jupyter notebook to open it.

Distributed Training

RLzoo supports distributed training frameworks across multiple computational nodes with multiple CPUs/GPUs, using the Kungfu package. The installation of Kungfu requires to install CMake and Golang first, details see the website of Kungfu. An example for distributed training is contained in folder rlzoo/distributed, by running the following command, you will launch the distributed training process:

rlzoo/distributed/run_dis_train.sh

#!/bin/sh
set -e

cd $(dirname $0)

kungfu_flags() {
    echo -q
    echo -logdir logs

    local ip1=127.0.0.1
    local np1=$np

    local ip2=127.0.0.10
    local np2=$np
    local H=$ip1:$np1,$ip2:$np2
    local m=cpu,gpu

    echo -H $ip1:$np1
}

prun() {
    local np=$1
    shift
    kungfu-run $(kungfu_flags) -np $np $@
}

n_learner=2
n_actor=2
n_server=1

flags() {
    echo -l $n_learner
    echo -a $n_actor
    echo -s $n_server
}

rl_run() {
    local n=$((n_learner + n_actor + n_server))
    prun $n python3 training_components.py $(flags)
}

main() {
    rl_run
}

main

The script specifies the ip addresses for different computational nodes, as well as the number of policy learners (updating the models), actors (sampling through interaction with environments) and inference servers (policy forward inference during sampling process) as n_learner, n_actor and n_server respectively. n_server can only be 1 at current version.

Other training details are specified in an individual Python script named training_components.py within the same directory as run_dis_train.sh, which can be seen as following.

from rlzoo.common.env_wrappers import build_env
from rlzoo.common.policy_networks import *
from rlzoo.common.value_networks import *
from rlzoo.algorithms.dppo_clip_distributed.dppo_clip import DPPO_CLIP
from functools import partial

# Specify the training configurations
training_conf = {
    'total_step': int(1e7),  # overall training timesteps
    'traj_len': 200,         # length of the rollout trajectory
    'train_n_traj': 2,       # update the models after every certain number of trajectories for each learner 
    'save_interval': 10,     # saving the models after every certain number of updates
}

# Specify the environment and launch it
env_name, env_type = 'CartPole-v0', 'classic_control'
env_maker = partial(build_env, env_name, env_type)
temp_env = env_maker()
obs_shape, act_shape = temp_env.observation_space.shape, temp_env.action_space.shape

env_conf = {
    'env_name': env_name,
    'env_type': env_type,
    'env_maker': env_maker,
    'obs_shape': obs_shape,
    'act_shape': act_shape,
}


def build_network(observation_space, action_space, name='DPPO_CLIP'):
    """ build networks for the algorithm """
    hidden_dim = 256
    num_hidden_layer = 2
    critic = ValueNetwork(observation_space, [hidden_dim] * num_hidden_layer, name=name + '_value')

    actor = StochasticPolicyNetwork(observation_space, action_space,
                                    [hidden_dim] * num_hidden_layer,
                                    trainable=True,
                                    name=name + '_policy')
    return critic, actor


def build_opt(actor_lr=1e-4, critic_lr=2e-4):
    """ choose the optimizer for learning """
    import tensorflow as tf
    return [tf.optimizers.Adam(critic_lr), tf.optimizers.Adam(actor_lr)]


net_builder = partial(build_network, temp_env.observation_space, temp_env.action_space)
opt_builder = partial(build_opt, )

agent_conf = {
    'net_builder': net_builder,
    'opt_builder': opt_builder,
    'agent_generator': partial(DPPO_CLIP, net_builder, opt_builder),
}
del temp_env

from rlzoo.distributed.start_dis_role import main

print('Start Training.')
main(training_conf, env_conf, agent_conf)
print('Training Finished.')
	

Users can specify the environment, network architectures, optimizers and other training detains in this script.

Note: if RLzoo is installed, you can create the two scripts run_dis_train.sh and training_components.py in whatever directory to launch distributed training, as long as the two scripts are in the same directory.

Contents

Algorithms

Choices for AlgName: 'DQN', 'AC', 'A3C', 'DDPG', 'TD3', 'SAC', 'PG', 'TRPO', 'PPO', 'DPPO'

Environments

Choices for EnvType: 'atari', 'box2d', 'classic_control', 'mujoco', 'robotics', 'dm_control', 'rlbench'

• OpenAI Gym:

  • Atari
  • Box2D
  • Classic control
  • MuJoCo
  • Robotics

• DeepMind Control Suite

• RLBench

• Make sure the name of environment matches the type of environment in the main script. The types of environments include: 'atari', 'box2d', 'classic_control', 'mujoco', 'robotics', 'dm_control', 'rlbench'.

• When using the DeepMind Control Suite, install the dm2gym package with: pip install dm2gym

• When using the RLBench environments, please add the path of your local rlbench repository to python: export PYTHONPATH=PATH_TO_YOUR_LOCAL_RLBENCH_REPO

• A dictionary of all different environments is stored in ./rlzoo/common/env_list.py

• Full list of environments in RLBench is here.

• Installation of Vrep->PyRep->RLBench follows here->here->here.

Configurations:

The supported configurations for RL algorithms with corresponding environments in RLzoo are listed in the following table.

Properties

As shown in the interactive use case in Section of Usage, a jupyter notebook is provided for more intuitively configuring the whole process of deploying the learning process (rlzoo/interactive/main.ipynb)

Troubleshooting

• If you meet the error 'AttributeError: module 'tensorflow' has no attribute 'contrib'' when running the code after installing tensorflow-probability, try: pip install --upgrade tf-nightly-2.0-preview tfp-nightly
• When trying to use RLBench environments, 'No module named rlbench' can be caused by no RLBench package installed at your local or a mistake in the python path. You should add export PYTHONPATH=/home/quantumiracle/research/vrep/PyRep/RLBench every time you try to run the learning script with RLBench environment or add it to you ~/.bashrc file once for all.
• If you meet the error that the Qt platform is not loaded correctly when using DeepMind Control Suite environments, it's probably caused by your Ubuntu system not being version 14.04 or 16.04. Check here.

Credits

Our core contributors include:

Zihan Ding, Tianyang Yu, Yanhua Huang, Hongming Zhang, Guo Li, Quancheng Guo, Luo Mai, Hao Dong

Citing

@article{ding2020rlzoo,
  title={RLzoo: A Comprehensive and Adaptive Reinforcement Learning Library},
  author={Ding, Zihan and Yu, Tianyang and Huang, Yanhua and Zhang, Hongming and Mai, Luo and Dong, Hao},
  journal={arXiv preprint arXiv:2009.08644},
  year={2020}
}

and

@book{deepRL-2020,
 title={Deep Reinforcement Learning: Fundamentals, Research, and Applications},
 editor={Hao Dong, Zihan Ding, Shanghang Zhang},
 author={Hao Dong, Zihan Ding, Shanghang Zhang, Hang Yuan, Hongming Zhang, Jingqing Zhang, Yanhua Huang, Tianyang Yu, Huaqing Zhang, Ruitong Huang},
 publisher={Springer Nature},
 note={\url{http://www.deepreinforcementlearningbook.org}},
 year={2020}
}

Other Resources