简介面向社会科学、经济学与复杂系统建模初学者的Repast完整英文教程与实例包适合希望系统掌握多Agent仿真平台的读者。资源共72个文件以38个htm和28个html教程页面为主体搭配CSS样式表、界面位图、JavaDoc索引及内嵌示例压缩包覆盖安装设置、Agent定义、模型构建、脚本控制、可视化与数据收集等模块方便离线阅读与对照实践。包体仅303KB轻量精炼目前已有730人学习。教程内含HowTo系列32个操作主题、Eclipse环境配置说明以及H2R完整案例从环境搭建到结果分析均配有实例既可深化对Repast原理的理解也可直接参考代码开展仿真实验适合不同基础的研究者和开发者使用。1. 完整教程不等于能跑起来的仿真Repast 实例到底该怎么选不少仿真方向的新手拿到 repast 教程和实例包之后都以为把代码导入 IDE、启动模型、看到网格动起来就算学会了实际上这只是 GUI 演示的幻觉。真正的 repast 学习曲线藏在两个地方一是理解 Context 与 Agent 的双重构建逻辑二是搞明白 Schedule 调度器里的 tick 控制和时间单位换算。这两点不看实例源码永远想不通而多数资源包恰恰把源码折叠在 lib 里没有配套讲解。这份 repast 完整教程和实例资源适合两类人一类是有 Java 基础、想用 ABM基于智能体建模做仓储配送、物资分配、人员流动仿真的从业者另一类是被官方文档英文术语劝退的初学者。资源的核心价值不是演示 Demo 的视觉效果而是把仿真建模的完整流程——环境构建、行为调度、参数扫描、数据导出——串成了一条能动手照做的链路。我会按拆项目的习惯把里面的模板工程拆开讲重点说清楚编辑器的边界、调度器的坑、以及批量仿真时最容易翻车的那几步。2. Repast 的核心机制双构建、调度器与单位换算2.1 双重构建Context 与 Agent 谁先谁后很多第一次接触 Repast Simphony下文简称 Repast S的人会把它当成普通的 Java 库上来就 new 一个 Agent 丢进去跑结果发现网格上没有实体、行为列表空白。原因在于 Repast S 的运行模型不是“类驱动”而是“上下文驱动”。一个模型必须包含两个层面的构建先是数据层面也就是用 Context 去承载 Agent 所在的空间环境网格、GIS 或连续空间然后是行为层面用 Schedule 去安排每个 tick 该执行哪些方法。最常见的报错是项目里只有 XmlContext 文件却没有对应的 ContextBuilder 实现类这样模型加载时连 context 都不会生成。public class WarehouseContext implements ContextBuilderObject { Override public ContextObject build(ContextObject context) { context.setId(warehouse_sim); // 创建连续空间坐标范围 0-100单位是“米” GeographyObject geography new GeographyObject( new ContinuousSpace(floor_space, 100, 100)); context.addProjection(geography); // 创建网格投影用于示意货架的位置 GridObject grid new GridObject( new Grid2D(shelf_grid, 50, 50)); context.addProjection(grid); // 创建随机数种子保证实验可复现 context.add(new RandomHelper()); for (int i 0; i 20; i) { Agent worker new WorkerAgent(i, geography, grid); context.add(worker); } return context; } }这段代码里最容易忽视的是ContinuousSpace和Grid2D的坐标系关系。Geography管理连续坐标而Grid是离散坐标两者通过MoveTo方法联动。初学者若只添加其中一种投影后面的路径规划、碰撞检测都会失效因为 Agent 在 Repast S 里必须至少属于一个 projection 才能被调度器感知。逻辑上的顺序是先建空间和网格再建智能体最后把智能体放入投影——顺序反了会导致 Agent 虽然存在却不在任何空间内。参数说明上ContinuousSpace构造函数的两个 100 表示空间宽高单位取决于你的业务建模。这里的“米”是我在代码中自定的逻辑单位Repast 本身不感知物理单位所有数值都只是 double。如果你想做的是线边库位布局仿真建议把单位改成“库位格”这样在后面的参数扫描中更容易解释结果。2.2 调度器 Schedule从 tick 到行为执行设计好 Context 后问题紧接着出现Agent 放进了空间但谁来驱动它动起来答案是 Schedule。Repast S 的调度器采用“时间步”机制每个 tick 会遍历用户注册的 TickAction执行相应的行为方法。这有点像离散事件仿真里的“步进时钟”但它没有严格的事件队队里只有行为列表。public class WarehouseSchedule { public static void main(String[] args) { Schedule schedule new Schedule(); schedule.scheduleActionStarting(1, () - { // 每 1 tick 执行一次上架任务分配 ContextObject context Contexts.getContext(warehouse_sim); for (Object obj : context) { if (obj instanceof WorkerAgent worker) { worker.pickNextTask(); } } }); schedule.scheduleActionAtInterval(10, () - { // 每 10 tick 记录一次库存数据用于后期统计 System.out.println(tick schedule.getTickCount() data); }); } }调度器的核心参数有三个。第一个是起始时间scheduleActionStarting(1, ...)表示从第 1 tick 开始执行第二个是间隔scheduleActionAtInterval(10, ...)表示每隔 10 tick 执行一次第三个是优先级可以在方法末尾追加ScheduleParameters.LAST或FIRST来指定先后顺序。常见误用是调度普通方法时直接传方法引用却忘了该方法必须在 Agent 内部且被 Context 管理否则调度器会因找不到类而抛出ClassNotFound运行时异常。在真实项目中我一般会把调度逻辑从主类里抽出来统一挂在WarehouseSchedule里管理因为 Repast S 的 GUI 界面和批处理模式都需要通过这个类去控制行为时序。如果调度器里写法混乱后面做参数扫描时不同实验之间会互相污染——最典型的现象是上一轮的 Agent 还在跑下一轮又 new 一批出来结果每个 tick 的实体数量翻倍。2.3 SimClock 与时间单位换算另一个新手看不见的坑是时间单位。Repast S 内置了SimClock工具允许把 tick 映射成现实时间比如 1 tick 1 分钟60 tick 1 小时。这个映射必须在模型初始化时设定而不是在调度器里写死。SimClock clock SimClock.getInstance(); clock.setUnitPerTick(1.0, TimeUnit.MINUTES);举一个真实场景某仓库模拟昼间 8 小时作业每 1 tick 表示 1 分钟则整个仿真需要跑 480 tick。如果你没做单位设定后期读输出时就会分不清 tick 500 到底是哪天的数据。这类问题在单次运行中不易察觉但一旦做多周实验时间轴就乱套了。规范做法是每做一个模型先在初始化方法里打印clock.getCurrentTime()确认 tick 与业务时间比例无误后再跑正式实验。3. 动手做一个仓储模型实例环境搭建到行为实现3.1 实例背景仓库货物调配仿真网络检索到的项目资料里有一类资源和 repast 匹配度最高——仓库配送系统仿真。这恰好也是 ABM 建模的典型应用工人Agent从收货区领取货物按订单需求搬运到相应货架区期间要避免碰撞、等待队列堆积、超时未完成。在这份资源包中源码组织比很多网上零碎代码规范得多src/main/java下分出model、agent、behavior、analysis四个包。其中behavior包里的TaskScheduler.java是仿真核心它把任务的生成、分配、移动分成了三个独立的调度方法。我觉得这种拆分值得保留因为后续调参时你只需要改taskGenRate参数不需要动移动逻辑。3.2 核心类实现搬运工 Agent 的行为控制资源包里的WorkerAgent.java是一个标准 ReLogo 风格 Agent 类继承Agent基类。它的核心行为不是移动本身而是“决策 移动”两段式设计决策阶段判断最近的任务点、当前货物数量移动阶段通过连续空间里的moveByVector逐步逼近目标坐标。下面是从资源中整理出的核心模板去掉了无关的窗口样式代码。public class WorkerAgent extends Agent { private GeographyObject geography; private double x, y; private int carryingAmount; private static final double SPEED 1.5; // 每 tick 移动距离 ScheduleMethod(start 1, interval 1, priority ScheduleParameters.LAST) public void step() { // 1. 查找可用任务列表由市场对象 push 到共享队列 Task task TaskBoard.getNearestTask(x, y); if (task null || carryingAmount 0) { // 没有任务或已满载时去暂存区卸货 moveToDropZone(); return; } // 2. 移动到任务取货点 double[] target task.getPickupLocation(); double distX target[0] - x; double distY target[1] - y; double len Math.sqrt(distX * distX distY * distY); if (len 0.1) { // 到达取货点装载 carryingAmount Math.min(5, task.getAmount()); task.consume(carryingAmount); } else { // 按实际距离移动而不是直接跳到目标 x (distX / len) * SPEED; y (distY / len) * SPEED; geography.move(this, new ContinuousPoint(x, y)); } } }这个类写法上有两个细节值得说明。第一ScheduleMethod注解里用了priority ScheduleParameters.LAST目的是先让环境更新比如订单生成在优先级为FIRST的方法里执行随后智能体再读取环境状态。顺序不对时通常会出现“货物还没生成、工人已经取完”的荒谬结果。第二move到ContinuousPoint时没有用geography.moveTo直接指定绝对位置而是用累积式x ...因为moveTo在每 tick 只能执行一次配合连续空间才能形成连续动画效果。这段代码在各种教程资源中几乎都能见到但真正理解的人不多。我在初次运行时就翻过车把geography.move与x/y坐标更新写成了两个分支导致模型界面里 Agent 在网格上“原地抽搐”实际坐标却没有变化。后来看了源码里ContinuousSpace的边界实现才明白x之后还必须显式调用geography.move()否则空间投影不会感知坐标变化。3.3 运行模型与观察输出运行 Repast S 模型有两种方式一种是直接 Run 项目会弹出 REPAST 自带的 2D 界面左侧有模型树右侧是空间画面另一种是无头批处理模式适合跑大量参数组合。配置批处理模式的关键文件是model.score里的参数定义。以资源包为例它定义了三个可变参数工人数量worker_count默认 10、任务生成间隔taskGenGap默认 20 tick、最大携带量maxCarry默认 5。sweepParameter nameworker_count typeint defaultValue10 / sweepParameter nametaskGenGap typeint defaultValue20 / sweepParameter namemaxCarry typeint defaultValue5 /这里有一个使用误区很多人以为在 Java 类里直接声明static int worker_count 10就能被批处理识别。实际上必须通过Parameter注解或在.score文件中显式声明Repast 的批处理引擎才有权在每一轮实验前替换参数值。如果你没有定义这些参数项参数扫描窗口会一直是空的而单个实验跑得再顺批量做不了就等于把你的时间浪费在人工调参上。我习惯在开发初期先手动跑一次单模型确认 UI 上实体数量正确、tick 推进流畅再去配置批处理。不然一次扫描十几组参数结果异常时很难判断是业务逻辑问题还是参数声明问题。4. 多实验批量仿真参数扫描与数据导出的完整做法4.1 数据采集DataSet 设置做仿真如果不采集数据那跑出来的动画只是“看个热闹”。对于仓储项目最重要的指标是每一 tick 的“未完成订单数量”和“空闲工人比率”。要拿到这些数据需要在一个定时执行的方法里方法化地刷新数据集。DataSetInteger ds new DataSetInteger( warehouse_stats, tick, pendingOrders, idleWorkers); // 注册数据源 ds.addSource( () - (double) TaskBoard.getPendingOrderCount(), pendingOrders, 订单未完成数量);这里的DataSet会在每个 tick 结束时刷新底层数据绑定在analysis包里的ChartCreator类。有一个细节容易被忽略addSource传递的 Lambda 返回值类型必须为 Double如果你从业务方法里拿到的是 Integer就手动转一下。否则运行时会在数据源绑定处抛ClassCastException而且这个异常只在 GUI 模式右下角日志小窗里一闪而过批处理模式下根本看不到。4.2 使用 ParameterSweep 跑多组实验Repast S 的批处理实验由RepastBatchRunner驱动通过在 main 方法里传入实验配置.xml来执行。以下是一份可以直接跑起来的批处理主类模板public class BatchLauncher { public static void main(String[] args) { RepastBatchRunner runner new RepastBatchRunner(batch_params.xml); runner.setRunCount(10); // 每个参数组合重复 10 次消除随机性 runner.run(); runner.cleanUp(); } }参数文件batch_params.xml里可以这样写batch parameter nameworker_count value[10, 15, 20]/ parameter nametaskGenGap value[5, 10, 20]/ /batch运行完后输出目录下会有名为ModelOutput.txt的数据文件。这个文件每行对应一列数据列顺序与DataSet中注册的顺序一致。为了后续直接用 Python 或 Excel 分析我通常会在BatchLauncher中手动把ModelOutput.txt复制一份并重命名同时附带上对应轮的参数值。参数扫描最大的价值是把“玄学调参”变成“网格搜参”。你不需要反复在 GUI 里手动拖动滑块而是提前把全部组合一次性跑掉再根据曲线选点。这一步是 repast 区别于其他教学 Demo 的核心竞争力——它让仿真真正变成可重复实验。4.3 数据导出的注意事项批处理模式下数据导出有三个坑都是从血泪经验里来的。第一DataSet注册的数据源和writeToFile方法被调用时DataSet 对象必须被显式flush否则最后一 tick 的数据可能不落盘。第二批量实验的随机种子若没有手动设置同一组参数跑多轮得到的数据波动会很大。建议在ContextBuilder里手动设置种子为固定值比如 42再配合runCount 10做方差分析。第三写 CSV 时列分隔符默认是 tab 而不是逗号如果你用 Excel 打开乱成一行就把后缀改成.txt看或者用文本编辑器打开。这一点在官方文档里写得很隐晦很多初学者在这里浪费了大半天。5. 避坑指南Repast 实例实战中容易翻车的四个点现象一界面项目能正常运行但参数扫描窗口是空的。原因.score文件里没有声明sweepParameter或声明名称与 Java 类属性名不一致。解决检查.score文件中sweepParameter的name属性确保与Parameter注解名称完全一致注意大小写。如果还是空白把model.score用纯文本打开确认 XML 结构没有折叠注释。现象二Agent 在网格上移动但坐标从未更新。原因调用move方法没有使用ContinuousPoint或者坐标更新逻辑放在了不存在geography投影的 Context 里。解决在移动前打印geography.isHosted(agent)检查 Agent 是否已放入投影。未放入时先context.add(agent)再移动。现象三重载模型后旧的 Agent 还在界面上。原因Repast S 的重载机制不会自动清空 Context 中的实体问题是旧的 Context 没有销毁。解决在ContextBuilder的build方法开头调用context.setId(...)强制清空或者在重载方法中手动遍历旧 Context 里的对象并逐个remove。现象四批处理跑出来的数据文件和 GUI 模式下的结果不一样。原因两种模式使用的随机种子不同且 GUI 模式有显示渲染开销会影响调度节奏。解决为两种模式分别指定随机种子为与批处理模式区分在ContextBuilder的初始化逻辑里增加系统属性判断。这些坑每一条我都自己踩过。尤其第二条当时界面里的工人原地打转看起来像是在疯狂转向实际上是因为我漏了geography.move()而坐标的 x/y 已更新动画回调拉取了错误的旧位置。后来我习惯性在每次x ...后加一行System.out.println(agent.getX())验证状态才彻底解决。6. 进阶用法把单次仿真演成可重复实验的工程化习惯一份好的 repast 教程不只是教怎么点按钮而是教你如何把仿真过程变得可检查、可复用。资源包末尾有一个analysis模块里面封装了三个我觉得非常值得借鉴的工程化技巧。第一个技巧是结果自动汇总批处理跑完后不是直接看ModelOutput.txt而是用一个ResultParser类自动读取数据目录下的所有文本生成均值、最大最小值并输出成一个简洁的 CSV 表。这样当你跑完 30 组实验时不用手动复制粘贴数据。# 外部脚本处理 repast 输出的多组数据 import pandas as pd files [model_output_%d.txt % i for i in range(1, 31)] frames [] for f in files: data pd.read_csv(f, sep\t, headerNone) frames.append(data) summary pd.concat(frames).groupby(level0).mean() summary.to_csv(summary.csv)第二个技巧是时间比例校正。在做完第一轮实验回看数据时如果发现“未完成订单量”曲线在 50 秒内持续上升先不要急着改参数而是检查时间单位映射。很多仿真结果失真并不是因为逻辑错而是时间尺度与业务时间尺度对不上——这在多智能体仿真里是最隐蔽的坑。第三个技巧是可视化对比。Repast S 内置的 2D 图可以同时打开多个运行窗口但窗口切换会拖慢模拟。更合理的做法是使用ChartCreator在批处理模式下输出图表再导出为图片把不同参数曲线叠在一张图上对比。资源包里的示例自带了一个line_chart.py我通常直接用这个脚本打开数据表对比。总的来说从头到尾把这个仓库配送模型跑通、跑熟、跑透之后你会发现 repast 实例的真正价值不在演示动画而在于给了你一套针对“随机性、时序、空间交互”的完整处理框架。从那以后我每次接新仿真项目都会强制自己先走一遍这样的流程定义 Context、确定调度顺序、设定随机种子、跑通批处理、再调参。整个流程走通后数据质量和可解释性完全不一样。希望这段拆解和踩坑记录能帮到你让你的仿真项目少走几周弯路。本文还有配套的精品资源点击获取