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] [--verbose] {run,sweep,report} ...

Positional Arguments#

command

Possible choices: run, sweep, report

Named Arguments#

--version

show program’s version number and exit

--verbose

Show the library’s INFO log lines (hidden by default, also in sweep workers).

Default: False

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: the scenario’s simulationParams.dt, else jupedsim’s built-in 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

sweep#

Run a scenario over many seeds, optionally scaled up, into an output directory.

jps-scenarios sweep [-h] [--seeds SEEDS | --seed-start SEED_START]
                    [--seed-end SEED_END] [--scale SCALE]
                    [--scale-mode {count,flow}] [--workers WORKERS] --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#
--seeds

Number of seeds, 0..N-1 (default 1).

Default: 1

--seed-start

First seed (use with –seed-end).

--seed-end

Last seed, inclusive (use with –seed-start).

--scale

Agent scaling factor (default 1.0).

Default: 1.0

--scale-mode

Possible choices: count, flow

count: multiply start-area counts (refuses on capacity overflow, checked with the scenario’s base seed; a seed that still cannot place the agents is recorded as a failed trial); flow: keep the spawn rate and stretch flow windows (needs flow spawning).

Default: 'count'

--workers

Parallel worker processes (0 = all CPUs).

Default: 1

--out

Output directory for sqlites and sweep.json.

--dt

Iteration step in seconds (default: the scenario’s simulationParams.dt, else jupedsim’s built-in).

--every-nth-frame

Trajectory writer stride. Default 10, matching run.

Default: 10

report#

Render a saved sweep as a self-contained HTML report.

jps-scenarios report [-h] [--out OUT] [--playback] results_dir
Positional Arguments#
results_dir

Directory written by jps-scenarios sweep –out.

Named Arguments#
--out

Report path (default <results_dir>/report.html).

--playback

Also write per-trial plotly playback files next to the report (large).

Default: False

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