Verification

The model is verified: tests check that its components reproduce hand calculations and adapted IMO test cases. It is also compared with the results published in the EvacuatioNZ verification report; no EvacuatioNZ runs were made. A published network of a real building is compared with its EvacuatioNZ results in The Station nightclub. It is not validated: it has not been compared with evacuation drills, experiments or JuPedSim’s microscopic models.

Tests

The tests are in tests/. Run them from a clone of the repository:

uv run --extra cli --extra tui --group tui-test pytest -q

This runs the tests that every pull request runs on Python 3.13: the hand calculations and IMO cases, the EvacuatioNZ cases, the property tests on random networks (hypothesis profile pr, derandomized), the documented-number tests, the tests of the command line and those of the terminal UI. It ends with no failures and lists the long tests as deselected. In a fresh environment, a plain uv run pytest -q skips the tests of the coloured help and the pilot flows and snapshots of the terminal UI (tests/test_tui.py); uv run --extra cli pytest -q, the Python 3.10 leg of CI, skips only the latter.

The terminal UI is tested by pilot flows, by a byte-for-byte comparison of its result files with those of jupedsim-network run, and by SVG snapshots, which are also the figures of the Terminal UI page.

Two further commands run the long tests:

uv run --extra cli pytest -m slow
uv run pytest -m fuzz --hypothesis-profile=fuzz

The first runs the documented numbers of long runs: the 300-run case study, the max_density and hydraulic-coefficient sweeps, the time-step example in Limitations and the snippets that call run_many(500). CI runs it as its own job, docs-numbers, and the site deploys only when it passes. The second runs the long property runs and fixed-seed sweeps of .github/workflows/fuzz.yml, weekly and on demand.

The property tests check on random networks that

• no agent is lost;
• no link, and no shared two-way connection under "bounding" and "estimate", passes more than $1 + C\,t$ agents in any interval $t$;
• no node exceeds max_density;
• a seed reproduces its run;
• networks with no two-way pair in use give the same result under all three counterflow values;
• route tables take only tied shortest links.

The weekly job also reports how the evacuation time changes when $\Delta t$ is halved. It does not assert that a smaller $\Delta t$ never gives a later time, because that does not hold (Limitations).

The documented-number tests (tests/test_docs_numbers.py) rebuild every number on these pages that a run produces from the code and compare it with the page text exactly.

The table lists the tests with a hand-calculated expectation. “Result” is what the test measures with the current code. In the counterflow rows, values separated by “/” are for counterflow="independent" / "estimate" / "bounding"; the derivation is under Counterflow at a shared door.

The two supply-ramp tests check that the code delivers the share $\varphi_n$ of the update scheme, with $D_\text{max} = 2.75\,\text{m}^{-2}$ (the default max_density) and $D_\text{peak} = 1.88\,\text{m}^{-2}$. In the first, two 20 m² rooms of 45 agents each swap occupants through two one-way doors, 1 m wide and 2 m long, with $C\,\Delta t = 0.455$. The swap keeps $D = 2.25\,\text{m}^{-2}$ in both rooms, so one share $\varphi = 0.5745$ holds for all 45 passages. Walking 2 m at $0.5621\,\text{m/s}$ takes 8 steps, so the first step with a queue starts at $t_q = 3.5$ s. Each group then leaves through a 50 m one-way link to the far exit. Walking 50 m at the same speed takes 178 steps, so the first agent to pass, at 5.5 s, exits at 94.5 s. $T = 150.0$ s follows from a step-by-step recursion of these exits. In the second, a 40 m² room is fed through a 1 m one-way door ($C_\text{in} = 0.91\,\text{s}^{-1}$) and left through a door of width $w$, with $C_\text{out} = 1.3\,(w - 0.3) = 0.52$ and $0.78\,\text{s}^{-1}$. Setting $\varphi\,C_\text{in} = C_\text{out}$ gives $D^* = D_\text{max} - (D_\text{max} - D_\text{peak})\,C_\text{out}/C_\text{in}$. The test averages the occupancy over $t \ge 500\,\text{s}$ for $w = 0.7\,\text{m}$ and over $t \ge 800\,\text{s}$ for $w = 0.9\,\text{m}$.

Further tests check pre-movement delays, route choice, conservation of agents, that max_density is never exceeded, that no link passes more than $1 + C\,t$ agents in any interval $t$, reproducibility with a fixed seed, the stair-range warning, nan for incomplete runs, quantiles with incomplete runs, the error messages, that counterflow rejects unknown values (test_counterflow_rejects_unknown_value), and the means and truncation of the distributions. The two room swaps of test_supply_carry_admits_large_agent_swap are pinned to counterflow="independent".

Counterflow at a shared door

The rule is described in Counterflow. All five rows use $\Delta t = 0.5\,\mathrm{s}$, seed 1 and no pre-movement. Every agent queues at its first link in step 0; it reaches its next link, the exit or, for a responder, flight→floor, one step after its previous passage.

Door geometry (door_swap in tests/test_network.py). Rooms A and B are joined by connect("A", "B", width=1.0), a two-way door of length 0: $C = 1.3\,(1 - 0.3) = 0.91\,\mathrm{s^{-1}}$ and $C\,\Delta t = 0.455$. A’s agents head for B’s exit and B’s for A’s; both exits are 20 m openings of length 0. An agent that passes the door in step $k = 0, 1, \ldots$ is recorded in link_flow at $(k + 1)\,\Delta t$ and exits at $(k + 2)\,\Delta t$.

independent. A fresh link passes its first agent in step 0 and its $k$-th agent ($k \ge 2$) in step $\lceil (k - 1)/(C\,\Delta t) - 1\rceil$. With 20 agents: $\lceil 19/0.455 - 1\rceil = 41$, so $T = 43 \cdot 0.5\,\mathrm{s} = 21.5\,\mathrm{s}$. With 36: $\lceil 35/0.455 - 1\rceil = 76$, $T = 39.0\,\mathrm{s}$; the 4 agents in B pass in steps 0, 2, 4 and 6.

Bound for the shared door. In steps $0 \ldots m$ a pair passes at most $1 + g\,C\,\Delta t\,(m + 1)$ agents. Forty passages with $g \le 1$ need $m \ge 39/0.455 - 1$, so $m \ge 85$ and $T \ge 87 \cdot 0.5\,\mathrm{s} = 43.5\,\mathrm{s}$. With $g \le 0.94$: $m \ge \lceil 39/(0.94 \cdot 0.455) - 1\rceil = 91$, so $T \ge 46.5\,\mathrm{s}$, which bounding attains.

Recursion. The estimate and bounding values apply the rule step by step. With $n_A$, $n_B$ the queues, $s$ the minor share, $g = g_0 + (g_{1/2} - g_0)\,2s$, $y_A = 0.17 + 0.66\,n_A/(n_A + n_B)$, budget $B_P = c_P + g\,C\,\Delta t$ and key $\lambda = \sigma + (j + 1)/y$, the first steps of the balanced swap under estimate ($g_0 = 0.90$, $g_{1/2} = 1.00$, $c_P = 1$ at the start) are:

The first steps of 36 against 4 under bounding ($g_0 = 0.84$, $g_{1/2} = 0.94$) are:

In step 7, B’s key is still $1/y_B = 1/0.2414 = 4.143$ ($\sigma_B = 0$), so B’s first agent passes and is recorded at 4.0 s.

Stair (test_counterflow_stair_responders). Node “flight” of 30 m² with 18/28 cm steps; rooms “lobby” and “floor” of 100 m²; safe node “street” off the lobby and “roof” off the floor, through 20 m one-way openings of length 0. connect("flight", "lobby", width=1.2, kind="stair") and the same to “floor”: $k = 51.8\sqrt{28/18}\ \mathrm{m/min} = 1.0768\,\mathrm{m/s}$, $F_s = k/(4a) = 1.0120\,\mathrm{s^{-1}m^{-1}}$, $C = 1.0120 \cdot 0.9 = 0.9108\,\mathrm{s^{-1}}$ and $C\,\Delta t = 0.4554$. The stair values $g_0$, $g_{1/2}$ apply. The 20 evacuees leave the flight to the lobby and exit at $(k + 2)\,\Delta t$; the 4 responders start in the lobby, target the roof, pass lobby→flight in step $k$, flight→floor in step $k + 1$ and exit at $(k + 3)\,\Delta t$. independent: evacuees $\lceil 19/0.4554 - 1\rceil = 41$, so 21.5 s; responders in steps 0, 2, 4, 6, so out at 1.5, 2.5, 3.5 and 4.5 s.

Chain. Rooms A–E as in the chain row above, with 10 agents per room. A’s queue never empties, so $T = \Delta t\,\lceil (N_A - 1)/(C\,\Delta t)\rceil$, where $N_A$ is the number of agents leaving through A->s0. With ties split, C’s 10 agents split 5/5, so $N_A = 25$ and $T = 26.5\,\mathrm{s}$. split_ties=False sends C’s 10 via B (and warns), so $N_A = 30$ and $T = 32.0\,\mathrm{s}$. The link totals for A->s0, B->A, C->B, C->D, D->E, E->s1 are 25, 15, 5, 5, 15, 25 and 30, 20, 10, 0, 10, 20.

Supply uses the door share. The door geometry, with B of 20 m² holding 50 agents ($D_B = 2.5\,\mathrm{m^{-2}}$) and 1 agent in A. B is above $D_\text{peak} = 1.88\,\mathrm{m^{-2}}$, so it admits A’s agent only when $\alpha_B = \gamma_B + \varphi_B\,\tilde C_A\,\Delta t \ge 1$, with $\varphi_B = (2.75 - D_B)/(2.75 - 1.88)$ and $\tilde C_A = y_A\,g\,C$, A’s share of the door. Under bounding, $y_A = 0.17 + 0.66/51 = 0.183$, $g = 0.844$ and $\tilde C_A\,\Delta t \approx 0.070$. $D_B$ falls by $0.05\,\mathrm{m^{-2}}$ with each agent that leaves B.

$\alpha_B$ first exceeds 1 in step 24, but the pair budget allows a passage only in step 26, where A’s key wins: A’s agent exits at $28 \cdot 0.5\,\mathrm{s} = 14.0\,\mathrm{s}$. With $C\,\Delta t$ in place of $\tilde C_A\,\Delta t$ it would exit at 6.0 s (5.5 s under estimate); with $\tilde C_A = 0$, only after $D_B$ falls below $1.88\,\mathrm{m^{-2}}$, at 17.5 s (16.5 s).

IMO tests as written and as tested

The IMO test cases are in MSC.1/Circ.1533, Appendix 2, paragraphs 3–6 [4].

• Test 1 (one person, 2 m × 40 m corridor, 1 m/s, 40 s) is tested as written.
• Test 3 as written asks that one person with a walking speed of 1 m/s covers a 2 m wide stair of 10 m, measured along the incline, in 10 s [4]. With 18/28 cm steps this model does not meet it, by design. On a stair the input speed only caps the walking speed, which comes from the stair geometry: $k = 51.8\sqrt{T/R}$ gives 1.077 m/s for 18/28 cm steps, and $k(1 - 0.266 \cdot 0.54) = 0.922$ m/s. A lone walker takes 10.84 s by hand calculation (11.0 s in the run at $\Delta t = 0.1$ s) instead of 10 s. Shallower steps with $T/R \ge 1.83$ cap the stair speed at or above 1 m/s. The test checks this adaptation, the same one EvacuatioNZ uses for its stair verification [2, §2.1.3].
• Test 4 asks for 100 persons in an 8 m × 5 m room with a 1 m exit, and that the flow over the whole period does not exceed 1.33 persons/s [4]. The link capacity of 0.931 persons/s and the mean flow of 100/106.5 s = 0.94 persons/s both meet this criterion. Specific flow, boundary layers and a target time are not part of the test; the construction $1.33 \times 0.7$ m is EvacuatioNZ’s [2, §2.2].

Passage time: (N−1)/C and N/C

The door rows check the model’s own convention, in which the first agent passes at once and the last after $(N-1)/C$ (update scheme). The SFPE hand calculation is $N/C$ [1, Eq. 67.9, p. 2177]:

The SFPE value for IMO 4 lies 1.07 s from the test’s expectation, more than its tolerance of 1 s. The model result lies 0.9 s below it.

EvacuatioNZ verification cases

The cases of the EvacuatioNZ verification report version 2.11 [2] are rebuilt with this model and compared three ways: the hand value, the result published in the report, and this model at $\Delta t = 0.5$ s. No EvacuatioNZ runs were made. Page numbers are the printed page numbers of the report; the PDF page is one higher. The tests are in tests/test_evacuationz_verification.py. Every expected value in them is a hand calculation; values read from figures of the report are never asserted.

The report’s inputs are mapped the same way in every case. These rules are accepted for the EvacuatioNZ cases only:

• A door (enz_door) is a door with $b = 0.15$ m and $F_s = 1.33$ persons/s/m, EvacuatioNZ’s value, passed explicitly in each case; the model’s default stays $F_s = 1.3$. An untyped connection is an opening with $b = 0$ and $F_s = 1.33$, and stairs (enz_stairs) are a stair node with $F_s = k/(4a)$ from the step geometry.
• A connection that is both stair and door is one link with the lower of the two capacities.
• This model walks a link’s length inside the source node, so stair travel is put on the link leaving the stair node. The total distance is unchanged.
• A stair given by its height $H$ has the length $L = H\sqrt{1 + (T/R)^2}$.
• A random start distance is $U(0, L_{\max})$ with $L_{\max}$ stated per case; the report does not give the range.

Door and opening flow with the IMO 4 room, $F_s = 1.33$, start at the door. Every result lies within one step above $(N-1)/C$:

Stair flow with 180/280 mm steps: $k = 1.0768$ m/s, free stair speed $S_0 = k(1 - 0.266 \cdot 0.54) = 0.9221$ m/s and $C = 1.012\,(w - 0.3)$. The text of §2.3 names two stairs; the caption of Fig. 2.7 names 200 m stairs of 1.0 m and 5.0 m. All three are run.

While fewer than $0.54\,L\,w$ agents are on the stair, everyone walks at $S_0$ and the result lies within two steps of the hand value. With more agents the stair fills and everyone on it walks at $k(1 - 0.266\,D)$, so the hand value is only a lower bound. On the 10 m stair the node stays at its limit of 27 agents (2.7 m⁻²), and the slower walk adds about 18 s. On the 200 × 1 m stair the node holds 550 agents, its limit, and all walk at about 0.29 m/s. The flow from the first to the last exit is 1.012 persons/s per metre of effective width for both 1000-agent runs on the 200 m stairs, equal to the stair’s $F_s = k/(4a) = 1.012$. Fig. 2.7 of the report shows 1.0 persons/s/m.

Fire Engineering Design Guide. The example is the FEDG’s room over one stair [18, pp. 229–231]. The 10 × 10 m room holds $N_o = A_f D_o = 100 \times 0.9 = 90$ people, with $D_o = 0.9$ m⁻² from Table 11.1 [18, p. 229]. The report starts all agents 20 m from door B, a 1.0 m door into a 10 × 1.2 m stair [2, §2.4, p. 13], and this model’s test does the same. The stair link, $1.012 \times 0.9 = 0.911$ persons/s, limits the exit, not exit C with $1.33 \times 0.7 = 0.931$ persons/s (door B has the same capacity). The first agent reaches door B at 19.0 s and leaves the stair at 30.5 s: 30.0 s at the free stair speed, slowed by the agents that follow onto the stair. The capacity bound for the last exit is $30.5 + 89/0.911 = 128.2$ s; this model gives 129.0 s.

This model uses capacities instead: 0.931 persons/s at door B and 0.911 persons/s on the stair link. EvacuatioNZ puts exit C, the 1.0 m door, on the stair connection (enz_door in Listing 2.10, lines 46–48) [2, §2.4, pp. 13–14]. By the rule above, this model maps that connection to one link with the lower of the two capacities. The stair’s 0.911 persons/s is below the door’s 0.931 persons/s, so fedg() uses the stair link and exit C does not bind. The FEDG’s lower flow at exit C (0.522 persons/s) accounts for most of the 57 s between 186 s and 129 s: $89/0.522 - 89/0.911 \approx 73$ s more, 19 s less for the room walk and about 1 s more on the stair (our arithmetic).

EvacuatioNZ’s 179 s is about 50 s longer than this model’s result. In Fig. 2.8 its stair holds about 33 agents from about 80 s to 133 s, and its exits run at about 0.6 agents/s, below both capacities. In this model the stair holds at most 14 agents. The report does not say what limits the flow out of a full node in EvacuatioNZ, so the difference is unexplained. The two documents use different EvacuatioNZ versions and inputs: Spearpoint (2009) uses a zero-length room–stair connection and minimum, maximum or random start positions and reports 257 s, 275 s and 260 ± 4 s [7, manuscript pp. 16–17]; the report uses a 0.1 m connection and a 20 m start and gives 179 s and 168 s [2, §2.4, pp. 14–15].

Tied stairs. EvacuatioNZ splits the agents of §2.6 between the two stairs with a least-populated-connection rule. This model has no such rule; the two stairs are tied, and agents alternate between them (Networks). This gives the same 150/150 split by a different, fixed rule. With split_ties=False all 300 agents take one stair and leave after 455.5 s (start at the door) and 506.0 s (start 200 ft away). The report’s EvacuatioNZ result of 221.5 s lies within 1.6 s of $150/0.682 = 219.9$ s, although the last agent still has about 16 s of stair to descend; the Guide’s 246 s does not match $N/C$ at the door or the stair with these constants. In §2.5 the two stairs are tied at each corridor, so 150 agents per floor go to each, the same 150/150 split as the SFPE Solution B, which says “Divide each floor in half to produce two exit calculation zones” [1, p. 2182]. With split_ties=False all 2400 agents take one stair and leave after 3027.5 s.

In §5.1 the report gives no node sizes or widths; the test assumes 25 m² nodes, 1 m doors and a start $U(0, 5)$ m and checks only the exit used. The report’s distances of 5 m to Exit 5 and 15 m to Exit 3 leave out the 1 m link from Room 1 to Room 2; the full paths are 6 m and 16 m.

Rules of the report that this model does not have: door leaves and door closers (§2.2), the maximum-distance, minimum-nodes and random single exit choices (§5.1.2–5.1.4), required connections (§5.2) and the least-populated connection (§2.6).

Door flow and merging

(a) IMO test 4 geometry. The model follows $1 + C\,t$, the $(N-1)/C$ convention, to within one time step. The SFPE hand calculation $C\,t$ lies one agent lower and ends at $N/C = 107.4$ s; the inset shows the last 13 s. (b) Two rooms feeding a full corridor with merge weights 1 : 3. Over 150 s the flows reach 3 : 1. At the start, room a passes no one from 2.0 s to 17.0 s while room b catches up on the share it lost before the corridor filled (Limitations).

Sensitivity to max_density

In EvacuatioNZ version 1.2, raising the maximum node density from 2.5 to 3.5 m⁻² more than doubled the evacuation time of a 21-storey hotel without pre-movement delay, from 539 s to 1232 s [5, Table 5.5, p. 55]. With pre-movement delay it rose from 796 s to 1156 s. These are means of 100 runs with the local door queue density fixed at 2.2 m⁻²; the runs ranged from 529 to 553 s at 2.5 m⁻² and from 1107 to 1502 s at 3.5 m⁻², both without delay. Tsai judged the 3.5 m⁻² result improbable, since it was longer without delay than with delay [5, p. 56], and recommended 2.5 m⁻² [5, pp. 62, 69]. Tsai attributes the wider spread to queuing at higher allowed densities [5, p. 56]. We attribute the increase to the speed–density relation: close to the jam density $1/a = 3.76$ m⁻², a full node lets almost no one move, and a hard capacity limit lets nodes fill up to that density until the stream locks up.

The figure repeats the experiment with this model on a ten-storey building with one stair, comparing the two settings of supply_reduction. With a hard limit only, the evacuation time grows sharply above 3 m⁻². With supply reduction it stays almost constant. This shows only that supply reduction removes the effect in this building. The building is not the one Tsai used, so it says nothing about EvacuatioNZ’s numbers.

Ten floors of 60 agents each (400 m² per floor, pre-movement U(30, 120) s) and one stair of 1.2 m with 0.9 m doors, all connected one way. The line is the median of 30 runs and the band covers 5–95 %. No run was incomplete.

Sensitivity to the hydraulic coefficients

HydraulicParameters lets a study change the SFPE coefficients (Networks). The figure changes one coefficient at a time in the one-stair building of the max_density sweep, with the default max_density. The stair is the bottleneck, so the evacuation time should follow its capacity: 600 agents pass its effective width of 0.9 m at the maximum specific flow $k_\text{stair}/(4a)$, after the earliest pre-movement time of 30 s. This bound is the dashed line.

• The stair coefficient sets $k_\text{stair}$, so the time falls as $1/k$: from 924 s at 40 m/min to 590 s at 65 m/min.
• The slope $a$ scales the maximum flow as $1/a$, so the time grows in proportion to $a$: from 540 s at 0.19 to 726 s at 0.266. With the default door_specific_flow of 1.3, $a$ is at most 0.269 (Networks), so the sweep ends at the default. Below 0.182 the peak-flow density $1/(2a)$ exceeds the default max_density and supply reduction switches off, so the sweep starts at 0.19.
• door_specific_flow changes nothing here: the ten doors together pass far more than the stair even at 0.7 persons/s/m. The median moves by 2 s between 0.7 and 1.3.

In every case the median lies 35 to 41 s above the bound: the start-up of the stream and the last agent’s walk down the stair. The line is the median of 30 runs and the band covers 5–95 %. No run of the sweep was incomplete. The sweep shows which coefficient this building responds to; it says nothing about which values are right. Changed coefficients are study assumptions, not validated ranges.

Reproducing the figures

The figures and animations on this site are produced by scripts/figures/make_figures.py and scripts/figures/make_gifs.py:

uv run --group docs python scripts/figures/make_figures.py OUTDIR
uv run --group docs python scripts/figures/make_gifs.py OUTDIR

Without OUTDIR they write to site/static/images/network/. The figures of the Terminal UI page are the snapshots of the terminal UI tests; scripts/figures/copy_tui_snapshots.py copies them, by default to site/static/images/tui/:

uv run --group docs python scripts/figures/copy_tui_snapshots.py OUTDIR