A crowd in a real fire

This page runs a larger case end to end: 150 people try to leave a T-shaped corridor while a 2 MW PVC fire, computed by FDS, fills it with smoke. Each step shows the command and what it produces.

It builds on the Quickstart (one agent, prescribed smoke) and the Real-FDS walkthrough (small tracked FDS cases). Unlike those, it needs FDS output that is not in the repository; step 3 says how to get it.

1. Check the scenario runs

Run every command on this page from the repository root, in the environment installed with uv sync. Without FDS output the example runs the scenario in clear air, in about 5 s:

uv run python examples/first_fds_case.py

The last line of the output is:

evacuated: 144/150 in 300 s

2. The scenario

The scenario is a folder, assets/t_junction: a JuPedSim config.json and the walkable area as geometry.wkt. It sits beside the FDS deck that made its fire.

uv run python run.py --scenario assets/t_junction --print-summary --export-only

  Model:         CollisionFreeSpeedModel
  Seed:          42
  Max time:      300s
  Exits:         2
  …
  Sequence:      jps-distributions_0 -> jps-checkpoints_0 -> exit_A_left -> exit_B_right
    jps-distributions_0: 200 agents (flow: 0-400s)

In plan view:

Agents enter the branch one every 2 s. The run stops at 300 s, so 150 of the 200 planned agents take part. Every agent walks to the junction, then to exit A, 20 m from the junction, or exit B, 10 m from it and past the fire.

The agents are discovery agents ("familiarity": "discovery" in config.json). They start knowing only the spawn area. They learn the junction and the exits when they can read their signs. Smoke can hide a sign. The rules are on the wayfinding page.

3. The fire

The fire comes from FDS. pyFDS-Evac does not run FDS; it reads the slice files that FDS wrote.

Get the FDS output. The deck is assets/t_junction/t_junction.fds: a 2 MW PVC fire on a 2 m × 1 m burner, 300 s, four meshes. Either run it yourself:

mkdir -p fire && cp assets/t_junction/t_junction.fds fire/
cd fire && mpiexec -n 4 fds t_junction.fds && cd ..

It takes 20 to 30 minutes on four cores. Or use the output the maintainers keep in their data store, fds-evac-data/t_junction/fire_2MW_PVC/ (about 125 MB). The data store is not public; ask for it on the issue tracker.

The rest of this page calls the output directory $FDS:

FDS=fire   # or the path to fire_2MW_PVC

Check what it contains.

uv run python run.py --scenario assets/t_junction --fds-dir "$FDS" --inspect-fds

{
  "data_3d": [],
  "devices": [],
  "slices": [
    "CARBON DIOXIDE VOLUME FRACTION",
    "CARBON MONOXIDE VOLUME FRACTION",
    "HYDROGEN CHLORIDE VOLUME FRACTION",
    "OXYGEN VOLUME FRACTION",
    "SOOT EXTINCTION COEFFICIENT",
    "SOOT VISIBILITY"
  ],
  "smoke_3d": []
}

The extinction coefficient slows the agents and hides signs. CO, CO2 and O2 give the toxic dose (FED). The deck has no TEMPERATURE slice, and heat FED is off by default anyway.

Smoke reaches the junction at about 30 s. By 90 s it fills the whole T, with a median extinction coefficient K of 8 1/m, a visibility of about 0.4 m.

The deck writes its slices at z = 2.0 m only. pyFDS-Evac samples at 1.6 m by default, the FDS+Evac head height, and takes the nearest slice, here 2.0 m.

4. Run it

mkdir -p tj
uv run python run.py --scenario assets/t_junction --fds-dir "$FDS" \
    --output-sqlite tj/tj_fire.sqlite \
    --output-smoke-history tj/tj_fire_smoke.csv \
    --output-fed-history tj/tj_fire_fed.csv \
    --output-route-history tj/tj_fire_routes.csv

It takes about 45 s. Most of that goes into computing which signs are readable through the smoke. The output ends with:

Configuring smoke calculation.
Configuring FED calculation.
Heat FED is off; pass --enable-heat-fed to accumulate it.
Configuring rerouting.
Configuring visibility model (3 signs).
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).
Initialization finished.
Simulation started.
…
Simulation stopped after 300.00 s (76/150 evacuated, 74 remaining).
Route switches: 173

Before this, fdsreader logs Module vents: could not convert string to float for this deck, and the terminal also shows Reroute debug and Waypoint lines and numpy UserWarning/RuntimeWarning messages. None of them affects the run. The progress line counts the 200 planned agents, not the 150 that spawned (#279).

These are the defaults, as in FDS+Evac: every agent is incapacitated at FED = 1, heat FED is off, and irritants (the HCl slice) slow nobody unless you pass --enable-fic-speed.

The run writes five files:

For the clear-air comparison below, run the same command without --fds-dir:

uv run python run.py --scenario assets/t_junction \
    --output-sqlite tj/tj_clear.sqlite

The same run from Python. examples/first_fds_case.py takes the FDS directory as its argument:

uv run python examples/first_fds_case.py "$FDS"

build_run_kwargs is the function run.py calls, so the run is the same. The script imports:

import sys
from collections import Counter
from types import SimpleNamespace

from pyfds_evac import build_run_kwargs, load_scenario, run_scenario

FDS_DIR = sys.argv[1] if len(sys.argv) > 1 else None

and runs:

scenario = load_scenario("assets/t_junction")
opts = SimpleNamespace(
    seed=None,  # the scenario's baseSeed, 42
    fds_dir=FDS_DIR,
    constant_extinction=None,
    smoke_update_interval=1.0,
    smoke_slice_height=1.6,
    disable_tenability=False,
    fed_threshold=1.0,
    fic_alpha=0.7,
    fic_min_factor=0.3,
    enable_rerouting=True,
    reroute_interval=1.0,
    vis_cache=None,
)
result = run_scenario(scenario, **build_run_kwargs(scenario, opts))

print(f"evacuated: {result.agents_evacuated}/{result.total_agents} in 300 s")
if FDS_DIR is not None:
    print(f"FED max:   {result.metrics['fed_max']:.2f}")
    reasons = Counter(r["reason"] for r in result.route_history)
    print(f"route changes: {dict(reasons)}")

evacuated: 76/150 in 300 s
FED max:   0.37
route changes: {'smoke_reroute': 8, 'wander': 165}

5. Results

The figures below are drawn from these files by scripts/docs/first_fds_case_figures.py:

uv run python scripts/docs/first_fds_case_figures.py --data "$FDS" --runs tj

Where the agents went

In clear air everyone takes the nearer exit B. In the fire, 8 early agents turn to exit A as smoke builds up on B’s side. Half the agents are still inside at 300 s.

The run, animated

The background is the extinction field the agents read. Red, large dots are agents the smoke has slowed. From about 120 s almost every agent crawls.

Evacuated over time

In clear air, agents leave about as fast as they arrive. In the fire, the gap opens at about 45 s, when the smoke has filled the junction.

Dose and speed

Nobody is incapacitated by the toxic dose: the highest FED is 0.37. This does not mean that conditions were tenable; section 6 compares visibility and irritant limits with the exit times. In the run, the smoke acts on the agents through their speed, their route choice and the signs they can read; the engine records the irritant measure (FIC) but does not act on it by default. The default speed law (lund) multiplies the walking speed by 1 + beta * K / alpha, clamped to [0.1, 1]. At K = 3 1/m this is 1 + (-0.057 × 3.0) / 0.706 = 0.76. Above K = 11 1/m it is the floor, 0.1, and from 120 s the median agent is there.

Exit usage

The route log explains the fire run. The 8 agents who switched to exit A (smoke_reroute) did so in the first 26 s, and all 8 left by it. 18 agents, spawned between 22 and 92 s, never learned an exit: no exit sign was readable to them. They walk back and forth between the spawn area and the junction (wander, 165 of the 173 route changes), and all 18 are still inside at 300 s.

6. Was there time to get out? (ASET and RSET)

Fire-safety engineering compares two times. The available safe escape time (ASET) runs until conditions become untenable. The required safe escape time (RSET) runs until people reach safety. The ASET and RSET page gives the definitions. This section applies them to the run above, one agent at a time. For each agent it asks when the air at the agent’s own position first crossed a tenability limit, and whether the agent got out before that.

The answer in short

• There is no single RSET and no single margin. Agents keep arriving until the run is cut off at 300 s, with half of them still inside.
• Visibility and HCl became untenable early. Each of six points in the T crossed the visibility limit between 18 and 46 s after ignition. The first agent met it at 15 s. Of the 75 agents who got out, 69 met it before they reached an exit.
• The irritant limits were passed by most of those who got out. 64 of the 75 met HCl ≥ 1000 ppm (ISO fractional effective concentration, FEC, of 1, the concentration at which half of a population is expected to be incapacitated) before their exit. The engine records the irritant measure (FIC) and does not act on it, so these agents kept walking.
• The toxic dose came last. FED reached 0.3 only after 262 s, for 18 agents who were still inside. By then their FIC was already 4.5 to 5.9.

“Nobody reached FED 1” therefore does not mean “everyone had time”. This is one fire, one seed, and research software. The result describes this run. It is not a design verdict.

Make the numbers yourself

pyFDS-Evac does not compute ASET itself. A built-in report is planned in #210. The script scripts/docs/first_fds_case_aset.py reads the run files from step 4 and the FDS slices. The sign maps need a newer fdsvismap than the one pyFDS-Evac pins (#140). uv run --with adds that version for this one command, which only reads the FDS output:

uv run --with git+https://github.com/FireDynamics/fdsvismap@31dc0b6 \
    python scripts/docs/first_fds_case_aset.py --data "$FDS" --runs tj

It takes under a minute (about 8 s with the run files in place) and prints every number in this section. The report starts with:

agents 150, spawned last at 298 s
trajectory: 76 left before 300 s, last exit 299.8 s
counted out (exit < 299 s) 75, censored 75
travel time median 88.1 s, max 147.4 s

Who counts as out. The run reports 76 evacuated, and so does the trajectory: the last agent leaves at 299.8 s. The per-agent histories stop at 299 s, so they cannot show whether that agent met a limit in its last second. The script therefore counts an agent as out only if it left before 299 s: 75 got out and 75 are censored. For a censored agent we know only that its margin is negative or longer than the run.

Each agent against its own limits

Each row is one criterion, over all 150 agents. A limit counts as reached if the agent met it before it left, or before 299 s if it is still inside.

The 69 agents who got out after the visibility limit spent a median of 92 s, and at most 148 s, inside beyond it. The four HCl limits change the count of evacuees who met a limit only from 68 to 64. CO above 2,700 ppm is met next to the burner, by agents who pass it on their way to exit B.

One bar per agent (n = 150, seed 42), from spawn to exit, or to 299 s for the 75 censored agents (grey, arrow). The solid part is the time spent beyond K ≥ 0.3 1/m. Markers: first K ≥ 0.3 1/m (circle), first HCl ≥ 300 ppm (diamond), first FED ≥ 0.3 (square); the other criteria of the table are left out to keep the bars readable. Censoring is shown by the grey colour and the arrow, not by hatching. Values at the agent’s position, z = 2.0 m, 1 s resolution..

Read the figure from the left edge of each bar. The first dozen agents started in clear air, and the limits reached them on the way. From about 50 s on, every agent spawns into air that is already past the visibility limit, and meets HCl ≥ 300 ppm within about 3 s of spawning. After 46 s, when the last of the six points below crosses the visibility limit, 127 of the 150 agents are still to spawn.

At fixed points: location ASET

The classic ASET is read at a place, not at a person: the first time a limit is met at a fixed point, counted from ignition. It needs no agents, and it says nothing about who was there.

CO does not reach 2,700 ppm at any of these points within 300 s.

(a) Location ASET at z = 2.0 m on a 0.5 m grid: the earlier of K ≥ 0.3 1/m and HCl ≥ 300 ppm, for a person standing still from ignition. Labels: that time at the six points of the table. (b) The first time no sign can be seen from a cell (fdsvismap get_aset_map, 0.25 m grid, all three signs, c = 3, visibility capped at 30 m). A cell counts at its first loss of sight, even if a sign becomes visible again later, and a cell that never loses sight cannot be told apart from one that loses it at 300 s. Heat is not included in either panel. The map form follows Schröder et al. (2020); the Schröder room reruns their experiment.

Panel (b) is not a tenability limit. It shows when the signs stop guiding. This is consistent with section 5, where 18 agents spawned between 22 and 92 s never learned an exit: on this map the spawn centre loses sight of every sign at 39 s. The engine’s own sign test differs (see How the numbers are computed). ISO 13571 (§4.5, note) does not expect obscuration alone to make conditions untenable for people who are not carrying out cognitive or motor tasks: it treats obscuration as mattering through the tasks it impairs, such as finding an exit. This page assesses it through wayfinding. The slider shows sign visibility through time, one map per route.

Why there is no single RSET here

ISO/TR 16738 builds RSET from detection, alarm, pre-movement and travel times, counted from ignition (see ASET and RSET). This run fits none of it:

• The inflow never stops. One agent spawns every 2 s until the run ends. Each agent’s exposure starts when it spawns, while all times on this page count from ignition.
• The run is cut off. It stops at 300 s with most late spawners inside. The last exit, 299.8 s, is set by the time limit. It is not an RSET.
• There is no detection, alarm or pre-movement ("use_premovement": false). Exit minus spawn is travel time only: a median of 88.1 s and a maximum of 147.4 s for the 75 who got out.

More seeds would not supply an RSET either, because every seed stops at the same 300 s. For a scenario in which everyone gets out, see the ensemble how-to. For one where everyone is placed at t = 0 and gets out, with RSET mapped cell by cell, see the Schröder room.

What this does not show

The exit times rest on walking speeds far outside the data. The default speed law comes from Frantzich and Nilsson’s experiments, which covered K = 1.9–7.4 1/m. Purser’s fit to Jin’s data covers K ≈ 0.30–1.27 1/m (see walking speed in smoke). In this run the median K at the agents is 13.3 1/m, a visibility of about 0.2 m with C = 3. 89 % of the agent-seconds lie above 7.4 1/m, and 74 % sit at the speed floor of 0.1, which the law reaches at K = 11.15 1/m. The exit times, and the number still inside, are set by that floor, not by measured behaviour. Sign legibility and route choice are extrapolated in the same way: Jin’s visibility data end near K ≈ 1.8 1/m (see Visibility).

Extinction coefficient K [1/m] at the agents, one count per agent and second inside (n = 13,925; the 255 with K < 0.1 1/m are not shown). Hatched: the K ranges of the data behind the speed laws, from walking speed in smoke. Shaded: Jin’s sign-visibility data for lit signs, K ≈ 0.3–1.8 1/m, from Visibility. Dashed: the default lund law reaches its floor of 0.1. The figure counts every agent-second, not only the K at each agent’s first crossing, because the speed law and the sign test act at every second.

The other limits:

• Per agent goes beyond the standard. ISO 13571 is meant for estimates over a population, not for specific individuals (§5.2, p. 4). The per-agent comparison is our use of it. The SFPE Handbook frames the same question, the time between losing visibility and incapacitation (Purser and McAllister 2016, p. 2414).
• The FED is not the ISO 13571 asphyxiant FED. It is the FDS+Evac sum (CO + CN + NOx + FLD_irr) × HV_CO2 + O2, which includes Purser’s lethal-dose term for HCl (see FED model). ISO keeps irritants out of the asphyxiant FED (§4.2.1). Applying the ISO thresholds to it is an analogy. FED 0.3 is a threshold for susceptible people, not a “safe” value: ISO treats 1 as the median of a log-normal response, so at 0.3 11.4 % of a population is still expected to be affected (A.5.2, p. 18; see Incapacitation thresholds).
• The irritant criteria are analogies too. ISO 13571 ties one threshold to its own FED and FEC (§5.4; A.5.2, p. 18). Here that threshold is applied to an FDS+Evac FED and to HCl. The table gives each source’s own value, and the conclusion is the same for all four.
• HCl is probably overestimated. The deck has no loss of HCl to walls, so all the HCl produced stays in the gas. The irritant crossings are likely early.
• Visibility. The EA note gives 10 m, not a K. C = 3 (Jin’s value for a reflecting sign, and the FDS default) turns it into 0.3 1/m. The result barely depends on this: any K from 0.23 to 0.8 1/m changes the first crossing of at most 14 agents, by at most 12 s. The EA limits apply to exposures under 10 minutes. The 10 m criterion is from EA, not from ISO: ISO 13571 clause 9 (pp. 11–12) treats obscuration through a fuel mass-loss concentration, not a visibility distance.
• One height. Every value is at z = 2.0 m, the only slice height in the deck. The EA note evaluates its limits at 2.0 m too.
• Heat is not evaluated. The deck has no temperature slice, so the FED CSV reports a constant 20 °C. The only temperature is the T_fire device above the burner, which is not a value on the route.
• The engine does not act on these limits. It records FIC; the script finds the visibility crossings afterwards. The speed reduction in smoke is a separate model, and --enable-fic-speed turns on an irritant slowdown, not incapacitation by FIC.
• Time resolution. Crossings come from the 1 Hz histories, to about 1 s. Exit times come from the trajectory, to 0.1 s.
• ASET/RSET is itself contested. Babrauskas, Fleming and Russell (2010) argue that it treats people as moving mechanically and depends heavily on the scenario chosen.

What next

• What your FDS case must provide, before you use your own FDS output.
• Real-FDS walkthrough: FED from FDS slices, and how to spot a run that finishes but has no FED in it.
• How do I get RSET with its spread from an ensemble of seeds?
• Evacuation with and without the fire: the same fire, run uncoupled and coupled.
• Models: smoke and speed, FED, wayfinding, routing.
• Verification: ISO 20414, the tests the models are checked against.
• Fundamentals, the published laws behind the models: walking speed in smoke, asphyxiant FED, visibility.

pyFDS-Evac is research software, provided without warranty.