pyFDS-Evac example: ISO 20414 Test 19: incapacitation by toxic gases
====================================================================

One occupant stands in a room with fixed CO, CO2 and O2 levels, in four
cases a-d; pyFDS-Evac must stop it at the first FED update after the
hand-calculated time t*. You run the four small FDS decks yourself.

Page: https://pedestriandynamics.org/pyFDS-Evac/verification/iso-test-19/

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
  run.py                                        the pyFDS-Evac command line
  scripts/verification/iso_test19_figures.py    prints each check and draws the figures
  assets/iso_table22_coupled/build_geometry.py  writes the four decks, scenarios and geometry
  assets/iso_table22_coupled/iso_table22_a.fds  FDS deck, case a: CO, CO2 and reduced O2
  assets/iso_table22_coupled/iso_table22_b.fds  FDS deck, case b: reduced O2 alone
  assets/iso_table22_coupled/iso_table22_c.fds  FDS deck, case c: CO alone
  assets/iso_table22_coupled/iso_table22_d.fds  FDS deck, case d: CO and CO2
  assets/iso_table22_coupled/config_a.json      JuPedSim scenario, case a
  assets/iso_table22_coupled/config_b.json      JuPedSim scenario, case b
  assets/iso_table22_coupled/config_c.json      JuPedSim scenario, case c
  assets/iso_table22_coupled/config_d.json      JuPedSim scenario, case d
  assets/iso_table22_coupled/geometry.wkt       walkable area
  assets/iso_table22_coupled/README.md          what the four cases are and where they come from
  assets/ISO-table22/config.json                the second version of this test (Limits on the page), scenario
  assets/ISO-table22/geometry.wkt               the second version of this test, walkable area
  assets/ISO-table22/README.md                  the second version of this test

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. Run FDS on the four decks, one process each (about 25-45 s per case).
   OUT is a folder of your choice:

     OUT=$HOME/iso-test-19
     for c in a b c d; do
       mkdir -p $OUT/fds/$c && cp assets/iso_table22_coupled/iso_table22_$c.fds $OUT/fds/$c/
       (cd $OUT/fds/$c && fds iso_table22_$c.fds)
     done

3. Run pyFDS-Evac on the four cases and draw the figures (about 1 min):

     for c in a b c d; do
       python run.py --scenario assets/iso_table22_coupled/config_$c.json \
         --fds-dir $OUT/fds/$c --seed 420 --incapacitation-mode deterministic \
         --smoke-update-interval 1 \
         --output-sqlite $OUT/evac/$c/run.sqlite \
         --output-fed-history $OUT/evac/$c/fed_history.csv \
         --vis-cache $OUT/evac/$c/vis_cache.npz
     done
     python scripts/verification/iso_test19_figures.py --data $OUT

Runtime
-------
  FDS: 30 s (a), 44 s (b), 44 s (c) and 24 s (d) wall clock, one process each, on an Apple M3 Pro, macOS
  pyFDS-Evac: about 1 min for the four cases

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.

  a: t* <= t_sim < t* + 1: True; stop == crossing: True
  d: t* <= t_sim < t* + 1: True; stop == crossing: True
  all pass criteria hold

scripts/verification/iso_test19_figures.py prints a table with, per
case, t* by hand, the FDS device time and the simulated stop: 981.71,
981.65 and 982.00 s for case a, 1666.49, 1666.49 and 1667.00 s for b,
1692.82, 1692.72 and 1693.00 s for c, 846.50, 846.45 and 847.00 s for d,
as on the page. Then one line per case, as above, and the verdict. The
script stops at the first pass criterion that fails.

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.
