简介：一套基于多智能体算法的城市交通信号控制仿真系统源码，面向交通工程、计算机科学等专业的研究者与学生，用于解决复杂交通流环境下的信号灯协调控制问题，也可作为课程设计、毕业设计或算法研究的基础平台。项目完整覆盖交通流建模、智能体决策机制、信号控制策略与仿真评价环节，核心模块如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 策略前先跑一遍已有测试，能确认基础逻辑没有被动坏。

这张职责清单的作用，是让你在动手改代码之前先建立起「哪些文件改错了会影响什么」的心理地图。调信号控制策略找 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 至少要处理四件事：目标车速、前方车辆的安全跟驰距离、加减速限制、路口前的停走决策。常见做法是采用简化跟驰模型——当前方距离缩短到安全跟驰距离以内时，车辆把目标速度临时限制到前车速度；前方空闲时，再按道路限速加速。这个模型虽然简单，但足以复现排队、饱和流率和绿灯启亮后的启动波这三个最重要的交通现象。

参数上，一个合理的起步配置可以参照下表：

这些参数大多集中在 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++ 内核需要四样东西：支持 C++14/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_TYPE=Release \ -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 章的流程编译一次，能过，这套资源就是你的调参试验台。希望帮到你。

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