Repast仿真入门到进阶：从饥饿-觅食模型到论文级应用

简介：面向社会科学、经济学与复杂系统研究者的 Repast 仿真建模完整教程与实例，整合了英文原版教材、可运行的 H2R 案例代码及 JavaDoc API 文档，帮助学习者从零搭建多 Agent 仿真模型并完成调试。资源包共 72 个文件，主体为 htm/html 教程页面与配套 css 样式，辅以 gif/bmp 示意图、H2R 代码压缩包和 JavaDoc 索引，整体仅 303KB，轻量便携，适合离线查阅。已有 730 人学习。内容按安装设置、基本概念、模型构建、脚本控制、可视化界面、运行调试与数据收集分析等模块展开，具体包括 Agent 与 Environment 的核心概念、Jython/Groovy 脚本驱动、图形界面定制实操，并通过城市人口动态、传染病传播等案例演示从概念到实现的完整流程。对需要开展复杂系统模拟的科研人员，以及正在使用 Repast 进行项目开发的工程师，这份资料兼顾原理讲解与实战参考，能有效缩短上手周期。

1. 为什么要用 Repast：一次仿真课设引发的重构

某高校的课程设计里，要用「兔子吃草」这类生态模型演示复杂系统仿真。A 同学一开始用脚本语言硬写仿真，主循环、随机数、数据统计全部手搓，模型跑到第 200 步直接崩了；换了一个商业仿真工具，又因为授权和环境问题卡了一整周。折腾下来才意识到：做基于 Agent 的建模与仿真，真正需要的不是图形界面，而是一套能把「离散事件调度、空间结构、Agent 生命周期、结果统计」一揽子解决的框架。Repast 正是为数不多能做到这一点的开源仿真平台。这份方案按「需求—设计—实现—避坑—进阶—验收」的路径，把 Repast 的完整教程和可直接照抄的实例组织成一套能落地的学习体系，适合正在做仿真类毕设、课程设计，或者想从零入门 Agent 仿真的工程师参考。

2. 总体设计：一条主线、两种实现、三类成果

2.1 主线模型：为什么选「饥饿—觅食」而不是上来就复现经典论文

做教程最容易犯的错误就是一上来套用复杂论文模型，读者要么调不出参数，要么跑半天看不到有意义的现象。我建议把主线落在「饥饿—觅食」这样的极简生态模型上：网格上有食物，Agent 消耗能量、吃草回血、耗尽即死，能量高时繁殖。麻雀虽小，却把 Repast 的核心机制全部串了起来，覆盖调度注解、空间管理、Agent 生命周期与数据采集中最容易被忽略的四个点。

这一个模型跑通了，后面的传染病、供应链、土地利用全都能按同一个套路迁移。我把这条主线拆成三层：第一层解决“每一步发生了什么”，对应 Repast 的调度系统；第二层解决“Agent 跟 Agent、Agent 跟环境怎么挨着”，对应连续空间和网格空间；第三层解决“仿真结果怎么变成论文图表”，对应数据采集和参数扫描。三层正好对应一份教程资源里最容易缺失的三块内容。

2.2 技术栈选型：Simphony、Repast4py 与 HPC 版怎么选一个

Repast 家族有四条线，踩错线的成本很高。第一梯队是 Repast Simphony，Java 实现，带图形化 Scenario 编辑器，适合课设和中小规模仿真；第二梯队是 Repast4py，Python 实现，跟数据科学栈衔接顺滑，适合要把仿真结果直接交到 Pandas、Matplotlib 手里的人；第三梯队是 Repast HPC，面向集群大规模计算，一般出现在高性能仿真领域。对绝大多数毕设和课设来说，选 Simphony 就够了，图形界面能直接展示 Agent 移动过程，答辩时一张截图就是最好的“模型可运行”证据。

提示：一个常见误解是“教程必须全覆盖三个版本”。实际上 Simphony 和 Repast4py 的建模心智完全一致，先吃透一个，另一个半天就能迁移。

2.3 一份「完整教程和实例」的骨架应该怎么组织

我一般把这类资源组织成四块：docs 放原理讲解，src 放可运行模型，parameters 放参数扫描配置，output 放基准结果。拿到资源先看 src 再看 parameters，而不是先啃文档。一条铁律是每个模型都要带一个“稳定跑完的默认配置”，否则读者照着教程敲进 IDE 却跑不出来，学习热情在第一分钟就被浇灭。

文件清单不必面面俱到，但建议至少包含：一个 README 说明环境要求；一个最小可运行场景（scenario.rs）；一个包含模型参数的 XML；一个带注释的 Agent 类；一个结果 CSV 的样例。拿到手之后，先跑最小场景验证环境，再逐行读 Agent 类，最后改参数做实验，这套顺序能把试错成本降到最低。教程资源能不能用，关键看这份骨架是否完整，而不是看代码量有多大。

2.4 从面向过程的脚本，到面向 Agent 的建模：思想转变

从脚本写作切换过来最容易犯的错是把 Repast 当成一个大循环，硬要在主线程里写 while 循环控制 step。实际上 Agent 的行为由注解驱动，框架会按时间表回调各个 Agent 的方法；你不需要自己写循环，也不应该直接操作循环计数。这个转变是所有后续代码的基础，理解透了再看第 3 章的代码，每一行都不会陌生。

3. 核心实现：一个可复现的「饥饿—觅食」仿真

3.1 Schedule 调度：用注解告诉框架“每步干什么”

先说调度。在 Repast Simphony 中，Agent 的行为围绕@ScheduledMethod注解组织，核心结构示意如下：

package demo.model; import repast.simphony.engine.schedule.ScheduledMethod; import repast.simphony.space.continuous.ContinuousSpace; import repast.simphony.space.grid.Grid; import repast.simphony.random.RandomHelper; public class ForagerAgent { private ContinuousSpace<Object> space; private Grid<Object> grid; private double energy = 20.0; private double drain = 0.2; @ScheduledMethod(start = 1, interval = 1, priority = 1) public void stepAction() { // 1. 更新能量，这是每一步的“基础成本” energy -= drain; if (energy <= 0) { // 2. 能量耗尽，标记死亡，由模型层统一移除 return; } // 3. 通过随机角度移动一个单位，保持空间坐标同步 double angle = RandomHelper.nextDoubleFromTo(0.0, 2 * Math.PI); space.moveByVector(this, 1.0, angle); grid.moveTo(this, (int) space.getLocation(this).getX(), (int) space.getLocation(this).getY()); } }

代码里start = 1表示初始延迟 1 个步长，interval = 1表示每步调度一次，priority = 1用于保证同一时刻多个事件之间的先后顺序。移除 Agent 时不能直接在方法里做context.remove(this)，因为调度仍在进行，会引发并发修改异常；通常的做法是维护一个待死亡队列，在本步结束后由主模型统一清理。这是初学者最容易踩的坑，后面避坑章会专门展开。

3.2 Context 与 Grid：空间结构怎么搭出来

空间是 ABM 的第二个支柱。用Context<Object>管理所有 Agent，再用Grid<Object>表示二维网格。核心结构示意：

package demo.model; import repast.simphony.context.Context; import repast.simphony.context.DefaultContext; import repast.simphony.space.continuous.ContinuousSpace; import repast.simphony.space.grid.Grid; import repast.simphony.space.grid.GridBuilderParameters; import repast.simphony.space.grid.SimpleGridAdder; import repast.simphony.space.grid.WrapModeBorders; import repast.simphony.space.continuous.WrapAroundBorders; public class DemoContext extends DefaultContext<Object> { public static final int WIDTH = 50; public static final int HEIGHT = 50; @Override public Context<Object> build() { // 连续空间用于平滑移动，网格空间用于邻居计算 ContinuousSpace<Object> space = new ContinuousSpace.Builder<Object>() .name("space") .borders(new WrapAroundBorders()) .build(); // 网格同样是环状边界，避免 Agent 走到边缘出界 Grid<Object> grid = new Grid.Builder<Object>() .name("grid") .borders(new WrapModeBorders()) .build(WIDTH, HEIGHT); // 初始化 N 个 ForagerAgent，放入两个空间 for (int i = 0; i < 30; i++) { ForagerAgent agent = new ForagerAgent(space, grid); add(agent); } return this; } }

WrapAroundBorders和WrapModeBorders表示“绕回”的环形边界，食物模型里很合适；如果要模拟封闭房间疏散，就要换成 strict 边界并加上墙面的逻辑。连续空间负责“移动”，网格负责“邻居关系”，两者通过同一个 Agent 的坐标同步。空间配好后，初始化 N 个 ForagerAgent 按随机位置分别放入两个空间即可。

3.3 数据采集：结果怎么从黑匣子里拿出来

模型跑完看不到数据，等于白跑。Repast 提供 DataRecorder，但更通用的做法是在模型里直接维护输出，每 N 步把统计量写入 CSV：

int stepCounter = 0; int aliveCount = 0; double totalEnergy = 0.0; @ScheduledMethod(start = 1, interval = 10) public void report() { // 每 10 步汇总一次全局状态，写入 report.csv String line = stepCounter + "," + aliveCount + "," + totalEnergy / aliveCount; // 追加写入，文件头在仿真启动时初始化一次 FileWriter writer = new FileWriter("output/report.csv", true); writer.write(line + "\n"); writer.close(); }

写数据时注意三件事：第一，report()的 interval 要和主行为错开，避免同一步内既移动又统计，数据会打架；第二，CSV 文件头必须在第一步就写好，不要边跑边改表头；第三，用追加模式而不是覆盖模式，这样多次运行的结果可以合并在同一个文件里。我一般会额外输出一个“Agent 平均存活时间”之类的指标，配合死亡事件的时间分布，就能画出生存曲线，这在答辩里非常加分。

3.4 参数实验：把「调参玄学」变成可重复的科学实验

模型跑十个不同参数组合，如果每次都要手动改代码，效率太低。Repast 本身支持 Parameter Sweep，也可以写成配置文件：

<parameter name="initialForagers" type="int" value="30"/> <parameter name="energyInitial" type="double" value="20.0"/> <parameter name="energyDrain" type="double" value="0.1"/> <parameter name="foodRegrowRate" type="double" value="0.4"/>

在运行界面勾选 Parameter Sweeps，指定扫描范围和步长，框架会自动跑完所有组合。每一次运行的输出文件都带上参数标记，方便事后对照。牢记一个原则：参数变化只改配置，不动代码。把参数写死在类里是教程实例翻车率最高的写法，属于典型的没有后悔药可吃的情况。真正把参数实验串起来跑批处理的工程手段，我会在第 5 章展开。

4. 避坑指南：环境、调度和随机性最容易翻的五个车

4.1 模型跑起来没几秒就内存溢出

现象：内存暴涨，仿真提前终止，常见于 500 步以后。

原因：Agent 繁殖逻辑只在能量足够时执行，但死亡 Agent 没有被及时移除，或ScheduledMethod每步都在创建新对象，旧对象仍然被空间引用，垃圾回收无法回收。

解决：统一维护存活 Agent 集合，死亡事件进入队列，在本步结束后批量移除；同时检查调度方法里是否创建了随步数增长的临时对象。调大堆内存只是治标，治本靠生命周期清理，把“创建—存活—死亡—移除”的闭环走完整。

4.2 同一条随机种子，两次结果不一样

现象：相同参数、相同种子，两次运行的曲线差异明显，报告里的结果别人复现不出来。

原因：在 Simphony 里设置种子，需要同时固定 Repast 的随机数引擎和 Java 的Random底数；有人只在代码里调用RandomHelper.setSeed()，却没有在 scenario 配置里同步，相邻两次运行的伪随机序列整体错位。

解决：把种子集中放在一个常量或参数文件里，启动阶段只设置一次；所有随机数一律通过RandomHelper获取，不要混用Math.random()。这一步做不好，后面的参数实验全是玄学。

注意：固定种子不等于做多次重复实验。固定种子只保证同一配置下可复现，要评估模型的波动性，至少跑 10 个以上不同种子并看均值与方差。

4.3 网格里的 Agent 莫名其妙少了一半，或全部挤在角落

现象：Agent 的空间位置在运行过程中错乱，重启后恢复正常。

原因：连续空间和网格空间各自独立，移动时只更新了ContinuousSpace，Grid里的坐标还是旧值；当后续代码用Grid.getObjectsAt()查询邻居时，就查到了过期坐标。

解决：任何移动操作后，同步调用grid.moveTo()，并且把“移动—同步—查询邻居”写进一个原子方法里。用@ScheduledMethod触发移动时尤其要注意，同一步内多次移动会丢位置更新。一个 Agent 每步只允许移动一次，是这条规则的简化版。

4.4 shapefile 加载失败，地图空白或坐标偏移

现象：GIS 模型里地图显示空白，或点和面叠不到一起去。

原因：八成是坐标系不统一。底图使用 Web 墨卡托，而项目默认的投影是 WGS84 经纬度，Repast 加载后坐标范围对不上，图自然就花了。

解决：在 GIS 软件里把底图和要素统一投影到同一个坐标系，再导入 Repast。文件名和路径全部使用英文，避免中文编码带来的读取异常。这个坑通常不在 Repast 本身，而在前期数据处理。

4.5 改了几行代码，IDE 直接编译不过

现象：加了一个属性，结果一堆类突然找不到，或者NoClassDefFoundError。

原因：Repast 的 Agent 类与 scenario 中的 Agent 类型注册列表不一致。新建的类没有被context.xml识别，或者打包产物里没有包含最新 class。

解决：每次新建 Agent 后，确认 scenario 里的 Agent 类型已经指向新类；用 Repast 的 Clean & Rebuild 功能清掉旧缓存。把模型工程和 scenario 放在同一个项目里，能避免不少 classpath 的坑。总结下来，这些坑有一半我在带模拟项目时见过不止一次，属于交学费才能积累起来的血泪经验，直接背下来能省很多排查时间。

5. 进阶落地：从觅食模型到论文级仿真场景

5.1 场景二：SEIR 传染病模型如何快速移植

框架已经跑通，场景投射就简单了。以 SEIR 疾病传播为例：把 ForagerAgent 换成 PersonAgent，增加四种状态（易感、暴露、感染、恢复）；把“吃草”换成“感染”，把“能量”换成“潜伏期计数”，把“空间邻居”换成“接触面”。Repast 的网格邻居查询正好承担“距离阈值内触发事件”的逻辑，代码结构跟觅食模型一一对应。

移植时最大的认知误区是以为要重写框架，实际只需要改 Agent 的行为方法，Context 和 Grid 的结构基本复用。改完之后，参数扫描仍然用原来的配置方式，只是参数名换成感染率、恢复率、隔离比例。这也是为什么我坚持让读者先把觅食模型吃透，因为传染病、供应链、生态、城市流动这些领域在 Agent 建模层面用的是同一套骨架。

5.2 场景三：接入 GIS 真实地图与土地利用模拟

把仿真从“抽象网格”推进到“真实地图”，是论文加分项。Repast 的 GIS 投影支持加载 shapefile 底图，进而让 Agent 在真实街道或地块上移动。技术要点有两个：一是空间类型从Grid换成Geography，坐标系统统一用 WGS84；二是把面要素和线要素转为 Agent 可访问的属性，比如地块的容积率或道路的通行速度。

在这个阶段，位置移动不再是简单随机游走，而要走“当前位置找最近可用地块—计算可达性—进入地块”的逻辑。GIS 数据预处理量不亚于代码量，通常的做法是先在地理软件里完成空间连接和字段整理，Repast 只负责加载和仿真。地图本身不需要在仿真里做渲染，把结果导出成带坐标的 CSV，再用外部工具出图，既快又稳，也更容易集成到论文排版里。

5.3 批处理与并行：三个种子 × 五组参数的正确跑法

论文级仿真要求可重复和可对比。单个模型一次跑完说明不了问题，通常的做法是写一个脚本按下面的组合批量执行：

for seed in 1 2 3; do for param in 10 20 30 40 50; do java -cp repast.jar demo.Main launch scenario.rs \ -seed $seed -param initialForagers=$param mv output/run.csv output/run_seed${seed}_param${param}.csv done done

每条命令跑完后把输出文件按“种子 + 参数”重命名，最后用 Pandas 或 Excel 汇总出均值、方差与图表。这个批处理流程看似简单，却是把仿真从演示变成实证的关键一步。如果模型较大且跑得慢，可以把不同的参数组合丢到多进程里并行，Repast 的调度内核本身是线程安全的，只要输出文件不冲突，并行提速非常直接。跑完一批之后，先看有没有“每个种子都复现”的核心结论，再看参数变化是否导致行为翻转，这两个检查做完，模型才敢写进报告。

6. 验收与答辩：三步证明你的模型不是自嗨

6.1 从三个层面证明仿真结果是可信的

第一个层面，单个 Agent 行为测试。跑一个 2×2 的微型网格，设置确定性条件，比如能量 0.1、食物永不生长、每次移动固定方向，断言这个 Agent 应该在第几步死亡、死亡前移动了多少格。这类测试能在半小时内揪出超过一半的实现 bug。

第二个层面，整体统计合理性。模型跑完后，把 Agent 存活曲线、总生物量曲线和平均能量曲线放在同一张图上，观察是否为单调或振荡的合理形态；如果出现锯齿或突跳，通常说明调度优先级或数据采集的频率设计有矛盾，而真实生态过程不会出现这类突变。

第三个层面，参数敏感性。对每个关键参数做加减 30% 的扫描，看结果是否剧烈跳变，跳变点在哪里，跳变的原因能否在机制上解释。答不上来解释的参数就是答辩时被追问的高危区，提前写好这段分析，等于提前堵住漏洞。

6.2 答辩时的呈现技巧

把“我调了半天参数终于这样”翻译成“在初始条件 A、参数 B、种子 C 下，模型表现出特征 D”，这是答辩场上最实用的表达结构。一张包含参数配置表、十个种子的箱线图、三组敏感性曲线的图，比任何“结果很好”的口头描述都有说服力。若被问到模型局限，如实说“当前忽略了某因素，这恰好是后续工作”，比强行辩解更能拿到分。

从那以后我每次跑仿真前都强制走一遍“固定种子 → 微型测试 → 统计自检”的流程，缺一环就不跑批处理，这个习惯在带别人的模型时依然适用。希望你也能用这套流程少走点弯路。

本文还有配套的精品资源，点击获取