How do I set a waiting time on a checkpoint?

A checkpoint is a stage that agents pass through on their journey. Giving it a waiting_time turns it into a timed gate: agents wait at the checkpoint for the specified number of seconds before continuing.

Use set_checkpoint_waiting_time(stage_id, waiting_time) to update an existing checkpoint.

import logging
from datetime import datetime

# Silence jupedsim-scenarios' INFO/DEBUG output. See the howto
# "How do I inspect a scenario?" for the full list of levels.
logging.getLogger("jupedsim_scenarios").setLevel(logging.WARNING)

print(f"Executed on {datetime.now().strftime('%d.%m.%Y, %H:%M')}")

Executed on 21.07.2026, 09:45

Load a scenario that already contains a checkpoint, then list stages to find the id:

from jupedsim_scenarios import load_scenario

scenario = load_scenario("../assets/waiting-stage-corridor")
scenario.list_stages()

[{'index': 0, 'id': 'jps-checkpoints_0', 'waiting_time': 5.0}]

Apply the wait by index or by string id:

scenario.set_checkpoint_waiting_time(0, 10.0)                # by index
scenario.set_checkpoint_waiting_time("jps-checkpoints_0", 10.0)   # by string id

Verify the change

Read the underlying stage dict to confirm. The exact key path depends on the stage type:

import json

print(json.dumps(scenario.stages["jps-checkpoints_0"], indent=2, default=str))

{
  "coordinates": [
    [
      6.0,
      0.3
    ],
    [
      7.0,
      0.3
    ],
    [
      7.0,
      1.7
    ],
    [
      6.0,
      1.7
    ],
    [
      6.0,
      0.3
    ]
  ],
  "waiting_time": 10.0,
  "waiting_time_distribution": "constant",
  "type": "polygon"
}

When to use this

Timed checkpoints model real-world holdups:

• Boarding doors: a fixed dwell time before agents continue.

• Security checks: per-agent processing delay.

• Phased evacuations: stagger groups by delaying upstream checkpoints.

To explore the effect of different wait times, sweep the value with run_sweep (see How do I sweep parameters?).