SUMO-RL

SUMO-RL 提供了一个简单的接口，用于使用 SUMO 为交通信号控制实例化强化学习 (RL) 环境。

本仓库的目标：

• 提供一个简单易用的接口，利用 SUMO 进行交通信号控制的强化学习
• 支持多智能体强化学习
• 兼容 gymnasium.Env 和流行的 RL 库，如 stable-baselines3 和 RLlib
• 易于自定义：状态和奖励的定义可以轻松修改

主类是 SumoEnvironment。 如果实例化时设置参数 'single-agent=True'，它将表现得像一个标准的 Gymnasium Env。 对于多智能体环境，请使用 env 或 parallel_env 来分别以 AEC 或 Parallel API 实例化一个 PettingZoo 环境。 TrafficSignal 负责通过 TraCI API 获取信息并控制交通信号灯。

更多详情，请查看 在线文档。

安装

安装 SUMO 最新版本：

sudo add-apt-repository ppa:sumo/stable
sudo apt-get update
sudo apt-get install sumo sumo-tools sumo-doc

别忘了设置 SUMO_HOME 变量（SUMO 的默认安装路径是 /usr/share/sumo）：

echo 'export SUMO_HOME="/usr/share/sumo"' >> ~/.bashrc
source ~/.bashrc

重要提示：为了获得巨大的性能提升（约 8 倍），可以启用 Libsumo，并声明变量：

export LIBSUMO_AS_TRACI=1

请注意，如果此选项启用，则无法使用 sumo-gui 或同时运行多个模拟（更多详情)。

安装 SUMO-RL

稳定版可通过 pip 安装：

pip install sumo-rl

或者，您也可以安装最新的未发布版本：

git clone https://github.com/LucasAlegre/sumo-rl
cd sumo-rl
pip install -e .

MDP - 观测、动作与奖励

观测

每个交通信号代理的默认观测是一个向量：

    obs = [phase_one_hot, min_green, lane_1_density,...,lane_n_density, lane_1_queue,...,lane_n_queue]

• phase_one_hot 是一个独热编码向量，表示当前激活的绿灯相位
• min_green 是一个二进制变量，指示当前相位是否已超过最小绿灯时间
• lane_i_density 是进入车道 i 中的车辆数除以该车道的总容量
• lane_i_queue 是进入车道 i 中排队（速度低于 0.1 m/s）的车辆数除以该车道的总容量

您可以定义自己的观测，方法是实现一个继承自 ObservationFunction 的类，并将其传递给环境构造函数。

动作

动作空间是离散的。 每隔 delta_time 秒，每个交通信号代理可以选择下一个绿灯相位配置。

例如，在 双路单交叉口 中，有 |A| = 4 个离散动作，对应以下绿灯相位配置：

重要提示：每次相位切换时，下一个相位之前都会有一个持续 yellow_time 秒的黄灯阶段。

奖励

默认的奖励函数是累计车辆延误的变化：

也就是说，奖励是总延误（所有驶入车辆等待时间之和）相对于上一时间步的变化量。

您可以通过在 SumoEnvironment 构造函数中使用参数 reward_fn 来选择不同的奖励函数（参见 TrafficSignal 中实现的奖励函数）。

也可以实现您自己的奖励函数：

def my_reward_fn(traffic_signal):
    return traffic_signal.get_average_speed()

env = SumoEnvironment(..., reward_fn=my_reward_fn)

API（Gymnasium 和 PettingZoo）

Gymnasium 单智能体 API

如果您的网络中只有一盏交通信号灯，那么您可以实例化一个标准的 Gymnasium 环境（参见 Gymnasium API)：

import gymnasium as gym
import sumo_rl
env = gym.make('sumo-rl-v0',
                net_file='path_to_your_network.net.xml',
                route_file='path_to_your_routefile.rou.xml',
                out_csv_name='path_to_output.csv',
                use_gui=True,
                num_seconds=100000)
obs, info = env.reset()
done = False
while not done:
    next_obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
    done = terminated or truncated

PettingZoo 多智能体 API

对于多智能体环境，您可以使用 PettingZoo API（参见 Petting Zoo API）：

import sumo_rl
env = sumo_rl.parallel_env(net_file='nets/RESCO/grid4x4/grid4x4.net.xml',
                  route_file='nets/RESCO/grid4x4/grid4x4_1.rou.xml',
                  use_gui=True,
                  num_seconds=3600)
observations = env.reset()
while env.agents:
    actions = {agent: env.action_space(agent).sample() for agent in env.agents}  # 这里可以插入您的策略
    observations, rewards, terminations, truncations, infos = env.step(actions)

RESCO 基准测试

在 nets/RESCO 文件夹中，您可以找到来自 RESCO（交通信号控制强化学习基准测试）的网络和路由文件。RESCO 是基于 SUMO-RL 构建的。有关结果，请参阅他们的 论文。

实验

请查看 experiments，了解如何实例化环境并训练您的强化学习智能体的示例。

在单向单交叉路口使用 Q-learning：

python experiments/ql_single-intersection.py

在 4×4 网格中使用 RLlib PPO 多智能体：

python experiments/ppo_4x4grid.py

在双向单交叉路口使用 stable-baselines3 DQN：

注意：您需要使用 pip install "stable_baselines3[extra]>=2.0.0a9" 安装 stable-baselines3，以实现与 Gymnasium 的兼容性。

python experiments/dqn_2way-single-intersection.py

绘制结果：

python outputs/plot.py -f outputs/4x4grid/ppo_conn0_ep2

引用

如果您在研究中使用了本仓库，请引用：

@misc{sumorl,
    author = {Lucas N. Alegre},
    title = {{SUMO-RL}},
    year = {2019},
    publisher = {GitHub},
    journal = {GitHub repository},
    howpublished = {\url{https://github.com/LucasAlegre/sumo-rl}},
}

使用 SUMO-RL 的出版物列表（请提交拉取请求以添加缺失条目）：

• 量化基于强化学习的交通信号控制中非平稳性的影响（Alegre 等，2021）
• 用于多视角强化学习的信息论状态空间模型（Hwang 等，2023）
• 面向自动驾驶车辆的城市级基于 TD 学习的智能交通信号控制：使用 SUMO 进行性能评估（Reza 等，2023）
• 处理自适应系统中的不确定性：基于本体的强化学习模型（Ghanadbashi 等，2023）
• 用于交通信号控制的多智能体强化学习：基于 k 最近邻的方法（Almeida 等，2022）
• 从局部到全局：基于课程学习的强化学习交通信号控制方法（Zheng 等，2022）
• 海报：通过多模态强化学习实现可靠的匝道汇入（Bagwe 等，2022）
• 利用本体指导强化学习智能体应对未见情境（Ghanadbashi & Golpayegani，2022）
• 信息向上、建议向下：用于交通信号控制的分层强化学习（Antes 等，2022）
• 智能交通信号控制算法比较研究（Chaudhuri 等，2022）
• 基于本体的智能交通信号控制模型（Ghanadbashi & Golpayegani，2021）
• 交通信号控制强化学习基准测试（Ault & Sharon，2021）
• EcoLight：用于符合人体工学的交通信号控制的深度强化学习奖励塑造（Agand 等，2021）

SUMO-RL 快速上手指南

SUMO-RL 是一个用于交通信号控制强化学习（RL）的简洁接口，基于 SUMO 仿真器构建。它支持单智能体和多智能体 RL，并兼容 gymnasium、stable-baselines3 和 RLlib 等主流库。

1. 环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu/Debian)
• Python: 3.8+
• SUMO: 交通仿真软件

前置依赖

在安装 Python 包之前，必须先安装 SUMO 及其工具集。

安装 SUMO (Ubuntu/Debian):

sudo add-apt-repository ppa:sumo/stable
sudo apt-get update
sudo apt-get install sumo sumo-tools sumo-doc

配置环境变量: 设置 SUMO_HOME 变量（默认安装路径为 /usr/share/sumo）：

echo 'export SUMO_HOME="/usr/share/sumo"' >> ~/.bashrc
source ~/.bashrc

可选性能优化: 若需大幅提升性能（约 8 倍），可启用 Libsumo。注意：启用后将无法使用图形界面 (sumo-gui) 或并行运行多个仿真。

export LIBSUMO_AS_TRACI=1

2. 安装步骤

方式一：通过 Pip 安装（稳定版）

pip install sumo-rl

国内加速建议：如遇下载缓慢，可使用清华源： pip install sumo-rl -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装（最新版）

git clone https://github.com/LucasAlegre/sumo-rl
cd sumo-rl
pip install -e .

3. 基本使用

SUMO-RL 提供两种主要 API：Gymnasium（适用于单路口/单智能体）和 PettingZoo（适用于多路口/多智能体）。

场景 A：单智能体环境 (Gymnasium API)

适用于只有一个交通信号灯的路网。

import gymnasium as gym
import sumo_rl

# 创建环境
env = gym.make('sumo-rl-v0',
                net_file='path_to_your_network.net.xml',      # 路网文件
                route_file='path_to_your_routefile.rou.xml',  # 交通流文件
                out_csv_name='path_to_output.csv',            # 输出结果路径
                use_gui=True,                                 # 是否开启图形界面
                num_seconds=100000)                           # 仿真时长

# 重置环境
obs, info = env.reset()

done = False
while not done:
    # 采样随机动作（实际使用时替换为你的策略）
    action = env.action_space.sample()
    
    # 执行一步
    next_obs, reward, terminated, truncated, info = env.step(action)
    
    done = terminated or truncated

env.close()

场景 B：多智能体环境 (PettingZoo API)

适用于包含多个交通信号灯的复杂路网。

import sumo_rl

# 创建并行多智能体环境
env = sumo_rl.parallel_env(net_file='nets/RESCO/grid4x4/grid4x4.net.xml',
                  route_file='nets/RESCO/grid4x4/grid4x4_1.rou.xml',
                  use_gui=True,
                  num_seconds=3600)

# 重置环境，获取初始观测
observations = env.reset()

# 仿真循环
while env.agents:
    # 为每个智能体生成动作 (此处为随机策略)
    actions = {agent: env.action_space(agent).sample() for agent in env.agents}
    
    # 执行一步
    observations, rewards, terminations, truncations, infos = env.step(actions)

env.close()

关键概念说明

• 观测 (Observation): 默认包含当前相位独热编码、最小绿灯时间标志、各车道密度及排队长度。
• 动作 (Action): 离散空间，代表下一个绿灯相位配置。每次切换相位前会自动插入黄灯时间。
• 奖励 (Reward): 默认为累积车辆延误的变化量（即总等待时间的减少量）。可通过 reward_fn 参数自定义。