Concepts#
Three objects carry state through jupedsim-scenarios. Knowing
which one you are holding — and what mutating it does — prevents
most surprises.
Lifecycle#
zip / json / directory
│
▼ load_scenario(...)
┌──────────────────┐
│ Scenario │ mutable; .copy() to branch
└──────────────────┘
│
▼ run_scenario(scenario, seed=...)
┌──────────────────┐
│ ScenarioResult │ owns a temp sqlite; call .cleanup()
└──────────────────┘
│
▼ .trajectory_dataframe() / .sqlite_file
pandas / pedpy analysis
For parameter studies:
base : Scenario ──► run_sweep(base, axes=..., apply=..., seeds=...)
│
▼
┌──────────────┐
│ SweepResult │ .save(...) / load(...)
└──────────────┘
Scenario — the mutable plan#
A Scenario is the in-memory
representation of one simulation setup: geometry, agents, journeys,
solver settings, seed, and time limits.
It is mutable. Every add_* / remove_* / set_* call,
and every direct attribute assignment, changes the instance in place:
base = load_scenario("bottleneck.zip")
base.seed = 99 # base is now permanently at seed=99
If you want to keep the original intact — and you almost always do
once you start sweeping or comparing variants — call .copy()
first and edit the clone:
trial = base.copy()
trial.seed = 99
trial.max_simulation_time = 60
# base is untouched
run_sweep() does this for you per
trial. The copy-first discipline only matters when you assemble
variants by hand. See
How do I sweep over scenario shapes that axes / apply can’t express? for the worked pattern.
Inspecting the plan#
scenario.plot() draws the walkable area with labelled
distributions, exits, zones, and checkpoints. Two arguments turn it
into a before/after view of a run:
show_journeys=True(the default) overlays each journey’s route as curved arrows in stage order. Both schema versions are read, so current web-editor exports (journeys_v2) show routes too.trajectories=takes aScenarioResult(or a pedpyTrajectoryData) and draws the agent paths from a completed run on top of the plan. Useshow_trajectories=Falseto force it off.
result = run_scenario(scenario, seed=42)
scenario.plot(show_journeys=True, trajectories=result)
See Visualisation for the full tour.
ScenarioResult — the run output#
run_scenario() returns a
ScenarioResult. It carries
summary metrics (evacuation_time, agents_evacuated,
frame_rate, …) and owns a temporary SQLite trajectory file
written by the simulator.
Two things to remember:
trajectory_dataframe()materializes the trajectory as a pandas DataFrame compatible with pedpy.visualise()returns an interactive plotly animation of the run — agents coloured by speed, with a play button and time slider. Passsave_path="run.html"to write a self-contained file.cleanup()deletes the temp sqlite. Call it when you are done, or wrap your run in atry / finallyblock. The file does not vanish on garbage collection.
result = run_scenario(scenario, seed=42)
try:
df = result.trajectory_dataframe()
# ...analysis...
finally:
result.cleanup()
SweepResult — the persisted study#
run_sweep() and
run_sweep_from_factory() return a
SweepResult. It is the artifact
you save, re-load, and analyze across sessions.
to_dataframe()returns one row per trial: parameter values, metrics, sqlite path.save(path)/SweepResult.load(path)round-trip a sweep, including the per-trial trajectory databases. Useful for long studies that you want to analyze separately.cleanup()removes all per-trial temp files.
See How do I persist a sweep and reload it later? for the save/reload pattern.
Per-area agent parameters#
A spawn area can override per-agent model fields (for example
time_gap or strength_neighbor_repulsion) without touching the
global settings. Pass agent_parameter_overrides to
set_agent_params(), shaped
{model_type: {field: value}}. Only the entry for the active model
applies; a value of None removes a field’s override, and an area
without overrides inherits the global settings.
scenario.set_agent_params(
0,
agent_parameter_overrides={
"CollisionFreeSpeedModelV2": {"time_gap": 0.5},
},
)
radius and desired_speed are not overridable here; use their own
keys. Initial placement and flow spawning resolve the same values. An
invalid override, or an inherited setting outside the field’s bounds,
raises AgentParameterError before any
agent is placed. If a sweep changes a global default that a spawn area
overrides, the sweep logs a warning, because the area keeps its value.
Where each object lives#
Object |
Lives in |
Disk footprint |
|---|---|---|
|
Python memory only |
None until you |
|
Python + temp sqlite |
One trajectory db |
|
Python + temp dir |
One sqlite per trial |
Next#
Choosing an entrypoint — pick the right function for the job.
Troubleshooting — common pitfalls and their fixes.