jupedsim_scenarios.runner

jupedsim_scenarios.runner#

High-level helpers for loading and running JuPedSim web-UI scenario JSON files.

A thin scenario layer on top of the simulation primitives in utils.simulation_init and shared.direct_steering_runtime. Used by the trajectory regression test and the scripts/run_scenario.py CLI; the web runtime itself goes through services.simulation_service.

This module replaced the previous backend/core/scenario.py mirror — see the chore/drop-core-mirror PR. The longer-term plan is to migrate to jupedsim.internal.scenarios (jupedsim PR #1565) once it lands upstream.

Usage:

from scenarios import load_scenario, run_scenario

scenario = load_scenario("scenario.zip")
print(scenario.summary())

result = run_scenario(scenario)
print(result.metrics)

df = result.trajectory_dataframe()

Classes#

`Scenario`	A loaded scenario ready for inspection and execution.
`ScenarioResult`	Results from running a scenario.

Functions#

`load_scenario`(→ Scenario)	Load a scenario ZIP or directory exported from the JuPedSim web UI.
`run_scenario`(→ ScenarioResult)	Run a scenario with the same shared setup/runtime semantics as the web app.

Module Contents#

class Scenario[source]#

A loaded scenario ready for inspection and execution.

copy(**overrides) → Scenario[source]#: Return an independent deep copy of this scenario, with optional field overrides.

list_distributions() → list[dict][source]#: Return a list of {"index", "id", "agents", "flow"} dicts.

list_stages() → list[dict][source]#: Return a list of {"index", "id", "waiting_time"} dicts.

list_zones() → list[dict][source]#: Return a list of {"index", "id", "speed_factor"} dicts.

plot(ax=None)[source]#

Plot the scenario geometry with labeled distributions, exits, zones, and checkpoints.

Returns the matplotlib Axes so callers can further customise the figure.

set_agent_count(distribution_id: int | str, count: int)[source]#

set_agent_params(distribution_id: int | str, **kwargs)[source]#

Set agent parameters for a distribution.

Supported keys: radius, desired_speed (or v0), radius_distribution, radius_std, desired_speed_distribution (or v0_distribution), desired_speed_std (or v0_std), use_flow_spawning, flow_start_time, flow_end_time, distribution_mode, number.

set_checkpoint_waiting_time(checkpoint_id: int | str, waiting_time: float)[source]#: Set the waiting time for a checkpoint/stage.

set_flow_schedule(distribution_id: int | str, schedule: list[dict], *, keep_initial_agents: bool = False)[source]#: Attach a time-windowed inflow schedule to one source distribution.

set_max_time(seconds: float)[source]#

set_model_params(**kwargs)[source]#: Set model-specific parameters (e.g. strength_neighbor_repulsion, range_neighbor_repulsion).

set_model_type(model_type: str)[source]#

set_seed(seed: int)[source]#

set_zone_speed_factor(zone_id: int | str, factor: float)[source]#: Set the speed factor for a zone.

summary() → str[source]#

property distributions: dict[str, Any][source]#

property exits: dict[str, Any][source]#

property journeys: list[dict[str, Any]][source]#

property max_simulation_time: float[source]#

model_type: str[source]#

raw: dict[str, Any][source]#

seed: int[source]#

sim_params: dict[str, Any][source]#

source_path: str | None = None[source]#

property stages: dict[str, Any][source]#

walkable_area_wkt: str[source]#

property walkable_polygon[source]#

property zones: dict[str, Any][source]#

class ScenarioResult[source]#

Results from running a scenario.

cleanup()[source]#: Delete the temporary SQLite trajectory file.

trajectory_dataframe()[source]#

Load trajectory data into a pandas DataFrame.

Columns: frame, id, x, y, ori_x, ori_y

property agents_evacuated: int[source]#

property agents_remaining: int[source]#

property dt: float[source]#: Simulation timestep in seconds.

property evacuation_time: float[source]#

property frame_rate: float[source]#

Trajectory frame rate in frames per second.

Sourced from metrics (computed from the actual dt and writer stride used at simulation time). Falls back to 10.0 only when metrics are absent — that fallback is a safety value, not the true rate.

metrics: dict[str, Any][source]#

property seed: int[source]#: Random seed used for this run.

sqlite_file: str | None = None[source]#

property success: bool[source]#

property total_agents: int[source]#

property walkable_polygon[source]#: Walkable area as a Shapely Polygon (for pedpy analysis).

load_scenario(path: str) → Scenario[source]#: Load a scenario ZIP or directory exported from the JuPedSim web UI.

run_scenario(scenario: Scenario, *, seed: int | None = None) → ScenarioResult[source]#: Run a scenario with the same shared setup/runtime semantics as the web app.