简介面向城市交通研究者与系统开发者的多智能体交通信号控制仿真项目基于MAS框架将路口信号灯建模为自治智能体通过协同博弈优化配时策略。资源包共173个文件约49.64MB以C源码.h/.cpp、Python脚本、JSON配置文件为主辅以CMake构建文件、Markdown说明文档及效果图构成完整可编译运行的工程化仿真环境。已有241人学习使用适合具备一定编程基础、希望深入智能交通控制算法的读者。压缩包内包含车辆与路网建模engine/roadnet、DSA_Agent与AgentCenter等核心智能体实现以及pybind11绑定接口、场景配置与可视化资源便于二次开发与仿真对比。项目整合多学科技术覆盖交通流模型、信号策略、评价指标与实时优化模块可帮助读者快速搭建实验平台并支撑论文写作或竞赛验证。1. 多智能体城市交通信号控制仿真从交叉口协商到系统级复现多智能体城市交通信号控制仿真系统的核心矛盾在于单路口定时配时在过饱和流量下失效排队溢出沿干道逐级扩散而集中式配时方案的更新周期又跟不上突发拥堵。这套源码把信号灯抽象成独立智能体通过相邻交叉口的排队状态交换与相位协商在秒级调整绿灯时长引擎侧由 engine.cpp、roadnet.cpp、vehicle.cpp 构成决策侧由 DSA_Agent.cpp 与 AgentCenter.cpp 承担再用 pybind11 暴露给 Python 驱动仿真实验。适合要跑通多智能体协同场景并拿到延误、排队等量化数据的课设、毕设与智能交通方向研究者。2. 智能体通信拓扑与信号相位决策原理2.1 为什么选多智能体而不是集中式配时集中式信号配时典型代表是 TRANSYT 离线配时依赖长周期流量统计一套配时方案的重算间隔以十分钟为单位检测器数据一旦延迟或者某路口发生事故性排队中心立刻给出新方案并不现实。多智能体把决策权下放到交叉口每个智能体只感知自身检测器数据与相邻智能体的排队快照通过多轮协商在数秒内收敛到一组绿灯时长。工程上最直接的收益是去掉中心实时重算依赖单点故障只影响局部协商质量不会拖垮整个路网的信号输出。但这套方案也有明确的适用边界。路网过于稀疏、相邻交叉口间距超过约 800 米时车辆在协商周期内根本到不了下一个路口排队快照携带的信息对当前决策没有意义协商基本退化为各自独立控制此时干线绿波带反而更有效。判断依据很简单比较相邻路口间的旅行时间与协商周期前者若接近后者多智能体的优势就体现不出来。在这套源码里AgentCenter.cpp 并不是集中决策者它只承担三类工作维护智能体注册表、同步每轮协商的启停时机、把协商结论写入日志。真正的相位决策逻辑在 DSA_Agent.cpp 中这里 DSA 取 Distributed Signal Agent 之意每个智能体持有一份相位表、一组进口道排队计数器和一个相邻智能体地址列表。这也是多智能体系统MAS里「个体自治 局部通信」的典型架构没有全局黑板不依赖统一决策模型。2.2 智能体状态感知与协商数据流每个智能体在一轮协商内按感知、广播、决策三步推进。我一般固定这个顺序顺序颠倒会导致本智能体用上一轮的旧数据做本轮决策形成隐含的一轮延迟从引擎读取本交叉口各进口道的排队长度与到达率构造排队快照消息广播给相邻智能体收到全部相邻快照后按阈值规则计算各相位绿灯时长并写回信号表// DSA_Agent.cpp 中一轮协商的消息载荷 struct Snapshot { // 相邻路口发送的排队快照 int agent_id; // 来源智能体编号 float queue_ratio; // 主进口排队长度 / 车道容纳上限 float arrive_rate; // 主进口到达率veh/s }; struct PhaseDecision { // 本智能体写回引擎的相位决策 int phase_id; // 相位编号0 东西直行1 东西左转 int min_green; // 最小绿灯秒数由行人过街时间约束 int max_green; // 最大绿灯秒数限制单相位占用 float queue_ratio; // 本路口最大排队比供下一轮对外广播 };逻辑说明min_green 由行人过街和清空路口时间共同决定max_green 是协商的竞争边界。当邻居路口的 queue_ratio 超过阈值时本路口需要压缩自己的 max_green把绿灯窗口让出去队头阻塞风险高的路口则保持 max_green 不降。queue_ratio 是消息里的核心载荷它必须使用与对方统一的排队容量口径否则协商结果会系统性偏向某个方向。排队比阈值 0.8 是常见起点但这个数值要跟车道数绑定四车道进口的排队比 0.8 和三车道进口的 0.8 对应的绝对排队长度不同协商结果容易被车道数多的路口带偏。我一般把 queue_ratio 的分母换成车道数乘以阻塞密度再乘以车道长度这样不同几何条件的路口之间才有可比性。2.3 路网参数与建模口径roadnet.cpp 把交叉口拓扑组织成路口、路段、车道三层结构每个路口关联一个智能体。车道级参数对协商结果影响最大我平时维护这张表参数典型值说明lane_length150~600 m决定排队容量上限过短会出现不真实的溢出sat_flow1800 veh/h饱和流率影响绿灯期间的放行总量jam_density0.15 veh/m堵塞密度排队长度换算的依据dt0.5 s引擎推进步长见第 3 章2.2 里的 queue_ratio 分母就是 lane_length 与 jam_density 的乘积。参数口径不统一比如一个智能体用车道的最大排队长度另一个用所有进口道的排队平均值协商结果会出现方向性偏差这是排错时要先检查的建模问题。3. C 仿真引擎核心模块实现3.1 车辆跟驰与路网拓扑vehicle.cpp 与 roadnet.cpp微观仿真中车辆是独立实体vehicle.cpp 负责跟驰与换道行为。源码采用的是 IDM智能驾驶员模型变体加速度由当前车速、车间距和期望速度共同决定// vehicle.cpp 跟驰加速度计算IDM 变体 double idm_accel(double v, double gap, double v_target, double t_gap) { double s_star v * t_gap v * (v - v_target) / (2.0 * sqrt(3.5)); double accel 1.4 * (1.0 - pow(v / v_target, 4) - pow(s_star / gap, 2)); return std::clamp(accel, -3.4, 1.4); }逻辑说明v 为当前车速gap 为到前车的车间距v_target 为期望速度t_gap 为跟车时距。s_star 是期望跟车间距当 gap 小于 s_star 时产生负加速度车辆自然减速形成无冲突的跟驰流。常数 1.4 是常用加速度-3.4 是普通小汽车最大减速度卡车参数差异明显需要单独配置否则排队消散阶段的加速度不真实。网格路网的瓶颈通常在左转车道。如果 vehicle.cpp 里换道逻辑允许最后一格强制变道左转车道排队会把直行车道堵死检测器统计到的 queue_ratio 会虚高协商因此给出过多左转绿灯。我一般把换道禁区的终点设在上游 50 米处留给直行车辆足够的反应距离。roadnet.cpp 将路网组织成 路口→路段→车道 三层结构并为每个路口关联一个信号智能体。路网文件里除了拓扑连接还包含相位的方向映射同一相位可能同时放行直行和对向直行这个映射关系决定了 DSA_Agent 决策写回后信号灯组的亮灯组合。3.2 DSA_Agent 决策流程与 AgentCenter 同步机制DSA_Agent.cpp 的协商通常按固定轮次收敛每轮所有智能体并行完成感知与广播。这里的「并行」要小心多线程下如果快的智能体领先一个轮次它读到的邻居数据就是上一轮的噪声会被放大。AgentCenter 用一轮到齐计数来避免这种时序错乱// AgentCenter.cpp 一轮同步的核心判断 while (round_ready_count agents.size()) { std::this_thread::yield(); // 等待全部智能体上报本轮完成 } round_ready_count 0; // 清空计数开放下一轮 round_index; // 本轮结束全局轮次推进代码说明每个智能体完成快照广播后调用 mark_ready() 增加计数AgentCenter 只有收到全部智能体的到齐信号才推进轮次保证所有智能体在同一轮数据之上做决策。如果省掉这一步会出现某个路口总是领先一个轮次、协商结果偏向该路口的假象。协商轮次上限一般设 3~5 轮。轮次太少排队溢出信息传不到远端路口轮次太多单步仿真耗时明显增加。我通常在网格路网里从 4 轮起步观察延误变化是否在第二轮之后趋于稳定。一个容易踩的细节决策写回信号表后如果下一个相位仍处于最小绿灯未完成状态max_green 的压缩在当轮不生效必须等下一轮。这也是 AgentCenter 的 round_index 在日志里必须保留的原因——轮次对不上压缩逻辑看起来就像偶尔失效。3.3 引擎主循环与时间步推进engine.cpp 按固定步长 dt 推进仿真状态每步依次完成车辆更新、排队快照收集再判断是否到达协商时刻。协商触发频率独立于车辆更新的步长这是避免配时抖动的一个关键设计// engine.cpp 主循环骨架 while (sim_time total_time) { for (auto v : vehicles) { v.update(dt); // 车辆跟驰与换道推进 } for (auto a : agents) { a.push_snapshot(); // 智能体上报排队快照 } if (sim_time next_negotiation) { agent_center.sync_round(); // 到达协商时刻执行多智能体协商 next_negotiation 5.0; // 协商周期固定 5s } sim_time dt; }逻辑说明dt 取 0.5s 是精度与耗时的折中。车辆更新在每步执行信号相位切换只在协商时刻生效两者解耦后配时调整不会打断车辆微分方程推进的连续性。协商周期 5s 是经验值频率过高时排队长度的短时波动会放大到绿灯时长上频率过低时排空滞后明显。把 dt 从 0.5 改成 0.2 后车辆跟驰更平稳但 1200 秒仿真的循环次数翻两倍多pybind11 绑定层的调用开销也会放大。仿真精度不足时优先调车辆模型参数而不是盲目缩小 dt。4. CMake 构建与 Python 绑定实战4.1 setup.cfg 与 CMake 配置压缩包根目录的 setup.cfg 描述的是「C 内核 Python 壳」的典型结构结合 CMakeModules 里的 pybind11Tools.cmake、FindPythonLibsNew.cmake、FindEigen3.cmake构建时按顺序解决三件事找到 Python 开发头文件、找到 pybind11、找到 Eigen 线性代数库。FindCatch.cmake 是单元测试框架 Catch2 的定位器用于把 DSA_Agent 的纯函数逻辑比如阈值判断抽出来单独跑测试避免每次验证都依赖整个仿真主循环。我改动协调逻辑前会先补两个用例queue_ratio 归一化的 0/1 边界以及 max_green 压缩区间的开闭。setup.cfg 的常用形态是[metadata] name trafmas version 0.1 [options] packages find: python_requires 3.8 [build_requires] cmake 3.14 ninja逻辑说明setup.cfg 只声明包元数据与最低构建工具版本真正的扩展模块编译入口在 setup.py 里调用 cmake 完成。python_requires 限定 Python 版本是避免 pybind11 的 ABI 冲突后面 4.3 会看到 undefined symbol 大多和这个相关。本地调试用可编辑安装即可一条命令把编译产物直接链接到当前环境pip install -e .也可以显式走 cmake适合要改编译参数如 -O2 优化等级、Sanitizer的场景mkdir -p build cd build cmake .. -DPYTHON_EXECUTABLE$(which python) cmake --build . --parallel 4说明PYTHON_EXECUTABLE 显式指定当前虚拟环境的解释器避免 cmake 找到系统 Python 导致绑定层的库被链接错。Ninja 缺失时去掉 --parallel 参数仍可构建只是并行度下降。4.2 pybind11 接口设计与数据交换pybind11 绑定层只做类型转换不写业务逻辑。Engine 类绑定成 Python 可调用的对象后step 一次对应 dt 的一次推进get_agent_stats 返回按路口组织的统计字典// engine_bind.cpp绑定层示意 #include pybind11/pybind11.h #include pybind11/stl.h PYBIND11_MODULE(trafmas_core, m) { pybind11::class_Engine(m, Engine) .def(pybind11::initconst std::string()) .def(step, Engine::step) .def(get_agent_stats, Engine::get_agent_stats); }代码说明init 接收路网配置文件的路径Engine 在 C 侧完成全部内存分配step 参数是推进秒数get_agent_stats 把 std::map 转成 Python 字典键为 agent_0、agent_1 这样的路口编号值为延误、平均车速和排队长度。注意pybind11 的 STL 容器转换有开销逐 step 调用会放大这部分成本。数据量大的实验建议在 C 侧先做时间窗口聚合Python 端只读取最终统计。4.3 编译排错与首个仿真跑通编译成功后验证链路最简单的是直接推进一组定长仿真import trafmas_core as tc engine tc.Engine(configs/4x4_grid_network.json) for _ in range(1200): # 1200 步 × 0.5s 600s engine.step(0.5) stats engine.get_agent_stats() print(stats[agent_0][delay]) # 路口 0 的平均延误单位秒说明前 300 步属于初始排队排空阶段对比实验要丢弃 warm-up 段统一从第 600 步开始采样。delay 字段是总等待时间除以通过车辆数轻流量下数值很小重流量下接近 60s 时说明路网已经接近锁死。跑批量实验建议把配置抽象成参数化命令而不是每轮改源码python run_experiment.py --network 4x4 --strategy negotiation --max-green 45 --seed 42这里 strategy 固定成 fixed 与 negotiation 两个值seed 固定则两次实验的车辆到达序列一致差值才完全来自配时策略本身。两个高频报错ModuleNotFoundError: trafmas_core 基本是没执行 pip install -e .或者运行目录不包含扩展的 .so 文件ImportError: undefined symbol 则是 pybind11 与当前 Python 的头文件版本不匹配重建虚拟环境时优先固定 python_requires。排查时先确认当前环境的 include 路径与编译时一致python -c import pybind11; print(pybind11.get_include())这个命令输出的 include 路径要和当前 Python 头文件路径处于同一套环境两个路径对不上时优先重建环境。5. 实验对比与配时参数验证5.1 对照场景与评价指标用 4×4 网格路网做两组对照固定配时南北/东西绿灯各 30s无协商与多智能体协商max_green45s协商周期 5s。总仿真 1800s取后 1200s 数据。三个指标最容易看出差距指标固定配时多智能体协商平均延误s/veh48.233.7平均车速km/h21.429.8最大排队长度m452287数据是典型量级本地结果与路网规模强相关。跑对照实验时保持随机种子一致只切换协商开关否则两次实验的车辆到达序列不同差值会被随机性淹没。5.2 最值得先调的两个参数第一个是协商周期。5s 换到 10s平均延误通常上升 15%~25%但仿真耗时下降明显换到 2s排队波动的反馈被放大绿灯频繁切换延误反而恶化。协商周期要和到达流的波动周期错开这是经验法则。第二个是 max_green 的让渡系数。系数太大干道绿灯间歇性让给支路干道排空速度反而不如固定配时系数太小协商退化成定时配时。我习惯从 2s 起步每次加 2s观察最大排队长度的方差而不是均值——方差下降说明排队被分散到多个交叉口这是多智能体真正起作用的信号。5.3 一个实用的验证技巧判断协商是否真的改变了信号行为可以用「拔线测试」临时清空某个智能体的邻居列表等价于该智能体失联。如果失联路口延误上升、相邻路口延误无明显恶化说明通信冗余设计合理如果失联路口排队溢出并连带后方路口锁死说明排队约束没有参与邻域目标的带权计算需要回头检查 Snapshot 里 queue_ratio 的聚合方式。拔线测试的结果要同时看延误均值和排队长度方差。均值反映协商是否退步方差反映排队是否在向相邻路口转移只报平均值会被初始排空阶段的噪声遮盖。本文还有配套的精品资源点击获取