Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions ACCESSIBILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,14 @@
Intersection Lab is a visual simulator: its main content is an animated map of traffic
and a set of live charts. That makes some of it hard or impossible to use without sight,
and some of it hard to use without a mouse. This page says what works today, what
doesn't, and how to get every result without the visual app.
doesn't, and which results are available without the visual app.

Last reviewed: November 2026, version 0.5.1.

## Every result is available as text
## Results available as text

Everything the app measures can be produced from the command line as plain-text tables,
which work with screen readers, braille displays and any terminal:
The main results can be produced from the command line as plain-text tables, which work
with screen readers, braille displays and any terminal:

```bash
cargo run --release --bin bench all 20 6 # every controller on every layout
Expand All @@ -20,6 +20,13 @@ cargo run --release --example lpi # pedestrian safety treatments
cargo run --release --example cooperative # signal-free cooperative crossing
```

These commands print the average and 95th-percentile delay, throughput, stops, person
delay, pedestrian waits and near misses, a corridor's end-to-end trips and the safety
counts. They don't print everything the app shows. Some numbers appear only in the app,
such as CO₂ per vehicle, the level of service, the breakdowns by approach, movement and
vehicle class, the charts and a selected vehicle's own figures, and only the
`cooperative` example prints the maximum delay.

The [README](README.md#results) and [docs/insights.md](docs/insights.md) report the
findings as text and tables, and every image in them has a text description.

Expand Down
6 changes: 3 additions & 3 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,9 @@ Last reviewed: November 2026, version 0.5.1.
[SECURITY.md](SECURITY.md) and the [assurance case](docs/assurance-case.md) will be
updated to match.
* **Accessibility.** Work through the known limitations listed in
[ACCESSIBILITY.md](ACCESSIBILITY.md): keyboard ways to select a vehicle, place sensors
and choose a crosswalk corner, shortcuts between panels, map views that don't rely on
color alone, and a light or high-contrast theme.
[ACCESSIBILITY.md](ACCESSIBILITY.md): keyboard ways to select a vehicle and choose a
crosswalk corner, shortcuts between panels, map views that don't rely on color alone,
and a light or high-contrast theme.

## If time allows

Expand Down
25 changes: 13 additions & 12 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -713,12 +713,12 @@ this step. A stopped driver waits out their reaction time before pulling away.
* It retires vehicles that have reached the end of their route. Each becomes a
`stats::Done` record and, in a corridor, an `Exit` for `World` to hand over.
* **Safety check (`check_overlaps`):** when `check_safety` is on, as it is in the app,
the safety and cooperative tests, the sweeps and the corridor and cooperative studies,
every step looks for touching vehicles. Bodies are chains of oriented rectangles that
bend through turns (`body`, `obb_overlap`). It flags vehicles on the same lane that
overlap by more than 0.3 m, and runs the rectangle test, with rectangles shrunk by
0.25 m, on pairs in or just past the box. Each pair counts once per step in
`collisions`.
`bench`'s strategy tables, the safety, cooperative and green-wave tests, the sweeps and
the corridor and cooperative studies, every step looks for touching vehicles. Bodies
are chains of oriented rectangles that bend through turns (`body`, `obb_overlap`). It
flags vehicles on the same lane that overlap by more than 0.3 m, and runs the rectangle
test, with rectangles shrunk by 0.25 m, on pairs in or just past the box. Each pair
counts once per step in `collisions`.
* **Drawing helpers (`body_lagged`, `lag`, `lc_offset`, `ped_pos_lerp`):** let the app
draw positions *between* steps for smooth motion. The safety check and lane changes
use the same functions with no lag.
Expand Down Expand Up @@ -3028,7 +3028,7 @@ gap policy comparison: batches with fail-safe, mitigated and nominal gaps at 27.
#### About

<img src="images/architecture/about-window.png" width="618" alt="About window:
Intersection Lab 0.5.1, its description, copyright, dual MIT and Apache 2.0 license, the
Intersection Lab 0.6.0, its description, copyright, dual MIT and Apache 2.0 license, the
repository link and the start of the third-party license notices">

The About window shows:
Expand Down Expand Up @@ -3065,7 +3065,7 @@ The notices run to thousands of lines, so only the visible lines are laid out.
|---|---|
| `src/main.rs` | **Native:** opens a 1600 × 1000 window (at least 1100 × 700) with the embedded icon and runs `gui::App`. Release builds on Windows use the GUI subsystem, so no console window appears. **Browser:** finds `<canvas id="app">` in `web/index.html`, starts `eframe::WebRunner` and replaces the loading message with the outcome |
| `src/lib.rs` | Declares the four modules. `scenario(kind, mode, ctrl, demand, sensors, seed) -> Sim` builds a headless simulation, and `run_scenario(sim, warmup, duration) -> (Summary, collisions)` runs it and summarizes everything after the warm-up. `bench` and the app's benchmarks use them; the browser's benchmark queue steps each `Sim` itself and calls `Stats::summary` the same way |
| `src/bin/bench.rs` | `bench [layout\|all] [minutes] [seeds] [demand-scale] [pattern]` prints a table per layout: every control strategy, averaged over seeds 1,000 and up after a 300 s warm-up, with delay, 95th percentile delay, throughput, stops, person delay including unserved vehicles, pedestrian wait, unserved vehicles and collisions. `bench sensors <layout> [minutes] [seeds]` runs the command-line sensor study: the app's five sensor packages (§9.4) and an ideal version of loops, camera and radar, then weather and faulty loops |
| `src/bin/bench.rs` | `bench [layout\|all] [minutes] [seeds] [demand-scale] [pattern]` prints a table per layout: every control strategy, averaged over seeds 1,000 and up after a 300 s warm-up, with delay, 95th percentile delay, throughput, stops, person delay including unserved vehicles, pedestrian wait and unserved vehicles. The `coll` column counts the overlaps found by the safety check (§6.1), which these runs turn on: a total over the seeds, warm-up included. `bench sensors <layout> [minutes] [seeds]` runs the command-line sensor study, without the safety check: the app's five sensor packages (§9.4) and an ideal version of loops, camera and radar, then weather and faulty loops |
| `src/bin/train.rs` | Trains the Deep RL and Hybrid networks (§8.5) |

### 10.2 Studies
Expand All @@ -3087,21 +3087,22 @@ The examples are the studies behind `docs/insights.md` and

### 10.3 Tests

`cargo test` runs nine integration test files and the unit tests in `sim/coop.rs`,
`sim/signal.rs` and `gui/mod.rs`. CI runs them in release mode on Linux, macOS and
Windows, and measures how much of the crate they cover (§11).
`cargo test` runs nine integration test files and the unit tests in `bin/bench.rs`,
`sim/coop.rs`, `sim/signal.rs` and `gui/mod.rs`. CI runs them in release mode on Linux,
macOS and Windows, and measures how much of the crate they cover (§11).

| File | Tests | What they require |
|---|---:|---|
| `tests/safety.rs` | 4 | Every layout and control combination runs without collisions and serves at least 80% of arrivals at default volumes (65% under two-way stop and under all-way stop on the arterial, which are over capacity); different controllers receive identical arrivals; no gridlock in seeds that used to jam; no collision between a turn finishing late in the yellow and the next stage's traffic |
| `tests/cooperative.rs` | 14 | The cooperative crossing: no signals, sensors or crosswalks; its geometry and phase order; every gap policy safe under heavy demand, bursts, heavy vehicles and live switching; about 18,000 vehicles per hour served at the design demand, about 19,000 oversaturated and less with single left lanes or first come, first served; reproducible runs; light traffic barely delayed; emergency vehicles first; hand-placed vehicles crossing every way. Every run must show no monitor violations |
| `tests/cooperative.rs` | 14 | The cooperative crossing: no signals, sensors or crosswalks; its geometry and phase order; every gap policy safe under heavy demand, bursts, heavy vehicles and live switching; about 18,000 vehicles per hour served at the design demand, about 19,000 oversaturated and less with single left lanes or first come, first served; reproducible runs; light traffic barely delayed; emergency vehicles first; hand-placed vehicles crossing every way. Every run, except those of the no-signals, single-left-lane and reproducibility tests, must show no overlap between vehicle bodies, no zone entered while occupied, no box entry without a reservation, no step off a granted trajectory, no crossing inside its required gap and no line or zone time off its reservation (both to within a microsecond), and at least one crossing measured |
| `tests/pedestrian_rule.rs` | 4 | Deep RL's shield serves a crosswalk whose pedestrians have waited longer than `PED_MAX_WAIT`, longest wait first, and leaves shorter waits to the controller; the reward counts waiting pedestrians |
| `tests/weights_files.rs` | 6 | The shipped weights load, misshapen networks are rejected, a Hybrid without a fitting network keeps its base tuning and says so, Hybrid files saved with a score that isn't finite load again, a copy that doesn't load is skipped for the next one and networks that overflow don't crash (§8.7) |
| `tests/green_wave.rs` | 2 | The green wave runs every signal of a corridor fixed-time, and ending it gives back the controllers they ran before, except where another was chosen during the wave, without collisions; a single intersection isn't coordinated |
| `tests/networks.rs` | 7 | Backpropagation agrees with the gradient measured numerically, Adam fits a line, the shape check rejects every malformed network (sizes whose product overflows included), the target network moves part way toward the online one, the action mask is respected, Double DQN learns which action pays in which state and the replay memory keeps the latest 60,000 transitions |
| `tests/gui.rs` | 16 | The app, run without a window by `egui_kittest` and driven through its accessibility tree, the keyboard and the pointer: every panel opens and every control has a name; Space pauses and Step advances one second; every layout, control mode and controller runs, side by side too and along a corridor with the green wave; the demand, sensor and operations settings apply; the learning controllers show what they learn; every overlay and coloring draws; vehicles and pedestrians placed by hand, movements an approach lacks refused; a clicked vehicle's details; pan, zoom and *Fit view*; both benchmark windows; *About* |
| `tests/scripted.rs` | 8 | Each `TS_*` variable of the scripted mode sets up its scene, a scripted screenshot stops the clock at its moment and screenshots are valid PNG files. The app reads the variables as it starts, so each scene opens in a process of its own |
| `tests/tools.rs` | 7 | `bench` compares every strategy on every layout without collisions, takes each arrival pattern and runs the sensor study; `train` trains, saves and resumes both learning controllers, in a scratch directory with its own home directory |
| `src/bin/bench.rs` | 1 | A run for a strategy table counts a vehicle placed on top of another, so the `coll` column can show an overlap |
| `src/sim/coop.rs` | 4 | Approach profiles arrive on time and at speed, a short run-up enters slower but on time, the gap policies give the gaps in §6.11 and the following law holds its time gap |
| `src/sim/signal.rs` | 1 | The signal history records a change's yellow and all-red between the two greens, with no gaps |
| `src/gui/mod.rs` | 1 | The safety monitors' margin over the gap keeps its sign |
Expand Down
8 changes: 6 additions & 2 deletions docs/assurance-case.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,8 +68,12 @@ The design follows the principles set out by Saltzer and Schroeder:
and four direct dependencies (eframe, egui, serde and serde_json, plus two small ones
for the browser build). The simulation and the neural network are the project's own
code.
* **Fail-safe defaults.** A weights file that doesn't parse or doesn't fit its controller
is rejected, and the controller starts from a fresh network instead of running it.
* **Fail-safe defaults.** A network that doesn't fit its controller is never run. A
weights file that doesn't load is skipped for the next copy, ending with the copy
built into the executable, and a Hybrid file whose network doesn't fit loads without
the network and runs only its saved base tuning. If no copy loads, Deep RL starts from
a fresh network and the Hybrid runs the planner's default tuning (see
[section 8.7 of the architecture document](architecture.md#87-controlweightsrs-loading-and-saving)).
Every workflow's token is read-only unless a job needs more, and packages are signed
only on version-tag builds.
* **Complete mediation.** Every weights file goes through the same loader and the same
Expand Down
Binary file modified docs/images/architecture/about-window.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
49 changes: 46 additions & 3 deletions src/bin/bench.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,28 @@
//!
//! usage: bench [layout|all] [minutes] [seeds] [demand-scale] [pattern]
//! bench sensors <layout> [minutes] [seeds] (sensor-package study)
//!
//! Each row of a strategy table gives means over the seeds, except in the `coll` column:
//! the overlaps between vehicle bodies that the safety check counted, warm-up included,
//! totaled over the seeds. It should always be 0.

use intersection_lab::control::CtrlKind;
use intersection_lab::sim::ControlMode;
use intersection_lab::sim::demand::{DemandConfig, Pattern};
use intersection_lab::sim::network::{LayoutKind, Network};
use intersection_lab::sim::sensors::{Conditions, SensorConfig};
use intersection_lab::sim::stats::Summary;
use intersection_lab::sim::{ControlMode, Sim};
use intersection_lab::{run_scenario, scenario};
use std::time::Instant;

/// [`run_scenario`] with the safety check on, so that the overlaps it returns were
/// counted. The check is off in a new simulation, and a strategy table's `coll` column
/// could then only be zero.
fn run_checked(mut sim: Sim, warmup: f64, duration: f64) -> (Summary, u64) {
sim.check_safety = true;
run_scenario(sim, warmup, duration)
}

/// How much does each sensor package help each sensor-driven controller, with ideal
/// and field-realistic sensors, across weather, and with failed loop detectors?
fn sensor_study(kind: LayoutKind, minutes: f64, seeds: u64) {
Expand Down Expand Up @@ -181,7 +194,7 @@ fn main() {
&sensors,
1000 + seed,
);
let (s, coll) = run_scenario(sim, 300.0, minutes * 60.0);
let (s, coll) = run_checked(sim, 300.0, minutes * 60.0);
acc[0] += s.avg_delay;
acc[1] += s.p95_delay;
acc[2] += s.throughput_vph;
Expand All @@ -191,7 +204,9 @@ fn main() {
acc[6] += s.unserved as f64;
acc[7] += coll as f64;
}
for a in acc.iter_mut() {
// Means over the seeds, except the overlaps: a total, so that one
// overlap in one run can't round away.
for a in acc.iter_mut().take(7) {
*a /= seeds as f64;
}
(name, acc, t0.elapsed().as_secs_f64())
Expand All @@ -207,3 +222,31 @@ fn main() {
}
}
}

#[cfg(test)]
mod tests {
use super::*;

/// The T-intersection after a minute, with one vehicle moved on top of another in
/// its lane.
fn overlapping() -> Sim {
let kind = LayoutKind::Tee;
let demand = DemandConfig::default_for(&Network::build(kind));
let mut sim =
scenario(kind, ControlMode::Signal, CtrlKind::Fixed, &demand, &SensorConfig::default(), 1000);
sim.run_for(60.0);
let n = sim.vehicles.len();
let (one, other) = (0..n)
.flat_map(|i| (i + 1..n).map(move |j| (i, j)))
.find(|&(i, j)| sim.vehicles[i].link() == sim.vehicles[j].link())
.expect("two vehicles in one lane");
sim.vehicles[other].s = sim.vehicles[one].s;
sim
}

#[test]
fn a_strategy_run_counts_overlaps() {
let (_, coll) = run_checked(overlapping(), 0.0, 1.0);
assert!(coll > 0, "two vehicles overlap, and the `coll` column would show 0");
}
}
4 changes: 3 additions & 1 deletion src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,9 @@ use sim::stats::Summary;
use sim::{ControlMode, Sim};

/// Run a headless simulation (see [`scenario`]) for `warmup + duration` seconds and
/// summarize everything that exited after warm-up, with the number of overlaps.
/// summarize everything that exited after warm-up, with the number of overlaps. Overlaps
/// are counted, from the start of the run, only if the simulation's `check_safety` is
/// on; it is off in a simulation that [`scenario`] has just built.
pub fn run_scenario(mut sim: Sim, warmup: f64, duration: f64) -> (Summary, u64) {
sim.run_for(warmup + duration);
let s = sim.stats.summary(warmup, sim.t, &sim.vehicles, &sim.queues);
Expand Down
3 changes: 2 additions & 1 deletion tests/tools.rs
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,8 @@ fn bench(dir: &Path, args: &[&str]) -> String {
run(env!("CARGO_BIN_EXE_bench"), dir, args, &[])
}

/// The rows of a strategy table, with the number of collisions each run had.
/// The rows of a strategy table, each with the overlaps between vehicles that the safety
/// check counted in its runs (`bench` turns the check on for these tables).
fn collisions(table: &str) -> Vec<(String, f64)> {
table
.lines()
Expand Down
Loading