v0.6.1, MIT licence

Visibility-aware evacuation
modelling on FDS output

A Python library that couples a finished Fire Dynamics Simulator run to 
JuPedSim agents: smoke slows them, dose stops them, smoke along a route 
changes their exit, and sign legibility decides which exits they know.

Quickstart Coming from FDS+Evac Documentation
Research software, provided without warranty. Not intended for regulatory or design use.
Defaults follow FDS+Evac; see what changed.

Speed

Extinction coefficient reduces walking speed with the Frantzich–Nilsson law (the linear FDS+Evac law), or the fridolf option (Fridolf et al. 2019, Eq. 7), from Python, with an optional irritant slowdown.

Dose

Purser fractional effective dose as computed by FDS+Evac (the FED function of FDS), from up to 12 gas species, plus an opt-in convective heat dose accumulated separately. By default every agent stops at FED 1, as in FDS+Evac.

Route choice

Optical depth integrated along the route the agent will actually walk refuses exits and orders the rest. Re-decided every second by default in run.py.

Wayfinding

fdsvismap decides which signs an agent can read through smoke. What it reads enters its cognitive map; fully familiar agents know the building, discovery agents learn it.

Verification

Each model checked against hand calculations, published tables and FDS’s own output, one page per test with the setup, the expected value and the simulated result.

One-way coupling

FDS runs once. Egress reads the stored slices through one sampling interface, so a synthetic field replaces FDS in tests and routing sweeps never re-run the fire.

One entry point

Script, test, command line, and the optional web GUI and terminal UI all call the same run_scenario(); the pyfds-evac command (run.py) and both front ends also build the same models for it. Results are a JuPedSim trajectory file plus per-agent CSV histories.

Installation

Install pyFDS-Evac from PyPI and check it. Requirements (Python 3.12 to 3.14) and a full check on a scenario are on the Install page.

pip install pyfds-evac            # the pyfds-evac command
pip install "pyfds-evac[gui]"     # adds what pyfds-evac-gui needs
pip install "pyfds-evac[tui]"     # adds what pyfds-evac-tui needs
pyfds-evac --help

The package contains no scenarios or examples. Each example page offers its input files as a zip. To run the scripts and the scenarios with tracked FDS output, clone the repository and use uv:

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

Where to start

Install
Requirements, install, and a one-line check.
Quickstart
One run on a tracked scenario, no FDS output needed.
Coming from FDS+Evac
Where each FDS+Evac input goes, and what has no equivalent.
Real-FDS walkthrough
From tracked FDS output to doses and exit times.
Limitations
Status, library-level parameters, and what is not modelled.

Your own FDS case

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 the deck has to dump specific slices for that to work.

Workflow

LibraryRole
FDSFire physics. Writes slices: extinction coefficient, temperature, CO, CO₂, O₂, HCN, irritants.
fdsreaderNearest-neighbour lookup of any slice quantity at a time and position.
fdsvismapPer sign and time: which floor cells can read it, Beer–Lambert along the sight line.
pyFDS-EvacSpeed factor, dose, route ranking, cognitive maps. Decides where each agent goes and how fast.
JuPedSimMoves agents collision-free on the walkable area.

pyFDS-Evac adds no movement model and no fire model.

For the ideas behind speed, route choice and wayfinding, read Concepts and the talk A Modular Workflow for Visibility-Aware Evacuation Modelling.