简介这份资源是面向多Agent系统建模初学者与研究者的Repast完整教程与实例合集重点解决从环境搭建到模型落地的学习路径问题适合社会科学、经济学及复杂系统仿真方向的师生与工程师使用。压缩包共72个文件约303KB以htm与html网页文档为主体辅以css样式、gif与bmp图像及package-list索引整体呈离线文档站结构便于按章节顺序浏览。内容围绕Repast的安装配置、Model与Agent等基本概念、行为定义与交互规则、Jython与Groovy脚本控制、可视化界面定制、运行调试及数据收集分析展开并配有H2R等实践案例帮助读者从概念理解走向动手实现。目前已有729人学习可作为系统入门与案例演练的参考材料。1. 从一份能跑通的 Repast 教程说起仿真项目最缺的不是文档是能复现的实例很多做 Agent-Based Modeling 的同行都有个共识Repast 的官方文档不算少但真正卡住人的从来不是 API 查不到而是拿到一个仿真需求后不知道第一个 Agent 类该怎么写、Context 怎么建、调度器挂在哪一层。这份「Repast 完整教程和实例」资源核心价值就在于它把建模流程从环境搭建到实例运行串成了一条线而不是散落成一堆概念。它适合两类人一类是刚接触多主体仿真、需要照着跑通第一个模型的新手另一类是已经用过 NetLogo 或 MASON、想迁移到 Repast 做更复杂空间交互的熟手。下面我按自己拆包复现的顺序把这份资源里真正能落地的部分讲清楚。2. Repast 仿真环境搭建与第一个 Agent 类从安装到跑通最小模型2.1 为什么选 Repast 而不是其他仿真框架做多主体仿真选型绕不开三个维度Agent 规模、空间建模能力、以及和外部数据/代码的耦合程度。NetLogo 上手快但自定义 Java 逻辑和集成外部库时比较别扭MASON 性能好但缺少开箱即用的可视化与调度封装。Repast Simphony 的定位正好卡在中间——它基于 Java 生态自带调度器、Context 管理、GIS 空间支持和运行时 GUI同时允许你直接写 Java 或 Groovy 代码去控制每一个 Agent 的行为细节。这份教程和实例资源里实例部分覆盖了典型的 Agent 交互场景比如网格空间上的移动与资源竞争、基于状态的决策切换。它没有停留在「Hello Agent」级别而是给出了带参数扫描和批量运行的完整工程结构。对于需要做论文实验或项目验证的人来说这种「能直接改参数跑出结果」的实例比纯文档有用得多。2.2 环境搭建JDK、Eclipse 与 Repast Simphony 的版本对齐Repast Simphony 对 JDK 版本比较敏感这是第一个容易翻车的地方。我一般会按下面的组合来配避免版本玄学组件推荐版本说明JDK11 或 17不要用 JDK 8 以下也不要用 21部分插件未适配Eclipse2022-03 及以上需带 PDE 插件Repast Simphony2.9 或 2.10与 JDK 11/17 匹配较好Groovy随 Repast 自带不建议单独升级安装步骤大致是先装好 JDK 并配置JAVA_HOME再安装 Eclipse然后通过 Eclipse 的 Install New Software 添加 Repast 的更新站点。这里有个细节——更新站点地址在教程里通常会给但如果你网络环境访问慢可以提前把离线包下好用本地归档方式安装。# 验证 JDK 版本确保和 Repast 要求一致 java -version # 输出应类似openjdk version 17.0.x # 检查 JAVA_HOME 是否指向正确路径 echo $JAVA_HOME # Linux/macOS 下应输出 JDK 根目录Windows 用 echo %JAVA_HOME%这两条命令看起来简单但很多「Eclipse 启动后找不到 Repast 运行时」的问题根源就是JAVA_HOME指向了 JRE 而不是 JDK或者系统里存在多个 Java 版本导致 Eclipse 用了错误的那个。参数上唯一要盯的就是版本号JDK 11 和 17 都可以但一旦选定就不要混用。2.3 第一个 Agent 类从 Context 到 Schedule 的完整链路Repast 的模型入口通常是一个继承自DefaultContext的上下文类加上一个ScheduledMethod标注的步进方法。教程里的最小实例结构大致如下// 定义一个简单的 Agent每个 tick 向随机方向移动一格 public class SimpleAgent { private int x, y; private GridSimpleAgent space; public SimpleAgent(GridSimpleAgent space) { this.space space; // 随机放置到网格上 this.x (int)(Math.random() * space.getSizeX()); this.y (int)(Math.random() * space.getSizeY()); } // start 参数表示从第 1 个 tick 开始执行interval1 表示每 tick 执行一次 ScheduledMethod(start 1, interval 1) public void step() { // 随机移动逻辑先移除旧位置再计算新位置最后放回 space.moveTo(this, (x (int)(Math.random()*3) - 1 space.getSizeX()) % space.getSizeX(), (y (int)(Math.random()*3) - 1 space.getSizeY()) % space.getSizeY() ); } }这段代码里几个关键点ScheduledMethod的start和interval决定了 Agent 在仿真时钟上的执行节奏interval1就是每个 tick 都跑一次Grid的moveTo会自动处理坐标越界但前提是你传进去的坐标已经取过模。教程实例里还演示了如何在 Context 构建阶段批量创建 Agent 并注入空间对象这一步如果顺序搞反——先调度后注入——运行时会报空指针这是新手最常见的翻车点之一。3. 参数扫描与批量运行把实例改成能出实验数据的工程3.1 用参数文件驱动仿真从硬编码到可配置教程里的实例如果只是写死参数那价值有限。真正能用于实验的部分是它演示了如何通过 Repast 的Parameters机制把关键变量外置。常见做法是在项目根目录放一个parameters.xml然后在代码里用RunEnvironment.getInstance().getParameters()读取。!-- parameters.xml 片段定义网格大小和 Agent 数量 -- parameters parameter namegridSize typeint value50 / parameter nameagentCount typeint value200 / parameter namemaxTick typeint value500 / /parameters// 在 Context 初始化时读取参数 Parameters params RunEnvironment.getInstance().getParameters(); int gridSize (Integer) params.getValue(gridSize); int agentCount (Integer) params.getValue(agentCount); // 根据参数创建网格和 Agent GridSimpleAgent grid new Grid(gridSize, gridSize); for (int i 0; i agentCount; i) { SimpleAgent agent new SimpleAgent(grid); context.add(agent); grid.put(agent, agent.getX(), agent.getY()); }这样改的好处是同一套代码不用重新编译就能跑不同规模的实验。参数类型支持 int、double、boolean 和 String读取时注意类型转换要和 xml 里声明的一致否则会抛ClassCastException。教程实例里还给出了参数扫描的批量运行配置通过 Repast 的批处理模式可以自动遍历多组参数并输出结果到 CSV这对做敏感性分析非常实用。3.2 仿真结果输出与数据回收跑完仿真只是第一步能把每个 tick 的状态落盘才算完整。Repast 提供了DataSets和DataSink机制教程实例里用的是自定义ScheduledMethod在固定间隔采集数据并写入文件。// 每 10 个 tick 采集一次 Agent 位置分布写入 CSV ScheduledMethod(start 10, interval 10) public void collectData() { String fileName output/agent_positions.csv; try (FileWriter fw new FileWriter(fileName, true)) { for (SimpleAgent a : grid.getAllObjects()) { fw.write(RunEnvironment.getInstance().getCurrentSchedule().getTickCount() , a.getX() , a.getY() \n); } } catch (IOException e) { e.printStackTrace(); } }这里要注意文件写入模式用FileWriter的追加模式避免每次覆盖但如果是多次独立运行最好在 Context 初始化时先清空或按运行编号分文件。教程实例里还提到了用DataSink做更结构化的输出但那个配置稍复杂新手先用 CSV 方式跑通更稳妥。3.3 批处理运行与结果对比Repast 的批处理运行器允许你在不启动 GUI 的情况下跑完整个参数空间。配置方式是在 Eclipse 的 Run Configuration 里选择 Repast Batch Runner指定参数文件中的扫描范围和输出目录。教程实例里给出的典型场景是网格大小固定Agent 数量从 100 到 500 分五档每档跑 20 次取平均。这种配置下一次批处理可能跑上百次仿真耗时较长建议先在单次运行确认逻辑无误后再开批处理。提示批处理运行时 GUI 不会显示所有输出依赖日志和文件。建议在代码里加好日志级别控制避免控制台被刷爆。4. 避坑与常见问题Repast 实例运行中容易翻车的几个地方4.1 现象Eclipse 启动后找不到 Repast 项目模板原因通常是 Repast 插件安装不完整或者 Eclipse 的更新站点缓存了旧版本元数据。解决方式是先卸载再重装插件安装时取消勾选「Contact all update sites during install to find required software」避免它去拉取不兼容的依赖。如果还是不行检查 Eclipse 的dropins目录里是否有残留的旧版 jar。4.2 现象仿真跑起来后 Agent 不动或者只动一次先看ScheduledMethod的start和interval参数。如果start0有些 Repast 版本会把它当作无效调度如果interval设成了大于 1 的值Agent 就是隔几个 tick 才动一次。另外确认 Schedule 是否在 Context 构建后被正确激活——教程实例里是在ContextBuilder的build()方法末尾调用RunEnvironment.getInstance().getCurrentSchedule().schedule(this)漏掉这步调度器不会启动。4.3 现象参数文件读取时报空指针或类型转换错误检查parameters.xml的路径是否在项目 classpath 下以及参数名是否和代码里getValue()的字符串完全一致大小写敏感。类型转换错误多半是 xml 里写了typeint但代码里用(Double)去接改成(Integer)即可。如果参数文件里某个参数没定义getValue()会返回 null直接拆箱就会 NPE建议加一层判空。4.4 现象批处理运行结果每次都不一样无法复现仿真里用了Math.random()且没有固定种子。Repast 提供了RandomHelper工具类可以在 Context 初始化时用RandomHelper.setSeed(42)固定随机源。教程实例里默认没开种子做实验时一定要手动加上否则结果波动会让你怀疑模型逻辑有问题。4.5 现象GIS 空间或网络空间加载失败如果实例里用到了Geography或Network类型的投影需要额外引入对应的 Repast 扩展包并且确保 shapefile 或网络文件的路径是绝对路径或正确的相对路径。常见错误是文件路径里带了中文或空格Repast 底层读取时可能解析失败换成纯英文无空格路径即可。5. 进阶技巧用 Repast 做参数敏感性分析的一个实用套路跑通基础实例之后真正拉开效率差距的是怎么组织参数实验。我自己的习惯是不直接在 Repast 的批处理配置里手写所有参数组合而是先用一个外部脚本生成多份parameters.xml每份对应一组参数然后循环调用 Repast 的无头运行模式。这样做的好处是参数组合逻辑可以用 Python 或 Shell 控制灵活得多。# 批量运行示例遍历 agentCount 和 gridSize 的组合 for grid in 30 50 80; do for agent in 100 200 400; do # 用 sed 替换模板中的参数值生成临时参数文件 sed s/gridSize\ value\[0-9]*\/gridSize\ value\$grid\/; \ s/agentCount\ value\[0-9]*\/agentCount\ value\$agent\/ \ parameters_template.xml parameters_run.xml # 调用 Repast 无头运行输出到带参数标识的目录 ./repast_headless.sh -params parameters_run.xml -output output/g${grid}_a${agent} done done这个套路的几个参数说明repast_headless.sh是 Repast 安装目录下的无头启动脚本不同版本名字可能略有差异-params指定参数文件-output指定输出目录。跑完之后每个目录下会有独立的 CSV后续用 Python 的 pandas 做聚合和可视化就很顺。教程实例里没有直接给这个脚本但它的批处理配置逻辑和这个思路是一致的我只是把它拆到了外部控制方便和现有的实验流水线对接。验证方法上我一般会先跑一组已知结果的参数做回归——比如 Agent 数量为 0 时输出应该为空网格大小为 1 时所有 Agent 坐标都应该是 (0,0)。如果这两条都过了再开大规模扫描。从那以后我每次改完 Agent 逻辑都强制先跑一遍最小参数集的回归确认没有引入调度或空间越界的低级错误再上批量。希望这份教程和实例能帮你少走几步弯路把精力留在模型设计本身。本文还有配套的精品资源点击获取