pyFDS-Evac example: Real-FDS walkthrough
========================================

One agent walks a 100 m corridor through smoke read from an FDS slice,
and one occupant gathers a toxic dose (FED) from CO, CO2 and O2 slices.
You run the two small FDS decks yourself, then the walkthrough script.

Page: https://pedestriandynamics.org/pyFDS-Evac/docs/getting-started/walkthrough/

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
  examples/walkthrough.py                             the example script
  run.py                                              the pyFDS-Evac command line (step 1 of the page: --inspect-fds)
  assets/iso_table21_coupled/iso_table21_coupled.fds  FDS deck of the smoky corridor
  assets/iso_table21_coupled/config.json              JuPedSim scenario of the corridor
  assets/iso_table21_coupled/geometry.wkt             walkable area of the corridor
  assets/iso_table21_coupled/build_geometry.py        writes the corridor deck, scenario and geometry
  assets/iso_table21_coupled/README.md                what the corridor case is and where it comes from
  assets/iso_table22_coupled/iso_table22_a.fds        FDS deck of the gas room, case a
  assets/iso_table22_coupled/config_a.json            JuPedSim scenario of the gas room
  assets/iso_table22_coupled/geometry.wkt             walkable area of the gas room
  assets/iso_table22_coupled/build_geometry.py        writes the gas-room decks, scenarios and geometry
  assets/iso_table22_coupled/README.md                what the gas-room cases are and where they come from

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
  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. Run FDS on the two decks, one process each (about 10 s and 30 s). The
   output goes to the folders the script reads:

     mkdir -p assets/iso_table21_coupled/fds
     cp assets/iso_table21_coupled/iso_table21_coupled.fds assets/iso_table21_coupled/fds/
     (cd assets/iso_table21_coupled/fds && fds iso_table21_coupled.fds)
     mkdir -p assets/iso_table22_coupled/fds/a
     cp assets/iso_table22_coupled/iso_table22_a.fds assets/iso_table22_coupled/fds/a/
     (cd assets/iso_table22_coupled/fds/a && fds iso_table22_a.fds)

3. Run the walkthrough (about 15 s):

     python examples/walkthrough.py

Runtime
-------
  FDS: 10 s (iso_table21_coupled) and 30 s (iso_table22_a) wall clock, one process each, on an Apple M3 Pro, macOS
  pyFDS-Evac: about 15 s

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

  exit time:    78.44 s clear, 85.30 s in smoke
  FED >= 1 at t = 982 s; incapacitated: True
  FED max: 1.000

python examples/walkthrough.py prints these lines among the others the
page shows. FDS 6.10.1 on the two decks writes slices identical, byte
for byte, to the ones in the repository.

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.
