pyFDS-Evac example: Start from your own FDS case
================================================

pyfds-evac init turns an FDS deck into a scenario folder. Check two
plain FDS decks before FDS runs, import them, add an exit and the
agents, and run them in clear air. The FDS+Evac guide deck of step 5 is
GPL-3.0 and is downloaded separately.

Page: https://pedestriandynamics.org/pyFDS-Evac/docs/getting-started/start-from-fds-deck/

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    plain FDS deck with two OPEN vents (steps 1 to 3)
  assets/t_junction/geometry.wkt      the hand-drawn walkable area, to compare with the derived one (step 2)
  assets/ISO-table21/ISO-table21.fds  plain FDS deck with no exit (step 4)

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 07206fde512501462d13c472c876f2d93dc62e70 (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
  FDS          not needed

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 deck before FDS runs:

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

3. Import it with 40 agents and run in clear air:

     pyfds-evac init assets/t_junction/t_junction.fds --agents 40
     pyfds-evac --scenario assets/t_junction/t_junction_scenario --seed 1

4. Add the missing exit of the corridor and run:

     pyfds-evac init assets/ISO-table21/ISO-table21.fds --exit 50,-1,50,1 --agents 20
     pyfds-evac --scenario assets/ISO-table21/ISO-table21_scenario --seed 1

Runtime
-------
  pyFDS-Evac: a few seconds per run

Expected result
---------------
The page shows these lines. They were produced at commit 29be041c with
Python 3.13.4 on Apple M3 Pro, macOS.

  Simulation finished in 34.70 s (40/40 evacuated).
  Simulation finished in 89.12 s (20/20 evacuated).

These are the last lines of the two runs. pyfds-evac init exits with
status 0 for both imports.

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.
