CLI reference

CLI reference#

jps-scenarios is a thin command-line wrapper around run_scenario(). It is intended for CI smoke tests and scripted pipelines. Interactive and notebook workflows should stay on the Python API.

The CLI installs as a console script with the package:

pip install jupedsim-scenarios
jps-scenarios --version

Command-line interface#

The full parser is generated from jupedsim_scenarios.cli.build_parser(), so this reference is always in sync with the installed CLI.

Run JuPedSim scenarios authored in the web app.

usage: jps-scenarios [-h] [--version] {run} ...

Positional Arguments#

command

Possible choices: run

Named Arguments#

--version

show program’s version number and exit

Sub-commands#

run#

Run a single scenario and emit a trajectory sqlite.

jps-scenarios run [-h] [--seed SEED] [--out OUT] [--dt DT]
                  [--every-nth-frame EVERY_NTH_FRAME]
                  scenario
Positional Arguments#
scenario

Scenario source: a self-contained JSON file, a ZIP archive, or a directory holding one JSON + one WKT.

Named Arguments#
--seed

Override the scenario’s seed (default: use the value in the JSON).

--out

Where to write the trajectory sqlite. If omitted, the file is created in a tempdir and deleted on exit (metrics are still printed).

--dt

Iteration step in seconds (default: jupedsim’s built-in, currently 0.01).

--every-nth-frame

Trajectory writer stride. Default 10 (≈ 10 fps at dt=0.01); set to 1 to capture every iteration.

Default: 10

Input shapes for SCENARIO#

jps-scenarios run routes through load_scenario() and accepts any of:

  • A self-contained JSON file with walkable_area_wkt embedded.

  • A ZIP archive exported from the web editor.

  • A directory holding one <name>.json + one <name>.wkt.

Output schema#

On success run prints a single line of JSON to stdout:

{
  "scenario": "/abs/path/to/scenario.zip",
  "seed": 42,
  "model_type": "collision_free_speed",
  "evacuation_time": 28.41,
  "total_agents": 50,
  "agents_evacuated": 50,
  "agents_remaining": 0,
  "sqlite_file": "/abs/path/to/out.sqlite"
}

sqlite_file is null when --out was not given. The temp trajectory is written during the run, then removed in a finally block immediately after the summary is printed — by the time the process exits, no trajectory file remains on disk.

Exit codes#

Code

Meaning

0

Run finished, scenario fully evacuated or time-limited.

1

Simulation reported a failure (message on stderr).

2

Bad input — scenario not found, invalid args, IO error.

Examples#

Smoke test in CI (discard trajectory, keep summary):

jps-scenarios run scenarios/bottleneck.zip --seed 0

Persist the trajectory for downstream pedpy analysis:

jps-scenarios run scenarios/bottleneck.zip \
    --seed 0 --out runs/bottleneck.sqlite

Higher-resolution trajectory (every iteration recorded):

jps-scenarios run scenarios/bottleneck.zip \
    --every-nth-frame 1 --out runs/dense.sqlite