Documentation
Getting started
Quickstart

Quickstart

Run the same evacuation twice, once in clear air and once in smoke, and see how smoke changes walking speed and evacuation time.

What you will do

  1. Run a clear-air evacuation.
  2. Add a prescribed smoke field.
  3. Compare both runs.
  4. Change the smoke density yourself.
  5. Inspect the manifest that records how the run was produced.

Runtime: about 3 s. No FDS output is needed.

Before you start

You need:

  • a clone of the repository;
  • the environment installed with uv sync (see Install);
  • a shell opened in the repository root.

The complete example is examples/quickstart.py. Run it with:

uv run python examples/quickstart.py

The scenario is assets/ISO-table21: a corridor 2 m wide and 100 m long, with one agent walking at 1.25 m/s from one end to the exit at the other. It is the geometry of ISO 20414 Test 18.

1. Import the API

Everything is imported from pyfds_evac.

from pyfds_evac import (
    ConstantExtinctionField,
    SmokeSpeedConfig,
    SmokeSpeedModel,
    load_scenario,
    run_scenario,
)

K_PER_M = 3.0  # extinction coefficient K [1/m]; visibility S = 3/K = 1 m
What are these objects?
  • load_scenario loads a tracked JuPedSim scenario.
  • run_scenario runs it and returns the result.
  • ConstantExtinctionField is a prescribed smoke field: the same extinction coefficient K everywhere, at all times.
  • SmokeSpeedModel slows the agents according to the smoke they stand in.
  • SmokeSpeedConfig chooses and configures the speed law.

2. Run in clear air 

scenario = load_scenario("assets/ISO-table21")
clear = run_scenario(scenario, seed=420)
print(f"clear air:   {clear.evacuation_time:.2f} s")

3. Run in smoke

Now run the same scenario, with the same seed, in a uniform smoke field.

smoke = SmokeSpeedModel(
    ConstantExtinctionField(K_PER_M),
    SmokeSpeedConfig(),
)

smoky = run_scenario(
    scenario,
    seed=420,
    smoke_speed_model=smoke,
)

print(f"K = {K_PER_M} 1/m: {smoky.evacuation_time:.2f} s")
Clear air
78.94 s
Smoke, K = 3 1/m
103.99 s
Difference: +25.05 s (+31.7 %)

In this example, one agent in one corridor, the evacuation time grows by about a third. Other scenarios change by other amounts.

Why did the agent slow down?

ConstantExtinctionField(K) returns the same extinction coefficient K at every point and time. SmokeSpeedConfig() selects the default speed law, "lund", which multiplies the walking speed by a factor that falls linearly with K:

speed factor = 1 + beta × K / alpha,  clamped to [min_speed_factor, 1.0]

With the defaults, K = 3.0 1/m gives 1 + (-0.057 × 3.0) / 0.706 = 0.7578. The agent walks at about 76 % of its clear-air speed. The clamp matters only above K ≈ 11 1/m, where the factor would drop below min_speed_factor = 0.1.

With a visibility factor C = 3 (a reflective sign), the visibility is S = C/K = 1 m.

The smoke-speed model page has the laws, their parameters and their sources.

4. Compare the runs 

factor = smoky.smoke_history[-1]["speed_factor"]
ratio = smoky.evacuation_time / clear.evacuation_time

print(f"speed factor in smoke: {factor:.4f}")
print(f"time ratio smoke/clear: {ratio:.4f}")
Why is the time ratio not exactly 1 / speed factor?
1 / 0.7578 = 1.3196, but the runs give 1.3174. The evacuation time comes from the full JuPedSim run, not from distance divided by speed. Time that does not scale with the speed, such as the agent’s start-up, makes the two differ slightly.

5. Try it yourself

Before running another simulation, explore what the smoke-speed model predicts when the extinction coefficient changes.

This widget evaluates the smoke-speed model only. It does not run JuPedSim and it does not predict evacuation time. The evacuation times above came from the actual simulation.

Model: the default lund law, factor = 1 + βK/α clamped to [0.1, 1], with α = 0.706, β = -0.057 and C = 3, the SmokeSpeedConfig() defaults of this version of pyFDS-Evac.

Try this

Set K = 1.0 1/m. Before running the simulation, ask yourself:

  • Is the visibility higher or lower?
  • Is the speed factor higher or lower?
  • Should the evacuation be faster or slower than with K = 3.0 1/m?
Show the expected trend
With less extinction, the visibility increases and the speed factor moves closer to 1. The evacuation should therefore be faster than in the K = 3.0 1/m case. The exact evacuation time still has to come from the simulation.

To check, change one line of examples/quickstart.py:

K_PER_M = 1.0

and run the example again:

uv run python examples/quickstart.py

6. Find the run manifest 

print(f"manifest: {smoky.manifest_file}")
What does the manifest record?
  • the versions of pyFDS-Evac, JuPedSim, fdsreader and fdsvismap;
  • the uv.lock hash;
  • the git commit and whether the working tree had uncommitted changes;
  • the random seed;
  • the scenario path;
  • the FDS directory and FDS version.

The FDS directory and version are null here, because no FDS output was read. run_scenario writes the trajectory to a temporary SQLite file and the manifest next to it, as <trajectory stem>.manifest.json.

7. Clean up 

clear.cleanup()
smoky.cleanup()

This deletes the temporary trajectory files and their manifests. Copy them before calling cleanup() if you want to keep them.

If the smoke run is not slower, check that you passed smoke_speed_model=. Without it, run_scenario models no smoke.

run_scenario builds only what you pass it. run.py builds more by default, rerouting every second among other things, so the same scenario can behave differently from the command line; see Python API and command line.

Next step

Use real FDS output instead of a prescribed uniform smoke field:

Real-FDS walkthrough →
Extinction and toxic gases read from FDS slices, and how to spot a run that succeeds but is wrong.

Also:

pyFDS-Evac is research software, provided without warranty.

Last updated on
Real-FDS walkthrough