pyFDS-Evac example: A crowd in a fire
=====================================

150 agents leave a T-shaped corridor while a 2 MW PVC fire fills it with
smoke. You run the FDS deck yourself, then pyFDS-Evac on its output.

Page: https://pedestriandynamics.org/pyFDS-Evac/docs/getting-started/first-fds-case/

Run every command from this folder, the folder that holds this
README.txt. The files keep the layout of the pyFDS-Evac repository, so
the commands are the ones on the page, with python instead of uv run
python.

Contents
--------
  README.txt                              this file
  LICENSE                                 MIT licence of the code
  requirements.txt                        pinned Python packages, from uv.lock
  assets/t_junction/t_junction.fds        FDS deck of the fire
  assets/t_junction/config.json           JuPedSim scenario
  assets/t_junction/geometry.wkt          walkable area
  run.py                                  the pyFDS-Evac command line
  examples/first_fds_case.py              the same run from Python
  scripts/docs/first_fds_case_figures.py  the figures of section 5
  scripts/animate_agents_smoke.py         animation helpers used by the figure script
  scripts/docs/first_fds_case_aset.py     the numbers and figures of section 6 (ASET and RSET)

Versions
--------
The zip was built from this commit. requirements.txt pins every Python
package to the version in its uv.lock.

  pyFDS-Evac   0.6.1, git commit e1f296725e70051f91d6741b4f4dd50dbee06a42 (2026-10-21)
  Python       >=3.12,<3.15
  jupedsim     1.4.2
  pedpy        1.4.0
  fdsreader    1.11.7
  fdsvismap    0.3.3
  numpy        2.4.4
  shapely      2.1.2
  matplotlib   3.10.8
  pandas       2.3.3
  seaborn      0.13.2
  FDS          FDS-6.10.1-0-g12efa16-release

Run it
------
The commands are for a POSIX shell (Linux, macOS; on Windows, WSL or Git
Bash).

1. Install pyFDS-Evac and the pinned packages:

     python -m venv .venv
     source .venv/bin/activate    # Windows: .venv\Scripts\activate
     pip install -r requirements.txt

2. Check the scenario runs in clear air (about 5 s):

     python examples/first_fds_case.py

3. Check the deck before FDS runs (writes nothing):

     pyfds-evac init assets/t_junction/t_junction.fds --check

4. Run FDS (about 20 min with 4 MPI processes):

     mkdir -p fire && cp assets/t_junction/t_junction.fds fire/
     cd fire && mpiexec -n 4 fds t_junction.fds && cd ..

5. Run pyFDS-Evac in the fire (about 10 s) and in clear air:

     FDS=fire
     mkdir -p tj
     python run.py --scenario assets/t_junction --fds-dir "$FDS" \
         --output-sqlite tj/tj_fire.sqlite \
         --output-smoke-history tj/tj_fire_smoke.csv \
         --output-fed-history tj/tj_fire_fed.csv \
         --output-route-history tj/tj_fire_routes.csv
     python run.py --scenario assets/t_junction \
         --output-sqlite tj/tj_clear.sqlite
     python examples/first_fds_case.py "$FDS"

6. Draw the figures of section 5:

     python scripts/docs/first_fds_case_figures.py --data "$FDS" --runs tj

7. Compute the numbers of section 6 (ASET and RSET):

     python scripts/docs/first_fds_case_aset.py --data "$FDS" --runs tj

Runtime
-------
  FDS: 1169 s wall clock (about 20 min) with 4 MPI processes on an Apple M3 Pro, macOS
  pyFDS-Evac: about 10 s for the fire run

Expected result
---------------
The page shows these lines. They were produced at commit e7bed1dd with
Python 3.13.4 on Apple M3 Pro, macOS, from FDS output of
FDS-6.10.1-0-g12efa16-release.

  evacuated: 99/150 in 300 s
  FED max:   0.23
  route history rows by reason: {'default_route': 150, 'initial': 1, 'smoke_reroute': 2, 'learned_exit': 10}

These are the last lines of python examples/first_fds_case.py "$FDS".
Without FDS output it prints evacuated: 144/150 in 300 s. run.py ends
with: Simulation incomplete: time limit reached after 300.00 s (99/150
evacuated, 51 remaining, 50 not spawned). and exits with status 2, as
for every run that reaches its time limit with agents inside.

Licence
-------
Code (the .py files): MIT, see LICENSE. FDS decks, scenario files and
geometry: CC-BY-4.0, https://creativecommons.org/licenses/by/4.0/.
Attribution: pyFDS-Evac,
https://github.com/PedestrianDynamics/pyFDS-Evac.

pyFDS-Evac is research software, provided without warranty.
