Reproducible CAV Platoon Control under Imperfect V2V Communication

This repository provides a SUMO–PyTorch reproduction project for longitudinal control of a six-vehicle platoon: one human-driven leader following an NGSIM I-80 trajectory and five controlled connected and automated vehicles (CAVs). It includes a time-varying SINR communication model, IDM and CACC baselines, physics-guided graph attention (PG-GAT), independent PPO (IPPO), checkpoint screening, and common-condition evaluation.

中文说明：本仓库用于复现“1 辆 NGSIM 轨迹领航车 + 5 辆受控 CAV”的非理想通信车队实验。原始 NGSIM 数据未上传，请按下文从美国交通部公开数据集下载并运行预处理脚本。

Reproducibility scope

The repository contains:

• source code and the exact JSON configurations used by the reproduction;
• the selected PG-GAT-IPPO checkpoints needed for immediate evaluation;
• the 300-episode training log and 15-case checkpoint-screening records;
• fixed-condition IDM, CACC, and PG-GAT-IPPO outputs used for comparison;
• unit tests and a SUMO smoke test.

The original NGSIM files are excluded because they are large and are distributed by the U.S. Department of Transportation. Generated caches, temporary GUI runs, and non-selected intermediate checkpoints are also excluded.

Repository layout

communication/       SINR channel and link-state model
configs/             inherited experiment configurations
controllers/         IDM and CACC baselines
data/                NGSIM trajectory loader
envs/                SUMO/TraCI platoon environment
evaluation/          metrics and plotting
models/              PG-GAT and actor–critic networks
training/            IPPO implementation and training entry point
tests/               core tests and SUMO smoke test
checkpoints/pg_gat_v2/  selected evaluation checkpoints
outputs/             retained training records and fixed-test results

1. Prerequisites

• Windows or Linux
• Python 3.10
• SUMO with sumo, sumo-gui, and TraCI available
• Git

Create an isolated Python environment and install the dependencies:

git clone https://github.com/mayuntian/CAV_Simulation.git
cd CAV_Simulation
python -m venv .venv

PowerShell activation:

.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Linux activation:

source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Verify that SUMO is visible:

sumo --version

If TraCI is supplied by the SUMO installation rather than PyPI, ensure that $SUMO_HOME/tools is on PYTHONPATH.

2. Obtain and preprocess NGSIM I-80 data

Download the official I-80 Emeryville, CA archive from the U.S. DOT NGSIM data portal. The dataset is public and its portal provides the recommended citation and licence information.

Place the 4:00–4:15 p.m. trajectory text file at:

NGSIM-I-80/NGSIM-I-80-vehicle-trajectory-dataset/0400-0415.txt

Then run:

python process_ngsim.py
python inspect_trajectories.py --limit 20

The expected processed file is:

NGSIM-I-80/NGSIM-I-80-vehicle-trajectory-dataset/0400-0415_processed_data.csv

The preprocessing script converts feet to metres, filters passenger vehicles in lanes 2 and 3, applies low-pass smoothing, derives acceleration, and retains continuous 200-step profiles.

3. Validate the installation

After preprocessing the data, run:

python -m unittest discover -v

tests/test_core.py checks the SINR channel, graph fusion, and metrics. tests/test_sumo_smoke.py starts SUMO and advances a short CACC simulation.

4. Reproduce the common-condition comparison

All controllers below use leader trajectory 1506, communication seed 42, the same initial state, and a ten-step metric warm-up.

python run_experiment.py --controller idm --config configs/tuned_v2.json --vehicle-id 1506 --seed 42 --output-name reproduce_idm

python run_experiment.py --controller cacc --config configs/tuned_v2.json --vehicle-id 1506 --seed 42 --output-name reproduce_cacc

python run_experiment.py --controller ippo --config configs/tuned_v2.json --checkpoint checkpoints/pg_gat_v2/best_balanced.pt --vehicle-id 1506 --seed 42 --output-name reproduce_pg_gat

Add --gui to any command to observe the run in SUMO-GUI. Results are written to outputs/<output-name>/ as metrics.json, trajectory.npz, and trajectory.png.

Create a comparison plot:

python compare_results.py outputs/reproduce_idm/metrics.json outputs/reproduce_cacc/metrics.json outputs/reproduce_pg_gat/metrics.json --output outputs/reproduced_comparison.png

The retained fixed-condition reference results are:

Controller	Mean damping	Tail damping	Mean jerk RMS	Mean spacing RMSE	Packet success	Collision / intervention
IDM	0.777	0.722	0.618	1.998	0.522	0 / 0
CACC	0.867	0.742	0.790	0.787	0.524	0 / 0
PG-GAT-IPPO	0.936	0.680	1.633	3.159	0.539	0 / 0

These results show tail-disturbance attenuation potential, not comprehensive superiority: the learned controller has higher platoon-average damping, jerk, and spacing error than CACC in this fixed case.

5. Retrain PG-GAT-IPPO

Run an independent 300-episode experiment:

python -u -m training.train_ippo --config configs/tuned_v2.json --episodes 300 --device cpu --run-name pg_gat_v2_repeat

Do not reuse pg_gat_v2 as the run name unless you intend to overwrite an existing local run. Training updates latest.pt every episode and saves a numbered checkpoint every 25 episodes.

Resume an interrupted run:

python -u -m training.train_ippo --config configs/tuned_v2.json --episodes 300 --device cpu --run-name pg_gat_v2_repeat --resume checkpoints/pg_gat_v2_repeat/latest.pt

6. Screen checkpoints over trajectories and channel seeds

The default v2 validation grid contains five high-disturbance leader profiles and three communication seeds, giving 15 trials per checkpoint:

python -u select_checkpoint.py --config configs/tuned_v2.json --checkpoint-dir checkpoints/pg_gat_v2_repeat

Outputs include:

• best_reward.pt: highest mean validation return;
• best_stability.pt: lowest stability score;
• best_balanced.pt and best.pt: lowest balanced engineering score;
• checkpoint_selection.csv: aggregate checkpoint results;
• checkpoint_trials.csv: all trajectory-by-seed trials.

The current validation set can be overridden:

python select_checkpoint.py --config configs/tuned_v2.json --checkpoint-dir checkpoints/pg_gat_v2_repeat --vehicle-ids 1506,2146,2151 --seeds 42,43,44

7. Ablation experiments

Train each variant using the same budget, leader profiles, and communication seeds:

python -m training.train_ippo --config configs/tuned_v2.json --episodes 300 --fusion-mode uniform --run-name v2_uniform
python -m training.train_ippo --config configs/tuned_v2.json --episodes 300 --fusion-mode no_decoupling --run-name v2_no_decoupling
python -m training.train_ippo --config configs/tuned_v2.json --episodes 300 --fusion-mode local --run-name v2_local

Run select_checkpoint.py separately for every completed variant. A single fixed-trajectory run must not be reported as a multi-condition ablation result.

8. Metric definitions

• damping_ratio: follower acceleration standard deviation divided by leader acceleration standard deviation; values below one indicate attenuation at that follower.
• jerk_rms: root-mean-square acceleration rate, in m/s³.
• spacing_rmse: RMSE from the constant-time-headway target gap, in metres.
• collisions: SUMO collision count.
• safety_interventions: number of deterministic shield takeovers.
• packet_success_rate: usable V2V-link fraction at control instants.

Metrics exclude the first ten simulation steps to reduce initialisation transients.

9. Configuration provenance and limitations

configs/default.json records traceable reproduction assumptions, configs/tuned.json records the first reward calibration, and configs/tuned_v2.json records the final calibration used here. The source paper did not fully specify the CTG parameters, actuator time constant, SINR threshold, reward weights, network widths, or PPO hyperparameters. These values are therefore reproduction assumptions and must not be described as original paper parameters.

The evidence currently covers one single-lane, homogeneous, all-CAV six-vehicle platoon and one 300-episode training seed. The SINR model is control-oriented rather than a complete DSRC or C-V2X protocol-stack implementation.

Licence and data citation

The repository code is released under the MIT Licence; see LICENSE. NGSIM data are not redistributed by this repository. Users must follow the terms and citation guidance on the official U.S. DOT dataset page.

Recommended dataset citation:

U.S. Department of Transportation Federal Highway Administration. (2016). Next Generation Simulation (NGSIM) Vehicle Trajectories and Supporting Data [Dataset]. https://doi.org/10.21949/1504477