Skip to content

Latest commit

 

History

History
430 lines (337 loc) · 20.2 KB

README_CN.md

File metadata and controls

430 lines (337 loc) · 20.2 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

  • DQN: Deep Q Network [论文]
  • Double DQN: DQN with Double Q-learning [论文]
  • Dueling DQN: DQN with Dueling Network [论文]
  • PER: DQN with Prioritized Experience Replay [论文]
  • NoisyDQN: DQN with Parameter Space Noise for Exploration [论文]
  • DRQN: Deep Recurrent Q-Netwrk [论文]
  • QRDQN: DQN with Quantile Regression [论文]
  • C51: Distributional Reinforcement Learning [论文]
  • PG: Vanilla Policy Gradient [论文]
  • NPG: Natural Policy Gradient [论文]
  • PPG: Phasic Policy Gradient [论文] [源码]
  • A2C: Advantage Actor Critic [论文] [源码]
  • SAC: Soft Actor-Critic [论文] [源码]
  • SAC-Discrete: Soft Actor-Critic for Discrete Actions [论文] [源码]
  • PPO-Clip: Proximal Policy Optimization with Clipped Objective [论文] [源码]
  • PPO-KL: Proximal Policy Optimization with KL Divergence [论文] [源码]
  • DDPG: Deep Deterministic Policy Gradient [论文] [源码]
  • TD3: Twin Delayed Deep Deterministic Policy Gradient [论文][源码]
  • P-DQN: Parameterised Deep Q-Network [论文]
  • MP-DQN: Multi-pass Parameterised Deep Q-network [论文] [源码]
  • SP-DQN: Split Parameterised Deep Q-Network [论文]

👉 Model-Based Reinforcement Learning (MBRL)

👉 Multi-Agent Reinforcement Learning (MARL)

  • IQL: Independent Q-learning [论文] [源码]
  • VDN: Value Decomposition Networks [论文] [源码]
  • QMIX: Q-mixing networks [论文] [源码]
  • WQMIX: Weighted Q-mixing networks [论文] [源码]
  • QTRAN: Q-transformation [论文] [源码]
  • DCG: Deep Coordination Graphs [论文] [源码]
  • IDDPG: Independent Deep Deterministic Policy Gradient [论文]
  • MADDPG: Multi-agent Deep Deterministic Policy Gradient [论文] [源码]
  • IAC: Independent Actor-Critic [论文] [源码]
  • COMA: Counterfactual Multi-agent Policy Gradient [论文] [源码]
  • VDAC: Value-Decomposition Actor-Critic [论文] [源码]
  • IPPO: Independent Proximal Policy Optimization [论文] [源码]
  • MAPPO: Multi-agent Proximal Policy Optimization [论文] [源码]
  • MFQ: Mean-Field Q-learning [论文] [源码]
  • MFAC: Mean-Field Actor-Critic [论文] [源码]
  • ISAC: Independent Soft Actor-Critic
  • MASAC: Multi-agent Soft Actor-Critic [论文]
  • MATD3: Multi-agent Twin Delayed Deep Deterministic Policy Gradient [论文]
  • IC3Net: Individualized Controlled Continuous Communication Model [论文] [源码]

已支持环境

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}
}