# FlowTwin — Project Masterfile *Everything about this project in one place: what it is, why it exists, how every part works, what was measured, how to pitch it, and how to defend it.* Written to be read cold. If you have never seen this project before, start at §1 and keep going — nothing later assumes anything earlier than what you have already read. --- ## Table of contents **Part I — Understanding the project** 1. [The one-paragraph version](#1-the-one-paragraph-version) 2. [The problem, properly explained](#2-the-problem-properly-explained) 3. [Why existing tools do not solve it](#3-why-existing-tools-do-not-solve-it) 4. [The core idea: the decision loop](#4-the-core-idea-the-decision-loop) 5. [A worked example, end to end](#5-a-worked-example-end-to-end) **Part II — How it actually works** 6. [The venue model](#6-the-venue-model) 7. [The simulation engine](#7-the-simulation-engine) 8. [The Crowd State Engine](#8-the-crowd-state-engine) 9. [Prediction](#9-prediction) 10. [The Strategy Engine](#10-the-strategy-engine) 11. [Counterfactual simulation](#11-counterfactual-simulation) 12. [Multi-objective optimisation and the decisiveness verdict](#12-multi-objective-optimisation-and-the-decisiveness-verdict) 13. [Dynamic routing](#13-dynamic-routing) 14. [Perception — the Hugging Face path](#14-perception--the-hugging-face-path) **Part III — The system as software** 15. [Architecture and module map](#15-architecture-and-module-map) 16. [Data flow and real-time transport](#16-data-flow-and-real-time-transport) 17. [The frontend](#17-the-frontend) 18. [Reproducibility and determinism](#18-reproducibility-and-determinism) 19. [The three venues](#19-the-three-venues) 20. [Testing and verification](#20-testing-and-verification) **Part IV — Evidence** 21. [Measured results](#21-measured-results) 22. [Every defect found and fixed](#22-every-defect-found-and-fixed) 23. [What is deliberately not built](#23-what-is-deliberately-not-built) **Part V — The hackathon** 24. [Mapping to the evaluation criteria](#24-mapping-to-the-evaluation-criteria) 25. [The pitch](#25-the-pitch) 26. [The demo, minute by minute](#26-the-demo-minute-by-minute) 27. [Q&A defence](#27-qa-defence) 28. [Failure drills](#28-failure-drills) --- --- # Part I — Understanding the project ## 1. The one-paragraph version FlowTwin is a **digital twin of a crowd**. You give it a venue — where the gates, walkways, concessions, exits and transport links are, and how much each can handle — plus how many people are coming and when. It then simulates tens of thousands of individual people walking through that venue, second by second. As it runs, it continuously asks three questions: *where is flow about to break down?*, *what could an operator do about it?*, and *which of those options actually works?* To answer the third question it does something unusual: it takes a perfect copy of the crowd's current state, applies each candidate action to its own copy, runs each copy forward four minutes, and **measures** what happened. Then it recommends the option that measured best, and shows you the arithmetic. If no option measurably beats doing nothing, it says so instead of inventing a recommendation. That last sentence is the project in miniature. Most systems in this space are dashboards that tell you what is happening. FlowTwin tells you **what to do**, and it earns the right to say it by simulating the alternatives rather than applying a rule of thumb. --- ## 2. The problem, properly explained ### 2.1 Crowd disasters are not headcount problems The intuitive model of crowd danger is "too many people in the building". That model is wrong, and the wrongness matters. A venue can sell out completely, admit exactly the number of people it is licensed for, and still kill someone — because danger is not a property of the total, it is a property of the **local density and the local flow**. Five people per square metre in one corridor is dangerous whether the rest of the venue is empty or full. Crowd crush injuries happen at pinch points: a gate that closed, a staircase that narrowed, two streams of people trying to cross. So the quantity that matters is not *how many people are here* but *how many people are in this twelve metres of corridor, how fast are they moving, and is that number rising*. ### 2.2 Flow failures are non-local and delayed Here is what makes it genuinely hard. Suppose an exit loses half its capacity. The people at that exit notice immediately. But the *consequence* is not local: - The queue at that exit grows backwards up the corridor. - When it reaches the concourse behind it, that concourse starts filling. - People arriving at the concourse from an entirely different direction — who have nothing to do with that exit — now find their route blocked. - The pressure propagates outward, several minutes after the original event, in places nobody was watching. This is the same mathematics as a traffic jam. The shockwave travels *backwards* through the crowd, slower than the people are walking, and it arrives somewhere unexpected several minutes later. Two consequences follow, and both shaped this project: 1. **You cannot reason about it locally.** A camera on the failing exit tells you about the failing exit. It does not tell you that the west concourse will be dangerous in six minutes. 2. **By the time you can see it, it may be too late to fix by rerouting.** Once a queue of four thousand people exists, it drains at the gate's service rate no matter where you send new arrivals. The people you would need to move are already in the queue and physically cannot move. FlowTwin models both of these explicitly, and — importantly — it *tells you* when you have hit the second one, rather than pretending it can still help. ### 2.3 The operator's actual problem Put yourself in the control room. You have: - Cameras and counters, so you know roughly where people are. - A handful of levers: reroute a percentage of people, hold back departures from a section, open contingency lanes, unlock an emergency gate, change where a shuttle picks up. - Minutes, not hours. - No way to test a decision before making it. That last one is the gap. Every lever has a cost and a side effect. Rerouting 40% of a stand relieves one corridor and loads another. Holding back departures keeps people safe but makes their evening longer, and if you hold too long the release is worse than the original problem. Opening an emergency gate means staffing it, breaking a perimeter, and explaining it afterwards. **An operator has to choose between options whose consequences are separated from the decision by five minutes and half a venue.** That is exactly the kind of decision a simulation should make for you, and nobody does it. ### 2.4 The specific case this project is built around The 2022 Spanish Grand Prix at the Circuit de Barcelona-Catalunya reported a weekend attendance of 277,836, with over 120,000 on race day. Contemporary reporting described severe road and public-transport congestion leaving the circuit, heavy pressure on the Montmeló rail infrastructure, long concession queues and water shortages. Formula 1 publicly told the promoter the fan experience was not acceptable. Nobody was hurt. That is the point: this is the *ordinary* failure mode, the one that happens dozens of times a year at venues that are competently run, and the one that becomes a disaster when the geometry is slightly worse or the crowd is slightly bigger. The same shape of failure covers the applications the problem statement names — railway station design, IPL match egress, airport terminals, Kumbh-scale gatherings. It is one problem, and it is not a motorsport problem. --- ## 3. Why existing tools do not solve it There are three categories of existing tool, and each stops short in a different place. **Crowd monitoring / people counting.** Cameras plus a counting model, feeding a dashboard with occupancy numbers and threshold alarms. This tells an operator *where people are*. It is reactive by construction: the alarm fires when the density is already high, which is after the point at which rerouting could have helped. It also has no notion of *why*, so it cannot suggest an action. **Offline crowd simulation.** Professional pedestrian modelling packages are excellent, and they are used at design time: you model the venue, run scenarios, and change the architecture or the plan. They are not real-time decision tools — a run takes minutes to hours, the model is not connected to live conditions, and the output is a report rather than an instruction. **Traffic-style routing.** Shortest-path or capacity-aware assignment can tell people where to go. But a pre-computed plan is blind to what actually happens on the day, and a purely reactive router chases congestion around the venue, producing oscillation: send people east, the east fills, send them west, the west fills. FlowTwin sits in the hole between these three. It is a **real-time simulation that is fast enough to run its own hypotheticals while an operator waits**. The architectural decision that makes this possible is described in §7.1, and it is the single most important engineering choice in the project. --- ## 4. The core idea: the decision loop ``` ┌─────────────────────────────────────────────────────────┐ │ │ ▼ │ ┌──────┐ ┌─────────┐ ┌──────────┐ ┌──────┐ │ │ SEE │ ───► │ PREDICT │ ───► │ SIMULATE │ ───► │ ACT │ ───┘ └──────┘ └─────────┘ └──────────┘ └──────┘ where are where will it what would apply the people, and break down, each option one that how fast are and when? actually do? measured best they moving? ``` **SEE.** Turn raw positions into the quantities that predict failure: density per short segment of corridor, walking speed against free speed, inflow and outflow per minute, queue length, how fast density is *changing*, and whether two streams are fighting for the same floor. **PREDICT.** Project each of those forward 30, 60, 90 and 120 seconds, and convert that into the only number an operator can act on: **how long until this corridor is critical**. **SIMULATE.** Generate the candidate actions that this venue's topology actually permits, then clone the entire crowd state once per candidate, apply the candidate to its clone, and run each clone forward four simulated minutes. **ACT.** Score the outcomes on a weighted objective, recommend the best — or refuse to recommend if nothing beat doing nothing — and show the arithmetic. When the operator applies it, the intervention enters the live simulation through the exact same code path that was measured, and the loop starts again. The loop is what makes this a decision-support system rather than a dashboard. Each stage exists because the stage after it needs something the stage before could not provide. --- ## 5. A worked example, end to end Concrete, from the flagship scenario, with real numbers from a real seeded run. **T+00:15.** The chequered flag. 40,000 spectators begin leaving six seating areas on an eighteen-minute departure curve. Everyone routes by shortest path towards one of four destinations: the rail interchange, the coach interchange, or one of two car parks. **T+04:00.** A scripted infrastructure failure fires: **Exit B loses half its throughput**, dropping from 760 people/minute to 380. This is a real change to the simulated network — the exit's service budget is halved — not a label on a map. **T+05:30.** *SEE.* The corridor feeding Exit B (`X_E_EXITB`, 114 m long, 11 m wide) is now taking more people per minute than it can pass. Measured: inflow 556 p/min, outflow 380 p/min. Density is rising at 0.14 p/m² per minute. Walking speed has fallen to 0.13 m/s against a free speed of 1.34. A queue is forming. **T+05:30.** *PREDICT.* The gradient-boosted model, fed seventeen features from the Crowd State Engine, projects density at +30/60/90/120 s. Crossing the venue's critical threshold of 2.8 p/m² happens inside the horizon, so the alert reads **"critical in 96 seconds"** — and it explains itself: *density rising, velocity collapsed, queue growing, downstream service constrained*. **T+07:30.** *SIMULATE.* The operator presses **Simulate strategies**. The engine inspects the topology around the bottleneck and generates eight candidates, including: do nothing; redirect 20/30/40% of the affected flow; stagger the release from the three stands feeding it; open contingency lanes at another exit and divert 30%; unlock the north-east emergency gate and divert 35%; move 30% of coach demand to the south apron; and a combined redirect-plus-stagger. Eight complete copies of the crowd — every agent's position, route, destination, compliance and the random number generator's internal state — are made. Each candidate is applied to its own copy. Each copy runs forward 240 simulated seconds. About nine seconds of wall-clock later, eight measured futures exist. **T+07:31.** *ACT.* Scored against the do-nothing arm on nine weighted terms. **Redirect 40%** wins by 17.1%. The panel says why, in measured deltas: peak density 2.19 → 1.58 (−28%), queue at end of window 1,636 → 1,245 (−24%), critical duration to zero, average journey time essentially unchanged, 834 people rerouted. The verdict reads **Decisive**. **T+07:45.** The operator applies it. 1,700 people are instructed; per-person compliance means roughly 70% actually change route. Green rerouting paths animate on the map. Over the next three minutes the queue metric falls and the alert drops from critical to warning. **And the counter-example, which is the more interesting demo.** Do nothing until **T+15:00** and press the button then. All eight candidates now return an *identical* peak density of 3.31 p/m². The engine does not pick a winner. It returns: > **Not decisive.** Every candidate landed within 0.0% of doing nothing. > `E CONCOURSE → EXIT B` is already discharging at its service limit (380 > people/min) with 3,275 people held, so it needs about 9 minutes to clear on > throughput alone. Rerouting only reaches people who have not yet committed to > this asset, and there are too few of them left for any routing change to > register. The remaining levers are capacity and staffing, not routing. Every number in that paragraph is read from the measured state. That is the system telling you the decision window closed — which is more useful, and far more credible, than a confident recommendation that would not have worked. --- --- # Part II — How it actually works ## 6. The venue model ### 6.1 A venue is a graph `backend/flowtwin/venue/models.py` A venue is a **directed, weighted graph**. Nodes are places a person can be; edges are the walkable links between them. **Node types**, and what each means to the engine: | Type | Role | |---|---| | `gate` | Entry point with a service rate in people/minute. An origin in arrival scenarios. | | `grandstand`, `general_admission` | Seating/standing areas. Origins; a route may *end* at one but never pass *through* one. | | `platform` | Railway platform. Same semantics as a grandstand — you leave from it, you do not walk across it. | | `concourse`, `junction` | Circulation space. Optionally rate-limited (a foot-over-bridge is a junction with a service rate set by stair width). | | `concession` | A dwell point. People passing through stop here for a while. | | `exit` | A perimeter throughput constraint. **Deliberately not a destination** — see §6.3. | | `emergency_exit` | A route that physically exists but is locked. **Absent from routing until opened** — see §6.4. | | `transport`, `parking` | Destinations. These absorb people, at a rate. | **Edges** carry `length_m`, `width_m` and `capacity_ppm` (people per minute that may *enter*). Capacity follows Fruin-style pedestrian flow: about 70 people per minute per metre of effective width in one direction. A bidirectional venue edge compiles into two directed edges that share the same physical floor, which is how opposing-flow conflict is measured. Edge lengths are **derived from node geometry** by `scripts/build_venues.py` rather than hand-written, so the map you see and the physics that runs can never drift apart. ### 6.2 Compilation and cells `CompiledVenue` turns the pydantic model into flat numpy arrays indexed by node or directed-edge index, so the simulation's inner loop never touches a Python object. Then every edge is split into **cells of about 12 metres**. Density and walking speed are evaluated per cell, not per edge. This is not a detail. It is the difference between a model that works and one that does not: > With edge-average density, a queue at a gate slows down *everyone* on that > corridor — including a person 200 metres back with completely clear space in > front of them. Measured effect when this was wrong: network throughput > collapsed to roughly **one tenth** of its correct value. Cells on a two-way corridor are mirrored to their opposite-direction twin (`cell_pair`), so two people walking towards each other in the same twelve metres are counted as sharing that floor. ### 6.3 The decision that an exit is not a destination A perimeter exit is modelled as a **throughput constraint on the way to somewhere else** — a station, a car park, a coach apron — not as a place journeys end. If an exit were a sink, everyone reaching it would vanish, and the queue *behind* it would never form. That queue is the single most important phenomenon this project exists to predict. Modelling exits as sinks would have made the demo easier and the model useless. ### 6.4 The decision that a locked gate is absent, not expensive An emergency exit is not modelled as an available-but-costly route. It is **excluded from every routing table for every policy and every destination**. The reason is precise. If a locked gate were merely expensive, the optimiser would quietly have access to capacity that nobody has unlocked; under enough congestion the crowd would start using it on its own, and the recommendation *"open the north gate"* would never appear, because the crowd would already be going there. Modelling it as absent makes opening it a real decision with a real consequence — and it makes `open_emergency_exit` the only candidate in the whole strategy set that **adds** network capacity rather than redistributing capacity already in service. ### 6.5 Concessions as dwell points A concession node carries `dwell_s` (mean stop time) and `dwell_share` (the fraction of passers-by who stop). A person who stops: - still occupies the floor they are standing on, and counts in the queue extent; - does **not** consume the downstream node's service budget, because they are not trying to go anywhere. That is what makes a food court a crowd feature rather than a label. It also requires the concession to be **on** a route — a dead-end spur is never on anybody's path, so nobody ever visits it. Both the fan zone at Circuit Alpha and the food court at Sangam Junction sit on the main circulation route, with a longer bypass available, which is what gives the strategy engine something to reroute people *onto*. The randomness lives in the agent population, sampled once at creation, not in a live random stream. That is deliberate: it means a counterfactual branch reproduces the same dwell decisions exactly, so two branches of one state stay byte-identical. --- ## 7. The simulation engine `backend/flowtwin/simulation/engine.py` ### 7.1 The critical architectural choice: mesoscopic, not microscopic A microscopic pedestrian model (social forces, agents in free 2-D space) is more physically detailed and completely unusable here: it is far too slow to run eight alternative futures while an operator waits. FlowTwin is **mesoscopic**. Agents are individuals — each has a personal walking speed, an origin, a destination, a route, a compliance probability and a position — but they move **along graph edges**, not across open floor. Agent state is stored as a **structure of arrays** (numpy), so a step is a handful of vectorised operations over the whole population rather than a loop over 40,000 objects. Measured: **2–4 ms per simulated second at 40,000 agents.** That number is the enabling fact for the entire project. Because a step is milliseconds, four minutes of simulation is about a second, and eight counterfactual futures are about nine seconds — short enough that an operator will actually press the button. Every other capability in this document is downstream of that choice. ### 7.2 The walking model Speed as a function of density uses **Weidmann's (1993) exponential fundamental diagram**, the standard empirical pedestrian relation: ``` v(ρ) = v_free · (1 − exp(−γ · (1/ρ − 1/ρ_jam))) ``` with `v_free = 1.34 m/s`, `γ = 1.913`, `ρ_jam = 5.4 p/m²`. Each agent has a personal multiplier drawn from a clipped normal (σ = 0.16), so a crowd contains fast and slow walkers. This reproduces the two behaviours everything else depends on: unimpeded walking at low density, and speed collapse as density approaches jam. ### 7.3 The step, in order Each simulated second: 1. **Timeline events** fire (capacity changes, phase transitions). 2. **Cell density and speed** are computed, including the mirrored opposite direction. 3. **Queue extent** is derived (§7.4). 4. **Agents advance** at their cell's speed × personal factor. A walker cannot step into a cell that is already at 90% of jam density, and stops when it reaches the back of a standing queue. 5. **Transition candidates** are gathered: everyone released and waiting, plus everyone standing at the head of an edge who is not currently dwelling. 6. **Node service budget** admits people first-come-first-served by how long they have been queueing. 7. **Edge admission** is limited by three separate constraints (§7.5). 8. **Moves and absorptions** apply. 9. **Measurement** updates the Crowd State Engine. 10. **Routing tables** refresh on a 5-second cadence. ### 7.4 Queue extent — a queue is a length, not a point A queue occupies corridor. If you measure it only at the stop line, the standing queue has zero physical extent, and the model then makes everyone behind it *walk through* a near-jammed corridor at a few centimetres per second to reach the back of it. Measured consequence when this was wrong: a gate rated at 500 people/minute discharged at **under 200**. The fix: queue extent is derived from everyone who has actually stopped — `queue_len = queued_count / (queue_pack_density × width)` — with a packing density of 4.6 p/m², lower than jam because a queue that has stopped moving is not yet a crush. Walkers then join the *back* of the queue where the back actually is. ### 7.5 Three admission constraints, and why each is needed An edge accepts people this second up to the minimum of: **(a) Nominal capacity.** `capacity_ppm × dt`, with fractional carry so a 70/min link does not admit zero people every second and then seventy at once. **(b) The backward-wave receiving function.** As a link fills, the rate at which it can accept anyone new falls towards zero. Congestion propagates *backwards* at `backward_wave_mps = 0.36 m/s`: ``` receiving_ppm = 0.36 × 60 × free_space / length ``` This is the cell-transmission idea from traffic flow. Without it a corridor silently absorbs an impossible crowd instead of pushing congestion upstream — and "congestion spills back" is the entire non-local behaviour described in §2.2. **(c) Entry-cell headroom.** People enter a corridor **at its mouth**, and the mouth is one cell wide. A 400 m corridor with room for 2,000 people cannot take 2,000 people this second, because they would all have to stand in the first twelve metres. Constraint (c) was added late, after an existing test caught a peak local density of **8.0 p/m²** against a jam density of 5.4 on a corridor whose mean was 1.3. Whole-edge headroom had been passing that traffic; the entrance had not. ### 7.6 Routing rules that had to be added - **No transit through seating areas or platforms.** A shortest path was otherwise happy to cut through a grandstand as a shortcut, misrouting the crowd and deadlocking against the people trying to leave. Barcelona gridlocked with 18,000 people stranded before this rule existed. - **No U-turns.** A routing table that has just been re-weighted can briefly make the corridor an agent is standing in look like the cheapest way onward. After repeated interventions this left 262 agents bouncing between two nodes forever. Reversing is refused unless it is genuinely the only option; the residue fell to 10. - **Penalty clamping and decay.** Intervention penalties are capped and relax towards neutral each refresh, so repeated operator action cannot permanently distort the cost surface. ### 7.7 Compliance Rerouting instructs people; it does not teleport them. Each agent carries a compliance probability sampled per scenario (typically 0.40–0.97). An instruction to reroute 40% reaches the agents whose route uses the bottleneck, and roughly 70% of those actually change. The measured improvement is therefore an improvement *net of people ignoring you*, which is why it is believable. --- ## 8. The Crowd State Engine `backend/flowtwin/crowd/` Turns raw agent positions into the quantities that predict failure. Per directed edge and per node, every second: | Quantity | Why it is measured | |---|---| | Occupancy, density | Density, not headcount, is the danger | | Peak **local** density | The worst 12 m, not the average | | Velocity, and velocity ratio vs free speed | Speed collapse precedes compression | | Inflow / outflow (people per minute) | The imbalance *is* the queue growth | | Capacity utilisation | How close to the design limit | | Density growth (per minute) | Rate of change is the leading indicator | | Queue growth (net people/minute) | Same, in people rather than density | | Opposing-flow conflict | Two streams on one floor is a distinct hazard | | Composite risk score (0–1) | One number for ranking | The **risk score** is a weighted sum, not a density threshold, because a single density number cannot distinguish a busy concourse from a compressing queue: ``` risk = 0.30·density + 0.18·utilisation + 0.18·density_growth + 0.12·queue_growth + 0.12·velocity_drop + 0.10·flow_conflict ``` Crucially, `risk_contributions()` exposes the per-term breakdown, so an alert does not just say "risk 0.81" — it says **why**: *density rising fast, velocity collapsed, queue growing, opposing flow*. A test asserts the contributions sum to the score, so the explanation can never drift from the number. Alerts are raised at 0.42 (watch), 0.58 (warning) and 0.74 (critical), and are de-duplicated so a two-way corridor produces one alert, not two. --- ## 9. Prediction `backend/flowtwin/prediction/` ### 9.1 The honest-baseline design The predictor is a **gradient-boosted regressor** (`HistGradientBoostingRegressor`), one model per horizon (+30, +60, +90, +120 s), predicting density on each edge. The important design decision is what it is measured against. There is an **analytic mass-balance baseline** — project density forward from current inflow, outflow and free storage — which is genuinely good, because pedestrian flow is substantially conservation of people. The trained model is used at inference time **only if it beats that baseline on held-out seeds.** Otherwise the system falls back to the baseline and says so in the UI. This is what stops "we used ML" from being decoration. ### 9.2 Features Seventeen, all from the Crowd State Engine, all quantities an operator would recognise: `density`, `density_growth_per_min`, `velocity_ratio`, `inflow_per_capacity`, `outflow_per_capacity`, `net_flow_per_capacity`, `occupancy_ratio`, `queue_ratio`, `flow_conflict`, `risk`, `upstream_density`, `downstream_density`, `downstream_wait_min`, `downstream_service_ratio`, `free_storage_ratio`, `length_m`, `width_m`. Note `upstream_density` and `downstream_density`: the model can see the neighbourhood, which is how it learns the spill-back behaviour of §2.2. ### 9.3 Training and validation The simulator is the data generator, which means **exact ground truth** — the label for "density here in 60 seconds" is simply what the density was, sixty seconds later, in a run that actually happened. Validation is on **disjoint seeds**: five seeds for training, two entirely different seeds held out, across all four scenarios including the railway terminus. 421,198 training rows, 169,364 test rows. Measured on held-out seeds: | Horizon | Model MAE | Baseline MAE | Improvement | R² | |---|---|---|---|---| | +30 s | 0.0097 | 0.0183 | **+47.3%** | 0.999 | | +60 s | 0.0159 | 0.0352 | **+54.7%** | 0.998 | | +90 s | 0.0221 | 0.0519 | **+57.4%** | 0.996 | | +120 s | 0.0278 | 0.0683 | **+59.3%** | 0.993 | The improvement *grows* with horizon, which is what you would hope: the physics baseline is nearly right in the short term and degrades as second-order effects accumulate; the model captures those. These numbers are visible in the dashboard, not just in a file. ### 9.4 The output an operator can use A density number in 90 seconds is not actionable. **"Critical in 96 seconds"** is. `time_to_threshold` interpolates the projected trajectory against the venue's critical density and reports lead time, which is what the alert displays and what the strategy engine uses to decide there is something worth acting on. ### 9.5 A performance trap worth knowing about Inference on 66 rows took **1,000 ms**. The same inference on one thread took **9 ms**. The BLAS/OpenMP thread pools were fighting over a tiny batch. Thread limits are pinned in `flowtwin/__init__.py` *before* numpy or sklearn are imported, which is the only place it works. --- ## 10. The Strategy Engine `backend/flowtwin/strategy/interventions.py` Candidates are **generated from the venue's topology and live state**, not read from a fixed list. A candidate only exists if the venue can actually support it. | Candidate | Generated when | What it does | |---|---|---| | **No action** | Always | The reference every other option is measured against | | **Redirect 20 / 30 / 40%** | An alternative path exists | Switches that fraction of the affected agents to adaptive routing with a cost penalty on the bottleneck | | **Stagger release** | Origin zones still have people to release | Holds 45% of the remaining departures from the top three feeding zones for 150 s | | **Open contingency lanes** | Another exit has **measured** spare capacity right now | +35% throughput there, and diverts 30% of the flow to it | | **Open emergency exit** | The venue has one still closed | Unlocks and staffs it — the only option that *adds* capacity — and diverts 35% | | **Destination split** | Two interchangeable destinations exist | Moves 30% of demand from one to the other: changing *where people are going*, not just how they get there | | **Combined** | Both a reroute and a stagger are available | Redirect 25% and hold 30% of remaining departures for 120 s | Two things are worth pointing out to a judge: - **"Open contingency lanes" quotes measured spare capacity in its own description.** It is not offered unless the alternative exit genuinely has room at this instant. - **Destination split is a different *kind* of lever.** Everything else changes routes; this changes destinations — operationally, "your coach has been moved to the south apron". --- ## 11. Counterfactual simulation `backend/flowtwin/strategy/counterfactual.py` This is the part that makes the recommendation a **measurement** rather than a rule. ``` capture the current state ├─ clone → apply "no action" → run 240 s → measure ├─ clone → apply "redirect 20%" → run 240 s → measure ├─ clone → apply "redirect 30%" → run 240 s → measure ├─ clone → apply "stagger release" → run 240 s → measure ├─ clone → apply "open emergency" → run 240 s → measure └─ … one clone per candidate compare → score → recommend ``` **Every clone starts byte-identical**, including the random number generator's internal bit-generator state. The only difference between two results is the intervention. That is the whole scientific claim, and two tests enforce it: one asserts that two branches of one state produce identical results, another that evaluating strategies does not advance the live run by a single step or move a single agent. Cloning is cheap because of the array layout: copy the agent arrays, three small integer routing matrices, the capacity budgets and the RNG state. Each roll-out measures sixteen quantities, including peak density on the watched asset, density **at the end of the window**, seconds spent critical, network-wide critical exposure, mean and p95 journey time, throughput, peak and final queue, aggregate risk, and how many people were rerouted. Note what is deliberately watched: **peak density on the asset under threat**, not the network maximum. A network maximum set by some unrelated corridor would be identical across all candidates and would make every option look the same. --- ## 12. Multi-objective optimisation and the decisiveness verdict `backend/flowtwin/strategy/optimizer.py` ### 12.1 The score Nine terms, each normalised against the no-action arm so a strategy's score reads directly as "fraction of the do-nothing outcome". The recommendation is `argmin J`. | Term | Weight | Asks | |---|---|---| | Peak density | 0.22 | How bad does it get? | | Critical duration | 0.20 | How long does it stay dangerous? | | **Density at end of window** | 0.12 | What state am I left in? | | **Queue at end of window** | 0.10 | What am I still holding? | | Average travel time | 0.10 | Are we punishing everyone to help a few? | | Aggregate risk | 0.10 | Integrated exposure, not just the peak | | Throughput | 0.08 | Are people actually leaving? | | Maximum queue | 0.04 | Worst single moment of holding | | Rerouting cost | 0.04 | Moving 20,000 people is heavier than moving 2,000 | All weights are environment-variable overridable, and the per-term contributions are exposed per strategy, so the table can be audited row by row. ### 12.2 Why "end of window" terms exist — the most interesting bug in the project Originally the score was dominated by peak terms. Intervene early and it worked beautifully. Intervene late and **every candidate returned an identical peak density to three decimal places**, and the "winner" was decided by the reroute-cost tiebreak — whichever option moved fewest people. The root cause is physical, not a coding error. Once a 4,000-person queue exists at a service-limited exit, it drains at the gate rate regardless of routing. The peak over the window is already determined. Peak-only scoring genuinely cannot tell the candidates apart. Two things were tried: 1. **Lengthen the roll-out.** Measured: separation returns only at a **720-second** horizon, costing 27 seconds of compute — for an answer that is still "this barely helps". Rejected on evidence. 2. **Add end-of-window terms.** Peaks ask "how bad does it get"; end-of-window terms ask "what am I still holding when the window closes". A strategy that leaves the bottleneck 1,500 people lighter at T+horizon is better even when both runs touched the same maximum. Adopted. ### 12.3 The decisiveness verdict The end-of-window terms sharpened the early case but did not manufacture a difference where there genuinely was none. So a second mechanism was added: > A candidate must beat no-action by at least **1.5%** of the do-nothing score > before it is *recommended*. Below that, the ranking still shows exactly what was > measured, but the recommendation falls back to no action and the system explains > why. The explanation is generated from the measured bottleneck state — queue held, discharge rate, arrival rate, estimated clearance time — and is quoted in full in §5. This turned the weakest moment in the demo into one of the strongest. A system that knows when it cannot help is more credible than one that always has an answer, and it removes the landmine of a judge pressing the button at the wrong moment. Guarded at both ends by tests: one asserts the early case still separates decisively, one asserts the late case refuses to pick a winner. The late fix cannot be obtained by flattening the early case. ### 12.4 Explainability with no language model anywhere The "why this strategy" panel is generated from **the same normalised terms that produced the score**. There is no narrative layer that could drift away from the arithmetic, and there is no LLM in the decision path. This is a deliberate, defensible position: every claim on screen is traceable to a measured number, and the reasoning shown is literally the reasoning used. --- ## 13. Dynamic routing `backend/flowtwin/routing/` ### 13.1 Next-hop tables Rather than storing a route per agent, FlowTwin stores, for every **policy** and every **destination**, the best next edge from each node. 40,000 agents then route with a single fancy-index lookup, and a change in conditions re-routes everybody who has not committed, in one Dijkstra per destination. It is also what makes counterfactuals affordable: cloning the routing state is cloning three small integer matrices. ### 13.2 Three policies, which are also the benchmark arms | Policy | What it is | |---|---| | **Shortest path** | Baseline A. Distance only. What people do without guidance. | | **Static assignment** | Baseline B. A real pre-event plan: method-of-successive-averages traffic assignment with BPR-style congestion costs, computed before the event from expected demand and never revised. | | **FlowTwin adaptive** | Live cost from distance, travel time, congestion, density, capacity and risk, refreshed every 5 simulated seconds. | Baseline B matters. It is not a straw man — it is what a competent operations team actually produces, and beating it is the interesting claim. ### 13.3 Oscillation control A naive adaptive router flaps: send people east, the east fills, send them west, the west fills. Four mechanisms prevent it: - **Hysteresis** — a node abandons its incumbent next hop only when the challenger is at least ~22% cheaper. - **Route commitment** — an agent keeps an adopted route for at least 25 s. - **Cycle breaking** — asserted acyclic by test. - **Penalty decay** — intervention penalties relax 2% per refresh towards neutral. --- ## 14. Perception — the Hugging Face path `backend/flowtwin/perception/` ### 14.1 Where it sits, and why that placement is the point ``` camera frame ──► Hugging Face crowd model ──► crowd observation ─┐ ├─► Crowd State Engine ─► prediction ─► strategy simulated agents ────────────────────────────────────────────────┘ ``` Both input modes converge on **one observation schema**. Density, risk, prediction, counterfactual and recommendation are then identical code whichever source is feeding them. A deployment can swap simulated crowds for real cameras without touching the decision path. It is deliberately **not** in the decision path itself. Nothing downstream depends on a neural network's opinion. ### 14.2 The candidate chain Tried in order; the first that loads wins; the selection is written to `models/perception_manifest.json`: 1. `AbdurRahman011/csrnet-indian-metro-crowd-density` — density-map regression. Counts by integrating a predicted density map, so it degrades gracefully in dense crowds where detectors fail. Trained on Indian metro crowds. 2. `AmineSam/irail-crowd-counting-yolov8n` — head detection fine-tuned on RPEE-Heads (railway platforms and event entrances). 3. `hustvl/yolos-tiny` — widely mirrored COCO detector, `person` class. 4. `facebook/detr-resnet-50` — second fallback. CSRNet's architecture is defined locally in `perception/csrnet.py` so a bare `state_dict` checkpoint can be loaded. ### 14.3 Sample frames with exact ground truth Three frames ship in `data/perception/`, **rendered from the digital twin** rather than photographed — a top-down view of a real corridor at a real moment of a real seeded run, one marker per person actually standing there. | Frame | People in shot | Area | Density | |---|---|---|---| | Exit B approach, free-flowing | 260 | 396 m² | 0.66 p/m² | | Exit B approach, standing queue | 1,762 | 396 m² | 4.45 p/m² | | Central foot-over-bridge, surge | 522 | 576 m² | 0.91 p/m² | Two reasons for renders rather than photographs. Shipping third-party crowd photographs in a public repository is a licensing problem. And a render has a property no photograph has: **the count is known exactly**, so the panel reports the model's *error* and not just its answer. A model that reports 1,300 on a frame containing 1,762 has undercounted by 26%, and being able to say that is worth more than a number with nothing to check it against. The UI labels them as renders. Uploading a real photograph runs the identical path. ### 14.4 Honest status **Not yet verified against downloaded weights.** The build environment has no network route to `huggingface.co` (every attempt returns `403 Tunnel connection failed`). Implemented and tested: the chain, the loader, the local CSRNet architecture, the manifest, the image → count → observation path, and the failure behaviour. Not executed: one real inference against real weights. One command closes it on any networked machine: ```bash pip install -r backend/requirements.txt python scripts/fetch_hf_model.py ``` **If it is never run, the endpoint reports the actual error and returns nothing. It has never fabricated a count, and a test asserts that.** Full record in [`HUGGING_FACE.md`](HUGGING_FACE.md). --- --- # Part III — The system as software ## 15. Architecture and module map ``` flowtwin/ ├── backend/ │ ├── flowtwin/ │ │ ├── __init__.py Thread-pool pinning (must precede numpy import) │ │ ├── config.py Every tuning constant, all env-overridable │ │ ├── main.py FastAPI app, lifespan, static mount │ │ ├── venue/ Domain model, compilation, scenario loading │ │ ├── simulation/ Agents, movement physics, the engine │ │ ├── crowd/ Density, flow, risk, alerts — the Crowd State Engine │ │ ├── prediction/ Features, analytic baseline, trained-model inference │ │ ├── routing/ Cost model, next-hop tables, static assignment │ │ ├── strategy/ Interventions, counterfactuals, optimiser, explanation │ │ ├── perception/ Hugging Face chain, CSRNet, observation schema │ │ ├── benchmarks/ Multi-seed, multi-arm evaluation harness │ │ ├── runtime/ Session lifecycle, broadcast loop, replay sessions │ │ └── api/ Routes, request/response schemas, WebSocket │ └── tests/ 79 tests across simulation, intelligence, API ├── frontend/ Zero-build ES modules + Canvas 2D ├── data/ │ ├── venues/ 3 venue JSON files │ ├── scenarios/ 4 scenario JSON files │ ├── perception/ 3 sample frames + ground-truth index │ └── fallback/ Pre-recorded frames (gitignored, regenerable) ├── models/ Trained predictor + its validation report ├── benchmarks/ Generated results, never hand-edited ├── scripts/ build_venues, train_predictor, run_benchmarks, │ make_perception_samples, fetch_hf_model, │ record_fallback, ui_check └── docs/ This file, ARCHITECTURE, DEMO, PS3_AUDIT, SPEC_AUDIT, HUGGING_FACE, ROADMAP ``` Roughly **6,600 lines of backend Python**, **2,750 lines of frontend**, and **1,100 lines of tests**. **Deliberate omissions.** No Redis, no PostgreSQL, no Docker, no build step. A simulation session is in-memory state on one process by nature; adding a datastore would mean serialising 40,000 agents per frame to solve a problem that does not exist at this scale. The rationale is written down in `ARCHITECTURE.md §10` so the absence reads as a decision rather than an omission. --- ## 16. Data flow and real-time transport ``` Browser FastAPI Simulator │ │ │ ├─ POST /api/simulation/start ───►│─ build venue, population ────►│ │◄──────── session + first frame ─┤ │ │ │ │ ├─ WS /api/simulation/{id}/stream►│ │ │ │ every 200 ms of wall clock: │ │ │ step × speed ──────────────►│ │ │◄──── state ───────────────────┤ │◄───────────── frame (push) ─────┤ │ │ │ │ ├─ POST /strategy/simulate ──────►│─ clone × 8, roll out ────────►│ │◄──── ranked strategies + why ───┤ │ ├─ POST /strategy/apply ─────────►│─ apply to the live run ──────►│ ``` **No per-frame polling.** The server pushes; the browser renders. Frames carry the crowd state, a bounded sample of agent positions for drawing (2,600 by default — a rendering budget, not a simulation limit), alerts, predictions and events. Sessions with no subscribers idle and are reaped. That was a real bug: a refreshed browser tab left an orphaned session simulating at 40×, which starved the event loop and made new runs appear to hang. --- ## 17. The frontend **Zero build step.** Vanilla ES modules served by the same FastAPI process. No npm, no bundler, no version skew, nothing to break on demo day. The trade-off against a React/Next.js frontend was made deliberately and is written down. **Layout.** The map dominates. Panels are subordinate. - **Left rail** — *Inputs*: expected crowd size, arrival/departure window, reroute compliance, the scheduled event and its severity, seed, baseline routing policy. Below it, the *Event schedule* showing what will execute and what has fired. Below that, on the Barcelona venue only, *Evidence & assumptions*. - **Centre** — the venue map on Canvas 2D: landmarks, corridors coloured by measured density, animated agents, predicted congestion drawn distinctly from current congestion, and rerouting paths when an intervention is applied. Layer toggles, a density legend and a scale bar. - **Right rail** — *Alerts* with severity, cause and lead time; *Prediction* with per-horizon projections and a model-accuracy modal; *Strategy* with the simulate button and the recommendation card. - **Drawer** — the strategy simulator: the full comparison table, the "why this strategy" panel, and the projected-density chart per candidate. **A rendering bug worth knowing about.** Frames arrive five times a second. Rebuilding an alert card on every frame restarts its CSS entry animation, which left the alert panel permanently mid-fade — measured opacity **0.26**, effectively invisible. Cards are now keyed on structure (`base_id:severity`) and live values are written in place. This shipped broken once. --- ## 18. Reproducibility and determinism Every run is fully determined by **(venue, scenario, seed, overrides)**. - The RNG's bit-generator state travels inside the snapshot, so a restored state produces the identical future. - Dwell decisions are drawn once at population creation, not from a live stream, for the same reason. - Interventions use a separate random stream so that applying a strategy never perturbs the population's own draws. - The seed is displayed in the metrics strip during every run. Tested directly: snapshot/restore is exact; two branches of one state are identical; branching does not disturb the parent; evaluating strategies does not advance the live simulation. This is what makes the benchmark numbers checkable rather than assertable. --- ## 19. The three venues All three are plain JSON against one schema. No venue-specific engine code exists. ### Circuit Alpha — fictional Grand Prix venue 30 nodes, 43 edges. Four perimeter exits, six spectator zones, a full concourse ring, three concession clusters, one emergency egress route, two transport interfaces and two car parks. **40,000 spectators**, simultaneous egress over an 18-minute curve, with Exit B losing half its throughput at T+4:00. This is the controlled stress test — the most instrumented venue, and the one the benchmark headline comes from. ### Circuit de Barcelona-Catalunya — documented-condition reconstruction 22 nodes, 33 edges. **78,000 spectators** at race-day scale, with the Montmeló rail approach deliberately constrained. The discipline here is the point. Every documented fact carries a source; every modelling assumption is labelled as an assumption; **both lists are on screen throughout**. The disclaimer is in the venue data, the briefing and the UI: > This is a counterfactual reconstruction using publicly documented event > conditions and a synthetic crowd model. It is not a replay of original > spectator telemetry, which is not public. The question it answers is *"given the documented conditions, what would FlowTwin have recommended?"* — never *"this is what happened."* ### Sangam Junction — fictional Indian metropolitan railway terminus 22 nodes, 34 edges. **26,000 passengers** discharged from six platforms over sixteen minutes, all of whom must change level through one of three routes: two foot-over-bridges and a subway. At T+4:30 the west bridge is closed to a quarter of its capacity on safety orders; at T+10:00 east gate screening slows. This venue exists as **evidence**, not decoration: - The **failure mode is different in kind**. A circuit fails at its perimeter; a terminus fails in the middle, at the level change, and the constraint is stair width rather than gate count. - The **food court is on the circulation path**, so about a quarter of the people crossing it stop for ~95 s and the concourse goes amber before the bridges do. The north gallery bypasses it at the cost of a longer walk — which is what gives the strategy engine a real question. - The **emergency gate is shut** and genuinely absent from routing. Building it required **one new node type and zero special-case simulation code**. It is fictional and labelled fictional; no real station is named and no real incident is reconstructed. --- ## 20. Testing and verification **79 automated tests**, in three files: - `test_simulation.py` (26) — the walking model's monotonicity, capacity budgets and fractional carry, queue behaviour, density never exceeding jam, snapshot exactness, branch independence, diversion and compliance, staggering, the What-If control genuinely retuning the scheduled event, emergency-exit routing exclusion and use, concession dwell and its reproducibility. - `test_intelligence.py` (28) — density and threshold maths, risk contributions summing to the score, bottleneck detection finding the right asset, alert de-duplication, feature-matrix sanity, prediction responding to a real change in state, routing acyclicity under hysteresis, adaptive routing genuinely avoiding the congested asset, counterfactual determinism, evaluation not advancing the live run, optimiser separation at an early intervention, optimiser refusal at a late one. - `test_api.py` (25) — every endpoint's success and failure modes, validation rejection, perception failing honestly, the sample route and its path-traversal guard, replay fallback. **Beyond unit tests:** - `scripts/ui_check.py` drives the entire acceptance path in a real Chromium browser via Playwright — load, run, wait for a critical alert, simulate strategies, check a recommendation is highlighted, apply it, watch the redistribution, switch to Barcelona and check the provenance panel, switch to the terminus and check its schedule, open the perception panel and verify every sample thumbnail actually loads. **Any console error or failed request fails the run.** It saves screenshots at each step. - `scripts/run_benchmarks.py` produces the quantitative results from real multi-seed runs. No figure in any document is typed by hand. - `.github/workflows/ci.yml` regenerates the venues and runs the suite on push. --- --- # Part IV — Evidence ## 21. Measured results Generated by `scripts/run_benchmarks.py`. Three arms — baseline shortest path, a static pre-event plan, and the full FlowTwin loop — across **8 independent seeds** of the complete simulation. Mean ± standard deviation. ### Circuit Alpha · 40,000 spectators · 8 seeds | Metric | Shortest path | Static plan | **FlowTwin** | vs baseline | |---|---|---|---|---| | Peak density (p/m²) | 3.6 ± 0.0 | 3.4 ± 0.1 | **2.0 ± 0.4** | **−42.6%** | | Critical exposure (corridor·s) | 1733 ± 130 | 1071 ± 216 | **0 ± 0** | **−100%** | | Maximum queue (people) | 4327 ± 56 | 4063 ± 111 | **2245 ± 440** | **−48.1%** | | Average journey (s) | 867 ± 12 | 798 ± 13 | **808 ± 15** | **−6.7%** | | 95th-percentile journey (s) | 2043 ± 89 | 1772 ± 94 | **1837 ± 106** | **−10.1%** | | Dispersal time, 95% (s) | 2523 ± 81 | 2241 ± 85 | **2286 ± 154** | **−9.4%** | | People rerouted | 0 | 2036 | 5814 | — | This is the headline. Time spent above the critical density goes to **zero on every seed**, peak density falls by 43%, the worst queue nearly halves — and average journey time gets *better*, not worse. Crowd-safety interventions usually trade delay for safety; here the congestion relief more than pays for the detour. The static plan is a genuine competitor, not a straw man: it beats naive shortest-path handily. FlowTwin beats it on every safety metric. The standard deviations are informative too. FlowTwin's peak density varies more across seeds (±0.4) than the baselines (±0.0–0.1), which is exactly what you would expect: the baselines always fail the same way, while an adaptive system's outcome depends on when the bottleneck happened to be caught. ### Circuit de Barcelona-Catalunya · 78,000 spectators · 6 seeds | Metric | Shortest path | Static plan | **FlowTwin** | vs baseline | |---|---|---|---|---| | Peak density (p/m²) | 3.2 ± 0.1 | 3.2 ± 0.1 | **1.3 ± 0.2** | **−59.0%** | | Critical exposure (corridor·s) | 1254 ± 165 | 1254 ± 165 | **0 ± 0** | **−100%** | | Maximum queue (people) | 3677 ± 152 | 3677 ± 152 | **1107 ± 228** | **−69.9%** | | Average journey (s) | 721 ± 3 | 721 ± 3 | 786 ± 26 | **+9.0%** | | 95th-percentile journey (s) | 1321 ± 7 | 1321 ± 7 | 1743 ± 144 | **+32.0%** | | Dispersal time, 95% (s) | 2514 ± 8 | 2514 ± 8 | 2837 ± 40 | **+12.8%** | | People rerouted | 0 | 0 | 8179 | — | **This one has a real trade-off and it is reported, not hidden.** Barcelona's danger sits on a narrow transport interface, and relieving it means sending thousands of people the long way round. Safety improves dramatically — peak density down 59%, the worst queue down 70%, critical exposure eliminated on every seed — and it costs 9% on the average journey and **32% on the 95th percentile**. That is the honest shape of the decision. One person in twenty gets home substantially later so that nobody stands in a dangerous crush. An operator should be told that price rather than sold a free lunch, and the optimiser's `avg_travel_time` weight is exactly the dial that sets how much of it you are willing to pay. **Two baselines, identical results.** On this venue shortest-path and the static plan produce byte-identical numbers, because most origin–destination pairs in the reconstructed topology have exactly one sensible route. That is a genuine property of the topology, not a broken benchmark, and it is documented rather than quietly dropped. ### Sangam Junction · railway terminus · 26,000 passengers · 6 seeds | Metric | Shortest path | Static plan | **FlowTwin** | vs baseline | |---|---|---|---|---| | Peak density (p/m²) | 3.0 ± 0.0 | 2.5 ± 0.2 | **2.4 ± 0.3** | **−20.3%** | | Critical exposure (corridor·s) | 0 | 0 | 0 | — | | Maximum queue (people) | 3600 ± 56 | 3459 ± 33 | 3883 ± 510 | +7.9% | | Average journey (s) | 887 ± 4 | 853 ± 40 | 1028 ± 87 | **+15.9%** | | 95th-percentile journey (s) | 1708 ± 33 | 1849 ± 295 | 2739 ± 613 | **+60.3%** | | Dispersal time, 95% (s) | 2257 ± 7 | 2431 ± 324 | 3298 ± 581 | **+46.1%** | | People rerouted | 0 | 2063 | 649 | — | **This is the worst table in the project and it is here on purpose.** On the terminus FlowTwin shaves 20% off peak density and pays for it with 16% on the average journey, 60% on the 95th percentile, and 46% on dispersal. Critical exposure is zero in *every* arm — at this crowd size the venue never becomes dangerous. So the system bought a safety improvement nobody needed, with a delay cost everybody paid. Do not hide this. Understand it, because the cause is precise and the fix is known. **Cause 1 — the venue is capacity-limited, not routing-limited.** Measured at the peak of the surge, every level-change route is at its service limit at the same moment: | Route | Capacity | In use | Spare | |---|---|---|---| | West foot-over-bridge (closed to 25%) | 130 /min | 129 | **1** | | Central foot-over-bridge | 900 /min | 900 | **0** | | East subway | 780 /min | 729 | 51 | Rerouting redistributes flow across capacity already in service. When all of it is saturated there is nothing to redistribute — which is why FlowTwin moves only 649 people here against 5,814 at Circuit Alpha. The decisiveness verdict is doing its job: most of the time it declines to act. **Cause 2 — the benchmark harness acts on a fixed review cycle; a human does not.** The FlowTwin arm re-evaluates every 180 s and applies whatever clears the 1.5% decisiveness bar, for the whole run. That makes the benchmark an **upper bound on intervention frequency**, not a model of the product's behaviour: in the console an operator presses the button when an alert says something is going critical, and on this venue nothing ever does. The measured cost above is the cost of intervening on a venue that did not need intervening on. **The fix, and it is the top of the roadmap.** The decisiveness threshold guards against candidates that are *indistinguishable from each other*. It does not yet guard against acting when *nothing is at risk*. A materiality gate — do not recommend an intervention if the projected peak stays below the venue's critical density across the whole window — closes it, and it is the same shape of judgement as the existing verdict. It is scoped in `ROADMAP.md` and it was found by this benchmark, which is the benchmark doing exactly what it is for. **What to say about it in a pitch.** Two true things, in this order: 1. *"A circuit is routing-limited: one exit failed while others had room, and we cut critical exposure to zero. A terminus is capacity-limited: all three staircases saturate at once, so we tell you rerouting won't help. Those are different problems and the system distinguishes them."* 2. *"And here's the honest part — on the terminus our benchmark harness keeps intervening anyway, on a cycle, and it costs journey time for a safety improvement that venue didn't need. That's a real finding from our own evaluation, and the gate that fixes it is the next thing we're building."* Owning that is worth more than a table with no weak column in it. The generated tables for all three venues, with every seed and every metric, are in `benchmarks/BENCHMARKS.md`. **No figure in this document was typed by hand.** --- ## 22. Every defect found and fixed This section exists because it is the strongest evidence that the model is right rather than merely convincing. Each of these was found by testing against physical reality, not by a linter. | # | Symptom | Root cause | Fix | |---|---|---|---| | 1 | Network throughput collapsed to ~1/10 of correct | Density averaged over a whole corridor, so a queue at a gate slowed people 200 m back with clear space | Density and speed evaluated per ~12 m cell | | 2 | Corridors absorbed impossible numbers of people | Links accepted at nominal capacity until physically full | Backward-wave receiving function — a link stops accepting *before* it is full, so congestion spills back upstream | | 3 | A 500/min gate discharged at under 200/min | Queue extent measured only at the stop line, so people had to walk *through* a near-jammed corridor to reach the back of the queue | Queue extent derived from everyone who has actually stopped | | 4 | Barcelona gridlocked with 18,000 stranded | Shortest paths used seating bowls as shortcuts, deadlocking against people leaving them | A route may start or end at a stand, never transit one | | 5 | 262 agents bouncing between two nodes forever | Re-weighted routing tables briefly made the corridor an agent was standing in look cheapest | U-turn guard; residue fell to 10 | | 6 | Repeated operator action permanently distorted the network | Intervention penalties compounded without limit | Penalties capped and decayed towards neutral each refresh | | 7 | Peak local density of 8.0 p/m² against a jam density of 5.4 | Admission limited by whole-edge headroom but not by space just inside the entrance | Entry-cell headroom limit | | 8 | The optimiser "recommended" on a rounding difference | Once a queue exists, the peak is already determined, so peak-dominated scoring cannot separate candidates | End-of-window objectives plus a 1.5% decisiveness threshold, with an explained hold verdict | | 9 | The explainability panel went blank exactly when it mattered | On a hold verdict, the winner *is* the baseline, so the comparison was an arm against itself | Falls back to the best rejected alternative, labelled as such | | 10 | A control that appeared to work and did nothing | The What-If capacity slider sent an empty override | The slider retunes the scheduled event itself | | 11 | The alert panel was effectively invisible (opacity 0.26) | Cards rebuilt 5×/second, restarting their entry animation | Cards keyed on structure; live values written in place | | 12 | New runs appeared to hang | Orphaned sessions from refreshed tabs kept simulating and starved the event loop | Sessions with no subscribers idle and are reaped | | 13 | A 66-row model inference took 1,000 ms | BLAS/OpenMP thread pools fighting over a tiny batch | Thread limits pinned before numpy is imported (9 ms) | | 14 | An opened emergency gate attracted nobody | An emergency route is geometrically longer, so the router kept using the old way | Opening a gate applies a routing bonus — unlocking it is also staffing and signing it | | 15 | The perception sample route 404'd | `samples()` advertised URLs for a route that was never implemented | Route added, with the filename reduced to its basename so a crafted name cannot escape the directory | --- ## 23. What is deliberately not built Recorded rather than hidden. Being able to answer "what's missing?" crisply is worth more than pretending nothing is. | Item | Status | Reasoning | |---|---|---| | Hugging Face chain verified against live weights | **Open** | No network route from the build environment. One command, one hour, on any networked machine. | | Personnel dispatch | Not built | The natural next feature — it answers *who should act*, which pairs perfectly with the hold verdict. Scoped in `ROADMAP.md`; about half a day. | | Ablation study | Not built | Nearly free; the benchmark harness already supports arms. Would answer "which part is doing the work". | | Venue upload / in-browser editor | Not built | Venues are JSON against a published schema and `build_venues.py` shows how to author one, but there is no upload endpoint. | | Multi-camera fusion | Not built | Single-frame perception only. | | Natural-language assistant | **Deliberately excluded** | Keeping every number in the decision path arithmetic is why the explainability story holds. | | Redis / PostgreSQL / Docker | **Deliberately excluded** | Simulation state is in-memory by nature. Rationale in `ARCHITECTURE.md §10`. | --- --- # Part V — The hackathon ## 24. Mapping to the evaluation criteria The rubric is 100 points across eight criteria. Here is what to point at for each. ### 1. Problem Understanding & Relevance — 15 Lead with §2.1: **crowd danger is not a headcount problem, it is a local density and flow problem**, and the failure is non-local and delayed. Then the killer detail: *by the time you can see it, rerouting may no longer help* — and show that the system knows this and says so. Ground it in the documented Barcelona 2022 conditions, then widen to the applications the problem statement names: railway stations, IPL egress, airport terminals, mass gatherings. Point at the terminus venue as proof you took "railway station design" literally rather than rhetorically. ### 2. Innovation & Originality — 15 The single strongest claim: **the recommendation is a measurement, not a rule.** Nobody else in this room will clone their entire simulation state eight times and race the futures against each other. Second: **the hold verdict**. A system that refuses to recommend when the measurement cannot separate the options, and explains why with the real discharge rate and clearance time, is a genuinely unusual piece of engineering judgement. Third: **the emergency exit is absent from routing, not expensive** — a small modelling decision with a large consequence, and easy to explain in ten seconds. ### 3. Technical Implementation — 20 The heaviest-weighted criterion, and where the depth lives: - Mesoscopic architecture chosen *because* counterfactuals must be affordable — 2–4 ms per step at 40,000 agents. - Weidmann fundamental diagram, per-cell evaluation, backward-wave receiving function, entry-cell admission, FIFO capacity budgets with fractional carry. - Gradient boosting validated on **disjoint seeds** against an analytic baseline, and used only if it wins. - Reverse-Dijkstra next-hop tables with hysteresis, commitment and cycle-breaking. - Byte-identical counterfactual branching including RNG state. - 79 tests, plus a real-browser acceptance run that fails on any console error. Have §22 (the defect table) ready. Fifteen real bugs, each with the symptom that revealed it, is the most persuasive artefact in the project. ### 4. Impact & Scalability — 15 Impact: the measured table — **critical exposure to zero, peak density −43%, max queue −48%, and journey times slightly better** — against a competent static plan, not a straw man. Scalability, and be specific rather than hand-wavy: - **Venue scalability** — three venues, one schema, zero venue-specific code. The terminus needed one node type. - **Population scalability** — 40,000 agents at 2–4 ms/step; 78,000 in Barcelona; hard-capped at 120,000. - **Deployment scalability** — one process, one command, no datastore, no build. - **Input scalability** — swap simulated agents for camera observations at the observation schema; nothing downstream changes. ### 5. User Experience & Design — 10 The map dominates; panels are subordinate. Every number on screen is measured; none are hard-coded. Alerts state their cause and their lead time. The strategy table is auditable row by row. The "why" panel is generated from the same arithmetic that produced the score. Mention the invisible-alert-panel bug (§22 #11) if design comes up — it shows the polish was verified, not assumed. ### 6. Completeness & Functionality — 10 One command, and the whole loop runs end to end without manual intervention. Three venues, four scenarios, 79 tests, a real-browser acceptance script, generated benchmarks, and six documents. `scripts/ui_check.py` output is the proof: it walks the entire acceptance path and fails on any error. Be honest about the one open item (§23) rather than letting a judge find it. ### 7. Presentation & Demo — 10 See §26. The rule: **run it live, and let the numbers on screen be the evidence.** Never read a figure aloud that is not visible behind you. ### 8. Q&A & Defense — 5 See §27. The general strategy: for every question, answer with a measured number or a named file, and if the answer is "not built", say so immediately and say why. --- ## 25. The pitch ### The 30-second version > "When a crowd turns dangerous, the problem isn't that there are too many people > — it's that there are too many people in one corridor, and by the time you can > see it, the queue that would need to move already can't. > > FlowTwin is a digital twin of the crowd. It simulates forty thousand people > walking through a venue in real time, predicts where flow will break down > ninety seconds before it does, and then does something no monitoring system > does: it clones the entire crowd, tries every option an operator has on its own > copy, and measures which one actually works. > > Across eight independent runs, time spent in dangerous density goes to zero — > and people get home *faster*, not slower." ### The 90-second version Add these three beats: **The mechanism, concretely.** "Eight complete copies of the crowd — every person's position, route and compliance, and the random number generator's internal state — one per candidate action. Each runs forward four minutes. Nine seconds later we have eight measured futures and we pick the best. The recommendation is a measurement, not a rule, and there is no language model anywhere in that path." **The honesty.** "And if you act too late, it tells you. Press the button fifteen minutes in and every option comes back identical, because a four-thousand-person queue drains at the gate's rate no matter where you send people. So it says: this exit is discharging at its limit with 3,275 people held, it needs nine minutes to clear, rerouting can't reach them, your remaining levers are capacity and staffing. A system that knows when it can't help is worth more than one that always has an answer." **The generality.** "It's not a motorsport product. Same engine, a railway terminus on a festival night — six platforms emptying through two foot-over-bridges and a subway. One new node type, zero special-case code. And on that venue it tells us rerouting *won't* help, because all three staircases are at their limit at once — which is the difference between a venue with an operations problem and a venue with a design problem." ### The one line to leave them with > **"Don't wait for the bottleneck. Simulate the intervention before it happens."** --- ## 26. The demo, minute by minute **Before you start:** server running, browser at 100% zoom, Simulation 1 pre-selected but **not** started. Have `benchmarks/BENCHMARKS.md` open in a second tab. Know your seed. | Time | What you do | What you say | |---|---|---| | **0:00** | Point at the header and the scenario switcher | The hook (§25). Name the three venues in one breath and move on. | | **0:30** | — | "Monitoring tells you where people *are*. The dangerous question is where flow will *fail*, and what to do before it does." | | **1:00** | Select **F1 Circuit Stress Test**, press **Run simulation**, set speed **20×** | "Forty thousand spectators, four exits, four destinations. At four minutes, Exit B loses half its throughput — a real change to the network, not an annotation." | | **1:45** | Point at the map as the east side reddens | "That's measured density per twelve metres of corridor, not a heat blob." | | **2:00** | Point at the Alerts panel | "Critical in ninety-six seconds. And it says *why*: density rising, velocity collapsed, queue growing. Those are the same six terms that produced the risk score." | | **2:30** | Point at the Prediction panel, click **Model accuracy** briefly | "Gradient boosting, trained on simulator ground truth, validated on seeds it has never seen — 47 to 59 per cent better than the physics baseline. If it hadn't beaten the baseline we'd be showing you the baseline." | | **3:00** | Press **Simulate strategies** | "Now the part that matters. Eight copies of the crowd — every person, every route, and the random number generator's internal state. One candidate each. Four minutes forward." | | **3:20** | Drawer opens; walk the table left to right | "These aren't estimates. Every column is measured from a run that happened. Redirect 40% wins by seventeen per cent." | | **3:40** | Point at the **why** panel | "Peak density down 28%, queue at end of window down 24%, critical time to zero, journey time unchanged, 834 people rerouted. That's the arithmetic that produced the score — there's no narrative layer that could drift from it." | | **4:00** | Press **Apply intervention** | "Same code path that was measured." | | **4:20** | Point at the reroute paths and the falling queue metric | "About seventy per cent comply. That's modelled per person, which is why the improvement is believable." | | **4:45** | Switch to **Barcelona 2022**, read the left rail | The provenance beat — facts with sources, assumptions labelled, and the disclaimer said out loud: *"we did not recreate Barcelona; we reconstructed the documented conditions."* | | **5:15** | Switch to **Railway Terminus**, run at 40× | "Same engine, no motorsport. Six platforms, two foot-over-bridges, a subway. The failure happens in the *middle* of the venue, not at the perimeter." Then the food court and the amber emergency gate (§19). | | **5:30** | Point at the benchmark table | "Eight independent seeds. Critical exposure to zero, peak density down 43%, max queue down 48% — and journeys six per cent *faster*. Every figure generated, none typed." | | **5:45** | — | The closing line (§25). | **If you have a spare minute, this is the beat to add:** the hold verdict. Re-run Simulation 1, jump to T+15:00, press **Simulate strategies**, and read the verdict aloud. It is the single most memorable thing in the demo. **Rules for yourself.** Run live. Never read a number that is not on screen. Press *Simulate strategies* while the prediction still says "critical in N seconds", not after the alert has been red for five minutes. --- ## 27. Q&A defence **"Is this real or is the simulation faked?"** Every number on screen is computed. The venue JSON has capacities and areas; the physics is Weidmann's fundamental diagram; the seed is displayed and the run is reproducible from it. Change the crowd size in the left rail and re-run — the outcome changes because the physics changed. **"Where is the AI?"** Three places, and be precise about each. A gradient-boosted model predicting density at four horizons, validated on disjoint seeds and used only because it beats a strong analytic baseline by 47–59%. A Hugging Face crowd-counting model on the perception path, converting camera frames into the same observation schema the simulator produces. And the decision layer — counterfactual search over a generated candidate set with multi-objective scoring. Deliberately **not** a language model, because the explainability story depends on the reasoning being the same arithmetic that produced the score. **"Isn't this just a shortest-path algorithm?"** Shortest path is baseline A in the benchmark, and it is the one FlowTwin beats by 43% on peak density. There is also baseline B — a proper capacity-aware pre-event plan using method-of-successive-averages assignment — which is what a competent operations team actually produces. FlowTwin beats that on every safety metric too. **"How do you know the recommendation is right?"** We don't assert it, we measure it. Each candidate is applied to a byte-identical clone and simulated forward; the numbers in the table come from those runs. And when the measurement can't separate the options, the system says so rather than picking one — that threshold is 1.5% and it's in the config. **"What if a judge presses the button at the wrong moment?"** Then they see the hold verdict, which is a better demo than the recommendation. That was a real bug we found and fixed: the optimiser used to pick a winner on a rounding difference. Now it explains why nothing helps, with the measured discharge rate and clearance time. **"Have you verified the Hugging Face model?"** Not against downloaded weights — the build environment has no route to huggingface.co, and I'd rather say that than claim otherwise. The chain, the loader, the local CSRNet architecture, the manifest and the failure behaviour are all implemented and tested; one command closes it on a networked machine. And what it does *today* if no model loads is report the actual error — it has never fabricated a count, and there's a test asserting it. **"Would this work at my venue?"** The venue is JSON against a published schema — nodes with positions, areas and service rates; edges with lengths, widths and capacities. Three venues ship, including a railway terminus, and none of them required engine changes. What is *not* built is an upload UI, so today it's a file you author with the script in `scripts/build_venues.py`. **"Does it scale to a Kumbh-scale gathering?"** The simulation is capped at 120,000 agents and runs 78,000 comfortably at 2–4 ms per step. Beyond that the honest answer is that the mesoscopic model would need to be partitioned, and that the harder problem at that scale isn't compute — it's that a single operator can't act on a hundred simultaneous bottlenecks, which is why personnel dispatch is the next feature. **"What would you build next?"** Personnel dispatch. Right now every lever moves the crowd; none of them moves staff. And it pairs exactly with the hold verdict — when routing can no longer help, "send four stewards to Exit B" is what the system should be able to say. **"Your railway venue barely improves. Isn't that a failure?"** It's the most useful result we have. That venue is *capacity*-limited, not routing-limited: at the peak of the surge all three level-change routes are at their service limit simultaneously — one, zero and fifty-one people per minute of spare capacity, with eight thousand people queued behind them. Rerouting redistributes capacity that's already in service; when all of it is saturated there is nothing to redistribute. So the engine says so, instead of claiming a win. And that answer is actionable in a different way: it says the fix is a fourth bridge or a phased platform release, not better signage. The problem statement lists railway station *design* as an application — that is what designing looks like. **"What's the weakest part?"** The Hugging Face path being unverified against live weights, and the absence of personnel dispatch. Both are in `ROADMAP.md` with the work scoped. The Barcelona static baseline also produces results identical to shortest path, because that topology mostly has one sensible route per origin-destination pair — a real property of the venue, documented rather than hidden. --- ## 28. Failure drills Practise these once. Confidence when something breaks is worth more than the thing not breaking. | If this happens | Do this | |---|---| | The live run stalls or the connection chip goes red | Re-select the scenario — the app tears the session down and starts cleanly. If it recurs, switch to the recorded fallback: it replays through the identical interface. | | Strategy simulation takes longer than expected | Say what it is doing: "that's eight full simulations running." It is ~9 s at 40,000 agents; at 78,000 it is longer and that is honest. | | The perception panel shows no model | This is the designed behaviour and a good beat. "No weights on this machine, so it reports the error instead of guessing. It has never invented a count." | | A judge asks for a venue you don't have | Show the venue JSON and `scripts/build_venues.py`. The schema is the answer. | | The projector eats the dark theme | The metrics strip and the strategy table are the highest-contrast elements. Demo from those. | | Everything fails | `docs/DEMO.md` carries the full narrative and every real number, and `benchmarks/BENCHMARKS.md` is generated evidence you can read from. | --- *Last verified against the repository at the commit that introduced the railway terminus, the emergency-exit routing semantics, the end-of-window optimiser objectives and the decisiveness verdict.*