Mesa 4 正在积极开发中！请查看我们最新的 预发布版本 和 问题追踪器。
关于 GSoC，请参阅我们的 2026 年 Google 夏季编程大赛 指南。

Mesa：基于代理的 Python 建模框架

CI/CD
软件包
元数据
聊天
引用

Mesa 使用户能够利用内置的核心组件（如空间网格和代理调度器）或自定义实现，快速创建基于代理的模型；通过基于浏览器的界面进行可视化；并使用 Python 的数据分析工具分析结果。其目标是成为 NetLogo、Repast 或 MASON 的 Python 替代方案。

上图：Mesa 实现的 WolfSheep 模型，可在浏览器窗口或 Jupyter 中显示。在线演示可在此处访问：链接。

特性

• 模块化组件
• 基于浏览器的可视化
• 内置分析工具
• 示例模型库

使用 Mesa

要安装我们最新的稳定版 Mesa 3，请运行：

pip install -U mesa

Mesa 4 的开发已经开始。要安装最新的 Mesa 4 预发布版本，请使用：

pip install -U --pre mesa

从 Mesa 3.0 开始，我们不再默认安装所有依赖项。

# 如果需要，您可以自定义所需的额外依赖项。可用选项如下：
pip install -U "mesa[network,viz]"

# 这等同于我们推荐的依赖项：
pip install -U "mesa[rec]"

# 若要安装所有依赖项，包括开发者依赖项：
pip install -U "mesa[all]"

您也可以使用 pip 安装最新的 GitHub 版本：

pip install -U -e git+https://github.com/mesa/mesa@main#egg=mesa

或者安装此仓库中的任何其他（开发）分支，或您自己的分叉：

pip install -U -e git+https://github.com/YOUR_FORK/mesa@YOUR_BRANCH#egg=mesa

资源

有关 Mesa 的资源或使用帮助，请参阅以下内容：

• 入门指南（一系列教程，将引导您完成一个基本模型。）
• Mesa 的 GSoC — 候选人指南（面向有意参与 Mesa 的 Google 夏季编程大赛的候选人。）
• Mesa 示例（一个包含经典 ABM 的仓库，属于 Mesa[rec] 安装的一部分，并使用最新的 Mesa 版本。）
• 文档（Mesa 的文档、API 和实用片段）
  • 开发版本文档（如果您使用的是预发布版 Mesa，则为最新版本的文档。）
• 讨论区（关于 Mesa 的 GitHub 线程式讨论。）
• Matrix 聊天（通过 Matrix 讨论 Mesa 的聊天论坛。）

在 Docker 中运行 Mesa

您可以通过几种方式在 Docker 容器中运行 Mesa。

如果您是 Mesa 的开发者，首先请安装 Docker Compose，然后在包含 Mesa Git 仓库的文件夹中运行：

$ docker compose up
# 如果希望在后台运行，可以改为：
$ docker compose up -d

这将运行谢林模型作为示例。

使用此 Git 仓库中的 docker-compose.yml 文件，docker compose up 命令会执行两项重要操作：

• 它会将 mesa 根目录（相对于 docker-compose.yml 文件）挂载到 /opt/mesa，并在该目录上运行 pip install -e，以便您对 mesa 所做的更改能够反映在正在运行的容器中。
• 它会将容器的端口 8765 绑定到主机系统的端口 8765，这样您就可以像往常一样通过浏览器访问 localhost:8765 与正在运行的模型交互。

如果您是希望在某个模型上运行 Mesa 的模型开发者，则需要：

• 确保您的模型文件夹位于包含 docker-compose.yml 文件的文件夹内。
• 将 docker-compose.yml 中的 MODEL_DIR 变量更改为指向您的模型路径。
• 确保模型文件夹中包含 app.py 文件。

之后，只需运行 docker compose up -d，即可通过 localhost:8765 访问该模型。

为 Mesa 做贡献

想加入 Mesa 团队，或者只是好奇 Mesa 目前的进展吗？你可以……

• 加入我们的 Matrix 聊天室，在这里可以非正式地讨论问题、提出想法。
• 参加每月的开发会议（开发会议的时间、议程和记录可以在 Mesa 讨论区 查看）。
• 直接在 GitHub 上查看代码。

如果你遇到问题，请提交一个 issue，以便我们讨论。如果可能的话，再附上一个 pull request。

如果你想添加新功能，请通过 issue 联系我们，或者参加一次开发会议（参见 Mesa 讨论区）。通常情况下，如果你自己实现这个功能，它被合并的可能性会更大！

别忘了查看 贡献者指南。

引用 Mesa

若要在你的论文中引用 Mesa，可以参考我们在《开源软件期刊》（JOSS）上发表的同行评审文章：

• ter Hoeven, E., Kwakkel, J., Hess, V., Pike, T., Wang, B., rht, & Kazil, J. (2025). Mesa 3：2025 年基于 Python 的主体建模。开源软件期刊，10(107), 7668. https://doi.org/10.21105/joss.07668

我们还提供了 CITATION.cff，可用于生成 APA、BibTeX 等多种引用格式。

Mesa 快速上手指南

Mesa 是一个用于在 Python 中构建、分析和可视化**基于代理的模型（Agent-Based Models, ABM）**的开源框架。它是 NetLogo、Repast 或 MASON 等工具的 Python 替代方案。

环境准备

• 操作系统：Windows、macOS 或 Linux
• Python 版本：建议安装 Python 3.9 或更高版本
• 前置依赖：
  • pip (Python 包管理工具)
  • (可选) Docker 及 Docker Compose（如需容器化运行）
  • (可选) Jupyter Notebook（如需在笔记本中进行交互式开发）

提示：国内用户建议在安装时使用清华或阿里镜像源以加速下载。

安装步骤

1. 安装稳定版（推荐）

安装最新的稳定版本（Mesa 3.x）：

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

2. 按需安装扩展依赖

从 Mesa 3.0 开始，默认不再安装所有依赖。你可以根据需求选择安装：

• 推荐配置（包含网络和可视化支持）：

  pip install -U "mesa[rec]" -i https://pypi.tuna.tsinghua.edu.cn/simple
  

• 自定义配置（仅安装特定功能，如网络分析或可视化）：

  pip install -U "mesa[network,viz]" -i https://pypi.tuna.tsinghua.edu.cn/simple
  

• 完整配置（包含所有开发依赖）：

  pip install -U "mesa[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple
  

3. 安装开发预览版（可选）

如果你想体验正在开发中的 Mesa 4 新功能：

pip install -U --pre mesa -i https://pypi.tuna.tsinghua.edu.cn/simple

或者直接从 GitHub 源码安装最新开发版：

pip install -U -e git+https://github.com/mesa/mesa@main#egg=mesa

基本使用

以下是一个最简单的“狼羊吃草”模型的核心代码示例，展示如何定义代理（Agent）和模型（Model）。

1. 创建模型文件

新建一个名为 model.py 的文件，写入以下代码：

from mesa import Model, Agent
from mesa.time import RandomActivation
from mesa.space import MultiGrid

class WolfSheepAgent(Agent):
    def __init__(self, unique_id, model, is_wolf):
        super().__init__(unique_id, model)
        self.is_wolf = is_wolf
        self.energy = 10

    def step(self):
        # 简单的移动逻辑
        self.model.grid.move_to_empty(self)
        self.energy -= 1
        
        # 简单的繁殖或捕食逻辑占位
        if self.energy <= 0:
            self.model.schedule.remove(self)

class WolfSheepModel(Model):
    def __init__(self, width=10, height=10, initial_agents=10):
        super().__init__()
        self.grid = MultiGrid(width, height, torus=True)
        self.schedule = RandomActivation(self)
        
        # 创建初始代理
        for i in range(initial_agents):
            a = WolfSheepAgent(i, self, is_wolf=(i % 2 == 0))
            self.schedule.add(a)
            x = self.random.randrange(self.grid.width)
            y = self.random.randrange(self.grid.height)
            self.grid.place_agent(a, (x, y))

    def step(self):
        self.schedule.step()

2. 运行模型

在 Python 脚本或 Jupyter Notebook 中运行模型：

from model import WolfSheepModel

# 初始化模型
model = WolfSheepModel(width=10, height=10, initial_agents=20)

# 运行 10 步
for _ in range(10):
    model.step()
    print(f"Step {_}: Agents remaining: {model.schedule.get_agent_count()}")

3. 启动可视化服务器（可选）

如果你安装了 [viz] 依赖并创建了相应的 app.py（参考官方示例），可以使用以下命令在浏览器中查看交互式界面：

mesa runserver

默认访问地址为：http://localhost:8521 (具体端口视配置而定，Docker 环境下通常为 8765)。

---

更多详细教程和示例模型，请访问 Mesa 官方文档 或查看仓库中的 examples 目录。