A traffic digital twin of Jeddah, built in the open

The films

Each film is rendered from real simulation outputs (edge bins, vehicle trajectories, event and strategist reports), one per simulation mode. Previews are 6-second GIFs; the full 1080p MP4s are attached to the v0.1.0 release. Scenarios are fictional.

city-24h

The weekday baseline as a 24-hour time-lapse across the whole city (Tier A, mesoscopic).

40 s · city-24h.mp4 (85 MB)

tahlia-street

Street level along Tahlia Street in the morning peak, vehicles coloured by speed (Tier B).

30 s · tahlia-street.mp4 (26 MB)

incident

A crash on the corridor into Madinah Road, split-screen against its baseline.

42 s · incident.mp4 (40 MB)

events

Heavy rain, a storm flood with closed flood sites, and a motorcade.

40 s · events.mp4 (45 MB)

strategist

An ambulance at 08:30: no strategy, then the top 3 ranked options with their reasons.

47 s · strategist.mp4 (35 MB)

evacuation

Phased release with contraflow from the Obhur Creek mouth near the Jeddah Tower site (fictional scenario).

52 s · evacuation.mp4 (35 MB)

policy-lab

Remote work, staggered schools and a cordon charge in difference mode.

45 s · policy-lab.mp4 (48 MB)

loop

The recommended Loop tunnel C1 against the weekday baseline.

46 s · loop.mp4 (94 MB)

showreel

All eight films as 20-second excerpts with title cards.

2 min 51 s · showreel.mp4 (192 MB)

Where would a Loop tunnel help Jeddah most?

The model sited candidate Boring-Company-style Loop corridors, simulated each on the city model, and swept operating policies under measured (Las Vegas) capacity.

1. Corridor C1, Al-Salamah to King Abdulaziz University (17.9 km, 8 stations) gives the most relief per dollar among the candidates.
2. About 63,000 vehicle-hours of road delay saved per day (mean of two seeds; noise band 23,000 to 103,000), AM-peak road delay -2.9 %.
3. 28,820 passengers per day as a shuttle capped at measured capacity, for an estimated USD 268 to 714 M capex; 70 % of riders would still be slower than by car under measured station waits.

10 % sample, seed 1 and 2, gridlock-affected baseline; shift share is an assumption (no mode-choice model). Full method and caveats: docs/loop.md.

Policy lab results

Changes against the matching baseline day, same seed, 10 % population sample on the city model (Tier A, mesoscopic). Run-to-run noise is about ±2 % on delay and VHT; a negative change (green) is an improvement.

Colour marks changes larger than the ±2 % noise. Synthetic demand, uncalibrated; the baseline network teleports about half of all vehicles (missing lane counts in OSM), so read these as comparisons between policies, not forecasts. Details: docs/policies.md.

Architecture

One engine at two resolutions. Tier A runs all of Jeddah mesoscopically for policy questions; Tier B cuts a 3-25 km² focus window out of it and runs every vehicle for events and the strategist. Layers only talk through run directories.

Policies change the population or the network before a run; events act through TraCI during a run. The AI recommends; a human approves high-impact actions. Full diagram: docs/architecture.md.

Quickstart

macOS (Apple silicon) or Linux with uv, Node 22+, make and curl. The demo window runs on any recent laptop; the city adds a 243 MB download and peaks at about 3 GB of RAM (measured on an 18 GB M3 Pro).

git clone https://github.com/alturkestani/TrafficTwin.git TrafficTwin && cd TrafficTwin
make demo CITY=0     # demo window only: setup + demo runs, then the viewer on http://localhost:5173
make demo            # adds the Jeddah city network and a one-hour city run (about 7 min first time)
make test            # ruff, pytest on the demo window, web typecheck

Everything else (24 h city baseline, policies, events, strategist, evacuation, Loop, calibration, films) is in the README.