Quickstart — your first run

Goal: load a scenario, run it, and see a result — in under a minute, with one zip already shipped with the repo.

If you have not installed the package yet:

pip install jupedsim-scenarios

Then run the cells below in order.

1. Load a scenario

A scenario bundles the walkable geometry, agents, journeys, and solver settings. quickstart.zip is a small square-room scenario shipped with the repo. load_scenario also accepts a ZIP exported from the Web-Based JuPedSim editor, a directory with *.json + *.wkt, or a single self-contained JSON file.

import logging

logging.getLogger("jupedsim_scenarios").setLevel(logging.WARNING)

from jupedsim_scenarios import load_scenario

scenario = load_scenario("../assets/quickstart.zip")
print(f"model: {scenario.model_type}")
print(f"max simulation time: {scenario.max_simulation_time} s")

model: WarpDriverModel
max simulation time: 300 s

2. Run it

run_scenario returns a ScenarioResult with summary metrics and a temporary SQLite trajectory file.

from jupedsim_scenarios import run_scenario

result = run_scenario(scenario, seed=420)
print(f"evacuation time : {result.evacuation_time:.1f} s")
print(f"agents evacuated: {result.agents_evacuated} / {result.total_agents}")

evacuation time : 31.1 s
agents evacuated: 104 / 104

3. Pull the trajectory and plot one frame

trajectory_dataframe() returns a pandas DataFrame with one row per agent per recorded frame. The schema is compatible with pedpy for downstream analysis.

import matplotlib.pyplot as plt

df = result.trajectory_dataframe()
frame_zero = df[df["frame"] == df["frame"].min()]

fig, ax = plt.subplots(figsize=(6, 4))
ax.scatter(frame_zero["x"], frame_zero["y"], s=20)
ax.set_aspect("equal")
ax.set_title(f"Initial agent positions ({len(frame_zero)} agents)")
ax.set_xlabel("x [m]")
ax.set_ylabel("y [m]")
plt.show()

4. Clean up

The temporary trajectory file is not removed on garbage collection. Call cleanup() (or wrap the run in try / finally) so long notebook sessions do not accumulate gigabytes of SQLite files.

result.cleanup()

1

Where to next

• Concepts — the Scenario / ScenarioResult / SweepResult lifecycle.

• Choosing an entrypoint — when to use run_sweep vs run_sweep_from_factory.

• Bottleneck tutorial — a guided tour with sweeps and model comparison.

• Troubleshooting — common pitfalls and fixes.