Limitations

This page lists every known limitation of version 0.5.0. Read it before using a result. SFPE asks that model results be presented with a description of the model’s limitations, including its level of validation [1, p. 2171].

Status

• Not validated. The model is verified against hand calculations and adapted IMO component tests (Verification). It has not been compared with evacuation drills, experiments, EvacuatioNZ runs or JuPedSim’s microscopic models; it is compared with EvacuatioNZ results published for one real building (The Station nightclub). It is not intended for regulatory or design use.
• Optimistic by construction. SFPE notes that the hydraulic model tends to give an optimistic estimate [1, p. 2165]. Gwynne et al. name five elements an egress model must address: pre-evacuation time, travel speed, route usage, route availability and flow constraints [11, p. 339]. They write that model defaults “often represent optimistic and even unrealistic evacuation conditions or occupant behaviour (e.g. immediate response and optimal use of routes available)” [11, p. 336], and propose bounding defaults instead: values from the literature that lengthen the evacuation time [11, pp. 335, 342]. The table below compares them with the defaults of this model.
• SFPE relations applied to a network. Shestopal and Grubits write that the analytical approach of Nelson and MacLennan, in the SFPE Handbook, “is not intended to be extrapolated to complex network of exit routes” [19, p. 625]. This model applies those SFPE relations on a network of nodes and links. The effect of this has not been tested.
• Prototype. The interface may change between versions.

Defaults compared with bounding defaults

One default of this model, counterflow="bounding", is chosen as a bound in Gwynne et al.’s first sense: values “derived from relevant empirical data” [11, pp. 335–336], not extreme outliers [11, p. 343]. Gwynne et al. propose no counterflow value themselves. The other defaults are not bounding defaults. Gwynne et al. give their values as “the first iteration of values that might then be modified”, and their approach gives “relative conservatism (within the application of each model)” [11, p. 343]. The paper does not test the values in a simulation.

• Pre-movement. Zero pre-evacuation time is the paper’s example of an optimistic default [11, p. 342]. A pre-movement time $T$ common to all agents adds $T$ to the evacuation time, because the agents start together and queue the same way. This holds exactly when $T$ is a multiple of $\Delta t$ and the run ends before t_max. Detection and alarm count only if added to pre_movement (Behaviour).
• Travel speed. 1.2 m/s is “a frequently used design value” [11, p. 345].
• Route availability and usage. Gwynne et al. give one bound for both elements. Taking all routes and exits as available “may produce optimistic results”; as a first step they discount the widest final exit, then refine this to the narrowest, most remote one [11, pp. 346–347]. Whether nearest exit and shortest path are conservative depends on the scenario [11, p. 341]. To test a blocked exit, build the network without that safe node and compare the results.
• Ties. The paper’s tie rule applies to final exits of the same minimum width and the same maximum travel distance; it does not cover ties at intermediate nodes [11, p. 347]. In the ten-storey case, splitting ties is faster than split_ties=False (407.5 s against 725.5 s, see Routes). With tied links of different widths, alternation can be slower, because it splits agents by count, not by capacity. Neither setting bounds the result.
• Door flow. 1.3 persons/s/m is the SFPE design value [1, Table 67.5, p. 2176]. Gwynne et al. and SFPE differ on whether the door data are conservative; see “Doors are open and the data are old” under Movement and capacity.
• Counterflow. While both directions queue, "bounding" takes the low end of the walkway data; stairs: Tofiło et al.’s 75 % [29, p. 520]. With a sparse minor stream the realised total is higher. Door values below a 50/50 split are borrowed from walkways, and at 50/50 the value lies below the only door measurement. Mixed with design-value defaults, it gives a mixed default set [11, p. 342]. "estimate" is the alternative (Counterflow).
• Merge weights. Gwynne et al. propose no bound; SFPE calls equal shares not conservative [1, p. 2178].
• max_density and supply reduction. Gwynne et al. propose no bound. Verification shows how the results depend on max_density.

Routes

• Ties are split by count, not by capacity. Where two routes are equally short, agents alternate between them, so each tied link gets the same number of agents whatever its width (Networks, issue #7). Routes that differ by more than floating-point rounding (10⁻⁹ of their length) are not tied, however small the difference. With split_ties=False every agent takes the route found first.

  

  The ten-storey building of the case study with pre-movement U(30, 120) s, seed 1. With ties split, 300 agents take each stair and the building is clear after 407.5 s. With split_ties=False all 600 take one stair and evacuate as slowly as a building with a single stair (725.5 s); splitting the tie cuts the time by 44 %.

• Routes are static. They are computed once before the run. Agents don’t react to queues, blocked exits, signs or smoke. By default (routing_policy="shortest_distance") routes use link lengths only, and walking speed (level or stair) plays no part.

• The free-flow-time policy is not a travel-time prediction. routing_policy="shortest_free_flow_time" costs each link at length / speed(0, k), the hydraulic speed at the density floor of the node the link leaves. This reference time has no congestion, no queues and no individual speeds. Because speed(0, k) = 0.856 k for every node, the cost is proportional to $k$, and the policy differs from shortest distance only through the node speed constants, today level (1.4 m/s) against stairs ($51.8\sqrt{T/R}/60$ m/s). A route changes only where a longer level path competes with a shorter stair-heavy one (Networks).

Movement and capacity

• Free speed is capped. Because the density is taken as at least 0.54 m⁻², no agent walks faster than 1.199 m/s on level ground or 0.922 m/s on an 18/28 cm stair, whatever its speed (Populations).
• Stair speed outside the SFPE range is extrapolated. The $\sqrt{T/R}$ law is supported for risers of 165–191 mm and treads of 254–330 mm [1, p. 2175]. add_stair warns for other values but still computes the speed (Networks).
• Stair length is taken along the incline. Stair links take the walking distance along the line of travel, as SFPE does in its Example 67.1 [1, p. 2178]. Entering the horizontal run makes the walk about 16 % too short for 18/28 cm steps (Networks).
• Densities above 1.9 m⁻². SFPE states that such densities should not be assumed in engineering designs [1, p. 2175]. The model allows nodes up to max_density, 2.75 m⁻² by default, and its behaviour between 1.88 m⁻² and max_density is its own choice.
• The supply reduction is a modelling choice. Its linear form between 1.88 m⁻² and max_density has not been calibrated against experiments. With supply_reduction=True it is off, with a UserWarning, when max_density ≤ 1.88 m⁻². max_density must stay below the jam density of 3.76 m⁻².
• Supply depends on which links have a queue. Above 1.88 m⁻² a node accepts a share of the summed rate of its incoming links that have a queue in this step; a link of a pair in counterflow counts with its share $y\,g\,C$ of the door. At the same density, a node fed through one queued link therefore accepts less than one fed through two (update scheme).
• Counterflow at links follows a model rule. SFPE has none. Door data exist only at a 50/50 split, from one door [6, pp. 5–6]; door values below 50/50 are borrowed from walkways; there are no emergency data. The rule is not validated (Counterflow, issue #8).
• The anchors are partly open. Whether Navin and Wheeler’s 17 % width intercept applies as a minimum share of passages ($y_0$) is not established. The stair value $g_0 = 0.75$ is a fraction of the measured no-counterflow flow on one stair, not of capacity [29, p. 520].
• Counterflow inside nodes is not modelled. Corridors and stair flights are nodes; their speed stays $k(1 - aD)$ with all agents counted, whatever their direction. Experiments show a speed loss in bidirectional streams [32, pp. 10–11; 28].
• Shares count agents, not area factors. The queue and pass shares of a pair use head counts.
• Equal pair keys go to the direction created first. A result can therefore depend on the argument order of connect, as it can on the population order (Numerics). In the balanced door swap of Verification the first passage goes A→B because connect("A", "B") created A→B first; swapping the arguments mirrors the result.
• Only the two links of one connect call form a pair. Two one-way connect calls between the same nodes are two doors, each with full capacity.
• The pair remembers recent use in either direction. The two links share one carry, so an agent can wait one step longer after an agent passed the other way.
• Default routing creates no counterflow. Default routing (no target) sends no agents both ways along a link, because every shortest route moves closer to a safe node, or as close over fewer links. Counterflow arises only when populations have different targets.
• Re-entry from a safe node cannot be represented. connect creates no link out of a safe node, and a population cannot start in one. Responders start in a room, such as a lobby, and target a safe node.
• Doors are open and the data are old. $F_s = 1.3$ persons/s/m assumes doors held open; for doors that are not, SFPE suggests 50 persons/min per door leaf. SFPE also notes that the door data are several decades old, come from non-emergency movement and drills, and should not be assumed to be conservative [1, p. 2176]. Gwynne et al. call 1.3 persons/s/m “possibly already conservative” [11, p. 348]; the question is open. With the boundary layers, $1.3\,(w - 0.3)$ equals their bound of 0.67 persons/s at a clear width $w$ of about 0.82 m; wider doors pass more. There are no door leaves or closers in the model.
• Equal merge weights are not conservative. SFPE says merge shares cannot be predetermined and recommends, conservatively, that the route of interest is dominated [1, p. 2178]. The default weight is 1 for every link.
• Merge shares remember the past. Virtual times accumulate while a node is not yet full. When it fills, the link with the lower weight can stall until the shares are balanced again, for example room a in the merge figure.
• Nodes are well mixed. All walkers in a node share one density and one speed, so local crowding inside a large room isn’t seen. Positions inside a node are not represented, so overtaking and local conflicts are not modelled [16, §2.2, p. 745]. Queued agents are taken to stand at the constriction, and a long queue doesn’t add walking distance. Splitting large spaces into several nodes helps.
• One length per link. The walking distance to a door doesn’t depend on where in the room an agent starts, apart from the sampled start_distance. Both directions of a connection use the same length.
• A link longer than its node limits the node’s flow. An agent walks a link’s length $L$ inside the source node, at that node’s speed $S(D) = k(1 - aD)$ ($k$ the node’s speed constant, $a = 0.266$ m²). A node of length $\ell$ and width $w$ at density $D$ then passes on average at most $D\,w\,\ell\,S(D)/L$ agents per second. This is largest at $D = 1/(2a)$, where it equals $k\,w\,\ell/(4aL)$: the node’s peak specific flow $k/(4a)$ times $w\ell/L$. For $L > \ell$ the node passes less than $k w/(4a)$, whatever the door widths. Putting landing travel on a stair link makes $L$ longer than the stair node. In the SFPE nine-storey building this lowers the exit flow from 0.811 to about 0.65 persons/s and raises the evacuation time from 1548.5 s to 1915.5 s (Verification). Model landings as their own nodes.
• The area factor is not calibrated. It scales an agent’s contribution to density. It is not the Predtechenskii–Milinskii method that SFPE describes for mixed body sizes [1, pp. 2185–2187].
• Full nodes can lock up. No node ever exceeds max_density, so an agent enters only if its area factor fits into the free space. When every node on a cycle is too full to take the next agent waiting for it, the run never finishes: two 20 m² rooms holding 55 agents each ($2.75 \times 20$) and swapping occupants through one door stay full for good. The evacuation time is nan, and a larger t_max doesn’t help. With mixed area factors a lock can also come from the queue order: a node serves the heads of its queues in turn, so a smaller agent that would fit waits behind a larger one that does not. An agent whose area factor exceeds max_density × area of a node on its route would never fit; NetworkSimulation rejects it with a ValueError (Running).

Numerics

• Results are quantised by the time step. Agents leave at the end of a step, so exit times are multiples of $\Delta t$: each one is the step time in times. Every link costs at least one step: six zero-length links in a row take 3.0 s at $\Delta t = 0.5$ s. Stair speeds need $\Delta t \approx 0.1$ s to match a hand calculation within 0.25 s.

• A full node makes a coarse step slightly slow. A node can use, in the same step, the space of agents who leave it. A node held at its max_density therefore stays full, and its agents walk at the speed for the full node, $S(D_{\max})$. Take a node whose link is longer than the node, so that its outflow is limited by walking (Movement and capacity). An agent walks the link length $L$ in $\lceil L/(S\,\Delta t)\rceil$ whole steps, so the node passes slightly fewer agents than with a fine step: the error is of the order of $\Delta t$ for each walk through the node, and the evacuation time converges from above as $\Delta t$ falls.

  In this example, 200 agents (speed=1.2, no pre-movement, start_distance=0) leave a 100 m² room through a one-way 2 m door of length 0.3 m into a 4 m² lobby, which leads through a one-way 4 m opening of length 10 m to a safe node. With max_density=3.5 and supply_reduction=False the evacuation time is 1451.5 s at $\Delta t = 0.5$ s against 1445.3 s at $\Delta t = 1/64$ s, 0.4 % on the long side. With the defaults (2.75 m⁻², supply reduction on) the same network gives 453.5 s against 446.9 s, 1.5 % on the long side. Check such cases with a smaller step. In the first case, halving $\Delta t$ divides the error by 1.8. Whether a node is held at its limit shows in node_occupancy (Results).

  A coarse step can still give too short a time in two cases. Agents who leave a node through a two-way connection in counterflow free their space only in the next step. In a search of 38 random networks, 2 finished 1–4 % early at $\Delta t = 0.5$ s with supply reduction at a max_density of 3.5 m⁻² (issue #79). Versions before 0.5.0 freed the space in the next step (issue #55).

• Passage time is one headway shorter than SFPE. A link idle for at least $1/C_\ell$ lets the first agent through at once, so $N$ agents need $(N-1)/C$ instead of the SFPE $N/C$ [1, Eq. 67.9, p. 2177] (Verification).

• Simultaneous arrivals are served in population order. Agents that reach the same queue in the same step at the same interpolated time pass in the order of the populations, not at random. This order is kept by design (issue #1). Individual exit times, and aggregate results when the tied agents differ in speed, area factor or target, can therefore depend on the order of the population list. In a small test, a 100 m² room with one 1 m door of zero length to a safe node holds 20 agents of area factor 1 and 20 of area factor 2. The evacuation time is 43.0 s in both orders, but the last agent of the area-factor-1 group leaves at 21.0 s when that group is listed first and at 43.0 s when it is listed second. At a route tie, the population order also decides which agents take which of the tied links.

• Pairs cost run time. Medians on an Apple M3 Pro: one run of the ten-storey building, which has no two-way connections, takes 0.076 s against 0.073 s before the counterflow rule (+4 %), the same under "independent" and "bounding". A swap of 200 + 200 agents through one two-way door takes 0.028 s under "independent" (0.027 s before) and 0.079 s under "bounding", with a pair in counterflow in every step: about three times slower.

Monte Carlo

• Incomplete runs make high quantiles infinite. A run that still has agents inside at t_max (3600 s by default) returns nan; its evacuation time is only known to exceed t_max. quantile ranks such runs above every finished run and returns inf for every quantile that depends on one of them. It warns whenever any run is incomplete. Raise t_max until runs.incomplete is 0 (Running).
• Quantiles describe the inputs. They reflect the spread of the sampled inputs, not the uncertainty of the model itself.

Behaviour

• Behaviour is minimal. There are no lighting or smoke effects on speed, no groups, phased evacuation or node delays, and no refuge model: a refuge can only be a safe node, with unlimited capacity and no onward movement. Mobility impairment can be represented only through speed and area factor.
• Detection and alarm are not modelled. They count only if added to pre_movement (defaults).

Input checks

Inputs that are almost certainly mistakes are rejected with a ValueError when the network, a distribution, a population or the simulation is built, so Python, a scenario file, the command line and the terminal UI give the same message (issue #53): stair dimensions of 1 m or more (mm instead of m), a negative plain pre_movement, start_distance, speed or count, area_factor 0 or negative, a negative boundary_layer, area together with length or width, a Weibull alpha or beta of 0 or less, a negative LogNormal std, a start_distance distribution with lower None or negative, a dt below 1e-6 s, and nan or inf anywhere. Fixed(-5) and Fixed(10, upper=3) raise ValueError, and so does every distribution with lower greater than upper. The messages are listed under Networks and Running.

Some inputs are accepted with a warning or without a message:

• max_density at or below 1.88 m⁻² turns supply reduction off. The simulation issues a UserWarning (Movement and capacity).
• A stair outside the SFPE range is extrapolated with a UserWarning (Networks).
• A negative sampled pre_movement with lower=None is kept: the agent starts at t = 0.
• A total population of 0 gives an evacuation time of 0 s.

Output

• node_occupancy counts heads. It counts agents, not area factors, so it differs from the density the model uses when area factors other than 1 are present.
• agents.csv has no population column. The result files of the command line list agents in population order, but a run does not record the population of each agent, and count can be sampled (Command line).
• No counterflow output. SimulationResult does not report in which steps a pair was in counterflow or its minor share (issue #40).