简介：这份资源是面向Repast仿真初学者的完整示例包，旨在帮助用户从零理解代理建模框架的核心用法，适合高校学生、科研人员以及需要对复杂系统进行仿真建模的开发者。压缩包共30个文件，以24个JAR依赖库为主体，覆盖模型构建、运行时支持与数据分析等模块，并配有4个Java源码文件、1篇通俗易懂的入门说明文本，以及一个包含更多案例的ZIP压缩包，整体大小约26.88MB，下载和本地部署都很便捷，目前已有619人学习。资源特意安排了从基础到进阶的学习路径：先阅读入门说明了解环境搭建与项目创建，再通过生命游戏等经典案例掌握代理定义、空间交互和结果可视化；例如生命游戏展示了代理如何在二维空间中根据邻居状态迭代更新，帮助理解自组织动态。附带的Repast例子ZIP包则呈现不同复杂度的建模场景，完整JAR库让用户无需额外配置即可运行。通过动手实践，读者能逐步理解Repast中Agent行为规则、调度机制与数据收集等关键模块，为自主构建仿真模型打下坚实基础。 接到一个命名为“Repast使用示例.zip”的文件时，大多数人都会陷入一种很自然的冲动：解压、找main方法、让程序跑起来。我当年就是这样浪费了一个下午的。因为我根本找不到入口，Eclipse里一片红色报错，连项目都导入不干净。后来才明白，Repast Simphony这种基于Agent的仿真框架，门槛不在语法有多难，而在它的运行思路和常规Java项目完全不一样。这篇我就结合这些年用Repast折腾项目的经验，把这个示例包应该怎么读、怎么跑、怎么改，从环境搭建到批量实验完整捋一遍，帮你少走那些我走过的弯路。
1. 打开示例包之前：Repast到底帮你解决了什么问题
1.1 为什么需要Agent仿真这种玩法
Repast全称很长，核心就是“递归多Agent仿真工具包”。面向的问题也很聚焦：一群个体，各自按简单规则行动，整体上却能涌现出你完全预料不到的模式。社会学的舆情扩散、流行病学的传播模拟、交通领域的人群疏散、博弈论里的策略演化，都是它的典型场景。
这套思路和我们写传统程序最不一样的地方在于：你在代码里不需要去控制宏观结果。你把200个人的行为规则定义清楚，疫情曲线的形态不是任何一行if语句直接画出来的，而是从那些个体之间的交互中“长”出来的。想通过数学公式直接推演当然也可以，但个体规则一旦带上空间位置、随机性、局部交互，公式推导的复杂度会爆炸，Agent仿真反而是表达这类问题最自然的方式。
1.2 Repast相较于NetLogo多给了什么
不少新手会拿Repast和NetLogo对比。NetLogo确实上手极快，拖拖控件就能跑模型，教学演示的体验几乎无敌。但它有两个让我比较难受的地方：一是模型语言是自成一派的Logo方言，很难把学校里积累的编程能力平滑迁移过去；二是想往模型里接Java生态的东西，比如GIS数据、机器学习库、复杂的统计分析包，不是不行，但很别扭。
Repast的主干就是Java（也有.NET版本和Python的Repast4py），这意味着你可以把仿真的Agent直接写成普通Java对象，然后在里面调用你喜欢的任何库。示例包里通常还会看到GIS投影、网络分析工具的依赖，这些都是Repast被选来做社会科学严肃研究的原因。如果你的模型需要做空间上的精细计算、需要批量化参数扫描、需要和外部数据管道对接，Repast起步会痛苦一点，但后面路会宽得多。
1.3 示例压缩包里那些文件都是干嘛的
拿到一个Repast Simphony的示例包，解压后通常会看到这些结构：
src目录：Agent类、ContextBuilder的Java源码都在这。scenario目录（或者叫model.rs这类后缀的场景配置）：里面是.score文件（场景模型定义）、参数配置、model.score之类的东西。你可以把这个目录理解为整个仿真项目的“总装配车间”。lib目录：运行时依赖。batch相关文件：参数扫描用的配置和输出目录。- README、license之类的不重要，但README值得先花两分钟扫一眼。
很多人栽在第一步就是直接去src里找入口类。Repast Simphony里，模型启动真正的控制中心是scenario下的场景文件。Eclipse里跑模型的时候，框架会读取这个场景文件，根据里面配置的ContextBuilder、投影类型、Schedule定义去装配整个世界。所以理解这个包的切入点是：先顺着场景进，再顺着代码出。
2. 环境准备：版本搭配在这个项目里真的会要命
2.1 我建议的组合和防止踩雷的安装方式
Repast Simphony目前主流的形象是Eclipse插件式IDE。这里的版本坑比普通Java项目要多得多：JDK版本不匹配、Eclipse发布版本太新、插件安装源对不上，都会让你在导入示例包的第一时间就收到一堆莫名其妙的编译错误。
我自己用下来比较顺手的组合是JDK 11配合Eclipse 2022-06左右的版本，再加对应年份的Repast Simphony插件。如果你不想在这些版本排列组合上消耗太多个小时，最简单粗暴的方案是直接去Repast官网下载内置好一切功能的完整版Eclipse发行包，解压就能用。这种all-in-one包虽然文件大，但省掉了脑细胞。能让你把精力放回模型本身，这买卖划算。
安装好了之后，先别急着导入示例，建议先启动一次发行包自带的环境，在菜单里确认Repast的图标和Demo运行正常。如果自带Demo能跑，说明你的Java环境与IDE是协调的；这时再导入你的示例zip，遇到问题你就能确认是示例本身的问题而不是环境问题。
2.2 导入示例项目后的三个验证动作
把解压后的文件夹用Eclipse的Import功能导进来，这里有些细节要额外小心：
- 检查项目的JDK编译级别（Java Build Path里的JRE System Library），确认与你安装的JDK一致。
- 检查项目是否自动识别为Repast项目：右键项目，看菜单里有没有“Repast Simphony”这一级子菜单。如果没有，说明项目属性里的Project Facets没配对，需要去
Properties > Project Facets里勾上Java和Repast相关项。 - 确认
scenario目录下的.score文件能被IDE识别。双击它如果能打开Scenario Tree窗口，说明场景配置成功加载；如果打开报错，多半是模型类名和类路径对不上。
2.3 看懂Scenario Tree是玩转示例的关键
Scenario Tree这个编辑器是Repast里所有人都绕不开的界面。它左侧是一棵树，把模型拆成了几个分支：Context、Projection、Agent、DataLoaders、Display、Schedule、Parameters等。
示例包里的模型跑起来之前，我建议你先在这个树里到处点一点，有个粗略印象。后面很多操作——比如加参数扫描、配置数据输出、修改Agent初始数量——都不用碰代码，直接在这个树上操作。很多教程只讲代码怎么写，却忽略了这个可视化配置层，导致新手经常改一个参数都要全项目搜索硬编码。Repast的设计哲学其实是“能配置的不写代码，能显示的不打日志”，顺着这个思想去用，会舒服很多。
3. Context、Agent、Projection：读懂示例代码前必须理顺的三件事
3.1 Context和Agent的关系：城市与市民
在Repast Simphony里，Agent就是模型中的个体，通常是一个带有@Agent注解的普通Java类。它可以是人、细胞、车辆，也可以是组织。Context则是所有Agent的容器，可以理解为一个“世界”。你的模型可以有一个主Context，也可以在里面嵌套子Context，用来表达多层级结构。
示例代码里大量出现context.add(agent)这类调用，本质就是往这个世界里加入成员。Agent之间的交互，默认情况下不会自动发生，必须通过Context去查找彼此，或者通过下面的Projection来定义“谁在谁的附近”。一个只有Agent没有Context的模型，跑起来就是一个一个孤零零的对象，什么也演化不出来。
3.2 Projection：Agent之间怎么发生关系
Projection在中文里常被翻译成投影，我更喜欢叫它“空间关系的定义器”。示例包里一定会出现至少一种Projection，常见的有这么四类：
ContinuousSpace：连续二维/三维空间，Agent有(double)坐标，适合物理运动、扩散类模型。Grid：网格空间，Agent落在离散格点上，适合元胞自动机或格子气风格的模型。Network：网络投影，定义Agent之间的连线关系，适合社交网络、供应链这类拓扑结构问题。Geography：地理投影，坐标绑定到真实经纬度或者GIS数据上，适合ArcGIS生态下的空间分析。
这四个投影的对比可以简单理解成：ContinuousSpace是“自由放养”，Grid是“格子间办公”，Network是“人脉关系图”，Geography是“地图打卡”。示例包里的模型通常只用到其中一到两种，但读懂它们的差异后，你会更清楚为什么有的模型要指定space.getDistance，有的模型却在操作network.getPredecessors。
3.3 Schedule：时间是怎么推进的
Repast里没有while循环来推进时间。它用的是事件队列机制，整个仿真时间轴由tick（步数）驱动。Agent上带有@ScheduledMethod(start = 1.0, interval = 1.0)这样的注解，意思是从第1个tick开始，每隔1个tick执行一次这个标注的方法。
这里有个初学者特别容易踩的误解：同一时刻所有Agent的方法都按顺序执行。实际上Repast在同一tick内的事件顺序是带有随机性的，如果你需要严格的执行顺序（比如先更新状态再生产新Agent），得去研究ScheduleParameters里的优先级参数，或者重写Agent的step方法里的调用逻辑。示例包里的模型可能没有显式涉及这么深，但理解了这个机制，后面调试奇怪行为的时候才能推断出“啊，这是顺序问题”。
4. 从SIR示例复盘一次完整建模：代码结构和运行界面
4.1 为什么推荐SIR作为第一个读懂的例子
如果你手上的示例包包含不止一个模型，SIR传染病模型永远是我最推荐先啃的。它代码量不大，但覆盖了一个Repast模型需要的全部核心部件：Agent状态枚举、空间移动、局部交互、定时调度、数据统计。而且结果很容易验证——感染人数曲线应该大致符合先升后降的形态，如果跑出来完全不是这样，说明你某些环节没搭对。
我下面的代码示例会以Repast Simphony 2.x的典型写法来展示，不同小版本在包的导入路径上可能有细微差异，但核心接口基本稳定。
4.2 Agent类的骨架代码
一个Person Agent通常长这样：
package sir; import repast.simphony.engine.schedule.ScheduledMethod; import repast.simphony.random.RandomHelper; import repast.simphony.space.continuous.ContinuousSpace; import repast.simphony.space.continuous.NdPoint; public class Person { public enum State { SUSCEPTIBLE, INFECTED, RECOVERED } private State state = State.SUSCEPTIBLE; private double infectionRate = 0.3; private double recoveryRate = 0.1; private ContinuousSpace<Object> space; public Person(ContinuousSpace<Object> space) { this.space = space; } @ScheduledMethod(start = 1.0, interval = 1.0) public void step() { if (state == State.INFECTED) { infectNeighbors(); if (RandomHelper.nextDouble() < recoveryRate) { state = State.RECOVERED; } } } private void infectNeighbors() { NdPoint pt = space.getLocation(this); Iterable<Object> neighbors = space.getObjectsWithinRadius(pt, 1.0); for (Object obj : neighbors) { if (obj instanceof Person) { Person other = (Person) obj; if (other.state == State.SUSCEPTIBLE && RandomHelper.nextDouble() < infectionRate) { other.state = State.INFECTED; } } } } }这段代码的逻辑很直观：感染者每步尝试感染周围半径1.0范围内的邻居，同时按概率康复。所有这些规则都发生在个体层面——没有全局控制器告诉系统“今天应该感染几个人”。
4.3 ContextBuilder：装配整个世界
模型中央的装配类要实现ContextBuilder，得到的是Agent之间的连接和初始布局：
package sir; import repast.simphony.context.Context; import repast.simphony.context.space.continuous.ContinuousSpaceFactory; import repast.simphony.context.space.continuous.ContinuousSpaceFactoryFinder; import repast.simphony.dataLoader.ContextBuilder; import repast.simphony.random.RandomHelper; import repast.simphony.space.continuous.ContinuousSpace; import repast.simphony.space.continuous.RandomCartesianAdder; import repast.simphony.space.continuous.WrapAroundBorders; public class SIRContextBuilder implements ContextBuilder<Object> { @Override public Context<Object> build(Context<Object> context) { context.setId("sir"); ContinuousSpaceFactory spaceFactory = ContinuousSpaceFactoryFinder.createContinuousSpaceFactory(null); ContinuousSpace<Object> space = spaceFactory.createContinuousSpace( "space", context, new RandomCartesianAdder<Object>(), new WrapAroundBorders(), 50, 50); for (int i = 0; i < 200; i++) { Person p = new Person(space); context.add(p); space.moveTo(p, RandomHelper.nextDouble() * 50, RandomHelper.nextDouble() * 50); } int infected = 0; for (Object obj : context) { Person p = (Person) obj; if (infected < 10) { p.setInitialInfected(); infected++; } } return context; } }这里有几个细节值得留意：第一次是给每个Agent分配随机初始坐标时会用到space.moveTo把位置绑定到空间上；第二是感染者的初始化不能放在Agent构造里，因为有200个Agent批量生成时你应该先把所有人都放入世界，再统一把前10个标记为感染者，这样后面感染循环时不会跳过那些还没加入Context的对象。
4.4 跑起来以后你要看什么
右键项目里的模型场景文件（通常叫model.rs或.score），选择Run As里的Repast Simphony运行项。界面上会弹出运行面板，里面有2D/3D显示视图、图表、输出控制台。左侧的Scenario Tree和运行时界面会联动，你能实时看到Agent的移动和状态变化。
第一次跑通时，建议做的验证动作是：把所有Agent画成绿色（易感），感染者在初始时刻变红，然后观察红色是否在空间里扩散。如果红色范围10秒内完全不动，大概率是space.getObjectsWithinRadius的半径设置太小，或者Agent被RandomCartesianAdder自动替代、坐标没真正写进空间里。
5. 参数扫描与批量运行：示例包后半段真正的价值
5.1 为什么单独跑一次仿真基本没有意义
仿真模型和普通程序的一个本质区别就是随机性。Agent的初始坐标、决策阈值、交互对象都是带随机数的。单次运行的结果就像一次抽样，你很难判断那一波疫情曲线是模型本质规律，还是仅仅是某次幸运的随机数组合。
真实研究里，核心参数（感染率、康复率、人口密度）在多个取值下，每个组合都得重复跑二三十次，取均值、算方差，才能得到有统计意义的结论。这就引出了Repast最有价值的功能之一：批量参数扫描。
5.2 用@Parameter把参数暴露出来
要让参数能够被框架识别并扫描，需要在Agent或者ContextBuilder里用注解声明参数：
@Parameter(usageName = "infectionRate", defaultValue = "0.3") private double infectionRate = 0.3;这么写之后，Scenario Tree里会多出对应的参数配置项。批处理工具运行时，就能在不改代码的情况下自动改变这个值，跑不同的场景组合。这比手动一遍遍修改硬编码再重新运行要高效太多。
5.3 数据收集与批处理操作的完整链路
批量运行之前记得先把CSV输出配置好。在Scenario Tree里找到输出相关的Data Set、Data Recorder分支，把要观察的变量加进去（比如感染人数、康复人数），指定输出目录。不然你跑完了会发现只有动画，没有可分析的数据，那就白跑了。
配置好之后，右键需要批运行的项目，选择Repast Simphony中的Batch Run（部分版本叫Parameter Sweep），在弹出的界面里设置照射参数范围和重复次数。Repast会把结果以CSV格式输出到约定的目录下（通常会在你的项目output文件夹里产生一行一条记录的数据）。之后你可以用R、Python或者直接Excel去画曲线，分析不同参数组合下的系统行为差异。
这一整套“把参数暴露出去、配置批量任务、收集CSV、事后统计”的范式，是Repast示例包里最值得学习的工作流之一。学会它，你就从“玩单次模拟”升级到了“做仿真实验”的层次。
6. 重装一次我会避开的坑：版本、路径和内存
6.1 一个版本冲突问题的排查思路
我去年帮别人核对过一个示例包跑不起来的问题，报错是java.lang.NoClassDefFoundError，而且只在导入某个旧版本示例时出现。排查链路是：先确认所有依赖jar都在，没有问题；然后确认JDK编译级别，还是没有解决；最后发现是Eclipse工作区里残存了旧版本的Repast插件缓存，导致模型运行时用了错误的类加载器。
解决方法不复杂：把工作区里的.metadata目录备份后清理，重新导一次项目就好了。这个坑的通用启示是：Repast Simphony的插件状态和项目状态极容易不同步。遇到诡异的类找不到、注解不生效问题，第一步永远是清理Eclipse工作区缓存，而不是去翻业务代码。
6.2 永远不要在中文路径下运行模型
这个错误我犯得很早：把项目放在D:\项目\仿真模型\这种路径下，结果运行到一半经常出现读写配置文件异常、某些资源路径解析失败。原因很简单：Repast的一些底层库在读取资源时，对非ASCII字符的路径兼容性并不好。后来我的规矩很简单：所有Repast项目一律放在纯英文路径下，目录名不带中文、不带空格。别在这个问题上检验框架的鲁棒性，不值得。
6.3 模型越跑越慢时，优先级最高的是内存调整
上千个Agent在空间里频繁交互时，内存占用会迅速爬升，JVM堆设得不够会频繁GC，甚至直接OOM。如果你拿到的示例包扩展成大规模实验，两件一定要做的事：第一，在Eclipse的运行时配置或者启动脚本里调大JVM最大堆内存，比如-Xmx2048m；第二，关闭或者降低2D/3D显示的刷新频率。很多人忽略了显示图层是性能大头，一旦可视化关闭，计算速度能提升好几倍。
另一种常见性能陷阱是每步都用context.getRandomObjects遍历全体Agent。数据量几十的时候没感觉，数据量上千甚至上万时，这种写法会瞬间拉垮。正确思路是尽量利用空间投影自带的邻域查询方法，让框架通过空间索引去帮你找邻居，而不要自己遍历所有Agent。
最后分享一个我自己的习惯：每次拿到新模型或者写完新逻辑，先把所有参数恢复到示例自带默认值，回到最简单的初始条件再跑一遍，保留一份原始输出的CSV作为基线版本，之后再改代码就有了对照物。Repast这类Agent仿真的特点是规则稍微变一点，宏观表现可能完全不一样，没有基线输出，你根本说不清某个现象到底是新逻辑带来的还是本来就存在。这个土办法帮我挡住了很多次模型行为莫名其妙的回归问题。
本文还有配套的精品资源，点击获取
