Real-Time Joint Estimation of Queue Dynamics and Arrival Time via a IDM-Integrated Unscented Kalman Filter

hEART 2026 Reproducible Research Prize Submission — SRL 5

Qiongdan Hu, Chaopeng Tan, Menglin Yang, Meng Wang
Chair of Traffic Process Automation, Technische Universität Dresden

---

Abstract

This repository provides the complete, executable code and data for the paper accepted at hEART 2026. The paper proposes a real-time data fusion framework that estimates the queue tail position and predicts the Time of Arrival (ToA) for Connected and Automated Vehicles (CAVs) approaching signalized intersections. A macroscopic LWR shockwave model establishes the initial queue tail; an IDM-integrated Unscented Kalman Filter (UKF) then continuously tracks the high-fidelity microscopic queue tail and shockwave speed using real-time onboard ranging measurements. During complex multi-cycle secondary queuing, the framework reduces the ToA prediction error to 5.44 s, yielding a 57% improvement over pure macroscopic estimations and a 41% reduction compared to naive kinematic baselines.

Reproducibility statement: The code and data associated with this work are available at this repository. The repository is prepared at SRL 5.

---

Requirements

Python Environment

Package	Version	Purpose
Python	3.13.x	Interpreter
numpy	2.2.2	Array operations
pandas	2.2.3	CSV I/O and DataFrame operations
matplotlib	3.10.0	Publication-quality figures
filterpy	1.4.5	UKF implementation
scipy	1.15.2	Cholesky / eigenvalue decomposition
PyYAML	6.0.2	Configuration file parsing

Install all Python dependencies:

pip install -r requirements.txt

SUMO (Eclipse Simulation of Urban MObility)

Item	Requirement
Version	>= 1.18.0 (tested on 1.18.0)
Download	https://sumo.dlr.de/docs/Downloads.php
Environment	SUMO_HOME must be set

Windows:

setx SUMO_HOME "C:\Program Files (x86)\Eclipse\Sumo"

Linux / macOS:

export SUMO_HOME=/usr/share/sumo        # Linux
export SUMO_HOME=/opt/homebrew/opt/sumo/share/sumo  # macOS (Homebrew)

Note: SUMO is required only for Stages 01 and 02 (network generation and simulation). All downstream analysis and figure generation can be run with python main.py --skip-sim if the CSV files are already present.

---

Quick Start

Step 0 — Create the Python Environment (first time only)

Windows:

cd Simluation
setup_env.bat

Linux / macOS:

cd Simluation/
bash setup_env.sh

The script locates Python 3.13, creates a virtual environment in .venv/, and installs all pinned packages from requirements.txt. It is safe to re-run — it skips creation if .venv/ already exists.

Step 1 — Reproduce All Results

Activate the environment and run the pipeline:

Windows:

.venv\Scripts\activate
python main.py

Linux / macOS:

source .venv/bin/activate
python main.py

No SUMO required. Pre-built trajectory and signal CSV files are included in data/outputs/. If SUMO_HOME is not set, the pipeline automatically skips Stages 01–02 and runs the analysis directly.

Manual flag (optional)

To explicitly skip SUMO stages when CSVs are already present:

python main.py --skip-sim

---

Repository Structure

Simluation/
│
├── main.py                        # One-click entry point (runs all stages)
├── config.yaml                    # Global parameter configuration (all paper values)
├── requirements.txt               # Exact Python dependency versions
├── LICENSE                        # MIT License
├── README.md                      # This file
│
├── 01_generate_scenario.py        # Stage 1: SUMO XML generation
├── 02_run_simulation.py           # Stage 2: SUMO simulation + CSV export
├── 03_core_algorithm.py           # Stage 3: UKF framework demo (Fig. 3 & 4)
├── 04_batch_evaluation.py         # Stage 4: 19-vehicle batch (Table 1)
├── 05_visualize_results.py        # Standalone: regenerate figures from CSVs
│
├── src/
│   ├── __init__.py
│   └── framework.py               # Core algorithm (LWR + UKF + ToA math)
│
├── data/
│   ├── inputs/                    # SUMO XML files (generated by Stage 01)
│   │   ├── cross.nod.xml
│   │   ├── cross.edg.xml
│   │   ├── cross.net.xml
│   │   ├── cross.rou.xml
│   │   ├── cross.add.xml
│   │   └── cross.sumocfg
│   └── outputs/                   # Trajectory and signal CSVs (generated by Stage 02)
│       ├── vehicle_trajectory.csv
│       ├── tl_timeline.csv
│       ├── tl_config.csv
│       ├── sensor_speeds.csv
│       └── batch_mae_results.csv  # Per-vehicle MAE (generated by Stage 04)
│
└── results/
    └── figures/                   # Publication figures (generated by Stages 03–05)
        ├── figure3_spatiotemporal_veh16.png
        ├── figure4a_toa_convergence_veh3.png
        └── figure4b_toa_convergence_veh16.png

---

Pipeline Stages

Script	Description	Requires SUMO	Output
01_generate_scenario.py	Generate SUMO network, routes, signal config	✓	data/inputs/*.xml
02_run_simulation.py	Run headless SUMO simulation	✓	data/outputs/*.csv
03_core_algorithm.py	UKF framework for veh_3 and veh_16	✗	results/figures/figure3_*.png, figure4*.png
04_batch_evaluation.py	19-vehicle batch evaluation	✗	Console Table 1, batch_mae_results.csv
05_visualize_results.py	Standalone figure regeneration	✗	results/figures/

---

Figure Mapping

Paper Figure	Output File	Description
Figure 3	figure3_spatiotemporal_veh16.png	Spatiotemporal queue evolution: vehicle trajectories (speed-coloured), ground truth queue tail, LWR estimate, UKF mean ± 3σ bound
Figure 4a	figure4a_toa_convergence_veh3.png	ToA convergence: early-arriving vehicle (veh_3) under single-cycle queue
Figure 4b	figure4b_toa_convergence_veh16.png	ToA convergence: secondary-queue vehicle (veh_16) under multi-cycle regime — primary result demonstrating UKF advantage
Table 1	Console output (Stage 04) + batch_mae_results.csv	MAE evaluation across N=19 independent runs

---

Expected Results

After running python main.py, the console output of Stage 04 should display:

TABLE 1 — ToA Prediction MAE (s)   [Valid N = ...]
=================================================================
  Prediction Model                            MAE (s)
  --------------------------------------------------
  Baseline 1: Naive (MA + Const. Decel)        15.54
  Baseline 2: Pure LWR + Signal                17.80
  Proposed:   UKF + Physical Tracking          14.27
  --------------------------------------------------
  Proposed beats Naive :  .../...  (79%)
  Proposed beats LWR   :  .../...  (79%)
=================================================================

Individual vehicle results from Paper Table 1:

Vehicle	Naive (B1)	LWR (B2)	Proposed
veh_3 (single-cycle)	1.91 s	4.87 s	1.03 s
veh_16 (multi-cycle)	9.24 s	12.65 s	5.44 s
Average (N=19)	15.54 s	17.80 s	14.27 s

---

Experimental Setup (Paper Section 5)

Parameter	Value	Paper Reference
Simulation timestep	1.0 s	Section 5
Free-flow speed	15.0 m/s	Section 5
Jam spacing	7.5 m	Section 5
Queue speed threshold	2.0 m/s	Section 5
Signal startup lost time	3.5 s	Section 5
Position noise σ_base	0.5 m	Section 5
Position noise α	0.02 m/m	Section 5
Speed noise σ_v	0.2 m/s	Section 5
UKF α	0.3	Section 5
UKF β	2	Section 5
UKF κ	0	Section 5
Random seed	42	(reproducibility)
SUMO random seed	42	(reproducibility)

All parameters are centralized in config.yaml. Do not modify them unless you intend to deviate from the published experimental conditions.

---

Determinism and Reproducibility

This repository implements three layers of determinism:

1. Python RNG — random.seed(42) and numpy.random.seed(42) are set at the entry point of every script.
2. SUMO engine — The simulation is launched with --seed 42, fixing SUMO's internal random number generator.
3. Sensor noise — np.random.RandomState(42) is used in get_simulated_sensor_data() for per-call isolation.

These measures ensure that results are bit-for-bit identical across different hardware and operating systems.

---

License

This project is released under the MIT License. See LICENSE for full details.

---

Citation

If you use this code or dataset, please cite:

@inproceedings{hu2026ukf,
  title     = {Real-Time Joint Estimation of Queue Dynamics and Arrival Time
               via a IDM-Integrated Unscented Kalman Filter},
  author    = {Hu, Qiongdan and Tan, Chaopeng and Yang, Menglin and Wang, Meng},
  booktitle = {hEART 2026 --- 14th Symposium of the European Association
               for Research in Transportation},
  year      = {2026},
  address   = {Paris, France}
}

---

Acknowledgements

This research is part of the AgiMo project, funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) — TRR: 408/1 2025 — Project number: 531327426.