PettingZoo 是一个用于多智能体强化学习研究的 Python 库，类似于 Gymnasium 的多智能体版本。

文档网站位于 pettingzoo.farama.org，我们还有一个公开的 Discord 服务器（我们也用它来协调开发工作），你可以在这里加入：https://discord.gg/nhvKkYa6qX

环境

PettingZoo 包含以下几类环境：

• Atari：多人 Atari 2600 游戏（合作、竞争及混合模式）
• Butterfly：由我们开发的合作型图形化游戏，需要高度协作
• Classic：经典游戏，包括纸牌、棋盘等
• MPE：一组简单的非图形化通信任务，最初来自 https://github.com/openai/multiagent-particle-envs
• SISL：3 个合作环境，最初来自 https://github.com/sisl/MADRL

安装

安装 PettingZoo 基础库：pip install pettingzoo。

这并不包含所有环境系列的依赖项（某些环境在特定系统上可能难以安装）。

要安装某一环境系列的依赖项，使用 pip install 'pettingzoo[atari]'，或者使用 pip install 'pettingzoo[all]' 来安装所有依赖项。

我们支持并维护 PettingZoo 在 Linux 和 macOS 上的 Python 3.9、3.10、3.11 和 3.12 版本。我们会接受与 Windows 相关的 PR，但不正式支持 Windows。

注意：部分 Linux 发行版可能需要手动安装 cmake、swig 或 zlib1g-dev（例如：sudo apt install cmake swig zlib1g-dev）

入门

有关 PettingZoo 的介绍，请参阅 基本使用。要创建新环境，请查看我们的 环境创建教程 和 自定义环境示例。 关于使用 PettingZoo 训练强化学习模型的示例，请参阅我们的教程：

• CleanRL：实现 PPO：在 Pistonball 环境中训练多个 PPO 智能体。
• Tianshou：训练智能体：在 井字棋 环境中训练 DQN 智能体。
• AgileRL：训练、课程设置与自我对弈：在 四子连珠 环境中使用课程学习和自我对弈训练智能体。

API

PettingZoo 将环境建模为 智能体环境循环 (AEC) 游戏，以便在一个 API 下干净地支持所有类型的多智能体强化学习环境，并尽量减少某些常见错误的发生。

在 PettingZoo 中使用环境的方式与 Gymnasium 非常相似，即通过以下方式初始化环境：

from pettingzoo.butterfly import pistonball_v6
env = pistonball_v6.env()

与环境互动的方式也与 Gymnasium 非常相似：

env.reset()
for agent in env.agent_iter():
    observation, reward, termination, truncation, info = env.last()
    action = None if termination or truncation else env.action_space(agent).sample()  # 这里可以插入你的策略
    env.step(action)

完整的 API 文档请参阅 https://pettingzoo.farama.org/api/aec/

并行 API

在某些环境中，可以假设智能体同时采取行动。对于这类游戏，我们提供了一个辅助 API，以支持并行行动，相关文档请参阅 https://pettingzoo.farama.org/api/parallel/

SuperSuit

SuperSuit 是一个库，为 PettingZoo 和 Gymnasium 环境提供了强化学习中常用的包装器（帧堆叠、观测值处理、归一化等），并具有友好的 API。我们开发它是为了替代 PettingZoo 内置的包装器。https://github.com/Farama-Foundation/SuperSuit

环境版本控制

为了可重复性，PettingZoo 对环境进行了严格的版本控制。所有环境名称都以 _v0 等后缀结尾。当环境发生可能影响学习结果的更改时，版本号会递增 1，以避免潜在的混淆。

引用

若要在出版物中引用该项目，请使用以下格式：

@article{terry2021pettingzoo,
  title={Pettingzoo: 多智能体强化学习的 Gym},
  author={Terry, J and Black, Benjamin and Grammel, Nathaniel and Jayakumar, Mario and Hari, Ananth and Sullivan, Ryan and Santos, Luis S and Dieffendahl, Clemens and Horsch, Caroline and Perez-Vicente, Rodrigo and others},
  journal={神经信息处理系统进展},
  volume={34},
  pages={15032--15043},
  year={2021}
}

项目维护者

• 项目经理：Travis Virgil - travis@farama.org
• 维护者：Albert Han - yjhan96@gmail.com。
• 项目的维护工作也由 Farama 团队共同完成：farama.org/team。

PettingZoo 快速上手指南

PettingZoo 是一个用于多智能体强化学习（Multi-Agent RL）研究的 Python 库，类似于多智能体版本的 Gymnasium。它提供了丰富的环境集合，涵盖从经典棋类游戏到复杂的协作任务。

环境准备

系统要求：

• 操作系统：官方支持 Linux 和 macOS。Windows 社区可提交 PR，但非官方正式支持。
• Python 版本：3.9, 3.10, 3.11, 或 3.12。

前置依赖： 在某些 Linux 发行版上，安装前可能需要手动安装以下系统级依赖：

sudo apt install cmake swig zlib1g-dev

安装步骤

1. 安装基础库 仅安装核心库（不包含特定环境的依赖）：

pip install pettingzoo

国内用户推荐使用清华或阿里镜像加速：

pip install pettingzoo -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装特定环境依赖 根据需求安装特定系列的环境（例如 Atari 游戏）：

pip install 'pettingzoo[atari]'

3. 安装所有依赖 若需使用全部环境系列（注意：部分环境在某些系统上可能难以安装）：

pip install 'pettingzoo[all]'

基本使用

PettingZoo 采用 AEC (Agent Environment Cycle) 模式建模，其使用方式与 Gymnasium 高度相似。

1. 导入并初始化环境 以下示例以 pistonball_v6（蝴蝶系列中的活塞球游戏）为例：

from pettingzoo.butterfly import pistonball_v6

# 初始化环境
env = pistonball_v6.env()

2. 运行交互循环 标准的交互流程如下：重置环境 -> 遍历智能体 -> 获取观测 -> 执行动作。

env.reset()

# 遍历当前回合中的所有智能体
for agent in env.agent_iter():
    # 获取当前智能体的观测、奖励、终止状态等信息
    observation, reward, termination, truncation, info = env.last()
    
    # 如果游戏未结束，采样一个随机动作（此处替换为你的策略模型）
    if termination or truncation:
        action = None
    else:
        action = env.action_space(agent).sample()
    
    # 执行动作
    env.step(action)

提示：对于允许智能体同时行动的环境，PettingZoo 还提供了并行 API (parallel API)，具体用法可参考官方文档。如需使用帧堆叠、归一化等常用包装器，建议配合 SuperSuit 库使用。