This is a Python3-based simulator designed for modeling multi-robot and swarm systems. It implements a simplified motion model, with an assumed level of low level control already acting on the simulated agents rather than calculating the full-body dynamics. This approach allows the simulator to efficiently handle a large number of agents simultaneously.
Related repositories
- Efficient Swarm Simulation: Simulate numerous agents with simplified motion models.
- Modular and Customizable: Easily extendable for different agent types and behaviors.
- Scalability: Optimized for handling multiple agents.
- Basic Visualizations: Includes simple tools for visualizing agent positions and swarm dynamics.
The following Python packages are required to run the simulator:
- Core Functionality:
numpy - Visualization & Animation:
matplotlib
Additionally SimAPI requires additional packages to interconnect with UE5:
- API functionality:
fastapi,uvicorn - Image processing:
opencv-python
Note that the installation will handle all the dependacy installations.
The package can be installed Globally to be accessible regardless the location.
For a generic installation, just run:
pip install git+https://github.com/save-xx/SwarmSwIM.gitNote that you will not be able to alter the code.
For a developer (editable) installation:
Clone the repository in a Folder of your choice:
git clone https://github.com/save-xx/SwarmSwIM.gitEnter the folder that has been cloned
in the SwarmSwIM folder:
cd SwarmSwIM/ # Go to download folderInstall SwarmSwIM as python pakage, -e indicates that is editable.
pip install -e .The installation should conclude with:
Successfully built SwarmSwIM
Installing collected packages: SwarmSwIM
Successfully installed SwarmSwIM-x.x.x
If you want to install the dependancies manually:
pip install numpy matplotlib
pip install fastapi uvicorn opencv-pythonTo Uninstall the package simply:
pip uninstall SwarmSwIMNote: Dependace installed with the package will not be automatically unistalled (
numpy,matplotlib, etc..). Due toopencv-python, the installation will requirenumpy< 2.0.
The simulator can be directlely be used as python library to set up your own simulator. To Set you own simulation:
from SwarmSwIM import Simulator, CNNDetection
TIME_STEP = 1 / 24 # Simulation time step in seconds
# Initialize the simulator with the chosen time step
S = Simulator(TIME_STEP)
# Initialize a sensor model (e.g., CNN-based detection)
Detection = CNNDetection()
# Run the simulation until a specific condition is met
for i in range(1000):
S.tick() # Progress the simulation by one time step
Detection(S) # Apply detection on the current state of the simulator, return names of agents activatedThis code runs the simulator in discrete steps until the specified condition is met. Note that the simulator does not run in real time; it iterates through each time step as quickly as possible. This setup is particularly useful for post-analysis and machine learning applications, where real-time processing is not required, and fast iteration are preferrable.
The animator2D provides a simple representation of the agents on the planar position and heading of each agent. Within comutational capabilites of the hosting machine and simulation complexity, the animator will run the simulation in real-time. A code example of the minimal animation can be found in the file example2Danimation.py.
With the Package installed, from the SwarmSwIM folder, launch the example:
python3 -m SwarmSwIM.example2DanimationIn the swarmswim examples are stored more examples, showcasing the different functionalities as well as full case scenarios and examples of uses of SwarmSwIM.
This simulator is also avaiable for ROS2 implementation. The ROS2 impementation is designed as a stand-alone module based on this core. It will not require the core installation, since it is already designed with the simulator locally in-build. For information on the installation and use please check-out the ros2 swarmswim repo at: swarmswimros
Two files are added to give you the possibility to simulate a 3D marine environment. Use the sample project that is shared in the 'UE5_sim' folder as a sample.
When creating your own project, keep it simple:
- On the left sidebar, select
Games, thenBlank. Keep Blueprint mode! - After you reach the viewport, with
File-->New Level-->Empty Levelyou will create a new environment - Switch to
Landscape modeto create your o 63E8 wn landscape. In theSculptsection you can experiment different landscape setups.
SimAPI.py is providing an ongoing simulation mode through HTTP Request. On the loopback address, when you request /init_status the environment is set up as in the init_unreal.py file. During simulaiton, every tick will perform a /tick_exec request to update the visual simulation. As a result of this, for each agent simulated, a visual feedback is returned and shown through a OpenCV (python) operation.
Launch as requested here in order to avoid crashing of UE5 environment!
- Launch the
SimAPI.pyfile, that provides the link between simulation and visual representation - Open the UnrealEngine project. In
Plugin-->Python, add the path of the startup script intAdditional Pathsand the name of the script inStartup Scripts. In this way, UE5 will automatically launch theinit_unreal.pyscript and set up the environment on opening the project. - Play the simulation in Unreal Engine
UE5 SwarmSim for Linux (Ubuntu)
For more details, check out the Wiki.