Phantom Jam Lab
A traffic simulator for watching jams form on a ring road with no crash, lane closure or bottleneck to
cause them. It comes with a dimensional analysis that maps when traffic stays smooth and when it jams,
and a narrative report that tells the whole story.
Read the report
The Jam Nobody Started: The Ideas Behind Phantom Jam Lab
The report has animated replays from the simulator, eleven figures and a contents panel you can
collapse. It covers:
- the 2008 ring-road experiment and the car-following models behind the lab;
- the two numbers that decide whether a road jams;
- the regime map, and how many drivers who leave room it takes to keep a road smooth;
- a scale-model test of the analysis.
Its source text, figures and build scripts are in report/.
Other editions
What is here
| Folder | Contents |
|---|
src/ | the traffic model (engine.js) and the app page (app.html) |
test/ | tests of the traffic model |
analysis/ | the dimensional analysis, stability theory and simulation sweeps; results in analysis/results/ |
report/ | the narrative report: source text, fact and citation checks, figures, filmed media, page builder |
.claude/skills/documentary-report/ | a Claude Code skill that rebuilds or extends the report |
The model in brief
Each car is one of two kinds of driver.
- Tailgaters follow the Human Driver Model: the Intelligent Driver Model with a reaction delay, a
forward guess of the gap, and random wobble in speed.
- Drivers who leave room match the smoothed speed of the traffic ahead and keep a wider gap.
The analysis reduces the road to dimensionless groups. Two decide the outcome:
- Λ (load): how full the road is, compared with the space each car wants at its preferred speed.
- R: reaction time divided by the chosen time gap.
Run it
You need Node 24. The report steps also need ffmpeg and a Chromium for Playwright
(npx playwright install chromium).
npm install
npm run build # writes the simulator: dist/index.html (standalone) and dist/phantom-jam-lab.html (for claude.ai)
npm test # tests of the traffic model
npm run analysis # reruns the analysis into analysis/results/ (about 2 minutes)
npm run report:check # checks every number in the report against the results, and citations against Crossref
npm run report:media # films the GIFs and stills from the simulator
npm run report:build # writes the report page to report/dist/
npm run report:test-page # checks that every contents link lands on its heading
Open dist/index.html in a browser to run the simulator locally. Every push to main rebuilds it and
deploys it to GitHub Pages (.github/workflows/pages.yml); the claude.ai pages are republished by hand. report/README.md
gives the details of the report pipeline.
Background
The project started from the YouTube short
Why Do Phantom Traffic Jams Happen? and from Sugiyama and
colleagues' 2008 experiment, in which 22 cars on a circular track made a jam out of nothing.
License
MIT. See LICENSE.
