hmr_sim

⚠ Documentation is currently in progress. In the meantime, please refer to the Usage Examples section.

This package provides hmr_sim, a simulator with Gymnasium environments, for testing and developing multi-agent system algorithms. It is designed to facilitate the rapid creation and evaluation of different mission scenarios.

This project is an extension of the gym_connect package, originally developed for [1]. It expands the framework to support multiple mission scenarios and introduces a more modular code structure. Some features have not yet been ported — see checklist here for details.

Installation

# Clone the package
git clone https://github.com/KhAlamdar11/hmr_sim

# Navigate to the root of the project
cd hmr_sim

# Install dependencies via your python package manager
pip install -r requirements.txt

# Install the package
pip install -e . 

Availabe Environments

For simplicity, a single Gymnasium environment is created to handle all multiple mission scenerios and parameters using a config file. This environment is named Hetero-V0 and inherits from the Base environment. The Base environment handles all the map related behaviours and is created seperately from Hetero-V0 to allow extensions to multiple environments if needed in the future.

Usage Examples

The table below illustrates examples of creating different mission scenarios. The provided YAML files can be used as samples to experiment with various mission setups and parameters.

First navigate to the test folder: cd hmr_sim/tests/

Mission Scenario	Command	Visualization
Connectivity control with addition of new agents when the connectivity is low.	python3 test_hetro.py add_agent_base.yaml python3 test_hetro.py add_agent_near.yaml
An example of a heterogeneous system with a stationary base station (red), 4 mobile robots (yellow) that follow an RRT-defined path to goals, and UAVs (blue) that maintain connectivity of the entire network.	python3 test_hetro.py hetro.yaml
An example where the UAVs (blue) perform obstacle avoidance.	python3 test_hetro.py obstacle.yaml
A mission with 2 robots (yellow) exploring an unknown environment using frontier exploration, while UAVs (blue) maintain connectivity between these robots and the base station (red).	python3 test_hetro.py explore_x.yaml

TODOs

General

• Bug: For different path types (circle, ellipse, square), agents move at varying speeds even when the speed variable is the same. Redo perimeter sampling logic.
• Error Handling: Raise an error if a formation is initialized within an obstacle.
• Validation: Create a function to validate configuration combinations. For example: If there are two agents and the go_to_goal controller is chosen, ensure that two goal positions are specified.

Yet to port from gym_connect

• Fiedler based agent addition: Add the option to add agents based on min fiedler value (minor)
• Keyboard control: Allow a controller option for control by keyboard.

References

[1]: K.G. Alamdar, “Connectivity Maintainence for ad-hoc UAV Networks for Multi-robot Missions,'' Master's Thesis, University of Zagreb, 2024, June.

[2]: K. G. Alamdar and T. Petrović, "Decentralized Battery-Aware Connectivity Maintenance for Multi-UAV Missions," in IEEE Access, vol. 13, pp. 83738-83751, 2025, doi: 10.1109/ACCESS.2025.3569206.