pyFDS-Evac

Fire Dynamics Simulator (FDS) coupled evacuation modeling with smoke-speed reduction, toxic gas dose (FED), and dynamic route rerouting.

The project includes:

• Smoke-speed model (visibility/extinction-based speed reduction)
• Purser FED as computed by FDS+Evac (the FED function of FDS; toxic gas dose accumulation, up to 12 species)
• Convective heat FED (ISO 13571:2012 Eq. (9), fully clothed; Eq. (10) = SFPE Handbook Eq. 63.44 with --heat-clothing unclothed), opt-in with --enable-heat-fed (FDS+Evac has none), accumulated as a dose independent of the gas track -- an agent is incapacitated when either crosses the threshold, one for both by default as in ISO 13571; the heat dose is a running total of its own and is never added to the gas FED. Radiant heat enters only through the opt-in total-flux method (gas at the head, a hot layer above the head, or FDS INTEGRATED INTENSITY with a user factor; a radiant term below 2.5 kW/m² counts as zero, as in ISO 13571), and heat does not enter route choice. It also does not slow an agent down: unlike smoke and irritants, heat has no effect at all until the dose is reached, at which point the agent stops.
• Dynamic smoke-based route rerouting, with an optional exit-queue term (off by default)
• Smoke-gated exit availability, and sign visibility for what agents learn (fdsvismap integration)
• Per-agent cognitive maps with full and discovery familiarity tiers
• JuPedSim scenario loading and simulation

Documentation

The model descriptions, usage and verification live on the documentation site: https://pedestriandynamics.org/pyFDS-Evac/

• Install: requirements and a check that the install works
• Usage: CLI flags, post-processing scripts, run-and-plot driver
• Outputs and Scenario JSON: what a run writes, and the keys a scenario reads
• Defaults follow FDS+Evac; see what changed and the changelog
• Smoke-speed model, including FDS data access through fdsreader
• Fractional effective dose, including heat dose and irritant slowdown
• Dynamic route rerouting
• Wayfinding
• Verification suite

Talks

• A Modular Workflow for Visibility-Aware Evacuation Modelling, Visibility Seminar 2026, University of Wuppertal, 25 September 2026: slides

Installation

pyFDS-Evac needs Python 3.12, 3.13 or 3.14. Install it from PyPI:

pip install pyfds-evac
pyfds-evac --help

pyfds-evac runs a scenario; python -m pyfds_evac does the same. pyfds-evac init deck.fds starts a scenario from an FDS or FDS+Evac deck and reports what it could not carry over (Start from your own FDS case). The package contains no scenarios, examples or scripts. Each example page on the documentation site offers its input files as a zip, which unpacks into a folder of its own; run the commands from inside that folder. The Install page has a full check on a scenario.

Development

To work on the code, or to run the examples, scripts and tracked scenarios of the repository, clone it and use uv:

git clone https://github.com/PedestrianDynamics/pyFDS-Evac.git
cd pyFDS-Evac
uv sync
uv run run.py --scenario assets/ISO-table21

run.py is the same command line as pyfds-evac (uv run uses the project environment; source .venv/bin/activate activates it for the shell). Usage lists every CLI flag, the post-processing scripts, and the scripts/run_and_plot.sh driver that runs a simulation and produces every plot in one go.

Tests, the docs build and pull requests: see Development and CONTRIBUTING.md.

Bringing your own FDS case? Read what your FDS case must provide first. pyFDS-Evac does not run FDS, it samples the output of a finished run, and your deck has to dump specific slices for that to work. That page also covers the &REAC yields those slices depend on, and two failure modes that stay silent otherwise.

Terminal UI

For remote machines and SSH, a terminal UI configures, runs and inspects a scenario with the same options as pyfds-evac:

pip install "pyfds-evac[tui]"
pyfds-evac-tui

The run stops when the terminal closes; use tmux or screen for long runs. Documentation: Terminal UI.

Web GUI

An optional local web app runs the same model behind a form:

pip install "pyfds-evac[gui]"
pyfds-evac-gui

Then open http://127.0.0.1:5001. The GUI listens on this computer only; --host and --port change that. It lists the scenarios in ./assets and writes ./uploads and ./results under the folder it starts in. In a source checkout, uv sync --extra gui and uv run app.py start it with the checkout's folders, on 127.0.0.1 with auto-reload. The form groups, the options it does not offer, the result views and how to export a run as a Python script are on the Web GUI page.

Agent speed and pre-movement

The scenario keys that set an agent's speed, size and pre-movement, with their defaults, are on the Scenario JSON page. The smoke-speed law and its parameters are library-level fields, not scenario keys; see the smoke-speed model.

Agent scalars for fds-viewer

When --output-sqlite is combined with FED computation, the SQLite also carries an optional agent_scalars(frame, id, fed, heat_fed, speed) table. The base JuPedSim schema is unchanged, so jupedsim replay and Web-Based-JuPedSim still read the file. Note heat_fed was inserted before speed rather than appended, so a consumer reading positionally with SELECT * -- fds-viewer among them -- must be updated with this release; name your columns and it does not matter. fds-viewer reads this table to colour agents by FED dose or speed in a 3D scene alongside the FDS smoke.

Visualising agents

Agent visualisation is handled by fds-viewer, which renders the JuPedSim trajectory SQLite in a 3-D scene alongside the FDS smoke. Run with --output-sqlite to produce the file fds-viewer loads; this example uses a scenario and FDS output tracked in the repository, so run it in a source checkout:

uv run run.py --scenario assets/iso_table22_coupled/config_a.json \
              --fds-dir assets/iso_table22_coupled/fds/a \
              --output-sqlite results/demo.sqlite

--fds-dir must hold the output of a finished FDS run (the .smv file), not only the deck.

When FED is computed, the SQLite also carries the optional agent_scalars(frame, id, fed, heat_fed, speed) table (see above), which fds-viewer uses to colour agents by FED dose or speed.

References

See the model comparison for a section-by-section comparison of the FDS+Evac and pyFDS-Evac evacuation models (movement, smoke speed, FED, routing), referenced against the FDS+Evac guide below and the pyFDS-Evac source.

Short summaries are stored in materials/. The papers themselves are linked by DOI and not redistributed here:

• FDS+Evac Technical Reference and User's Guide — Korhonen (2021). Primary reference for the FED equations (Section 3.4) and smoke-speed model (Section 3.4, Eq. 11).
• Börger, Belt & Arnold (2024) (summary) — Beer-Lambert extinction averaged along the line of sight to a sign (Eq. 8-9), waypoint-based visibility maps. Fire Safety Journal 150:104269. Averaging along the walked route, as pyFDS-Evac's route cost does, is our extension.
• Haensel (2014) (summary) — Knowledge-based routing and cognitive map framework for evacuation modelling.
• Schroder et al. (2020) (summary) — A map representation of the ASET-RSET concept. Fire Safety Journal.
• Ronchi et al. (2013) — Representation of the impact of smoke on agent walking speeds in evacuation models. Fire Technology 49.
• evac.f90 — Original FDS+Evac Fortran source for cross-referencing implementation details.
• Haghani & Sarvi (2017) — Human exit-choice behaviour under evacuation conditions: literature synthesis.
• Haghani & Sarvi (2018) — Herding and route-choice in immersive-VR evacuation experiments.
• Lovreglio et al. (2014) — Random-utility discrete choice model of exit selection.
• Lovreglio et al. (2016) — Validation of a Bayesian random-utility exit-choice model.

Assets

Scenario definitions are stored in assets/. assets/README.md indexes the folders and the file conventions; Scenario assets describes what each scenario proves and where that proof is checked.

Dependencies

pyFDS-Evac depends on jupedsim, pedpy, fdsreader, fdsvismap, numpy, shapely, matplotlib, plotly and nbformat; the gui extra adds python-fasthtml, monsterui and python-multipart. fdsvismap is pinned exactly (0.3.2), and a plain pip install works on Python 3.12, 3.13 and 3.14. Versions and pins are in pyproject.toml.

License

pyFDS-Evac is released under the MIT license. Two third-party parts of the repository keep their own licenses and are not included in the published packages: assets/fds_evac_guide/, the FDS+Evac guide's input decks (GPL-3.0-only), and materials/evac.f90, the FDS+Evac source (NIST software notice). REUSE.toml records the license of every file, and CI checks it with reuse lint.