Transport Modelling Playbook

Use transport_modelling when you need a district-scale traffic microsimulation: build a base model of an area, calibrate it against observations, test a road scheme, and hand over a 3D replay plus a validation report. Everything happens inside the one tool — network, demand, signals, calibration and the observed journey times it calibrates against.

When To Reach For It

• A calibrated base model of a town centre, corridor or district (up to 5 km radius)
• Road closures, lane cuts, speed limits, one-way schemes and timed works on named streets
• Testing a signal plan at a junction, or loading a client's real plans
• Fitting the model to a client's traffic counts and reporting GEH
• A 3D baseline-versus-scenario replay and a report structured after TAG M3.1 / TfL / FHWA guidance

Do not use it for city-wide strategic assignment or freight matrices. Do not call google_maps to get travel times for it: the tool fetches observed typical journey times itself.

What A Run Does

1. Network from OpenStreetMap: driving side and lane defaults by country, sidewalks, crossings, bike access. The result reports how much of the network rests on tagged lane counts versus road-class defaults and lists roads to check by eye (with Street View links for a person to open).
2. Demand from residents (ONS Census 2021 in England and Wales, WorldPop 100 m elsewhere) × cited regional trip rates → cars, vans, HGVs, cyclists and pedestrians by zone, with boundary gateways for external and through traffic. Buses come from OSM route relations, or a GTFS zip via gtfs_file.
3. Signals where OSM maps them, timed by junction type and demand inside national rules, running actuated. Every other junction gives way. signal_plans replace generated plans.
4. Calibration: a saturation-flow bench sets driver headway to the regional capacity target; then demand is scaled until corridor journey times match observed typical times. journey_times (the user's surveys) override those. traffic_counts fit demand to counts instead and report GEH, leaving journey times as independent validation.
5. Scenario when interventions are given. None = base model only.

Outputs land in the session out/ folder: dash_*.html (3D replay), *_report.html and *_report.md (method, assumptions register, validation tables, sources), the manifest JSON, a reproducible SUMO bundle, and raw tripinfo / edgedata / stats XML.

Recipe

1. Confirm the location, radius (≤ 5 km) and the period (am_peak, inter_peak, pm_peak, off_peak). Coordinates or a place name both work: place: "Bedford town centre, UK" is looked up inside the tool, and the result's resolved_place says which place was used. Reuse its coordinates on later calls so the cached model is found again.
2. action: list_roads (optional road_query) for exact street names, lanes, speed and directions. Use names verbatim; a miss returns close matches — never invent a name.
3. If the user has real signal timings, action: list_junctions first: it lists each signalised junction with what every green stage serves. A signal_plans entry gives one green time per stage in that order.
4. action: run with region_label, place or center_lat / center_lon, radius_m, country_code, period, simulation_minutes (20–120; start with 30 — departures stop 10 minutes before the end), and any interventions, traffic_counts, signal_plans, journey_times. A calibrated run takes roughly 3–12 minutes; re-runs on the same area reuse the network, the observations and the calibration.
5. Report honestly from the result. Quote validation.statement, say which corridors passed, and name the roads_to_review.

When John Uploads His Own Data

The tool reads survey files itself — pass the uploaded filename, never transcribe rows into the call.

Parameter	What it takes
counts_file	CSV or Excel. One row per site, or 15-minute / hourly bins (reduced to the hour starting at the period; several survey days are averaged). A total column, or vehicle-class columns (cars, motorcycles, LGV, OGV1/OGV2, PSV, pedal cycles). Sites by latitude/longitude, OSGB easting/northing, or road name; direction as NB / Northbound / a bearing. Title rows above the header are fine.
signal_plans_file	CSV or Excel with junction, stage, green_s, optional cycle_s, offset_s, fixed_time. Junction = id or road names from list_junctions.
journey_times_file	CSV or Excel with from_lat, from_lon, to_lat, to_lon and seconds or minutes; an optional start-time column keeps the runs inside the modelled hour.
gtfs_file	GTFS zip for timetabled buses.

1. action: check_data with the files. It answers in seconds once the network is cached and returns, per file, what matched and what did not — with reasons: a two-way road with no direction, a site outside the model area, a junction whose stage count differs from the file.
2. Take every unmatched row back to John. Do not guess a direction or pick a nearby road for him.
3. action: run with the same files. Matched rows are used; unmatched rows are skipped and listed under user_data and in the report.

Classified counts are fitted and validated as cars + vans + HGVs (buses run from the timetable, pedal cycles have their own demand) and set the van / HGV share. Plain totals are compared with buses included. Signal timings that arrive as a PDF timing sheet or LinSig output have to be read with the PDF tools first; confirm the stage mapping with John before writing a plan.

Uncertainty: Monte Carlo

Ask how robust a result is, or describe an uncertain future, and Alfrada re-runs the calibrated model under sampled futures with monte_carlo. It reports P10 / P50 / P90 for the KPIs and corridor journey times, the probability the scenario is worse than the base, and which uncertain input drives the answer.

Alfrada builds the distributions from what John says and tells him what it assumed:

John says	Becomes
"Traffic will grow 5–20% by 2031, probably about 10%"	motor_demand, triangular, low 5, high 20, most likely 10
"The development adds 10–30% more cars"	car_demand, uniform 10–30, applies_to: scenario
"There's a 30% chance the depot moves here and HGVs rise 40%"	hgv_demand, discrete, values 0 / 40, weights 0.7 / 0.3
"What about wet winter mornings?"	driver_speed down a few per cent, driver_headway up

• Each sample draws one value per variable and its own random seed. Base and scenario share every draw, so the difference between them is the scheme, not chance.
• Samples run several at a time inside the same background job. The sidecar caps how many simulations run at once across all jobs (by CPU cores and memory; TRANSPORT_MAX_PARALLEL_SIMS overrides) and queues the rest.
• 20–30 samples for a first look, 100+ before quoting percentiles. Each sample is one more simulation per side.
• The network, signal plans, buses, cyclists, pedestrians and routing rules are held fixed, so the spread understates total uncertainty. The distributions are judgements, not measurements, and the report says so.
• Every sample is written to *_monte_carlo_samples.csv for histograms or a tornado chart.

Say This Out Loud

• Journey times alone do not prove traffic volumes: the same speed occurs at two different flows. Without counts the demand is speed-consistent, not validated.
• Generated signal plans are typical for the junction type, not the plans on street.
• Through traffic is a prior until counts arrive.
• No highway authority audits SUMO models today; VMAP is TfL's Vissim audit process. Use the report for screening and option testing, and agree software with the authority before a statutory submission.

Then ask John for what tightens it: traffic counts, real signal plans, journey-time surveys.

Time windows and one-way schemes

• Every intervention accepts start_minute / end_minute. Without them it is a planned change: the network is rebuilt and every driver routes around it. With a window it is applied live at that minute through SUMO rerouters and variable speed signs, so drivers already en route divert on the fly.
• one_way keeps the named direction (northbound / southbound / eastbound / westbound) open and closes the traffic lanes running against it. Closures shut traffic lanes only; footways stay open.

Copy-Ready Prompts

Base model with validation report

Build an AM-peak traffic model for a 1.5 km radius around 52.2030, 0.1235 labelled
"Cambridge centre" (GB). No scheme yet — I want the calibrated base, the validation
tables and the list of roads where lane counts are assumed.

Lane reduction against the calibrated base

On the Cambridge centre model, reduce "Gonville Place" by one lane in the AM peak.
Compare base and scenario: network KPIs, KPIs by mode, and the corridor journey times.

Fit to my counts

Same area, PM peak. Counts (veh/h): East Road northbound 550, southbound 500;
Gonville Place eastbound 600, westbound 650; Trumpington Road northbound 700.
Fit the model to these and show me the GEH table.

Work from uploaded surveys

I've uploaded atc_counts.xlsx, signal_timings.csv and jt_survey.csv for the Cambridge
centre model (AM peak). Check what matches first and tell me what you need from me,
then fit the model to the counts and show the GEH and journey-time tables.

How robust is the scheme?

On the Cambridge centre model, reduce "Gonville Place" by one lane in the AM peak.
Traffic could grow anywhere from 5 to 20% by 2031, most likely about 10%, and there's
roughly a one-in-three chance the new depot brings 40% more HGVs onto this corridor.
Run 30 samples and tell me the range of delay and how likely the scheme is to make
things worse.

Load a real signal plan

List the signalised junctions on Hills Road. Then run the AM model with the
Hills Road / Lensfield Road junction on a fixed 88 s cycle, greens 25, 12, 20, 12.

Timed closure

List the roads within 1.5 km of 52.205, 0.119, then close "Mill Road" from minute 5 to
minute 12 of a 30-minute run and make "Hills Road" one-way northbound. Chart the
travel-time distribution base vs scenario from the tripinfo files.

Operating Notes

• Prefer smaller radii on first runs; OSM download, network build and calibration dominate cold-start time.
• seeds runs each side several times with different random seeds and averages the KPIs (TfL asks for twenty on an audited model; start with 1–3).
• demand_mode: synthetic keeps the old quick illustrative run (random car trips, no calibration).
• GCC trip rates and signal rules are low-confidence assumptions: no household travel survey results are public there. Say so, and ask for local rates or counts.
• Background jobs keep the chat usable — cancel with background_job if the user abandons the run.
• Attribution (OSM ODbL, SUMO, OpenFreeMap/OpenMapTiles) stays visible on the dashboard; do not strip it.