---

MushroomRL

---

.. image:: https://github.com/MushroomRL/mushroom-rl/actions/workflows/continuous_integration.yml/badge.svg?branch=dev :target: https://github.com/MushroomRL/mushroom-rl/actions/workflows/continuous_integration.yml :alt: 持续集成

.. image:: https://readthedocs.org/projects/mushroomrl/badge/?version=latest :target: https://mushroomrl.readthedocs.io/en/latest/?badge=latest :alt: 文档状态

.. image:: https://qlty.sh/gh/MushroomRL/projects/mushroom-rl/maintainability.svg :target: https://qlty.sh/gh/MushroomRL/projects/mushroom-rl :alt: 可维护性

.. image:: https://qlty.sh/gh/MushroomRL/projects/mushroom-rl/coverage.svg :target: https://qlty.sh/gh/MushroomRL/projects/mushroom-rl :alt: 测试覆盖率

MushroomRL：强化学习 Python 库。

.. contents:: 本文档目录： :depth: 2

什么是 MushroomRL

MushroomRL 是一个 Python 强化学习（RL）库，其模块化设计使其能够轻松地与常用的 Python 库结合使用，例如用于张量计算的 PyTorch 和 TensorFlow，以及 RL 基准测试环境 Gymnasium、PyBullet 和 Deepmind Control Suite 等。它提供了一种简单的方式来执行强化学习实验，支持经典的强化学习算法（如 Q-Learning、SARSA、FQI）以及深度强化学习算法（如 DQN、DDPG、SAC、TD3、TRPO、PPO）。

完整文档和教程请见此处 <http://mushroomrl.readthedocs.io/en/latest/>_。

安装

您可以使用以下命令进行 MushroomRL 的最小化安装：

.. code:: shell

pip3 install mushroom_rl

安装所有功能

MushroomRL 还包含一些可选组件，例如对 Gymnasium 环境的支持、来自 Arcade Learning Environment 的 Atari 2600 游戏，以及对物理模拟器如 Pybullet 和 MuJoCo 的支持。这些功能默认并未启用。

要安装所有功能，您需要额外安装一些包。可以通过运行以下命令来完成安装：

.. code:: shell

pip3 install mushroom_rl[all]

这将安装 MushroomRL 的所有依赖项，但不包括绘图依赖。对于 Ubuntu > 20.04，您可能还需要安装 pygame 和 gym 的依赖：

.. code:: shell

sudo apt -y install libsdl-image1.2-dev libsdl-mixer1.2-dev libsdl-ttf2.0-dev \
                 libsdl1.2-dev libsmpeg-dev libportmidi-dev ffmpeg libswscale-dev \
                 libavformat-dev libavcodec-dev swig

请注意，对于不同的操作系统，您可能仍需安装某些依赖项，例如 macOS 上需要安装 swig。

以下是安装绘图依赖所需的代码：

.. code:: shell

sudo apt -y install python3-pyqt5
pip3 install mushroom_rl[plots]

您可能需要先安装一些外部依赖。有关 mujoco-py 安装的更多信息，请参阅 项目页面 <https://github.com/openai/mujoco-py>_。

注意！当使用 conda 时，可能会出现 QT 相关问题。您可以通过在代码中添加以下行来解决这些问题，其中将 ``<conda_base_path>`` 替换为您的 conda 发行版路径，将 ``<env_name>`` 替换为您正在使用的 conda 环境名称：

.. code:: python

import os os.environ['QT_QPA_PLATFORM_PLUGIN_PATH'] = '/envs//bin/platforms'

要使用 dm_control 的 MushroomRL 接口，请按照 此处 <https://github.com/deepmind/dm_control>_ 提供的说明安装 dm_control。

使用 Habitat 和 iGibson 与 MushroomRL

Habitat <https://aihabitat.org/>__ 和 iGibson <http://svl.stanford.edu/igibson/>__ 是提供逼真且富含感官信息的学习环境的仿真平台。在 MushroomRL 中，智能体的默认观测值是 RGB 图像，但也可以使用 RGBD、智能体的感官数据以及其他信息。

如果您已经安装了旧版本的 iGibson 或 Habitat，我们建议您将其卸载并重新进行干净安装。

iGibson 安装 ^^^^^^^^^^^^^ 请遵循 官方指南 <http://svl.stanford.edu/igibson/#install_env>，并安装其 资产 <http://svl.stanford.edu/igibson/docs/assets.html> 和 数据集 <http://svl.stanford.edu/igibson/docs/dataset.html>__。

对于 <MUSHROOM_RL PATH>/mushroom-rl/examples/igibson_dqn.py，您需要运行以下命令：

.. code:: shell

python -m igibson.utils.assets_utils --download_assets
python -m igibson.utils.assets_utils --download_demo_data
python -m igibson.utils.assets_utils --download_ig_dataset

您还可以使用 第三方数据集 <https://github.com/StanfordVL/iGibson/tree/master/igibson/utils/data_utils/ext_scene>__。

场景细节由 YAML 文件定义，该文件需要传递给智能体。示例请参见 <IGIBSON PATH>/igibson/test/test_house.YAML。

Habitat 安装 ^^^^^^^^^^^^^ 请遵循 官方指南 <https://github.com/facebookresearch/habitat-lab/#installation>， 并使用 habitat_baselines 进行 完整安装。然后，您可以按照 此链接 <https://github.com/facebookresearch/habitat-lab#data> 和 此链接 <https://github.com/facebookresearch/habitat-lab#task-datasets>__ 下载交互式数据集。 如果您需要下载其他数据集，可以使用 此工具 <https://github.com/facebookresearch/habitat-sim/blob/master/habitat_sim/utils/datasets_download.py>__。

Habitat 的基本使用方法 ^^^^^^^^^^^^^^^^^^^^^^ 当您创建 Habitat 环境时，需要传入一个包装器名称和两个 YAML 文件： Habitat(wrapper, config_file, base_config_file)。

• 包装器必须是 <MUSHROOM_RL PATH>/mushroom-rl/environments/habitat_env.py 中定义的其中之一， 它负责将动作和观测转换为类似 gym 的格式。如果您的任务或机器人有特殊需求， 您可能需要定义新的包装器。

• YAML 文件定义了所有细节：Habitat 环境、场景、机器人可用的传感器、奖励、动作离散化， 以及您可能需要的任何其他信息。第二个 YAML 文件是可选的，它可以覆盖第一个 YAML 文件中已定义的内容。

  如果您使用的是 habitat-lab 的 YAML 文件，请检查它们是否定义了 BASE_TASK_CONFIG_PATH。 如果有，则需要将其作为 base_config_file 传递给 Habitat()。事实上，habitat-lab 的 YAML 文件使用相对路径， 如果从其根目录之外调用，将会导致错误。

• 如果您使用数据集，请确保 YAML 文件中定义的路径正确，尤其是当使用相对路径时。habitat-lab 的 YAML 文件使用相对路径， 因此请务必小心。默认情况下，YAML 文件中定义的路径是相对于您启动 Python 代码的位置而言的。 如果您的 data 文件夹位于其他位置，您也可以创建一个符号链接。

重新排列任务示例 ^^^^^^^^^^^^^^^^^^^^^^

• 下载 ReplicaCAD 数据集（--data-path data 会将其下载到您启动代码的文件夹中）

.. code:: shell

python -m habitat_sim.utils.datasets_download --uids replica_cad_dataset --data-path data

• 对于此任务，我们使用 <HABITAT_LAB PATH>/habitat_baselines/config/rearrange/rl_pick.yaml。 该 YAML 文件定义了 BASE_TASK_CONFIG_PATH: configs/tasks/rearrange/pick.yaml, 由于这是一个相对路径，我们需要通过将它的绝对路径作为 base_config_file 参数传递给 Habitat() 来覆盖它。

• 接着，pick.yaml 根据 <HABITAT_LAB PATH> 定义了要使用的数据集。 如果您在之前的下载命令中没有使用 --data-path 参数， 那么 ReplicaCAD 数据集现在位于 <HABITAT_LAB PATH>/data，您需要为其创建一个链接：

.. code:: shell

ln -s <HABITAT_LAB PATH>/data/ <MUSHROOM_RL PATH>/mushroom-rl/examples/habitat

• 最后，您可以运行 python habitat_rearrange_sac.py。

导航任务示例 ^^^^^^^^^^^^^^^^^^^^^^^

• 下载并解压 Replica 场景

  警告！该数据集非常庞大！

.. code:: shell

sudo apt-get install pigz
git clone https://github.com/facebookresearch/Replica-Dataset.git
cd Replica-Dataset
./download.sh replica-path

• 对于此任务，我们仅使用自定义 YAML 文件 pointnav_apartment-0.yaml。

• DATA_PATH: "replica_{split}_apartment-0.json.gz" 定义了一个包含场景细节的 JSON 文件， 比如智能体的初始位置和朝向。其中的 {split} 值由 SPLIT 键定义。

  如果您想尝试新的位置，可以从场景的可导航点集中随机采样。 在初始化一个 habitat 环境后，例如 mdp = Habitat(...), 运行 mdp.env._env._sim.sample_navigable_point()。

• SCENES_DIR: "Replica-Dataset/replica-path/apartment_0" 定义了场景。 如前所述，这个路径是相对于您启动脚本的位置而言的，因此我们需要为 Replica 文件夹创建一个链接。 如果您从其示例文件夹中运行 habitat_nav_dqn.py，请执行以下命令：

.. code:: shell

ln -s <PATH TO>/Replica-Dataset/ <MUSHROOM_RL PATH>/mushroom-rl/examples/habitat

• 最后，您可以运行 python habitat_nav_dqn.py。

可编辑安装

您也可以通过以下方式进行本地可编辑安装：

.. code:: shell

pip install --no-use-pep517 -e .

如果还需要安装可选依赖项：

.. code:: shell

pip install --no-use-pep517 -e .[all]

如何设置并运行实验

为了运行实验，MushroomRL 需要一个提供实验所需信息的脚本文件。您可以参考“examples”文件夹中的脚本，了解如何运行一个实验。

例如，要使用提供的示例脚本之一快速运行一个实验，可以执行以下命令：

.. code:: shell

python3 examples/car_on_hill_fqi.py

引用 MushroomRL

如果您在科学出版物中使用 MushroomRL，请引用以下文献：

.. code:: bibtex

@article{JMLR:v22:18-056,
    author  = {Carlo D'Eramo and Davide Tateo and Andrea Bonarini and Marcello Restelli and Jan Peters},
    title   = {MushroomRL: Simplifying Reinforcement Learning Research},
    journal = {Journal of Machine Learning Research},
    year    = {2021},
    volume  = {22},
    number  = {131},
    pages   = {1-5},
    url     = {http://jmlr.org/papers/v22/18-056.html}
}

如何联系我们

如有任何问题，请发送邮件至 mushroom4rl@gmail.com。

欢迎关注我们的 Twitter @Mushroom_RL <https://twitter.com/mushroom_rl>_！

MushroomRL 快速上手指南

MushroomRL 是一个模块化的 Python 强化学习（RL）库，支持 PyTorch、TensorFlow 等深度学习框架，并兼容 Gymnasium、PyBullet、Deepmind Control Suite 等主流基准环境。它提供了从经典算法（如 Q-Learning）到深度强化学习算法（如 DQN, PPO, SAC）的完整实现。

环境准备

• 操作系统: Linux (推荐 Ubuntu > 20.04), macOS, Windows
• Python 版本: Python 3.x
• 前置依赖:
  • 若需使用绘图功能或 Atari 游戏，Ubuntu 用户需安装系统级依赖：

    sudo apt -y install libsdl-image1.2-dev libsdl-mixer1.2-dev libsdl-ttf2.0-dev \
                     libsdl1.2-dev libsmpeg-dev libportmidi-dev ffmpeg libswscale-dev \
                     libavformat-dev libavcodec-dev swig python3-pyqt5
    

  • 国内加速建议: 推荐使用清华或阿里镜像源安装 Python 包，以提升下载速度。

安装步骤

1. 最小化安装

仅安装核心库，不包含额外的环境模拟器依赖：

pip3 install mushroom_rl -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 全功能安装

安装所有可选组件（包括 Gymnasium, Atari, PyBullet 等支持）：

pip3 install "mushroom_rl[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 可选组件单独安装

• 绘图支持:

  pip3 install "mushroom_rl[plots]" -i https://pypi.tuna.tsinghua.edu.cn/simple
  

• Conda 用户注意: 若在使用 Conda 环境时遇到 QT 相关报错，需在代码开头添加以下配置（替换 <conda_base_path> 和 <env_name>）：

  import os
  os.environ['QT_QPA_PLATFORM_PLUGIN_PATH'] = '<conda_base_path>/envs/<env_name>/bin/platforms'
  

4. 开发者安装（可编辑模式）

如需修改源码或贡献代码：

pip install --no-use-pep517 -e .
# 包含所有依赖的可编辑安装
pip install --no-use-pep517 -e .[all]

注意: 若需使用 MuJoCo 或 Deepmind Control (dm_control)，请参照其官方文档单独安装对应依赖。

基本使用

MushroomRL 通过脚本运行实验。库中 examples 文件夹提供了丰富的示例。

运行示例实验

克隆仓库后，直接运行提供的示例脚本即可开始一个简单的强化学习实验（例如在“山坡小车”环境中使用拟合迭代算法 FQI）：

python3 examples/car_on_hill_fqi.py

自定义实验结构

编写自己的实验脚本通常包含以下步骤：

1. 定义环境（Environment）。
2. 定义代理（Agent）及策略（Policy）。
3. 定义核心（Core）并运行实验。

参考 examples 目录下的其他脚本（如 dqn_atari.py, ppo_gym.py）以了解针对不同环境和算法的具体配置方式。

---

引用: 若在科研工作中使用本库，请引用： Carlo D'Eramo et al., "MushroomRL: Simplifying Reinforcement Learning Research", JMLR 2021.