jupedsim-scenarios 0.3.2

Run, sweep, and analyze JuPedSim scenarios from the web-app JSON schema.

jupedsim-scenarios

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

Status

Alpha (0.3.0). Single-run (run_scenario), Monte Carlo sweeps (run_sweep — now multiprocess), and a jps-scenarios CLI are shipped. Restartable / resumable sweeps land in 0.4.0.

Install

pip install jupedsim-scenarios

For development from a clone:

pip install -e ".[dev]"

Single-run usage

from jupedsim_scenarios import Scenario, run_scenario

scenario = Scenario(
    raw=data_dict,                          # the JSON exported by the web app
    walkable_area_wkt=data_dict["walkable_area_wkt"],
    model_type="CollisionFreeSpeedModel",
    seed=42,
    sim_params=data_dict["config"]["simulation_settings"]["simulationParams"],
    source_path="my_scenario.json",
)
result = run_scenario(scenario, seed=42)
print(result.metrics["evacuation_time"])
df = result.trajectory_dataframe()
result.cleanup()

A higher-level load_scenario(path) is available for zipped exports (JSON + WKT file in the same archive or directory).

Monte Carlo sweep

from jupedsim_scenarios import load_scenario, run_sweep

base = load_scenario("faster_is_slower.zip")

sweep = run_sweep(
    base,
    axes={
        "v0":    [0.8, 1.2, 1.6, 1.8],
        "model": ["CollisionFreeSpeedModel", "AnticipationVelocityModel"],
    },
    apply={
        "v0":    lambda s, v: s.set_agent_params(0, desired_speed=v),
        "model": lambda s, v: s.set_model_type(v),
    },
    seeds=range(40, 50),
    output_dir="runs/",
)

df = sweep.to_dataframe()       # one row per (v0, model, seed) trial
print(df.groupby(["v0", "model"])["evacuation_time"].agg(["mean", "std"]))
sweep.cleanup()                 # delete the per-trial sqlite files

The library walks the cartesian product of the named axes, calls each axis's apply function on an isolated .copy() of the base scenario, runs the simulation, and tabulates the results. Anything the Scenario.set_* mutators can change is fair game for sweeping.

Pass workers=N (or workers=0 for one worker per CPU) to run trials in parallel:

sweep = run_sweep(base, axes=..., apply=..., seeds=range(40, 50), workers=4)

Mutations are applied in the calling process — only the resulting mutated Scenario crosses the process boundary, so user apply lambdas don't need to be picklable.

Command line

jps-scenarios run scenario.json --seed 42 --out trajectory.sqlite

Runs a single scenario and prints a one-line JSON summary (evacuation_time, agent counts, sqlite_file) to stdout. Useful in CI or scripted pipelines; notebook workflows should stay on the Python API.

Roadmap

Release	Scope
0.1.0	Verbatim extraction of Scenario + run_scenario from web app.
0.2.0	run_sweep(scenario, axes={...}, seeds=...).
0.3.0	Multiprocess worker pool + jps-scenarios CLI.
0.3.1	Public aliases for helpers shared with Web-Based-Jupedsim.
0.3.2	First PyPI release (this release).
0.4.0	Restartable / resumable sweeps, persisted results.

License

MIT. See LICENSE.