简介：这份资源面向希望入门或进阶代理建模（Agent-Based Modeling）的学习者，围绕开源仿真框架 Repast 提供从零搭建项目到案例实践的完整素材，适合课程实验、科研建模与自学练手。压缩包共 30 个文件，约 26.88MB，以 24 个 jar 库文件为主，涵盖 Repast 核心类库、图表绘制、地理信息与数学计算等依赖；另有 4 个 java 源文件、1 份通俗入门说明和 1 个示例压缩包，兼顾环境搭建与代码研读。资源中既有循序渐进的入门指引，也包含生命游戏等经典代理模型案例，可帮助读者理解代理定义、空间交互、参数设置与结果可视化的完整流程，并借助源码体会建模逻辑的组织方式。目前已有 626 人学习，适合作为 Repast 仿真教程的配套练习材料。

1. 拿到一个 Repast 示例包，先别急着双击运行

很多人第一次接触 Repast 仿真，卡住的地方不是建模思路，而是环境。压缩包解压出来一堆.java、.xml、.properties，双击没反应，命令行跑又报找不到类，最后只能放弃。这份 Repast 使用示例包的价值就在这儿：它把「一个能跑起来的仿真工程长什么样」直接摆在你面前，省掉从零搭骨架的时间。它适合两类人——一类是要交课程设计、需要快速理解 agent 建模流程的学生，另一类是已经会写 Java、但没碰过仿真框架的工程师。你要做的不是读它，而是把它跑通、改一个参数、看结果怎么变。下面按「环境怎么配、工程怎么读、参数怎么调、坑在哪」的顺序拆。

2. 环境与工程结构：把示例跑起来的第一步

Repast 是 Java 生态里的 agent-based modeling 框架，示例包本质是一个 Eclipse/IDEA 能导入的 Java 工程。跑不起来的原因九成在 JDK 版本和依赖路径，而不是代码本身。

2.1 JDK 与构建工具的选择

Repast 的不同分支对 JDK 要求不一样，老版本示例常见是 JDK 8 编译的，用 JDK 17 直接跑大概率报UnsupportedClassVersionError。我的习惯是先看工程根目录有没有pom.xml或.classpath，有 pom 就走 Maven，没有就按 Eclipse 工程导入。

# 先确认本机 JDK 版本，示例包多数按 8 或 11 编译 java -version javac -version # 如果工程带 pom.xml，先进目录看依赖能不能拉下来 mvn -q dependency:resolve

java -version输出里的主版本号要和工程编译版本对齐；mvn dependency:resolve只做依赖解析不编译，能提前暴露仓库地址失效的问题。如果输出里出现Could not resolve dependencies，先别改代码，去pom.xml里看<repositories>指向的地址是否还能访问，很多老示例的仓库地址已经下线，需要换成公共仓库或本地已有 jar。

没有 pom 的工程，导入后要手动确认 Build Path 里有没有 Repast 的运行时 jar。常见做法是把lib/目录下的 jar 全部 Add to Build Path，缺一个都会在启动时抛NoClassDefFoundError。

2.2 目录结构与入口类定位

一个典型的 Repast 示例工程，目录大致是这样组织的：

入口类通常名字里带Model或Main，里面会有public static void main(String[] args)，并且调用RunEnvironment.getInstance().startAt(...)之类的方法。找到它，右键 Run As Java Application，这是验证工程完整性的最快方式。如果报错指向某个 context 或 projection 类找不到，说明依赖没配全，回到 2.1 补 jar。

提示：不要一上来就改源码。先原样跑通一次，确认输出目录里有结果文件，再动手改参数，否则出了问题分不清是环境还是改动导致的。

2.3 第一次运行要看的三样东西

跑通之后别急着关，按顺序看三处：控制台最后几行有没有异常堆栈、output/下有没有生成 csv 或日志、参数文件里定义的步数是否真的执行完了。常见情况是程序「看起来跑完了」但实际在第一步就抛了异常被 catch 住，控制台只留一行 warning。我的做法是在入口类main末尾加一句打印当前 tick 数，确认仿真确实推进到了设定步数。

// 在 main 方法启动仿真后，打印最终步数，确认没有提前退出 RunState rs = RunEnvironment.getInstance().getCurrentRun(); System.out.println("final tick = " + rs.getTickCount());

getTickCount()返回的是当前仿真时钟，和参数文件里的总步数对比，差值大就说明中途有 agent 抛异常导致调度中断。这一步花两分钟，能省掉后面半小时的排查。

3. 读懂示例里的 agent 与调度：从代码到可改的参数

示例包真正有价值的部分不是「能跑」，而是它展示了一个最小可用的 agent 建模闭环：agent 怎么定义、context 怎么组织、调度器怎么驱动。看懂这三层，你才能把它改成自己的题。

3.1 agent 类的三个必备要素

Repast 里的 agent 一般继承DefaultAgent或实现Agent接口，核心是三样：状态字段、step()行为方法、以及注册到 context 的方式。示例里常见一个Agent类带x、y坐标和一个state枚举，step()里根据邻居情况改状态。

public class MyAgent extends DefaultAgent { private int x, y; private int state = 0; @Override public void step() { // 每 tick 执行一次：这里放状态转移逻辑 if (state == 0 && countNeighbors() > 2) { state = 1; } } private int countNeighbors() { // 邻居统计依赖 context 的 projection，示例里通常已封装 return 0; } }

step()是调度器每个 tick 回调的入口，所有行为逻辑都挂在这里或它调用的方法上。state字段是你要改的第一目标——把阈值2改成别的值，重跑，看结果分布怎么变，这是理解模型最直接的方式。countNeighbors()在示例里往往依赖某个 projection（比如 grid 或 network），改它之前先确认 context 里注册了对应 projection，否则返回恒为 0，模型等于没跑。

3.2 context 与 projection：agent 住在哪、怎么找邻居

context 是 agent 的容器，projection 决定 agent 之间的空间或网络关系。示例里最常见的组合是Context+Grid（网格）或Context+Network（网络）。初始化代码通常长这样：

Context<MyAgent> context = new DefaultContext<>(); for (int i = 0; i < agentCount; i++) { context.add(new MyAgent()); } // 注册网格投影，宽高来自参数文件 Grid<MyAgent> grid = new Grid<>(context, gridWidth, gridHeight, true, true, true);

agentCount、gridWidth、gridHeight这三个值一般从参数文件读，改它们比改代码安全。Grid构造里那几个布尔参数分别控制是否周期性边界、是否支持对角邻居等，示例注释里通常有说明，改之前先读注释，别凭感觉传。周期性边界打开意味着 agent 走到边缘会从对面回来，关掉则边缘 agent 邻居数偏少，这两种设定对结果影响很大，属于典型的「参数一改结论就变」的点。

3.3 调度器：谁在驱动 step

Repast 的调度靠RunEnvironment和Schedule。示例里常见两种写法：一种用ScheduleParameters声明每 tick 执行的动作，另一种直接在 context 上挂Action。前者更可控，推荐优先看这种。

// 声明每 tick 对所有 agent 执行 step ScheduleParameters params = ScheduleParameters.createRepeating(1, 1); context.addAction(params, (ctx) -> { for (MyAgent a : ctx.getObjects(MyAgent.class)) { a.step(); } });

createRepeating(1, 1)两个参数分别是起始 tick 和间隔，改成(1, 2)就是每两 tick 执行一次，用来观察「行为频率」对结果的影响。getObjects(MyAgent.class)拿到的是当前 context 里所有该类型 agent，遍历顺序不保证稳定，如果你的模型对执行顺序敏感，需要自己排序或改用随机化调度，这一点示例里往往不写，但实际做对比实验时必须注意。

4. 参数调优与结果验证：让示例变成你自己的实验

跑通、读懂之后，示例包才真正开始有用——它是你调参和验证的基线。这一章讲怎么系统地改参数、怎么看结果是否可信。

4.1 参数文件的组织与批量实验

示例的参数文件通常是 xml 或 properties，关键参数包括 agent 数量、网格尺寸、总步数、随机种子。做对比实验时，一次只改一个参数，其余固定，并且固定随机种子，否则两次运行的差异分不清是参数还是随机性。

# 用脚本批量跑不同 agent 数量，每次覆盖参数文件后启动 for n in 100 200 400; do sed -i "s/<agentCount>.*<\/agentCount>/<agentCount>$n<\/agentCount>/" params.xml java -cp "lib/*:bin" MyModel > "run_$n.log" 2>&1 done

sed那行只替换 agent 数量字段，java -cp里lib/*是通配所有 jar，bin是编译输出目录，按你工程实际路径改。每次输出单独日志，方便事后对比。注意sed -i会直接改原文件，跑之前先备份一份params.xml.bak，这是血泪经验——批量脚本改坏参数文件、原始配置找不回来的情况太常见了。

4.2 结果怎么算「可信」

单次运行的结果不能直接下结论。agent-based 模型有随机性，正确做法是同一组参数跑多次（常见 10 到 30 次），看结果的均值和波动范围。示例输出如果是 csv，用一段小脚本聚合：

import pandas as pd # 读取多次运行的结果，按参数分组统计均值和标准差 df = pd.read_csv("results.csv") summary = df.groupby("agent_count")["final_state_ratio"].agg(["mean", "std"]) print(summary)

groupby的键要和参数文件里的字段对应，agg里mean看趋势、std看稳定性。标准差过大说明随机性主导，这时候增加运行次数或固定更多随机源，否则你看到的「差异」可能只是噪声。这一步是区分「随便跑跑」和「能写进报告」的分水岭。

4.3 用输出反推模型是否按预期工作

结果文件除了看最终值，还要看中间过程。示例如果输出了每 tick 的状态分布，画一条时间序列，能发现很多逻辑错误：比如状态比例在第一步就跳到稳态，往往意味着step()被重复调用或阈值设错；比如曲线周期性震荡，可能是调度间隔和状态转移周期撞上了。我的习惯是先看前 10 个 tick 的原始输出，确认每一步的变化符合代码逻辑，再去看整体趋势。

5. 避坑与常见问题：这些错我基本都犯过

5.1 启动报 NoClassDefFoundError

现象：右键运行入口类，控制台抛NoClassDefFoundError，指向某个 Repast 内部类。原因：lib/下 jar 没全部加入 Build Path，或 Maven 依赖被标记为 provided 但运行时没提供。解决：检查 Build Path 的 Libraries 列表，把lib/下所有 jar 加进去；Maven 工程确认mvn dependency:tree里该依赖不是 provided 作用域。

5.2 仿真跑完但输出目录是空的

现象：程序正常结束，output/下没有结果文件。原因：输出路径写的是相对路径，而运行工作目录不是工程根目录；或输出逻辑挂在某个从未触发的分支上。解决：在写文件的地方打印new File(".").getAbsolutePath()，确认实际工作目录；把输出路径改成绝对路径或基于工程根目录拼接。

5.3 改了参数但结果完全没变

现象：修改参数文件后重跑，结果和之前一模一样。原因：代码里参数是硬编码的，参数文件根本没被读取；或读取了但被后面的默认值覆盖。解决：在参数加载处加打印，确认读到的值；搜索代码里是否有同名字段的直接赋值，优先级高于配置文件。

5.4 邻居统计恒为 0

现象：agent 行为逻辑不触发，排查发现邻居数一直是 0。原因：context 里没有注册对应的 projection，或 projection 的尺寸参数为 0。解决：确认new Grid(...)那行确实执行了，且宽高来自有效参数；在countNeighbors()里打印 projection 对象是否为 null。

5.5 多次运行结果差异巨大

现象：同一组参数跑两次，结果差一倍以上。原因：随机种子未固定，或遍历 agent 的顺序不稳定放大了随机性。解决：在初始化处显式设置随机种子；对顺序敏感的模型，在调度前对 agent 列表排序或使用固定随机序列。

6. 把示例改造成自己的模型：一个可复用的改造顺序

示例包最大的用处是当模板。我的改造顺序固定为四步，每步都能独立验证，避免一次性改太多导致问题定位不了。

第一步，换 agent 的状态字段和step()逻辑，其他不动，跑通确认调度还在工作。第二步，改 context 的 projection 类型，比如从 grid 换成 network，这一步最容易出问题，改完先只跑 10 个 tick 看邻居统计是否合理。第三步，调参数文件，把 agent 数量、步数、种子做成可配置，用 4.1 的批量脚本跑小规模实验。第四步，加输出，把你要分析的指标按 tick 写进 csv，再套 4.2 的聚合脚本。

改造过程中有一个检查表值得固定下来：

这张表我每次改完模型都过一遍，比事后翻日志快得多。Repast 这类框架的坑大多不在算法，而在「配置和代码对不上」——参数文件说一套、代码里默认值另一套、运行目录又是第三套。把这三者对齐，示例包就从「别人的代码」变成了「你的基线」。

从那以后我每次拿到一个仿真示例包，都强制先原样跑通、打印最终 tick、确认输出目录，再动第一行代码。希望帮到你。

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