pyFDS-Evac example: Quickstart
==============================

One agent walks a corridor 2 m wide and 100 m long (assets/ISO-table21),
once in clear air and once in uniform smoke with K = 3 1/m. No FDS run
is needed.

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

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/quickstart.py              the example script
  assets/ISO-table21/config.json      JuPedSim scenario
  assets/ISO-table21/geometry.wkt     walkable area
  assets/ISO-table21/ISO-table21.fds  FDS deck of the same corridor (ISO 20414 Test 18); the quickstart does not run it
  assets/ISO-table21/README.md        what the scenario is and where it comes from
  run.py                              the pyFDS-Evac command line, which the page compares with run_scenario

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          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. Run the example (about 3 s):

     python examples/quickstart.py

Runtime
-------
  pyFDS-Evac: about 3 s

Expected result
---------------
The page shows these lines. They were produced at commit 9c820e0f with
Python 3.12.13 on Apple M3 Pro, macOS.

  clear air:   79.24 s
  K = 3.0 1/m: 104.39 s
  speed factor in smoke: 0.7578
  time ratio smoke/clear: 1.3174

The last line, manifest: <path>, names a new temporary file on every
run.

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.
