XuanCe：一个全面统一的深度强化学习库

XuanCe是一个开源的深度强化学习（DRL）算法实现集合。

我们在中文中称之为玄策。 "玄"意味着不可思议和神奇的盒子，"策"意味着策略。

DRL算法对超参数调整敏感，在不同技巧下性能各异，并且训练过程不稳定，因此，有时DRL算法看起来难以捉摸和"玄"。这个项目提供了DRL算法的全面、高质量和易于理解的实现，希望这个实现能够揭示强化学习的魔力。

我们期望它能够兼容多个深度学习工具箱（ PyTorch， TensorFlow，和 MindSpore），并希望它能真正成为一个充满DRL算法的动物园。

论文链接：https://arxiv.org/pdf/2312.16248.pdf

:book: 完整文档 | 中文文档 :book:

为什么选择XuanCe？

XuanCe的特点

:school_satchel: 高度模块化。
:thumbsup: 易于学习，易于安装，易于使用。
:twisted_rightwards_arrows: 模型组合灵活。
:tada: 丰富的算法适用于各种任务。
:couple: 支持DRL和MARL任务。
:key: 对不同用户高度兼容。（PyTorch、TensorFlow2、MindSpore、CPU、GPU、Linux、Windows、MacOS等）
:zap: 借助并行环境实现快速运行。
:chart_with_upwards_trend: 使用tensorboard或wandb工具实现良好的可视化效果。

目前包含的算法

:point_right: DRL

<details open> <summary>（点击显示支持的DRL算法）</summary> - 深度Q网络 - DQN [[论文](https://www.nature.com/articles/nature14236)] - 双Q学习的DQN - 双DQN [[论文](https://ojs.aaai.org/index.php/AAAI/article/view/10295)] - 决斗网络的DQN - 决斗DQN [[论文](http://proceedings.mlr.press/v48/wangf16.pdf)] - 优先经验回放的DQN - PER [[论文](https://arxiv.org/pdf/1511.05952.pdf)] - 参数空间噪声探索的DQN - NoisyNet [[论文](https://arxiv.org/pdf/1706.01905.pdf)] - 深度循环Q网络 - DRQN [[论文](https://cdn.aaai.org/ocs/11673/11673-51288-1-PB.pdf)] - 分位数回归的DQN - QRDQN [[论文](https://ojs.aaai.org/index.php/AAAI/article/view/11791)] - 分布式强化学习 - C51 [[论文](http://proceedings.mlr.press/v70/bellemare17a/bellemare17a.pdf)] - 普通策略梯度 - PG [[论文](https://proceedings.neurips.cc/paper/2001/file/4b86abe48d358ecf194c56c69108433e-Paper.pdf)] - 分阶段策略梯度 - PPG [[论文](http://proceedings.mlr.press/v139/cobbe21a/cobbe21a.pdf)] [[代码](https://github.com/openai/phasic-policy-gradient)] - 优势演员评论家 - A2C [[论文](http://proceedings.mlr.press/v48/mniha16.pdf)] [[代码](https://github.com/openai/baselines/tree/master/baselines/a2c)] - 基于最大熵的软演员评论家 - SAC [[论文](http://proceedings.mlr.press/v80/haarnoja18b/haarnoja18b.pdf)] [[代码](http://github.com/haarnoja/sac)] - 离散动作的软演员评论家 - SAC-Discrete [[论文](https://arxiv.org/pdf/1910.07207.pdf)] [[代码](https://github.com/p-christ/Deep-Reinforcement-Learning-Algorithms-with-PyTorch)] - 近端策略优化（裁剪目标）- PPO-Clip [[论文](https://arxiv.org/pdf/1707.06347.pdf)] [[代码](https://github.com/agi-brain/xuance/blob/master/ https://github.com/berkeleydeeprlcourse/homework/tree/master/hw4] - 近端策略优化（KL散度）- PPO-KL [[论文](https://arxiv.org/pdf/1707.06347.pdf)] [[代码](https://github.com/agi-brain/xuance/blob/master/ https://github.com/berkeleydeeprlcourse/homework/tree/master/hw4] - 深度确定性策略梯度 - DDPG [[论文](https://arxiv.org/pdf/1509.02971.pdf)] [[代码](https://github.com/openai/baselines/tree/master/baselines/ddpg)] - 双延迟深度确定性策略梯度 - TD3 [[论文](http://proceedings.mlr.press/v80/fujimoto18a/fujimoto18a.pdf)][[代码](https://github.com/sfujim/TD3)] - 参数化深度Q网络 - P-DQN [[论文](https://arxiv.org/pdf/1810.06394.pdf)] - 多通道参数化深度Q网络 - MP-DQN [[论文](https://arxiv.org/pdf/1905.04388.pdf)] [[代码](https://github.com/cycraig/MP-DQN)] - 分离参数化深度Q网络 - SP-DQN [[论文](https://arxiv.org/pdf/1810.06394.pdf)]

:point_right: 多智能体强化学习 (MARL)

<details open> <summary>（点击显示支持的MARL算法）</summary> - 独立Q学习 - IQL [[论文](https://hal.science/file/index/docid/720669/filename/Matignon2012independent.pdf)] [[代码](https://github.com/oxwhirl/pymarl)] - 值分解网络 - VDN [[论文](https://arxiv.org/pdf/1706.05296.pdf)] [[代码](https://github.com/oxwhirl/pymarl)] - Q混合网络 - QMIX [[论文](http://proceedings.mlr.press/v80/rashid18a/rashid18a.pdf)] [[代码](https://github.com/oxwhirl/pymarl)] - 加权Q混合网络 - WQMIX [[论文](https://proceedings.neurips.cc/paper/2020/file/73a427badebe0e32caa2e1fc7530b7f3-Paper.pdf)] [[代码](https://github.com/oxwhirl/wqmix)] - Q变换 - QTRAN [[论文](http://proceedings.mlr.press/v97/son19a/son19a.pdf)] [[代码](https://github.com/Sonkyunghwan/QTRAN)] - 深度协调图 - DCG [[论文](http://proceedings.mlr.press/v119/boehmer20a/boehmer20a.pdf)] [[代码](https://github.com/wendelinboehmer/dcg)] - 独立深度确定性策略梯度 - IDDPG [[论文](https://proceedings.neurips.cc/paper/2017/file/68a9750337a418a86fe06c1991a1d64c-Paper.pdf)] - 多智能体深度确定性策略梯度 - MADDPG [[论文](https://proceedings.neurips.cc/paper/2017/file/68a9750337a418a86fe06c1991a1d64c-Paper.pdf)] [[代码](https://github.com/openai/maddpg)] - 反事实多智能体策略梯度 - COMA [[论文](https://ojs.aaai.org/index.php/AAAI/article/view/11794)] [[代码](https://github.com/oxwhirl/pymarl)] - 多智能体近端策略优化 - MAPPO [[论文](https://proceedings.neurips.cc/paper_files/paper/2022/file/9c1535a02f0ce079433344e14d910597-Paper-Datasets_and_Benchmarks.pdf)] [[代码](https://github.com/marlbenchmark/on-policy)] - 平均场Q学习 - MFQ [[论文](http://proceedings.mlr.press/v80/yang18d/yang18d.pdf)] [[代码](https://github.com/mlii/mfrl)] - 平均场演员评论家 - MFAC [[论文](http://proceedings.mlr.press/v80/yang18d/yang18d.pdf)] [[代码](https://github.com/mlii/mfrl)] - 独立软演员评论家 - ISAC - 多智能体软演员评论家 - MASAC [[论文](https://arxiv.org/pdf/2104.06655.pdf)] - 多智能体双延迟深度确定性策略梯度 - MATD3 [[论文](https://arxiv.org/pdf/1910.01465.pdf)]

当前支持的环境

经典控制

<details open> <summary>（点击隐藏）</summary> <table rules="none" align="center"><tr> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/0616ec24-6f8c-4b4e-a30b-029830811806.gif" height=100" /><br/><font color="AAAAAA">平衡车</font> </center></td> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/3169b509-8edc-4cef-bcab-cea989a3f3fc.gif" height=100" /> <br/> <font color="AAAAAA">钟摆</font> </center> </td> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/331d435b-6c62-43a2-b0d1-88812267e8dd.gif" height=100" /> <br/> <font color="AAAAAA">杂技机器人</font> </center> </td> <td> <center> <br/> <font color="AAAAAA">...</font> </tr> </table> </details>

Box2D

<details open> <summary>（点击隐藏）</summary> <table rules="none" align="center"><tr> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/2131603a-8f7d-44e2-b736-a8708e105c27.gif" height=100" /><br/><font color="AAAAAA">两足行走器</font> </center></td> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/690e9cbc-6807-4e55-8483-7b6d4c488c1d.gif" height=100" /> <br/> <font color="AAAAAA">赛车</font> </center> </td> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/ffe48dfc-1a7c-4b9f-91f3-1ec8b10fc7a7.gif" height=100" /> <br/> <font color="AAAAAA">月球着陆器</font> </center> </td> </tr> </table> </details>

MuJoCo环境

<details open> <summary>(点击隐藏)</summary> <table rules="none" align="center"><tr> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/3402e340-abe6-400a-8edd-ad0fa8923fc6.gif" height=100" /><br/><font color="AAAAAA">蚂蚁</font> </center></td> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/52881d97-fda8-40d5-94e1-450b1453678e.gif" height=100" /> <br/> <font color="AAAAAA">半猎豹</font> </center> </td> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/8aef4cf3-6d5c-453f-b919-d2805523c5e9.gif" height=100" /> <br/> <font color="AAAAAA">跳跃者</font> </center> </td> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/b22b30a3-0829-4833-b547-29f48d5c311d.gif" height=100" /> <br/> <font color="AAAAAA">人形机器人</font> </center> </td> <td> <center> <br/> <font color="AAAAAA">...</font> </center> </td> </tr> </table> </details>

Atari环境

Minigrid环境

无人机环境

XuanCe关于gym-pybullet-drones安装和使用的文档。

<details open> <summary>（点击隐藏）</summary> <table rules="none" align="center"><tr> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/65ed0cc6-f170-452b-a88e-ce06dfab1be5.gif" height=100" /><br/><font color="AAAAAA">螺旋</font> </center></td> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/9853dfca-10aa-4a0e-aa86-aae756c4ab0d.gif" height=100" /> <br/> <font color="AAAAAA">单智能体悬停</font> </center> </td> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/1daf12bf-7404-49c8-987e-360321ece83a.gif" height=100" /> <br/> <font color="AAAAAA">多智能体悬停</font> </center> </td> <td> <center> <br/> <font color="AAAAAA">...</font> </center> </td> </tr> </table> </details>

MPE环境

Magent2

<details open> <summary>（点击隐藏）</summary> <table rules="none" align="center"><tr> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/28f5a097-388f-475e-93c3-8a42496f46db.gif" height=100" /><br/><font color="AAAAAA">战斗</font> </center></td> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/afb71a22-173a-451e-8082-96b39e04b0ab.gif" height=100" /> <br/> <font color="AAAAAA">虎鹿</font> </center> </td> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/5390c7f8-a2c6-473d-a8f7-85772c8a451f.gif" height=100" /> <br/> <font color="AAAAAA">战场</font> </center> </td> <td> <center> <br/> <font color="AAAAAA">...</font> </center> </td> </tr> </table> </details> ### [SMAC](https://github.com/oxwhirl/smac) <div align="center"> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/57a88075-3ed3-475d-83fb-baf22b5695fb.png" width="715" height="auto" align=center /> </div>

Google研究足球

:point_right: 安装

:computer: 该库可以在Linux、Windows、MacOS和EulerOS等系统上运行。

在安装XuanCe之前，你应该安装Anaconda来准备Python环境。（注意：从这里选择合适版本的Anaconda。）

之后，打开终端并按照以下步骤安装XuanCe。

步骤1：创建一个新的conda环境（建议Python>=3.7）：

conda create -n xuance_env python=3.7

步骤2：激活conda环境：

conda activate xuance_env

步骤3：安装库：

pip install xuance

此命令不包括深度学习工具箱的依赖项。要安装带有深度学习工具的XuanCe，你可以输入pip install xuance[torch]安装PyTorch， pip install xuance[tensorflow]安装TensorFlow2， pip install xuance[mindspore]安装MindSpore，以及pip install xuance[all]安装所有依赖项。

注意：一些额外的包需要手动安装以供进一步使用。

:point_right: 快速开始

训练模型

import xuance

runner = xuance.get_runner(method='dqn',
                           env='classic_control',
                           env_id='CartPole-v1',
                           is_test=False)
runner.run()

测试模型

import xuance

runner_test = xuance.get_runner(method='dqn',
                                env='classic_control',
                                env_id='CartPole-v1',
                                is_test=True)
runner_test.run()

可视化结果

Tensorboard

你可以使用Tensorboard来可视化训练过程中发生的情况。训练后，日志文件会自动生成在".results/"目录中，运行以下命令后你应该能看到一些训练数据。

$ tensorboard --logdir ./logs/dqn/torch/CartPole-v0

Weights & Biases (wandb)

XuanCe还支持Weights & Biases (wandb)工具，供用户可视化运行实现的结果。

如何在线使用wandb？:arrow_right: https://github.com/wandb/wandb.git/

如何离线使用wandb？:arrow_right: https://github.com/wandb/server.git/

社区

Github问题

你可以在Issues中提出你的问题、建议或者发现的bug。

社交账号

欢迎加入官方QQ交流群（群号：552432695）和微信公众号（"玄策 RLlib"）。

<details open> <summary>（QQ群和微信公众号二维码）</summary> <table rules="none" align="center"><tr> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/f303513e-2c17-4488-8743-dbb11d48e870.jpeg" width="200" height="auto" /><br/><font color="AAAAAA">QQ群</font> </center></td> <td> <center> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/cf5c5482-869b-4881-bfa8-abc073a9ea75.jpg" width="200" height="auto" /> <br/> <font color="AAAAAA">公众号（微信）</font> </center> </td> </tr> </table> </details> [@TFBestPractices](https://twitter.com/TFBestPractices/status/1665770204398223361)

引用

@article{liu2023xuance,
  title={XuanCe：一个全面统一的深度强化学习库},
  author={刘文章 and 蔡文哲 and 姜坤 and 程广然 and 王远达 and 王嘉伟 and 曹静宇 and 徐乐乐 and 穆超旭 and 孙长银},
  journal={arXiv预印本 arXiv:2312.16248},
  year={2023}
}