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, headless=False, argos_config_filepath='output.argos', stats_name='stats.json', save_stats=False, output_log=None, port_num=8182, n_threads=1, sim_duration=6000, 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 32.

  • headless (bool, optional) – whether run in headless mode. If False, a visualization will be generated. Defaults to False.

  • 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 1800 * 10, meaning 1800 seconds.

  • 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 run in a singularity container. 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 has no action to execute in the ADG (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#

To run in headless mode 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 periodic invocation policy, use the following command:

python run_lifelong.py maps/kiva_large_w_mode.json --headless True --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 visualization

python run_lifelong.py maps/kiva_large_w_mode.json --headless False --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