Skip to content

Latest commit

 

History

History
431 lines (336 loc) · 19.5 KB

README_CN.md

File metadata and controls

431 lines (336 loc) · 19.5 KB

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

PyPI Documentation Status GitHub Downloads GitHub Repo stars GitHub forks GitHub watchers

PyTorch TensorFlow MindSpore

Python gym gymnasium pettingzoo

README.md |英文文档 | 中文文档

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

我们将其称为 Xuan-Ce（玄策）。 “玄（Xuan）”寓意神奇且多变的魔盒，“策（Ce）”意为策略。

由于 DRL 算法通常对超参数敏感、效果易随技巧（tricks）的不同而差异较大，训练过程本身也不够稳定，因此 DRL 算法有时显得难以捉摸，带有“玄”的感觉。本项目致力于提供深入、优质、易懂的 DRL 算法实现，希望能揭示强化学习中这些“魔法”背后的原理。

我们期望它能兼容多种深度学习框架（PyTorch、TensorFlow 和 MindSpore），并希望它能够成为涵盖多种 DRL 算法的“动物园”。

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

目录：

为什么选择 XuanCe？

XuanCe 的特性

  • 🎒 高度模块化设计。
  • 👍 易于学习，易于安装，易于使用。
  • 🔀 模型组合灵活。
  • 🎉 提供大量算法及多种任务支持。
  • 👫 同时支持 DRL 和 MARL（多智能体强化学习）任务。
  • 🔑 高度兼容不同用户需求。（PyTorch、TensorFlow2、MindSpore、CPU、GPU、Linux、Windows、MacOS 等）
  • ⚡ 支持环境并行，运行速度快。
  • 💻 支持多 GPU 分布式训练。
  • 🎛️ 支持自动化超参数调优。
  • 📈 与 tensorboard 或 wandb 工具结合，具备良好可视化效果。

已实现算法

👉 DRL

（点击以查看支持的 DRL 算法）
  • Deep Q Network - DQN [论文]
  • DQN with Double Q-learning - Double DQN [论文]
  • DQN with Dueling Network - Dueling DQN [论文]
  • DQN with Prioritized Experience Replay - PER [论文]
  • DQN with Parameter Space Noise for Exploration - NoisyNet [论文]
  • Deep Recurrent Q-Network - DRQN [论文]
  • DQN with Quantile Regression - QRDQN [论文]
  • Distributional Reinforcement Learning - C51 [论文]
  • Vanilla Policy Gradient - PG [论文]
  • Phasic Policy Gradient - PPG [论文] [代码]
  • Advantage Actor Critic - A2C [论文] [代码]
  • Soft Actor-Critic - SAC [论文] [代码]
  • Soft Actor-Critic for Discrete Actions - SAC-Discrete [论文] [代码]
  • Proximal Policy Optimization with Clipped Objective - PPO-Clip [论文] [代码]
  • Proximal Policy Optimization with KL Divergence - PPO-KL [论文] [代码]
  • Deep Deterministic Policy Gradient - DDPG [论文] [代码]
  • Twin Delayed Deep Deterministic Policy Gradient - TD3 [论文] [代码]
  • Parameterised Deep Q-Network - P-DQN [论文]
  • Multi-pass Parameterised Deep Q-Network - MP-DQN [论文] [代码]
  • Split Parameterised Deep Q-Network - SP-DQN [论文]

👉 多智能体强化学习（MARL）

（点击以查看支持的 MARL 算法）
  • Independent Q-learning - IQL [论文] [代码]
  • Value Decomposition Networks - VDN [论文] [代码]
  • Q-mixing networks - QMIX [论文] [代码]
  • Weighted Q-mixing networks - WQMIX [论文] [代码]
  • Q-transformation - QTRAN [论文] [代码]
  • Deep Coordination Graphs - DCG [论文] [代码]
  • Independent Deep Deterministic Policy Gradient - IDDPG [论文]
  • Multi-agent Deep Deterministic Policy Gradient - MADDPG [论文] [代码]
  • Independent Actor-Critic - IAC [论文] [代码]
  • Counterfactual Multi-agent Policy Gradient - COMA [论文] [代码]
  • Value-Decomposition Actor-Critic - VDAC [论文] [代码]
  • Independent Proximal Policy Optimization - IPPO [论文] [代码]
  • Multi-agent Proximal Policy Optimization - MAPPO [论文] [代码]
  • Mean-Field Q-learning - MFQ [论文] [代码]
  • Mean-Field Actor-Critic - MFAC [论文] [代码]
  • Independent Soft Actor-Critic - ISAC
  • Multi-agent Soft Actor-Critic - MASAC [论文]
  • Multi-agent Twin Delayed Deep Deterministic Policy Gradient - MATD3 [论文]

已支持环境

Classic Control

（点击收起/展开）

Cart Pole
Pendulum
Acrobot
...

Box2D

（点击收起/展开）

Bipedal Walker
Car Racing
Lunar Lander

MuJoCo 环境

（点击收起/展开）

Ant
HalfCheetah
Hopper
Humanoid
...

Atari 环境

（点击收起/展开）

Adventure
Air Raid
Alien
Amidar
Assault
...

Minigrid 环境

（点击收起/展开）

GoToDoorEnv
LockedRoomEnv
MemoryEnv
PlaygroundEnv
...

无人机环境（Drones Environments）

可参考 XuanCe 文档中关于 gym-pybullet-drones 的安装与使用说明。

（点击收起/展开）

Helix
单智能体 Hover
多智能体 Hover
...

MPE 环境

（点击收起/展开）

Simple Push
Simple Reference
Simple Spread
Simple Adversary
...

SMAC

Google Research Football

👉 安装方法

💻 本库可在 Linux、Windows、MacOS、EulerOS 等多种系统上运行。

在安装 XuanCe 之前，建议先安装 Anaconda，以便准备一个 Python 环境。（注：可从此处选择合适版本的 Anaconda。）

安装步骤如下（在终端 / 命令行下执行）：

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

conda create -n xuance_env python=3.7

步骤 2：激活该环境：

conda activate xuance_env

步骤 3：安装本库：

pip install xuance

上述命令不包含深度学习框架的依赖。如果需要同时安装特定的深度学习框架，可通过以下命令：

  • 仅安装 PyTorch: pip install xuance[torch]
  • 仅安装 TensorFlow2: pip install xuance[tensorflow]
  • 仅安装 MindSpore: pip install xuance[mindspore]
  • 一次性安装全部依赖: pip install xuance[all]

注意：如果还需要用到其他功能或特定的依赖，请手动安装相关包。

👉 快速上手

训练模型

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) 工具来可视化结果。

社区交流

（注：也可在 Stack Overflow 上提问。）

（QQ 群与微信公众号二维码）

QQ 群
微信公众号

@TFBestPractices

引用

如果您在研究或开发中使用了 XuanCe，请引用以下论文：

@article{liu2023xuance,
  title={XuanCe: A Comprehensive and Unified Deep Reinforcement Learning Library},
  author={Liu, Wenzhang and Cai, Wenzhe and Jiang, Kun and Cheng, Guangran and Wang, Yuanda and Wang, Jiawei and Cao, Jingyu and Xu, Lele and Mu, Chaoxu and Sun, Changyin},
  journal={arXiv preprint arXiv:2312.16248},
  year={2023}
}