Phantom Traffic Jam Detector

A real-time, interactive demo that detects and prevents phantom traffic jams — the stop-and-go waves that appear on busy highways with no crash, no merge, no bottleneck of any kind. They emerge purely from the way human drivers react to the car in front, and a single tap of the brakes can ripple backward and bring a whole lane to a crawl.

This app simulates a ring of 22 cars, lets you trigger that ripple, watches it form in real time, and shows how a few automated-vehicle (AV) controllers can damp it out before it becomes dangerous.

What you're looking at

Detection — no controller. One brake tap grows into a self-sustaining wave. Cars turn red as their collision risk climbs, and the monitor fires a DANGEROUS COMPRESSION DETECTED alert:

Prevention — turn on the velocity-filter controller for some of the cars (gold halos). The wave collapses, velocities flatten out, and the monitor goes green:

The idea

• Ring road. 22 cars on a 230 m loop follow the Intelligent Driver Model (Treiber, Hennecke & Helbing, 2000) with a 0.5 s human reaction delay. At this density the loop is unstable: tiny disturbances grow instead of fading.

• Detection. Every frame the app computes, from positions and velocities alone:

  • time-to-collision (TTC) with the car ahead,
  • minimum headway (gap to the next car),
  • velocity spread across all cars (how big the wave is), and
  • growth rate sigma — the rate at which small disturbances are amplifying. This is the early-warning signal: it goes positive before any wave is visible.

  These combine into a single composite risk score and a dangerous-compression flag.

• Prevention. A fraction of the cars can be switched to one of two communication-free AV controllers:

  • filter — a 5-second low-pass on the car's own speed, so it refuses to chase every wiggle of the car ahead;
  • reactive — time-to-collision braking plus headway-rate damping.

  Both run through the same [-8, +4] m/s^2 actuator limit, so it's a fair comparison. The filter typically stabilizes the ring at a much lower fraction of automated cars.

Install

Requires Python 3.10+.

pip install -r requirements.txt

Run

python3 app.py

Controls

Key	Action
SPACE	trigger a brake pulse on car 0 (seeds a phantom wave)
C	cycle controller: none -> filter -> reactive
UP/DN	add / remove one automated car
+ / -	simulation speed (1x .. 8x real time)
R	reset the ring (keeps your controller + penetration settings)
ESC	quit

A demo to try

1. Start with 0 automated cars, controller none.
2. Press SPACE. Watch the cars go red and the alert fire.
3. Press C to switch to filter, then tap UP a few times to convert some cars. The wave dies and the panel goes green — usually before you've even converted half the cars.

Project layout

File	Purpose
physics.py	IDM ring simulation + the two AV controllers (stepwise)
risk.py	real-time risk metrics + dangerous-compression detection
app.py	Pygame visualization, plots, controls
make_screenshots.py	regenerates the images in docs/ offscreen

Regenerating the screenshots

The images above are rendered headlessly from the same draw code the live app uses:

python3 make_screenshots.py