Scenario JSON

A scenario is a config.json plus a geometry.wkt walkable area, in a directory or a ZIP. This page lists the JSON keys that change a result, with their defaults. The meaning of the model parameters is on the Models pages; this page links there rather than repeating the equations.

The keys are read by load_scenario and the JuPedSim set-up in simulation_init.py. A key that is not listed here is either layout data for JuPedSim Web (config.ui_state) or not read by the run.

Where scenario files come from

Scenario files are drawn in JuPedSim Web and exported as a ZIP, or copied from an example and edited. The app does not write the pyFDS-Evac keys (routing, exit schedules, familiarity, the sign’s max_distance); add them by hand after the last export. Create a scenario shows the three routes and how to check the result.

Top-level structure

{
  "config": { "simulation_settings": { "simulationParams": {…}, "baseSeed": … } },
  "exits":         { "<id>": {…} },
  "distributions": { "<id>": { "coordinates": […], "parameters": {…}, "journey_weights": […] } },
  "checkpoints":   { "<id>": {…} },
  "waypoints":     { "<id>": {…} },
  "zones":         { "<id>": {…} },
  "journeys_v2":   [ { "id": …, "sequence": […] } ],
  "routing":       {…}
}

waypoints carry signs only. The older journey keys (journeys, transitions, waypoint_routing) are still read; see Old format (still read).

Journeys: journeys_v2

journeys_v2 is the journey format of JuPedSim Web and of pyFDS-Evac (#900). A scenario written by pyFDS-Evac opens in the app, and a scenario drawn in the app runs here with its journeys as the agents’ starting routes. The file format is shared; how the agents walk (route choice, rerouting, smoke, FED) is pyFDS-Evac’s own.

"journeys_v2": [
  {"id": "journey-a", "name": "Via the corridor", "color": "#4e79a7",
   "sequence": ["jps-checkpoints_0", "jps-exits_0"]}
],
"distributions": {
  "jps-distributions_0": {
    "coordinates": [[0, 0], [4, 0], [4, 4], [0, 4]],
    "parameters": {"number": 20},
    "journey_weights": [{"journey_id": "journey-a", "weight": 100}]
  }
}

Weights. A start area’s agents are split over its journeys at spawn by exact counts, not by random draws: each journey gets its rounded share and the last one takes the rest. A weight that cannot be read as a number, or is 0 or less, is skipped. A start area with no usable weight, and a start area without journey_weights, has no journey: at spawn its agents walk to the nearest exit by walking distance.

The weights set each agent’s starting journey and the split of the counts at spawn. With rerouting on, the default of run.py, the route-cost model picks each agent’s exit, and the shares need not carry over to the exits taken; only --no-enable-rerouting keeps the drawn exits. See Journey splits and Models › Routing.

Several journeys per start area. Give a start area one journey_weights entry for each journey it uses. Two journeys with weights 60 and 40 send 60 % of the agents along the first sequence and 40 % along the second. A route that splits at a checkpoint is written as two journeys that share their first stages.

Journeys: allocation

One hard journey through a spawn area makes the whole area hard. The rule is on Models › Routing. In the old format the key sits on journeys[].

Simulation settings

Under config.simulation_settings.

simulationParams.dt is the JuPedSim time step in seconds (default 0.01). It must divide 0.1 s (for example 0.1, 0.05, 0.025, 0.02, 0.01 or 0.005); 0, a negative value, NaN, infinity and a value that is not a number are rejected with an error that names simulationParams.dt. The trajectory keeps 10 frames/s whatever dt is, and Result.dt and the run manifest report the step. Exit times and other schedules take effect at the first step at or after their time, so up to one dt late. The Social Force and generalized centrifugal force models are untested above 0.01 s and log a warning there.

Social force model

Read when model_type is "SocialForceModel". The symbols are those of Helbing, Farkas & Vicsek (2000), Eqs. (1)–(3) (doi:10.1038/35035023); a missing key takes JuPedSim 1.4.2’s default.

Negative, non-finite or non-numeric sfm_body_force, sfm_friction or sfm_obstacle_scale stop the run with ValueError. JuPedSim 1.4.2 has one friction for the agent and wall terms and applies the wall term with the wrong sign (jupedsim#1677), so friction is always passed as 0, also when sfm_friction is missing (#635). A deck that declares sfm_friction above 0 gets a warning. The run manifest records what JuPedSim received under sfm.

Spawn areas: distributions.<id>.parameters

parameters is an object, or the same object as a JSON-encoded string; both read the same everywhere: the run, --show-config, the TUI, the GUI and the Scenario views (#644):

"parameters": {"number": 20, "v0": 1.2}
"parameters": "{\"number\": 20, \"v0\": 1.2}"

A missing or null parameters, a string that is not valid JSON, and a string or value that is not an object ("null", "[]", "42", []) read as no parameters, so every key takes its default. The Scenario.set_agent_params(), set_agent_count() and set_flow_schedule() setters store an object: a string is replaced by the object it encodes, with all its keys, and an unreadable value by an empty object, before the setter’s keys are written.

A spawn area’s own number, radius and v0 are read as the simulationParams values are: number with int(), radius and v0 with float(), so numeric strings are accepted, and true or false is not a number. The bounds are the same with one exception: a spawn area’s v0 may be 0, which places agents that stand still (the stationary FED verification cases use it), while simulationParams.v0 must be greater than 0, since it is the speed of every spawn area that sets none. A value that does not convert or is out of range, such as "-1" for number or "nan" for v0, stops the run at the start with a ValueError that names the distribution and the key (desired_speed when the deck set that alias). null means unset, as for the simulationParams values: the spawn area takes the deck-wide default (#649).

desired_speed, desired_speed_distribution and desired_speed_std are aliases of v0, v0_distribution and v0_std. An alias set alone is used as its v0* key. An alias and its v0* key with the same value are accepted; with different values the run stops at the start with a ValueError that names the distribution and both keys (Troubleshooting). --show-config, the TUI and the GUI report the same error before a run. This check applies to the scenario JSON; Scenario.set_agent_params() in Python lets desired_speed win instead (#586).

While an agent waits out its pre-movement time, the smoke update skips it, so it starts at its full clear-air speed.

Exits: exits.<id>

An exit with open_from_s or closed_after_s is open while open_from_s ≤ t < closed_after_s (#373). While it is closed:

• it removes nobody: an agent standing in it waits there;
• routes are ranked without it, both the opening choice and every re-evaluation, and it is no target for exploring or wandering. An exit is judged by whether it is open at the time of ranking, not at the time the agent would arrive;
• an agent whose route ends at it re-evaluates at the next reroute check (every second), whatever --reroute-interval says, and takes the best open exit it knows. The switch is logged with the reason exit_closed when the exit has closed (closed_after_s passed). An exit that has not opened yet (open_from_s still ahead) was never the agent’s exit: the first open exit it is given is logged as initial. An agent that knows no open exit acts by its spawn area’s no_known_exit mode. Under the default, default_route, it walks to the nearest open exit on foot, which need not be in its map, and the switch is logged as default_route. Under explore it is not told of another exit: it heads for a known node it has not visited, or else wanders over the nodes it knows; an agent that knows only its spawn area and the closed exit has neither, so it keeps its route and waits at the closed exit. With every exit closed, an agent keeps its route and waits.

When an exit opens, nobody is made to re-decide: an agent takes it at its next regular re-evaluation, up to --reroute-interval later.

A run without rerouting (--no-enable-rerouting or --smoke-blind) honours the schedule too (#395). At the same one-second check, only the agents whose route ends at a closed exit choose again, once for each closure, scored as their opening choice is: on the map they hold, without the queue term, with the smoke at that time, or in clear air when the run is smoke-blind. An agent that knows no open exit takes the default route to the nearest open exit on foot; with no exit open it waits and is checked again every second. The route history logs the switches: exit_closed for an exit that has closed, initial for an agent whose exit has not opened yet and is sent to an open one it knows, and default_route for an agent sent to an exit it does not know. Without rerouting nobody re-decides when an exit opens.

A schedule cannot be combined with --replay-exits, and a run with a scheduled exit stops with an error when an agent walks a JuPedSim journey instead of a routed path (a spawn area with no journey in a scenario that has journeys). Without a schedule nothing changes.

Signs: sign

Exits, checkpoints and waypoints can carry a sign. A node without one gets an omni-directional sign at its position with c = 3, so every exit is subject to smoke-dependent legibility.

"sign": false gives the node no sign, for an exit nobody can see from the room, the case the Station validation needs (Fahy); assets/station_fahy does not set it yet. A discovery agent then never learns that exit or checkpoint by sight or by reaching a neighbouring node, with or without a visibility model; it knows it only through "full" familiarity, the familiarity draw or the distribution’s entrance (#376). An agent that arrives on the node while walking a route it knew learns it as before. null or no sign keeps the default sign, and false is the only boolean value that is read (true is not valid). An agent that knows no exit under the default no_known_exit mode "default_route" still walks its default route, which may end at an unsigned exit; "explore" avoids that. If every way out of a spawn area runs through unsigned nodes, its explore, return and stay agents that have no entrance and no familiarity can learn no exit and stay where they spawned; the run warns once per such distribution.

The legibility rule is on Models › Wayfinding.

Checkpoints and zones

Where to draw checkpoints, how large, and how they join the route graph: How do I place checkpoints?.

Old format (still read)

Files written before journeys_v2 carry journeys (the stages of each journey), transitions (the from → to pairs) and, for a split, a top-level waypoint_routing. They load and run as before. The loader reads journeys_v2 only when journeys is empty: a file that has both runs on journeys. A journey in journeys needs its transitions (#504).

pyfds-evac-convert rewrites such a file as journeys_v2:

pyfds-evac-convert config.json -o config_v2.json

Each route a start area walks becomes one journeys_v2 entry, listed in that start area’s journey_weights with weights scaled to sum to 100 where that keeps the split unchanged. Exit shares at a checkpoint become one weighted entry per branch, and a patrol that returns to its first checkpoint becomes "loop": true. A start area whose journey leaves the exit to the route choice gets no journey, and the command prints a note for it. The command stops with error: … and exit code 1 when a loop returns to a stage other than the first, when waypoint_routing cannot be written as separate branches, or when the file has both journeys and journeys_v2.

Journey splits: waypoint_routing

A journey in which a checkpoint has more than one outgoing transition needs the shares of agents that take each branch:

"waypoint_routing": {
  "<checkpoint id>": {
    "<journey id>": {
      "destinations": [ { "target": "<stage id>", "percentage": 60 }, … ]
    }
  }
}

Without it, or with a target missing, the set-up stops with Explicit routing required for <checkpoint> in <journey> or Explicit routing for <checkpoint> in <journey> is incomplete (_create_journeys_with_percentages in simulation_init.py). The shares set the authored journey only. With rerouting on, the default of run.py, the route-cost model picks each agent’s exit: in assets/t_junction with 40 agents, shares of 99/1 and 1/99 both sent all 40 to the nearer east exit, while with --no-enable-rerouting 99/1 sent all 40 west. JuPedSim Web does not write this key. In journeys_v2 a split is two journeys with weights.

Route choice: routing

The routing block sets the route-cost model. Its keys, defaults and the constants that no key can set are listed in one place, Models › Routing › Parameters. cost_model must be exactly "gate" or "additive" (lower case); without the key it is "gate". Any other value stops the run with a ValueError that lists the two names, also with --no-enable-rerouting, since the first exit choice uses the cost model too.

fallback_return_lockout_s, the 10 s return lockout between two refused routes (#458), was removed in #187. A scenario that still sets it stops with a ValueError naming the removal, also with --no-enable-rerouting; delete the key. path_switch_anchor, the fraction of the walked path’s rank_cost a new path to the same exit had to come in under, was removed in the same issue and is refused the same way: the path is now taken whenever it is strictly cheaper. tau_return_margin, the factor (0.8) on tau_max that a rival exit’s optical depth had to come in under, was removed in the same issue and is refused the same way: every exit is now refused above tau_max. fed_return_margin, the fraction of fed_rejection_threshold above which a rival exit was refused for dose, was removed in the same issue and is refused the same way: a rival is now held to fed_rejection_threshold, as the current exit is. impassable_extinction_threshold, the route-average extinction above which the additive model fled a non-visible route regardless of the exit-switch anchor, was removed in #835 (part of #187) and is refused the same way: smoke never bypasses the anchor, only a FED violation does.

Each switching margin must be a number in its range, or the run stops with a ValueError naming the key, also with --no-enable-rerouting: exit_switch_anchor, current_exit_discount and clean_exit_margin in (0, 1]; tau_deadband and fallback_switch_margin in [0, 1]. The value that switches a margin off is in range: 1, or 0 for tau_deadband and fallback_switch_margin. fallback_switch_margin = 1 keeps the current exit between two refused routes unless it must be fled, the scenario-file way to the hold rule.

The routing keys alpha, beta, min_speed_factor and base_speed_m_per_s only estimate travel time when a route is priced. They do not change how fast agents walk.

fed_rate_memo (default true) remembers the FED rate a route reads at a point for the run; false reads the model every time. It changes run time only; see Segment caching. A value that is not true or false stops the run with a ValueError naming the key.

Not in the JSON

Some parameters exist only in Python, as fields of a config object:

• the smoke-speed law and its parameters (SmokeSpeedConfig: speed_law, alpha, beta, min_speed_factor, visibility_factor_c); a configured run always uses the Lund law with the defaults on Models › Smoke speed;
• RerouteConfig.exit_switch_anchor, which, when set, overrides the routing key exit_switch_anchor for that run.

Tracking issue for this reference: #119.