Quick Start with Python API#

We provide a Python API to easily run LSMART simulations with our provided planners, instance generators, invocation policies, and fail policies. You can customize the simulation parameters by changing the function arguments. In the repository, we have a python script run_lifelong.py that contains a function run_lifelong_argos to run LSMART simulations.

run_lifelong.run_lifelong_argos(map_filepath='maps/kiva_large_w_mode.json', num_agents=100, visualizer='argos', argos_config_filepath='output.argos', stats_name='stats.json', save_stats=False, output_log=None, port_num=8182, n_threads=1, sim_duration=6000, stop_at_congestion=True, sim_window_tick=20, ticks_per_second=10, velocity=200.0, planner='RHCR', container=False, seed=42, screen=0, backup_solver='PIBT', planner_invoke_policy='default', task_assigner_type='windowed', planning_window=10, frame_grab=False, cutoffTime=1, solver='PBS', single_agent_solver='SIPP', rotation=False, rotation_time=1, prioritize_start=True, suboptimal_bound=1, log=False, save_result=False, save_solver=False, save_heuristics_table=False)[source]#

Function to run the LSMART simulator with the given parameters.

Parameters:
  • map_filepath (str, optional) – file path to map. Example maps are in the maps directory. If maps contains workstations (w) and endpoints (e), robots’ tasks will be assigned alternately between workstations and endpoints. If not, robots’ tasks will be randomly generated from the empty spaces. Defaults to maps/kiva_large_w_mode.json.

  • num_agents (int, optional) – number of robots. Defaults to 100.

  • visualizer (str, optional) – visualization mode. Options are none for headless execution, argos for the native Qt/OpenGL visualizer, and web for the external event-stream visualizer used by lsmart-viz. Defaults to argos.

  • argos_config_filepath (str, optional) – file path to write the generated Argos config file. Defaults to “output.argos”.

  • stats_name (str, optional) – file path to store the stats from the simulator. Defaults to “stats.json”.

  • save_stats (bool , optional) – whether to save the stats. Defaults to False.

  • output_log (str, optional) – file path to store the stdout from the simulator. If None, the output will not be saved to a file. Defaults to None.

  • port_num (int, optional) – port number of RPC server. Defaults to 8182.

  • n_threads (int, optional) – number of threads to run Argos. Defaults to 1.

  • ticks_per_second (int, optional) – the simulator runs in ticks. The states of the robots are updated per tick. ticks_per_second specifies the number of ticks per simulation second used by the simulator. Defaults to 10.

  • sim_duration (int, optional) – number of simulation ticks to run the simulator. Defaults to 600 * 10 ticks, meaning 600 seconds at the default rate of 10 ticks per second.

  • stop_at_congestion (bool, optional) – whether to stop the simulation when congestion is detected. Defaults to True.

  • sim_window_tick (int, optional) – number of ticks to invoke the planner. Only applies to the periodic invocation policy. Defaults to 20 ticks.

  • velocity (float, optional) – velocity of the robots in cm/s. Defaults to 200.0 cm/s.

  • planner (str, optional) –

    planner to use. Options include:

    • RHCR: the Rolling Horizon Collision Resolution planner, (Li et al. 2021). RHCR plans for windowed paths for all robots.

    • MASS: the MAPF-SSIPP-SPS planner, (Yan et al. 2025). MASS plans for full-horizon paths with 2nd order dynamics for all robots.

    • PBS: the Priority-Based Search planner (Ma et al. 2019). PBS plans for full-horizon paths for all robots.

    • TPBS: the Transient Priority-Based Search planner (Morag et al. 2025). TPBS plans for full-horizon paths for all robots even if there are duplicate goals.

    Defaults to RHCR.

  • container (bool, optional) – whether to use the container installation paths. Defaults to False.

  • seed (int, optional) – random seed. Defaults to 42.

  • screen (int, optional) – logging options. Higher values increase verbosity. Defaults to 0.

  • backup_solver (str, optional) –

    backup solver (fail policy) used in case the MAPF planner fails. Options include:

    Defaults to PIBT.

  • planner_invoke_policy (str, optional) –

    planner invocation policy, options include:

    • default: the periodic policy where the planner is invoked periodically every sim_window_tick ticks.

    • no_action: the event-based policy where the planner is invoked when at least one robot’s number of unfinished ADG actions is less than or equal to the ADG look-ahead distance (Hönig et al. 2019).

    Defaults to default.

  • task_assigner_type (str, optional) –

    task assigner (MAPF problem instance generator) used to generate problem instances. Options include:

    • windowed: the windowed task assigner (Li et al. 2021), which assigns tasks within the planning window. This can only be used with the RHCR planner.

    • distinct_one_goal: the distinct one-goal task assigner, which assigns each robot a distinct goal. This can only be used with the PBS and MASS planners.

    • one_goal: the one-goal task assigner, which assigns each robot a goal regardless of duplicates. This can only be used with the TPBS planner.

    Defaults to windowed.

  • planning_window (int, optional) –

    planning window in timesteps. The final planning window is the max of this value and the inferred planning window from sim_window_tick.

    Specifically, given sim_window_tick and ticks_per_second, we compute the minimal planning window in timesteps required to cover the simulation window as follows:

    \[planning_window_ts = \lceil \frac{sim_window_tick}{ticks_per_second} \times \frac{velocity}{100} \rceil\]

    Then given the user-specified planning_window, the final planning window is:

    \[planning_window = max(planning_window_ts, planning_window)\]

    Defaults to 10.

  • cutoffTime (int, optional) – time limit of the planner in seconds. With the periodic invocation policy (default), the cutoffTime should be less than or equal to the simulation window in seconds (\(\frac{sim_window_tick}{ticks_per_second}\)). Defaults to 1.

  • frame_grab (bool, optional) – whether to enable frame grabber in Argos. If enabled, the simulator will save screenshots to the frames folder. The screenshots can be combined into a video using external tools. Defaults to False.

  • solver (str, optional) – MAPF solver in RHCR. Options include PBS (Ma et al. 2019) and PIBT (Okumura et al. 2019). Defaults to PBS.

  • single_agent_solver (str, optional) – single agent solver in RHCR. Options include SIPP (Phillips et al. 2011) and ASTAR. Defaults to SIPP.

  • rotation (bool, optional) – whether the single-agent planning consider rotation in RHCR. Defaults to False.

  • rotation_time (int, optional) – rotation time in timesteps in RHCR. Defaults to 1.

  • prioritize_start (bool, optional) – prioritize start in RHCR. Defaults to True.

  • suboptimal_bound (float, optional) – suboptimality bound of certain solvers in RHCR. Defaults to 1.

  • log (bool, optional) – logging in RHCR. Defaults to False.

  • save_result (bool, optional) – save planning results or not in RHCR. Defaults to False.

  • save_solver (bool, optional) – save MAPF solver process in RHCR or not. Defaults to False.

  • save_heuristics_table (bool, optional) – save heuristic table or not. Defaults to False.

Example Usage#

LSMART has three explicit visualization modes. none runs without a user interface, web streams events to the browser service, and argos opens the native Qt/OpenGL ARGoS visualizer. The same modes are available from a source build, Docker, and the Singularity image converted from Docker.

To run without visualization in the maps/kiva_large_w_mode.json map with 10 robots, RHCR planner (PBS MAPF solver and SIPP single-agent solver), PIBT fail policy, windowed problem instance generator, and the default invocation policy, use:

python run_lifelong.py maps/kiva_large_w_mode.json --visualizer none --screen 0 --num_agents 10 --save_stats True --rotation False --planner_invoke_policy default --sim_window_tick 10 --planner RHCR  --backup_solver PIBT --task_assigner_type windowed

To run the same simulation with the native ARGoS visualizer:

python run_lifelong.py maps/kiva_large_w_mode.json --visualizer argos --screen 0 --num_agents 10 --save_stats True --rotation False --planner_invoke_policy default --sim_window_tick 10 --planner RHCR  --backup_solver PIBT --task_assigner_type windowed

The web mode is launched through the Bun service, which supplies the external event-stream connection and serves the browser application. From a source build:

cd web/lsmart-service
bun run start --num_agents=10 --planner=RHCR --seed=42

Open http://localhost:3000 and press Start Simulation. See Installation for the equivalent Docker and Singularity commands, X11 setup for the native visualizer, and reproducibility guidance.