多智能体交通信号控制仿真：C++工程源码编译与实验调参实践

简介一套基于多智能体算法的城市交通信号控制仿真系统源码面向交通工程、计算机科学等专业的研究者与学生用于解决复杂交通流环境下的信号灯协调控制问题也可作为课程设计、毕业设计或算法研究的基础平台。项目完整覆盖交通流建模、智能体决策机制、信号控制策略与仿真评价环节核心模块如engine.cpp、roadnet.cpp、DSA_Agent.cpp、AgentCenter.cpp、vehicle.cpp均包含在内工程化实现了路网解析、车辆运动仿真与信号灯智能协调等关键功能并配套CMake构建脚本、Python辅助脚本和配置文件便于直接阅读、编译和二次开发代码注释与目录结构清晰有助于梳理多智能体协作流程。压缩包共173个文件、49.64MB以71个.h头文件、15个.cpp源文件、11个.py脚本为主其中.h与.cpp构成系统主体.py支撑仿真预处理和结果分析另有json、md、pdf等格式覆盖路网定义、参数配置与实验说明内容相对完整。已有241人学习下载适合希望掌握多智能体协同控制技术、进行交通信号优化实验的开发者与研究者。借助该源码可复现多路口信号协调仿真实验调整策略参数观察排队长度、平均延误等指标变化进而扩展信号配时方案为城市交通管理提供高效的仿真试验平台。1. 多智能体城市交通信号控制仿真一套能跑多路口联动的 C 源码工程把信号灯当定时器还是当谈判者是第一次拿到这套基于多智能体算法的城市交通信号控制仿真系统源码时最直观的感受。它不是一个只给图表的演示工程C 内核、pybind11 绑定、CMake 构建链、DSA_Agent 协调逻辑、路网与车辆模型全套都能在本地编译、运行、改参再通过 Python 扩展批量跑实验。与拿现成交通仿真软件拖拽路网相比这套源码把「交通流模型 智能体设计 信号控制策略 评价指标」四个环节全部敞开在代码里适合要做课程设计、论文仿真或早期策略验证的从业者。想快速落地一套可复现的多智能体交通信号控制实验这份工程是很好的起点前提是你愿意亲手把构建链跑通。2. 从工程骨架读源码setup.cfg、Find*.cmake 与五个核心模块的边界拿到一个源码包先别急着编译把根目录的文件名读一遍往往能省掉半天排错时间。这个工程里 setup.cfg、pybind11Tools.cmake 与多个 Find*.cmake 文件同时出现已经暗示了它的整体架构C 写仿真内核pybind11 做 Python 绑定CMake 管构建Catch2 管测试。理解这些文件的职责你才知道改哪一行会牵动哪一块。2.1 从 setup.cfg 读出构建意图pybind11、Eigen、Catch 都在找什么setup.cfg 在 Python 打包场景里通常被构建后端读取记录扩展模块的元信息、编译参数和 C 标准。它在 pybind11 工程里相当于「告诉编译器按什么标准编、编出什么模块名」。pybind11Tools.cmake 则是在 CMake 层提供 pybind11_add_module() 命令把 C 源码编译成可被 import 的扩展模块省去手写一堆导出宏的麻烦。这两个文件同时出现说明作者的设计意图很明确核心逻辑用 C 写实验和可视化放到 Python 层做。FindPythonLibsNew.cmake、FindEigen3.cmake、FindCatch.cmake 三个查找模块对应三组外部依赖。FindPythonLibsNew 负责定位当前 Python 版本的头文件和库这是最容易翻车的一步——如果它找到的是系统 Python而你在 conda 环境里编译最后 import 扩展模块时就会遇到符号对不上的问题。FindEigen3 找的是线性代数库 Eigen3交通流模型里车辆位置、速度、队列长度的向量化计算都要用到它。FindCatch 找的是 Catch2 测试框架用来给算法核心写单元测试改 DSA_Agent 策略前先跑一遍已有测试能确认基础逻辑没有被动坏。文件/模块职责定位setup.cfg构建后端配置记录编译参数与扩展模块元信息pybind11Tools.cmake提供 C 到 Python 的绑定构建命令FindPythonLibsNew.cmake定位 Python 头文件、库与版本FindEigen3.cmake定位 Eigen3 头文件矩阵与向量计算FindCatch.cmake定位 Catch2 测试框架engine.cpp仿真主循环与整体调度roadnet.cpp路网拓扑、路口、车道与信号相位建模vehicle.cpp车辆运动学与跟驰行为DSA_Agent.cpp单路口智能体决策逻辑AgentCenter.cpp多智能体注册、通信与消息分发这张职责清单的作用是让你在动手改代码之前先建立起「哪些文件改错了会影响什么」的心理地图。调信号控制策略找 DSA_Agent.cpp改车辆行驶行为找 vehicle.cpp改仿真整体推进节奏找 engine.cpp。很多人拿到源码就开始逐行读结果读了两天还在 vehicle.cpp 里打转原因就是没先看文件边界。我一般会把这张表贴在工程目录旁边改到哪个模块就只关注对应文件避免在文件之间反复横跳。2.2 五个核心源文件的职责边界与主循环骨架engine.cpp、roadnet.cpp、vehicle.cpp、DSA_Agent.cpp、AgentCenter.cpp 这五个文件基本覆盖了一个微观交通仿真器的全部主干。roadnet.cpp 管静态世界描述路口连接关系、车道数、限速与信号相位配置vehicle.cpp 管单辆车的行为包括速度更新、跟驰距离、路口转向规则DSA_Agent.cpp 管单个路口的信号决策根据排队和流量决定下一轮相位时长AgentCenter.cpp 管多路口之间的通信接收每个 Agent 发布的状态并把相邻路口关心的信息转发过去engine.cpp 则把以上对象放在一个固定时间步长的循环里推进。把主循环逻辑简化成伪代码大致是这个骨架// 伪代码仿真主循环 for step in range(total_steps): // 1. 按当前信号相位更新车辆位置 for veh in roadnet.vehicles: update_position(veh, delta_t) // 2. 收集各路口排队长度 for intersection in roadnet.intersections: queue_info[intersection] measure_queue(intersection) // 3. 各 Agent 发布本路口状态 for agent in agent_center.agents: agent.publish(queue_info[agent.intersection]) // 4. AgentCenter 把消息转发给相邻 Agent agent_center.exchange() // 5. 每个 Agent 结合邻居消息更新相位时长 for agent in agent_center.agents: agent.update_phase(neighbor_messages[agent.intersection]) // 6. 写回路网应用相位切换含最小绿灯与黄灯约束 roadnet.apply_phase_changes()这份骨架里有两个容易被忽略的细节。第三和第四步是分开的先发布、再协商保证每个 Agent 本轮看到的是邻居上一轮的状态不会因为更新顺序不同产生偶然偏差。第六步的「最小绿灯与黄灯约束」是防止相位频繁闪烁的关键——很多初版仿真翻车就翻在这里Agent 每轮小幅调整相位绿灯时长在 8 秒和 12 秒之间反复横跳路口实际通行能力反而下降。这些细节在后文避坑部分会具体展开。2.3 为什么是 C 内核 Python 实验层和外部仿真器的区别很多做信号控制的人第一个想到的是拿 SUMO 搭路网、外挂 Python 脚本控制信号灯。SUMO 确实成熟但它的边界在于路网模型、车辆行为和信号控制逻辑被封装在同一个仿真软件里改车辆跟驰参数要迁就它的模型接口改信号策略要适配它的外部控制协议遇到瓶颈时很难判断问题出在哪一层。这套工程采用 C 内核 pybind11 的方式把仿真器和实验环境做了隔离C 侧负责确定性和计算性能Python 侧负责参数扫描、可视化和结果统计。这种拆法对做算法实验特别友好。你可以把 Python 当控制台用批量修改排队权重、绿灯惩罚系数跑几百组参数后统一出指标对比核心逻辑仍然在 C 里一遍编译到处运行仿真速度不会因为 Python 层的调度而明显下降。更重要的是DSA_Agent 的协商逻辑可以独立测试——只要 AgentCenter 的消息结构不变你可以先造一个两路口的小路网验证 Agent 的决策是否收敛再放回完整路网跑大规模仿真。这种分层验证的思路在系统仿真和城市交通信号控制策略研究里能帮你省下大量排错时间。3. 控制回路串联DSA_Agent 协商、相位切换与微观跟驰模型的配合仿真主循环只是骨架真正决定仿真结果质量的是几个核心对象之间的配合方式。车辆怎么动、Agent 怎么协商、相位怎么切、指标怎么统计这四个问题串起来才是一条完整的控制回路。这一章照着代码结构逐层往下拆。3.1 车辆与路网微观跟驰模型的最小实现要素微观交通仿真里车辆与车辆之间的交互是最底层的模型。vehicle.cpp 至少要处理四件事目标车速、前方车辆的安全跟驰距离、加减速限制、路口前的停走决策。常见做法是采用简化跟驰模型——当前方距离缩短到安全跟驰距离以内时车辆把目标速度临时限制到前车速度前方空闲时再按道路限速加速。这个模型虽然简单但足以复现排队、饱和流率和绿灯启亮后的启动波这三个最重要的交通现象。参数上一个合理的起步配置可以参照下表参数建议初始值说明仿真时间步长 delta_t0.1 秒过大如 1 秒会导致路口冲突检测失真车辆车身长度4.5 米用于排队长度与密度计算最大期望车速60 km/h可随路段限速调整安全跟驰距离2 米静态安全距离速度相关的动态距离另算路口停车线检测距离30 米决定车辆何时开始为红灯减速这些参数大多集中在 vehicle.cpp 的头部常量和 roadnet.cpp 的路段定义里。调试时我一般只动 delta_t 和最大期望车速两个因为它们对结果的影响最直观delta_t 影响冲突消解精度最大期望车速影响路网整体吞吐上限。如果改了跟驰行为没生效先确认是不是 roadnet 初始化时又覆盖了一遍——这是源码工程里最常见的「改了白改」问题。3.2 智能体怎么交换信息AgentCenter 的消息分发与协商语义多智能体算法在这个工程里的核心体现是 DSA_Agent 之间的消息交换。AgentCenter.cpp 承担的不是中央控制而是消息路由每个 Agent 发布自己的路口状态AgentCenter 根据路网拓扑只把状态转发给物理上相邻的 Agent。这种设计让决策真正分布化——某个路口策略改了不会影响整张路网的运行。Agent 之间传递的消息一般包含以下几个字段// 相邻路口协商消息体 struct NeighborMessage { int agent_id; // 发送方路口 ID int cycle_id; // 当前信号周期序号用于去重 float queue_length; // 本路口当前最大排队长度米 float arrival_rate; // 本周期到达车辆数辆/周期 float suggested_green; // 建议下游延长的绿灯量秒 };即发送方 ID、周期序号、排队长度、到达率、建议调整量五元组。suggested_green 是关键字段它相当于一个 Agent 在告诉邻居「我这边排队压上来了麻烦你下一轮多放点车过来」这就是 Agent 之间的协商信号。看到这个字段你就明白信号灯式控制和 Agent 式控制的本质区别前者按固定配时走后者会主动「喊话」。注意 suggested_green 不要直接采用而是作为加权项参与本路口决策否则很容易出现两个路口互相迁就、绿灯越给越长的失控循环。cycle_id 是容易被忽略但很重要的字段。AgentCenter 在转发消息时按 cycle_id 去重一个信号周期内只保留最新一条邻居状态避免同一周期的多条消息被重复计入决策。没有这个去重机制Agent 的输入会是乱序的决策结果自然不稳定。3.3 相位时长怎么变一个带排队反馈和最小绿灯约束的策略有了邻居消息和本路口排队信息DSA_Agent 就可以更新相位时长了。这里给一个常见做法——基础绿灯加反馈调整再套最小最大约束# 伪代码DSA_Agent 更新下一周期相位时长 new_green base_green # 基础绿灯来自固定配时或历史统计 k * (my_queue - neigh_queue) # 排队反馈本路口排队高则多放行 w * suggested_green # 邻居建议适当照顾下游路口 # 约束不得小于最小绿灯也不得超过最大绿灯 if new_green min_green: new_green min_green if new_green max_green: new_green max_green # 应用相位切换前检查黄灯过渡时间 if abs(new_green - current_green) threshold: roadnet.apply_yellow_transition(delta_yellow)这个策略里出现 k 和 w 两个参数k 是本路口排队反馈系数w 是邻居建议采纳系数。实践经验是 w 不要超过 k 的三分之一否则会把相邻路口的排队问题揽到自己身上造成「帮忙帮出反效果」。min_green 和 max_green 的设置也很关键最小绿灯时间一般参考行人过街极限比如 8 到 10 秒最大绿灯一般不超过 60 秒否则一个方向等红灯的时间会超过驾驶员的心理容忍上限。调参时先调 k 和 w再动约束顺序颠倒容易让结果曲线完全不可解释。3.4 评价指标先从哪四项入手流量、车速、延误、排队仿真系统没有评价指标就只能看个热闹。摘要里提到的评价指标——交通流量、平均车速、车辆延误、排队长度——在这个工程里建议按优先级落地先统计每个周期通过路口的车辆总数吞吐量再统计平均行程车速然后计算车辆延误最后记录最大排队长度。吞吐量和延误是信号控制策略好坏的直观标尺排队长度则帮你定位瓶颈路口。这四项指标的统计代码通常放在 engine.cpp 的统计回调里每个仿真步或每个信号周期结束时汇总一次。要特别注意统计口径平均车速按「距离/行程时间」算还是按「瞬时速度算数平均」算结果会差不少。做策略对比时先把统计口径固定下来再跑实验否则你很难判断指标提升来自算法改进还是来自统计方式变化。这也是后面调参闭环绕不开的一步。4. 本地复现CMake 构建、pybind11 绑定与一趟完整的仿真运行这一章的目标只有一个让源码在你的机器上真正跑起来。按照下面的顺序执行从装依赖到跑出第一份统计结果大约需要半小时。如果中途卡住直接去第 5 章找对应的踩坑记录。4.1 准备构建环境编译器、Eigen3 与 Python 开发头文件编译这套 C 内核需要四样东西支持 C14/17 的编译器、CMake、Python 开发头文件对应你想绑定的 Python 版本、Eigen3 头文件。Catch2 是可选的只在你想跑单元测试时才会用到。Ubuntu 系环境里一条命令就能装齐大部分依赖# Ubuntu/Debian 系示例 sudo apt update sudo apt install -y cmake g libeigen3-dev python3-dev catch2 # 如果你用 conda 环境先激活再安装 # conda install -c conda-forge eigen cmake装完用两条命令确认 Eigen 和 Python 头文件的位置这在后面配置 CMake 时会用到# 确认头文件位置 ls /usr/include/eigen3 python3 -c import sysconfig; print(sysconfig.get_paths()[include])很多人在这一步就翻车了报错内容类似 found PythonInterp 和 find_package(PythonLibs) 版本不一致或者明明在 conda 环境里编译最后 import 时却说找不到 Python 开发头文件。这类问题的解决思路统一是让 CMake 用同一个 Python 解释器来找头文件和库具体做法在 4.2 里给出。4.2 两步构建CMake 配置、编译与 Python 导入验证构建流程拆成两个代码块。第一段是标准 CMake 构建流程Linux 和 macOS 通用第二段是 Python 侧导入验证确认扩展模块真的被编译出来了。# 解压工程后进入根目录 unzip 多智能体交通信号控制仿真系统源码.zip cd multi-agent-traffic-signal/ # 配置构建目录Release 模式跑得快 cmake -S . -B build -DCMAKE_BUILD_TYPERelease \ -DCMAKE_PREFIX_PATH$(python3 -c import sysconfig; print(sysconfig.get_paths()[data]))CMAKE_PREFIX_PATH 这行值得解释它让 CMake 优先在当前 Python 环境的基础目录里找依赖库而不是去 /usr 下找另一套。如果你的机器上只有一套 Python这行不写也能过但写了能省掉很多版本错配的麻烦。# 编译并安装扩展模块到 Python 可导入的位置 cmake --build build -j4 cmake --install build # 在 Python 里验证导入 python3 -c import engine; print(engine.__file__)如果最后一步 import 成功说明 C 内核已经通过 pybind11 暴露成 Python 模块了。建议把打印出来的路径记下来之后做策略实验时确保所有脚本都跑在同一个 Python 解释器下。4.3 修改参数的效率路径只重编改动、确认统计输出仿真实验必然要反复改参数。增量编译是提升效率的关键改完 DSA_Agent.cpp 里某个权重系数不需要重新 configure直接 cmake --build 就会只编译改动过的文件。改参数的流程建议遵循固定路径先改 C 常量或公式再编译再跑 Python 脚本然后回到指标检查。# run_sim.py —— 调用已编译好的扩展模块跑一趟仿真 import engine # 或实际编译出的扩展模块名 sim engine.create_simulation() sim.load_roadnet(data/grid_4x4.json) # 4x4 十字路网作为实验场 sim.set_duration(3600) # 仿真时长 3600 秒 1 小时 sim.set_random_seed(42) # 固定种子保证结果可复现 sim.run() stats sim.statistics() print(stats[throughput]) # 总通过车辆数 print(stats[mean_delay]) # 平均车辆延误秒/辆 print(stats[max_queue]) # 最大排队长度米注意一个细节具体模块名和函数名要以你这份源码里 pybind11 绑定的 .def(...) 导出为准。第一次导入后可以用 dir(engine) 把所有可调用的对象打出来看一眼避免因为命名差异卡在入门第一步。这个脚本把仿真过程封装成 create、load、set、run、statistics 五步正好对应 engine.cpp 主循环里的初始化、路网加载、参数设置、循环推进和指标汇总五个阶段。4.4 多路口联动的第一批实验先跑一个两路口场景第一次跑通后不建议直接上大规模路网。常见做法是先建一个两路口相连的小场景主干道方向车流大次干道方向车流小然后对比固定配时和 DSA_Agent 协调配时两组结果。这样能最快验证多智能体算法是否真的让信号控制产生正向效果——如果两路口协调都看不到收益放回大路网只会更难分析。这个小实验的检查点是主干道方向吞吐量是否提升、次干道方向排队是否超过设定阈值、Agent 协商的 suggested_green 是否频繁触发超调。5. 避坑记录构建失败、相位跳变与结果不收敛的四个典型翻车现场这段内容是血泪经验汇总每一条都对应一个具体的故障现象、原因和解决办法。如果你在复现过程中遇到类似问题直接对照处理。5.1 踩坑一pybind11 扩展导入报错多半是 Python 库路径不对现象cmake 配置和编译都通过了但 import 时报错内容类似 undefined symbol 或者找不到 Python 动态库。 原因FindPythonLibsNew.cmake 在配置阶段找到的是系统 /usr/bin/python3 对应的库而你在终端里用的是 conda 或 pyenv 的 Python。两个环境下的 Python 版本或 ABI 不一致扩展模块编译时的符号和导入时的解释器对不上。 解决在 CMake 配置时显式指明当前解释器cmake -S . -B build -DPython_EXECUTABLE$(which python3) \ -DCMAKE_PREFIX_PATH$(python3 -c import sysconfig; print(sysconfig.get_paths()[data]))改完清空 build 目录重新配置不要只做增量重编因为 CMake 的 Python 查找结果有时不会因为环境变量变化而自动刷新。5.2 踩坑二车辆直接穿过红灯先把时间步长降下来现象信号灯明明显示红灯仿真里却有车辆直接冲过路口甚至出现两辆车在路口中心重叠的场面。 原因最直接的是 delta_t 太大。如果仿真步长是 1 秒车辆在红灯相位尾段进入路口后相位切换发生在同一个步长内穿行检查来不及把停在停车线的车拦下来。另一个常见原因是冲突消解逻辑对「车辆已越过停车线但还没离开路口」的中间状态处理不严谨。 解决把 delta_t 从 1 秒降到 0.1 秒并且把相位切换判断放在车辆位置更新之前或之后的固定顺序里。改完再跑同一组随机种子穿红灯现象基本消失。若仍有个别穿行多半是 roadnet.cpp 里车道连接关系或转向规则写漏了需要检查路口转向是否允许冲突。5.3 踩坑三相邻路口协商「踢皮球」绿灯时长频繁抖动现象用 DSA_Agent 协调后两个相邻路口的绿灯时间每个周期都大幅波动主路通行能力反而比固定配时更差延误曲线像锯齿一样上蹿下跳。 原因协商消息只包含排队长度和到达率没有对「本周期与上周期相位差异」做惩罚。两个路口互相用 suggested_green 给对方加时长几轮循环里就把绿灯时长推到上限附近触发约束后又摔回下限形成振荡。 解决在 DSA_Agent.cpp 的相位更新公式里加两项约束——最小绿灯时间和相位切换惩罚项。切换惩罚项的做法是记录上一周期本路口相位时长如果新计算结果与旧值相差超过阈值先向当前值方向收敛一部分而不是直接跳到新值。同时在 AgentCenter 的消息处理里加一个合并窗口一个信号周期内只处理一次邻居消息避免同周期多条消息被重复计入。5.4 踩坑四结果波动大到不可复现先固定随机种子再谈调参现象同一个参数跑两遍平均延误差出 30%且找不到是哪里改了。 原因车辆出发时间、路网入口选择是随机生成的但工程没有固定随机种子也没有预热步骤。前几百步路网只有少量车辆统计平均延误时会把这段空转时间算进去导致不同轮次之间噪声远大于参数差异。 解决两个动作一起做。第一在 engine.cpp 初始化时读取一个可配置的随机种子并在 Python 侧固定第二在统计指标前加一段预热时间比如前 200 个仿真秒不记录指标只让车辆填满路网。预热的作用是让排队和延误进入饱和状态后再做对比否则你的指标反映的是路网启动过程而不是信号控制策略本身。6. 用评价指标倒推参数延误统计与信号控制调参的一个闭环6.1 延误怎么统计车辆行程时间与理想行驶时间的差延误是最能反映信号控制质量的指标。常见定义是车辆从进入路网到离开路网的总行程时间减去在自由流速度下跑完同样距离所需的理想行程时间差值就是延误。这个口径在代码里很好实现# 统计延误总行程时间减去理想行驶时间 ideal_time travel_distance / free_speed delay real_travel_time - ideal_time这里的要点是 real_travel_time 要穿越多个信号周期累计不能只在某个瞬间采样。我一般把统计周期设为一分钟跑完一小时仿真就是 60 个统计点把它们画成延误随时间的曲线才能看出某个路口的瓶颈到底是持续饱和还是瞬时波动。提示同一组参数至少跑三次不同随机种子取平均延误再比较单次结果容易误导调参方向。6.2 用延误与排队长度指标反推控制参数有了指标调参就有了依据。当某一路口平均延误偏高时先看它的最大排队长度是否持续超限再回头调 DSA_Agent.cpp 里的 k排队反馈系数和 w邻居建议采纳系数。一般做法是先把 k 调大让本路口更快响应排队增长再把 w 控制在 k 的三分之一以内避免跨路口干扰然后重新编译、重跑同样场景、对比延误曲线。如果延误曲线的锯齿还是没有收敛大概率是相位切换惩罚项不够强回去检查 5.3 里说的合并窗口。从那以后我每搭一个新场景都强制自己走一遍固定随机种子、预热 200 秒、按分钟统计延误三步否则后面所有对比都建立在噪声上。这套源码的价值恰恰在于它把交通流模型、DSA_Agent 协商、相位策略和评价指标放在同一个工程里让你能在自己改过的每条路上反复验证假设。决定是否下载之前先按第 4 章的流程编译一次能过这套资源就是你的调参试验台。希望帮到你。本文还有配套的精品资源点击获取