jupedsim-scenarios#

Useful links: Python Package | Source Repository | Issues | JuPedSim

What is jupedsim-scenarios#

jupedsim-scenarios is a Python toolkit for running, sweeping, and analyzing JuPedSim scenarios authored in the Web-Based JuPedSim editor.

Demo — a few lines of Python to load and run a scenario

Intro video (3 min) — overview of the load → run → sweep flow.

Where the main jupedsim package exposes the simulation primitives (geometry, agents, models, journeys), jupedsim-scenarios operates one level up: it consumes a scenario as exported from the web editor — a JSON config plus a WKT geometry, packaged as a zip — and gives you three things:

run_scenario() — run one scenario, get back a ScenarioResult with metrics and a trajectory database compatible with pedpy.
run_sweep() — Monte Carlo parameter sweeps over any axes the Scenario mutators expose, with multi-process workers.
run_sweep_from_factory() — factory-style sweeps for studies where the geometry itself depends on the trial parameters.

Install#

pip install jupedsim-scenarios

Quick start#

from jupedsim_scenarios import load_scenario, run_scenario

scenario = load_scenario("bottleneck.zip")
result = run_scenario(scenario, seed=42)

print(result.evacuation_time)        # seconds
print(result.agents_evacuated, "/", result.total_agents)
df = result.trajectory_dataframe()   # pandas DataFrame
result.cleanup()

In a hurry? The 5-minute quickstart uses a tiny scenario shipped with the repo — no web-editor export needed. For a guided tour with sweeps, model comparison, and a 2-D model × bottleneck width study, see the bottleneck tutorial.

Where to next#

Concepts — the object model: Scenario (mutable), ScenarioResult (owns a temp sqlite), SweepResult (savable artifact).
Choosing an entrypoint — decision table mapping goals to API calls.
Troubleshooting — common pitfalls and their fixes.
CLI reference — jps-scenarios command-line reference.

Citation#

If jupedsim-scenarios supports work you publish, please cite the upstream JuPedSim project and link to this repository (PedestrianDynamics/jupedsim-scenarios). A dedicated DOI for this toolkit will be added once a Zenodo deposit is in place.

Status#

Single-run, Monte Carlo sweeps (multi-process), save/resume of sweeps, and a jps-scenarios CLI are shipped. See the CHANGELOG for the full release history.

jupedsim-scenarios

Contents