Limitations
Status
pyFDS-Evac is research software, provided without warranty. It is not intended for regulatory or design use. It is developed at Forschungszentrum Jülich (IAS-7); its maintainers are listed in CODEOWNERS. It has no release policy yet, so behaviour and defaults can change between commits. A result from pyFDS-Evac is a research result. It is not an assessment of a building.
The evidence that exists is listed on the verification page. That evidence is verification (the code does what its equations say), not validation (the equations describe how people behave).
Some parameters are library-level
Not every model parameter is reachable from the command line or the scenario
JSON. The smoke-speed parameters (speed_law, alpha, beta,
min_speed_factor and visibility_factor_c) are fields of
SmokeSpeedConfig. run.py and the web GUI build that object with its
defaults, so every run they start uses the Frantzich–Nilsson law (the lund
option; the linear FDS+Evac law) with the defaults listed on the
smoke-speed model page. Another law or
other coefficients require building the model in Python and passing it to
run_scenario().
The JSON routing block has keys with the same names. They parameterise the
speed factor used to estimate travel time when a route is priced, not the
walking speed. Setting routing.alpha therefore changes which route an agent
prefers but leaves its speed in smoke unchanged. The same split applies to
speed itself: routing.base_speed_m_per_s (1.3 m/s) prices routes, while an
agent walks at its own v0 (1.25 m/s by default).
Incapacitation is deterministic by default
FED below means fractional effective dose. By default
(--incapacitation-mode deterministic), every agent stops when its FED
reaches --fed-threshold (1.0), as in FDS+Evac. A real population does not
stop all at once. With --incapacitation-mode probabilistic, each agent
draws its own threshold from a log-normal distribution with median
--fed-threshold and log-scale spread --susceptibility-sigma (defaults on
the FED model page).
About half of the agents then stop below FED = 1, and about 10 % stop
below FED = 0.3. The default spread is fitted to the incapacitation fractions
of NIST TN 1797
(#148). The
heat dose, which FDS+Evac does not have, is also deterministic by default: no
population spread for heat is published. Its threshold is --fed-threshold
unless --heat-fed-threshold sets another, a departure from ISO 13571:2012
§5.4. Its probabilistic mode reuses the
gas spread without a data basis of its own.
Evacuation time when anyone is incapacitated
An incapacitated agent stays in the simulation as a stationary obstacle. The
run ends early only when no agent is left, so a run in which any agent is
incapacitated continues until max_simulation_time (300 s by default). Its
reported evacuation_time is then that time limit, not the time the last
mobile agent left. success is also true at the time limit even when agents
remain (issue #139).
Read agents_remaining, and take the time each agent left from the
trajectory file, instead of relying on these two values
(issue #141).
Incapacitation during pre-movement is undone
An agent that is incapacitated while it is still waiting out its pre-movement time starts walking when that time ends (issue #145). Scenarios that combine pre-movement with FED therefore under-report incapacitations and over-report evacuees. A scenario that sets no pre-movement gets the FDS+Evac default of 10 s, so this applies to it too, for its first 10 s. Until this is fixed, check the per-agent FED history for agents that crossed their threshold and still reached an exit.
What is not modelled
Radiant heat. The heat dose is opt-in (--enable-heat-fed) and, by
default, convective only: ISO 13571:2012 Eq. (9) from the gas temperature of
an FDS TEMPERATURE slice. Radiation enters only through the opt-in
--heat-fed-method total-flux, from the gas at the head, a hot layer above
it (--heat-regime layer), or the FDS INTEGRATED INTENSITY slice with a
user factor; radiant flux from hot surfaces or a flame is otherwise missed
(#276). In
every total-flux variant a radiant term below the ISO 2.5 kW/m² threshold
counts as zero, and the code applies that threshold to a net or excess flux
rather than an incident one; the consequences, with numbers, are on
Models › Heat › Where the radiant threshold acts,
and the unsourced values on
Models › Heat › Assumptions.
Heat does not affect route choice or walking speed. The heat dose is
opt-in (--enable-heat-fed). When on, it is tracked per agent, separately from the toxic dose, and an agent is
incapacitated when either dose reaches its threshold, one value for both
by default, as ISO 13571:2012 asks (§5.4). The two doses have different
endpoints: gas FED = 1 is incapacitation, heat FED = 1 the time of ISO
Eq. (9), which ISO calls the time to prevention of escape or to
experiencing pain (see Fundamentals › Heat); the FED history’s
incapacitation_cause column says which dose stopped the agent. Before that
point, heat has no effect. Route choice is given the toxic dose only, so an agent can
choose a route that will incapacitate it thermally. Walking speed is reduced
by extinction and, with --enable-fic-speed, by irritant gases, but not by temperature, so an agent walks
at full speed through a hot layer until the heat dose is reached.
Multi-floor buildings and stairs. The walkable area is a single 2-D
polygon, and hazards are sampled from slices at one height
(--smoke-slice-height). There is no stair model, no floor-to-floor
connection and no speed reduction on inclines. generate_walkable_from_fds.py
treats stair treads and risers as floor, so a staircase in an FDS deck becomes
flat floor that agents cross at full speed. A zones entry with a
speed_factor can slow agents inside a polygon, but it does not represent
direction of travel on a stair.
FED activity level. The CO term of the toxic dose uses one fixed coefficient, the FDS+Evac default for light work (Korhonen 2021, Eq. 13; see the FED model). Rest and heavy work cannot be selected, although breathing rate changes the CO dose. Not supported; see issue #135.
Per-exit familiarity. Familiarity is set per spawn distribution, as
"full", "discovery", or one probability applied to every exit. The
entrance key adds one exit that the whole group knows. A separate
probability for each exit, as FDS+Evac allows with KNOWN_DOOR_PROBS, is not
supported; see
issue #136.
Familiarity does not change how agents treat smoke. Familiarity decides
which exits an agent knows, not how much smoke it accepts. The route-cost
settings, including every smoke setting of both cost models, are built once
per run from the scenario’s routing block and fixed defaults
(RouteCostConfig), so every agent shares them. In Wood’s UK
survey, people completely familiar with the building moved through smoke more
often than those less familiar (61 % against 51 %; Wood 1980, Table 6.4,
p. 87), though moving through smoke was not associated with leaving the
building (p. 91). See
issue #362.
Herding and social influence. Each agent chooses its route from its own
cognitive map and the hazard along each route. When routing.w_queue is
above zero (the default is 0.0), expected queueing at an exit also enters the
cost, so a crowded exit becomes less attractive. Agents do not follow others,
and an exit never becomes more attractive because others use it. See
issue #78.
Perception-limited route choice. A discovery agent knows only the exits
its familiarity, entrance or a legible sign gave it, but it prices the routes to them with the smoke
sampled along the whole route, including stretches it has never seen
(issue #125).
By default (routing.anticipate = true, routing.foresight_horizon_s
unbounded), each stretch is also priced with the smoke that the finished FDS
run holds for the time the agent would arrive there. Knowledge limits which
routes an agent ranks, and only fully familiar agents know the whole graph;
it does not limit the smoke those routes are priced with. The route choice of
a discovery agent is therefore not limited by what it has perceived.
Route choice. Route choice has open limitations: switching can oscillate where two routes cross in cost (#124), routes are priced with smoke the agent cannot perceive (#125), one path is priced per exit (#185), and the FED along the walk to the route’s first graph node is not counted (#171). The full list, with one line per issue, is on Models › Routing › Limitations.
Recovery from irritants. The irritant slowdown (opt-in with
--enable-fic-speed) is recomputed only while
the sampled fractional irritant concentration (FIC) is positive. When it
returns to exactly zero, the last slowdown stays in force, so an agent that
leaves an irritant plume into clean air does not return to full speed
(issue #142).
Pre-movement defaults are office data. The gamma, log-normal and Weibull
presets are fitted to office evacuations, mostly drills (Lovreglio et al. 2019,
Business Cluster 1). The uniform 0–60 s preset is RiMEA’s “speedy evacuation”
sensitivity scenario, not data. The 10 s used when a scenario sets no pre-movement is the FDS+Evac default, not
data. Set premovement_param_a and premovement_param_b for other occupancies.
Smoke-triggered detection. Pre-movement is one delay per agent, drawn from a distribution. Smoke reaching the agent does not end the delay early, and there is no separate detection phase.
Feedback from occupants to the fire. The coupling is one-way. The FDS run
is finished before the evacuation starts, so occupants cannot open doors or
otherwise change the fire. The time resolution of the hazard is that of the
slice output (&DUMP DT_SLCF).
Re-entry. An agent that reaches an exit is removed from the simulation
(run_scenario in pyfds_evac/core/scenario.py), so nobody goes back into
the building. In Wood’s UK survey, 43 % of those who had left the building
re-entered it (Wood 1980, Table 6.6, p. 95): 53 % of men and 34 % of women
(Table 6.3, p. 87).
Reproducibility
A fixed seed does not give identical trajectories. The verification suite found that individual trajectories differ between runs with the same seed, while aggregate outcomes (counts and fractions, such as the number of agents incapacitated or rerouted) reproduce. Report aggregate outcomes over several seeds, with their spread, and do not compare single trajectories between runs. See the verification page.
One known cause makes results depend on more than the seed:
- Python’s hash seed. For discovery agents, the order of tied routes can
depend on
PYTHONHASHSEED(#199). Set it to a fixed value for bit-identical reruns.
Earlier runs in the same Python process do not change the results. Every per-agent draw is seeded from the seed and the agent’s spawn order, not from its JuPedSim id. The outputs still label agents by JuPedSim id, which is numbered per process, so a second run in the same process reports the same agents under other ids.
References
Korhonen, T. (2021). Fire Dynamics Simulator with Evacuation: FDS+Evac. Technical Reference and User’s Guide. VTT Technical Research Centre of Finland.
Purser, D. A., and McAllister, J. L. (2016). Assessment of hazards to occupants from smoke, toxic gases, and heat. In SFPE Handbook of Fire Protection Engineering, 5th ed., Chapter 63. Springer.
Wood, P. G. (1980). A survey of behaviour in fires. In D. Canter (Ed.), Fires and Human Behaviour, pp. 83–95. John Wiley & Sons, Chichester. ISBN 0-471-27709-6.