Usage: running simulations and producing plots

This page catalogues every user-facing script in the repository: how to run an evacuation simulation, every run.py flag with its default, and which plotting script consumes each artefact. All commands assume the project venv (uv run ...) and run from the repository root. What each output file contains is on Outputs; error messages and their fixes are on Troubleshooting.

Running a simulation — run.py

run.py is the single entry point for an evacuation run. It loads a JSON-first JuPedSim scenario, optionally couples it to an FDS case for smoke-speed / FED / visibility, and writes CSV/SQLite artefacts for post-processing.

uv run python run.py --scenario <scenario.json|.zip|dir> [options]

Scenario selection and export

FDS coupling (smoke, FED, visibility)

--fds-dir must point at the output of a finished FDS run: the directory that holds the .smv file and the slice files. A directory with only the .fds deck stops the run with OSError: No simulations were found in the directory. Your deck has to write specific slices; see What your FDS case must provide for the lines to add and the failure modes that stay silent unless you read the warnings.

Dynamic rerouting (smoke-aware route choice)

The default route-choice model does not trigger the visibility model. The default "gate" route-cost model reads no vismap: its smoke criterion is the optical depth along the route polyline, and sign legibility only decides what enters an agent’s cognitive map. A deck whose agents all start fully familiar therefore builds no visibility model at all unless you pass --vis-cache or --clear-air-visibility. A deck with discovery agents builds one either way, because they need it to learn the graph. See route-cost-gate.md.

Smoke-blind runs and exit replay

For ASET/RSET comparisons the same FDS output can be run in three arms: a smoke-blind arm, a speed-only arm that keeps the smoke-blind arm’s exits, and the fully coupled default (#341).

A smoke-blind run with a fire gives the same trajectories as the run without the fire, for the same scenario and seed. Replay pairs the n-th agent spawned from an origin in one run with the n-th agent spawned from that origin in the other, which needs the same scenario and seed. The origin is initial for the agents placed at t = 0 and flow:<distribution> for a flow source, so a source that is blocked and spawns later does not shift the pairing of another. JuPedSim ids are not used: they can skip a number when a spawn position is refused, and a slower crowd changes which positions are refused. Every per-agent draw, such as the familiarity map, the target points and the journey variant, is seeded from this spawn order, so paired agents draw the same in both runs. An exit history written before per-agent draws were seeded this way (its run’s manifest has no agent_seeding key) still replays without error, but pairs agents whose draws differ; write it again. A replayed run fails when a spawn is missing from the file, when the file names an exit the scenario lacks, or when an agent cannot be sent to its exit; it logs a warning when agents of the file were never spawned. With rerouting on, a replayed agent can still switch exits, and the run logs a warning. The three arms, with tenability recorded but not acting in all of them, so that incapacitated agents do not stay in the building and lengthen the evacuation:

# U: smoke-blind; writes the exits for S
uv run python run.py --scenario S.json --fds-dir FDS --smoke-blind \
    --output-exit-history u_exits.csv --output-sqlite u.sqlite
# S: smoke slows agents, exits and routes as in U
uv run python run.py --scenario S.json --fds-dir FDS --no-enable-rerouting \
    --disable-tenability --replay-exits u_exits.csv --output-sqlite s.sqlite
# R: smoke slows agents and acts on routing
uv run python run.py --scenario S.json --fds-dir FDS --disable-tenability \
    --output-sqlite r.sqlite

Evacuation with and without the fire runs these arms against a run without the fire and compares them.

Tenability (FIC slowdown and incapacitation)

The two dose tracks are independent:

• Gas FED runs when --fds-dir has the CO, CO₂ and O₂ slices (HCN, NO, NO₂ and the irritants are used if present). It is on by default whenever those slices exist.
• Heat FED runs when --enable-heat-fed is given and --fds-dir has a TEMPERATURE slice. It is off by default, as FDS+Evac has no heat dose.

Incapacitation applies to whichever track runs. Without --fds-dir neither runs and the flags below have no effect. The FIC slowdown (a pyFDS-Evac assumption, source unknown; #147) is off by default, as FDS+Evac has none. The equations are on Models › FED and Models › Heat.

Heat dose (opt-in)

All flags in this table need --enable-heat-fed; without it they have no effect. With --fds-dir, the run then warns for --heat-endpoint, --heat-clothing, --heat-fed-method, --heat-radiant-source and --heat-regime; the other heat flags are ignored silently. The laws, parameters and their sources are on Models › Heat; the table only lists what each flag sets.

Seed and precedence

• --seed N overrides the scenario’s baseSeed; a scenario without one uses 42.
• --constant-extinction takes precedence over the FDS extinction slice for walking speed only.

Python API and command line

run.py and the web GUI build their models with build_run_kwargs. run_scenario() called directly builds nothing you do not pass, so the same scenario can behave differently:

For a run identical to the command line, parse the same flags and build the keywords the same way:

import run  # run.py at the repository root
from pyfds_evac import build_run_kwargs, load_scenario, run_scenario

args = ["--scenario", "assets/iso_table22_coupled/config_a.json",
        "--fds-dir", "assets/iso_table22_coupled/fds/a"]
opts = run._build_parser().parse_args(args)
scenario = load_scenario(opts.scenario)
result = run_scenario(scenario, **build_run_kwargs(scenario, opts))
print(f"FED max: {result.metrics['fed_max']:.3f}")
result.cleanup()

Run it from the repository root with PYTHONPATH=. uv run python script.py, so that run.py can be imported. It prints FED max: 1.170.

A crowd in a real fire does this end to end.

Agent visualisation

Agent 3-D visualisation is handled by fds-viewer, which loads the JuPedSim trajectory SQLite written by --output-sqlite (and its optional agent_scalars table for FED/speed colouring).

Typical invocations

# Bare JuPedSim run, no smoke coupling
uv run python run.py --scenario assets/t_junction/config.json --cleanup

Simulation stopped after 300.00 s (144/150 evacuated, 6 remaining).

# FDS-coupled run with all diagnostic outputs, on a tracked FDS output
uv run python run.py --scenario assets/iso_table22_coupled/config_a.json \
    --fds-dir assets/iso_table22_coupled/fds/a \
    --output-sqlite results/demo.sqlite \
    --output-smoke-history results/smoke.csv \
    --output-fed-history results/fed.csv \
    --output-route-history results/routes.csv \
    --output-route-cost-history results/route_costs.csv

Configuring smoke calculation.
Configuring FED calculation.
Heat FED is off; pass --enable-heat-fed to accumulate it.
Configuring rerouting.
Configuring tenability (FIC slowdown=off, FIC alpha=0.7, min=0.3, FED median=1.0, incapacitation=deterministic, heat FED median=1.0, heat incapacitation=deterministic).
…
Simulation stopped after 1150.00 s (0/1 evacuated, 1 remaining).
Route switches: 0
Route cost samples: 1149

The occupant of this ISO 20414 Test 19 case never leaves; it is incapacitated at 982 s. Rerouting is on by default, so --enable-rerouting is not needed. The tracked FDS output of the T-junction fire is not in the repository; run assets/t_junction/t_junction.fds with FDS, or see A crowd in a real fire.

Inspecting an FDS case

scripts/inspect_fds.py summarises what quantities FDS wrote and whether they are within tenability-relevant ranges. Its --height defaults to 2.0 m; pass 1.6 to match run.py (#313).

uv run python scripts/inspect_fds.py assets/iso_table22_coupled/fds/a --height 1.6

FED readiness:
  ✓ CO / CO2 / O2 all present and non-zero → default FED model will run
  ✗ Extinction coefficient → smoke-speed model will NOT run

This case has an extinction slice whose values are all zero, so run.py does build the smoke model; it reads K = 0 (clear air).

Probing FED without running a simulation

scripts/probe_fed.py integrates FED at fixed (x, y) points directly from the FDS output. Useful as a sanity check (“if an agent stood still here, would it be incapacitated?”). --slice-height defaults to 1.6 m.

uv run python scripts/probe_fed.py --fds-dir assets/iso_table22_coupled/fds/a \
    --point 5,5 --output results/probe.csv --plot results/probe.png

       point    peak FED    peak rate    t(FED=threshold)
      (5, 5)      1.1724       0.0611             981.0 s

Plotting

All plotting scripts are pure post-processors: they consume one of the CSV/SQLite artefacts produced by run.py and write PNGs.

Artefact → plotting-script map

FED curves — plot_fed_history.py

uv run python scripts/plot_fed_history.py fed.csv [options]

Trajectories coloured by speed — plot_trajectories_by_speed.py

uv run python scripts/plot_trajectories_by_speed.py fed.csv \
    --sqlite demo3.sqlite --output trajs.png

Per-segment RdBu colouring (red = slow, blue = fast) from the extended FED CSV; slower segments are also drawn wider, and the slowest sample is ringed and labelled. The walkable area is drawn as backdrop via pedpy.

Smoke history — plot_smoke_history.py

uv run python scripts/plot_smoke_history.py --input smoke.csv --output smoke.png
uv run python scripts/plot_smoke_history.py --input smoke.csv --output smoke_43.png --agent-id 43

Trajectories coloured by exit — plot_trajectories.py

Reads trajectory_data from the run’s SQLite: what agents did, as opposed to what rank_routes says they would do.

uv run python scripts/plot_trajectories.py <traj.sqlite> \
    --config <config.json> -o out.png [--title "..."] \
    [--route-history routes.csv] [--geometry geometry.wkt] [--reach 1.5]

Route cost curves — plot_route_costs.py

Mean composite cost per exit over time.

Under the default "gate" cost model this plot is not what ranks exits. The script reads the composite_cost column, which the gate computes and reports but does not order on — it orders on tau_route, the route’s optical depth, with rank_cost (travel time plus weighted queue time) as tie-break. Read the curves as a smoke-exposure diagnostic, and take exit choice from plot_exit_choice.py, the tau_route column or the rejection_reason column instead.

The CSV also carries the gate’s own diagnostics — tau_route, rank_cost, k_max_route, k_leg_max, clean and feasible — which is what makes a gate decision auditable: feasible says whether the route was available, tau_route is the optical depth that both refused it and ordered it, and rank_cost breaks ties between routes of equal tau_route. k_leg_max is the smokiest leg of the route and clean whether that puts the exit in the clean-exit tier; clean is False throughout unless the deck sets clean_extinction_threshold.

uv run python scripts/plot_route_costs.py route_costs.csv [routes.csv]

Exit choice distribution — plot_exit_choice.py

Time series of how many agents target each exit at each evaluation tick, plus a histogram of total agent-ticks per exit. Saves exit_choice_plot.png.

uv run python scripts/plot_exit_choice.py route_costs.csv [routes.csv [config.json]]

Quick interactive replay — vis.py

A one-line JuPedSim viewer: opens an interactive animation of a trajectory SQLite instead of writing a file. Handy for a fast look without picking plot options.

uv run python scripts/vis.py demo3.sqlite

Cognitive-map movies and diagnostics

One agent’s walk, animated — animate_cognitive_map.py

Renders an MP4 (requires ffmpeg on PATH for MP4 output) of a single agent walking a deck, with its known/unknown exits and checkpoints colour-coded, sign facing arrows, and amber trail segments where the agent is wandering (no known route). Runs its own simulation internally with collect_cognitive_map_history=True — it does not consume a run.py artefact.

uv run python scripts/animate_cognitive_map.py --scenario BUNDLE_DIR \
    -o cognitive_map.mp4 [--familiarity 0.0] [--agent ID] [--fps 12]

Deriving inputs from an FDS deck

Walkable area from FDS obstructions — generate_walkable_from_fds.py

Subtracts an FDS deck’s blocking &OBST records from its mesh footprint and writes the interior as WKT for JuPedSim. See the script’s module docstring for the XB axis-pairing pitfall, zero-thickness obstructions, and how the CAD layer name decides what blocks.

uv run python scripts/generate_walkable_from_fds.py DECK.fds -o out.wkt \
    [--z-band 0.1 1.8] [--min-hole 0.25] [--plot out.png] [--report]

Paper figures

These are generators for figures in ../pyFDS-Evac-paper/. They don’t need a simulation run.

Calibration sweeps

Route-cost queue weight — sweep_queue_weight.py

Sweeps RouteCostConfig’s queue weight against Fahy Table 2’s front-door share. Writes one scenario bundle per (w_queue, seed), runs each with run.py, and scores it against assets/station_fahy/validate.py’s observed_matrix. Unlike the paper-figure scripts above, this drives real simulation runs (in parallel processes), so it takes minutes, not seconds.

uv run python scripts/sweep_queue_weight.py \
    [--weights 0.0 0.03 0.1 ...] [--seeds 420 421 422] \
    [--jobs 4] [--out results/queue_weight_sweep] [--reuse-existing]

One-shot driver — scripts/run_and_plot.sh

Runs one simulation and produces the full plot set into a results directory.

./scripts/run_and_plot.sh assets/t_junction/config.json "$FDS" results/demo

Arguments: <scenario> <fds-dir> <results-dir>. <fds-dir> must hold a finished FDS run (the .smv file); $FDS stands for such a directory, for example the output of assets/t_junction/t_junction.fds. The script calls run.py with all diagnostic outputs enabled and then invokes each plotting script against the resulting CSVs / SQLite. It writes the vismap cache into <fds-dir>/vismap_cache.pkl, so do not point it at a tracked directory under assets/ (#313). The usage line in the script itself still names assets/t_junction, which has no FDS output (#312).