pyFDS-Evac example: Route choice in smoke after Schröder et al. (2015)
======================================================================

200 agents leave an assembly hall through door A or B and a corridor
with exits E and F while a fire grows in the room next to the hall. You
run the three FDS decks yourself, then pyFDS-Evac with and without
smoke-aware routing, then the scripts that print the page's numbers and
draw its figures.

Page: https://pedestriandynamics.org/pyFDS-Evac/docs/studies/study-schroeder2015/

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/schroeder2015_route/README.md                      what the inputs are and where they come from
  assets/schroeder2015_route/geometry.py                    every coordinate: walkable area, stages, FDS walls and doors
  assets/schroeder2015_route/make_configs.py                writes the two scenarios and geometry.wkt
  assets/schroeder2015_route/make_decks.py                  writes the FDS decks of all nine fire variants
  assets/schroeder2015_route/run_p1.sh                      runs the evacuation arms, seeds 1-10, on one FDS output
  assets/schroeder2015_route/evac/config_gate.json          scenario, cost model gate (also no fire and smoke-blind)
  assets/schroeder2015_route/evac/config_additive.json      scenario, cost model additive
  assets/schroeder2015_route/evac/geometry.wkt              walkable area
  assets/schroeder2015_route/a047_pvc_h40/a047_pvc_h40.fds  FDS deck of the main fire
  assets/schroeder2015_route/a047_pvc_h35/a047_pvc_h35.fds  FDS deck of a comparison fire (ceiling 3.5 m)
  assets/schroeder2015_route/a012_pvc_h30/a012_pvc_h30.fds  FDS deck of a comparison fire (medium growth, ceiling 3.0 m)
  run.py                                                    the pyFDS-Evac command line
  scripts/docs/schroeder2015_route.py                       the evacuation numbers and figures of the page
  scripts/docs/schroeder2015_fire_figures.py                the geometry and fire numbers and figures (needs all nine fires)
  scripts/docs/study_animations.py                          the animation of the page (subcommand schroeder2015)
  scripts/docs/first_fds_case_figures.py                    plan and colour helpers used by the animation script
  scripts/docs/schroeder_room_maps.py                       imported by the animation script (not used for this page)
  scripts/animate_agents_smoke.py                           animation helpers used by the animation script

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

  pyFDS-Evac   0.5.0, git commit 59fe74d8c71269f72e34f2610e1a2adcc1018137 (2026-10-11)
  Python       >=3.12,<3.15
  jupedsim     1.4.2
  pedpy        1.4.0
  fdsreader    1.11.7
  fdsvismap    0.3.2
  numpy        2.4.4
  shapely      2.1.2
  matplotlib   3.10.8
  pandas       2.3.3
  seaborn      0.13.2
  scipy        1.17.1
  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 three decks, 6 MPI processes each (about 60-100 min
   per deck). DATA is a folder outside this one:

     DATA=$HOME/schroeder2015-route
     for F in a047_pvc_h40 a047_pvc_h35 a012_pvc_h30; do
       mkdir -p "$DATA/$F" && cp assets/schroeder2015_route/$F/$F.fds "$DATA/$F/"
       (cd "$DATA/$F" && mpiexec -n 6 fds $F.fds)
     done

3. Run the evacuation arms, 10 seeds each (about 25-40 s per run; 6 in
   parallel):

     bash assets/schroeder2015_route/run_p1.sh "$DATA/a047_pvc_h40" "$DATA/p1_a047_pvc_h40" 6 --with-nofire
     bash assets/schroeder2015_route/run_p1.sh "$DATA/a047_pvc_h35" "$DATA/p1_a047_pvc_h35" 6
     bash assets/schroeder2015_route/run_p1.sh "$DATA/a012_pvc_h30" "$DATA/p1_a012_pvc_h30" 6

4. Print the page's numbers and draw its evacuation figures (about 3
   min):

     python scripts/docs/schroeder2015_route.py --data "$DATA"

5. Draw the animation of smoke-blind and gate (about 1 min; ffmpeg
   reduces the GIF's colours):

     python scripts/docs/study_animations.py schroeder2015 --data "$DATA"

6. Optional, for the fire-choice figures: write and run the other six
   fire decks (about 6 h in all):

     python assets/schroeder2015_route/make_decks.py "$DATA"
     for F in a047_pvc_h30 a047_pur_h30 a047_pur_h40 a012_pvc_h40 a012_pur_h30 a012_pur_h40; do
       (cd "$DATA/$F" && mpiexec -n 6 fds $F.fds)
     done
     python scripts/docs/schroeder2015_fire_figures.py --data "$DATA"

Runtime
-------
  FDS: 5423 s (a047_pvc_h40), 5929 s (a047_pvc_h35) and 3662 s (a012_pvc_h30) wall clock with 6 MPI processes on an Apple M3 Pro, macOS
  pyFDS-Evac: about 25-40 s per run, 100 runs

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

  main fire, exit-E share: no fire 0.520, gate 0.689, additive 0.447
  main fire, additive dy: -0.90 m (-1.16, -0.64)
  main fire, gate door-B share: 0.04 for starts 30-120 s, 0.83 for starts 150-300 s

scripts/docs/schroeder2015_route.py prints these lines after its tables
and before it writes the figures. The evacuation runs are reproducible
for a given seed; FDS output from another FDS build or machine can move
them slightly.

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.
