CityFlow

.. image:: https://readthedocs.org/projects/cityflow/badge/?version=latest :target: https://cityflow.readthedocs.io/en/latest/?badge=latest :alt: 文档状态

.. image:: https://dev.azure.com/CityFlow/CityFlow/_apis/build/status/cityflow-project.CityFlow?branchName=master :target: https://dev.azure.com/CityFlow/CityFlow/_build/latest?definitionId=2&branchName=master :alt: 构建状态

CityFlow 是一个用于大规模城市交通场景的多智能体强化学习环境。

来看看它的这些特性吧！

• 一款微观交通仿真器，能够模拟每一辆车的行为，提供最高级别的交通演化细节。
• 支持灵活的道路网络和交通流定义。
• 提供友好的 Python 接口，便于进行强化学习研究。
• 速度快！ 精心设计的数据结构和仿真算法，并采用多线程技术。能够模拟整个城市的交通状况。请参阅与 SUMO 的性能对比 [#sumo]_。

.. figure:: https://user-images.githubusercontent.com/44251346/54403537-5ce16b00-470b-11e9-928d-76c8ba0ab463.png :align: center :alt: 与 SUMO 的性能对比

CityFlow 在不同线程数（1、2、4、8）下与 SUMO 的性能对比。从小型的 1x1 格网路网到城市级的 30x30 路网。当您需要通过 Python API 与仿真器交互时，速度会更快。

屏幕演示

.. figure:: https://user-images.githubusercontent.com/44251346/62375390-c9e98600-b570-11e9-8808-e13dbe776f1e.gif :align: center :alt: 演示

使用 CityFlow 的特色研究与项目

• PressLight：学习最大压力控制以协调主干道网络中的交通信号（KDD 2019） <http://personal.psu.edu/hzw77/publications/presslight-kdd19.pdf>_
• CoLight：学习网络级协作以进行交通信号控制 <https://arxiv.org/abs/1905.05717>_
• 交通信号控制基准测试 <https://traffic-signal-control.github.io/>_
• TSCC2050：天壤智能推出的交通信号控制游戏（中文） <http://game.tscc2050.com/>_ [#tianrang]_

链接

• WWW 2019 演示论文 <https://arxiv.org/abs/1905.05217>_
• 主页 <http://cityflow-project.github.io/>_
• 文档与快速入门 <https://cityflow.readthedocs.io/en/latest/>_
• Docker <https://hub.docker.com/r/cityflowproject/cityflow>_

.. [#sumo] SUMO 主页 <https://sumo.dlr.de/index.html>_ .. [#tianrang] 天壤智能主页 <https://www.tianrang.com/>_

CityFlow 快速上手指南

CityFlow 是一个专为大规模城市交通场景设计的多智能体强化学习环境。它提供微观交通仿真，支持灵活的路网与车流定义，并拥有高性能的多线程仿真引擎，非常适合用于交通信号控制等强化学习研究。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：推荐 Linux (Ubuntu 16.04/18.04/20.04) 或 macOS。Windows 用户建议使用 WSL2 或 Docker。
• Python 版本：Python 3.6 - 3.9
• 前置依赖：
  • pip (Python 包管理工具)
  • cmake (构建工具)
  • g++ (C++ 编译器)

安装基础依赖示例 (Ubuntu):

sudo apt-get update
sudo apt-get install -y python3-dev python3-pip cmake g++ libboost-all-dev

安装步骤

推荐使用 pip 进行安装。为了获得更快的下载速度，国内开发者可以使用清华或阿里镜像源。

方式一：使用 PyPI 安装（推荐）

# 使用清华镜像源加速安装
pip install cityflow -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 Docker（最简便，避免环境冲突）

如果您希望隔离环境或直接运行，可以使用官方 Docker 镜像：

docker pull cityflowproject/cityflow

基本使用

CityFlow 的核心是通过 Python 接口加载配置文件并运行仿真。以下是一个最小化的使用示例。

1. 准备配置文件

CityFlow 需要两个主要的 JSON 配置文件：路网文件 (roadnet.json) 和车流文件 (flow.json)。您可以从官方 GitHub 仓库的 examples 目录获取示例文件。

假设您已准备好 roadnet_1_1.json 和 flow_1_1.json。

2. 编写仿真脚本

创建一个名为 run_simulation.py 的文件，写入以下代码：

import cityflow

# 初始化仿真引擎
engine = cityflow.Engine(
    path_to_conf_file="config_1_1.json",  # 主配置文件路径
    thread_num=4                          # 开启多线程加速
)

# 运行仿真
for i in range(1000):
    engine.next_step()
    
    # 在此处获取状态、执行动作（强化学习循环）
    # vehicles = engine.get_vehicle_ids()
    # ...

# 结束仿真
engine.end()

3. 创建主配置文件

在同一目录下创建 config_1_1.json，内容如下：

{
    "dir": "./",
    "roadnetFile": "roadnet_1_1.json",
    "flowFile": "flow_1_1.json",
    "rlTrafficLight": true,
    "saveReplay": false,
    "roadnetLogFile": "frontend/roadnet_1_1.json",
    "replayLogFile": "frontend/replay_1_1.txt"
}

4. 运行

在终端执行：

python run_simulation.py

如果未报错且程序正常结束，说明 CityFlow 已成功运行。您可以进一步结合 Reinforcement Learning 框架（如 TensorFlow 或 PyTorch）开发自己的交通信号控制算法。