This project is built on the original SwarmLab by Soria et al., found here: https://github.com/lis-epfl/swarmlab (commit 3574ded). Code has been refactored and new code has been added in order to conduct experiments.
With this repository, the intention is to provide snapshots of modifications made to the original SwarmLab as time goes on. A non-exhaustive summary is provided below.
- New projects:
examples/examples_courseandexamples/project_scenario. examples_coursehas been updated as of Oct 2025 to include a new wrapper with default values for a swarm with UAV awareness range limited to 30m. For the course, there is additionally a new placeholder@Swarm/compute_course_controller.m; remember to specify which controller should be used when executing a simulation run.- Directory
utilswith utility functions, e.g., to calculate separation distances. - Directory
wrapperwith wrapper functions that can be used to configure and execute a set of related simulation runs. - Tests in
RunSetOfTests.min directorytests: end-to-end tests; however, comprehensiveness and coverage needs to be improved. Run these using the MATLAB testing framework. - New obstacle type: rectangular "boxes" as obstacles; NOTE that this is just the result of some brainstorming and many assumptions were made about what block properties a UAV can "perceive",
@Swarm/compute_vel_vasarhelyi.mshould be examined for details.
- Refactored:
@Swarm/compute_vel_vasarhelyi.msuch that many calculations have been organized into subfunctions. - Bug fix: updates to handle the case where the "swarm" consists of only one agent.
- GUI-related code, e.g.,
examples/main_GUI.m. - Original tests.
- In addition to baseline MATLAB and the Statistics and Machine Learning Toolbox, the Parallel Computing Toolbox is required to run any parallel processes (but this is an extension and is not necessary to run baseline scenarios).
[Original documentation is below]
SwarmLab is a drone swarm simulator written in Matlab. It aims at:
- simulating single drones;
- simulating swarms of drones;
This software is designed with versatility and scalability in mind. It allows for fast programming and easy incorporation of various modules designed for drone and drone swarm simulations. It also decreases the coding effort by offering built-in and ready-to-use functionalities. These features make this package suitable to different applications in the area of drones and swarm robotics, including fast algorithm development, training, education, and the automatic collection of simulated data.
Only Matlab installation is required with the Statistics and Machine Learning Toolbox.
Single-drone simulations exploit the architecture proposed by Professors Beard and McLain in Small unmanned aircraft: theory and practice and illustrated below. The focus of these simulations is realism. Their code is available here. Two drone-types are supported: quadcopter and fixed-wing drones.
The graphical tools supported for single drone simulations are:
- 3D drone viewer
- state variable plotter
The following examples are provided:
- controller
- path follower
- path manager
- path planner
For ease of use, single-drone simulations can also be run from a dedicated GUI, that allows to change a selection of parameters, e.g. drone type, simulation type, debugging plots, simulation time.
Drone swarm simulations exploit either the Olfati-Saber or the Vicsek (Vásárhelyi’s version) algorithms. The focus of these simulations is the behaviour of the group of drones, as a result of interactions among individuals. In this case, quadcopter and point-mass (featuring no vehicle dynamics) are supported. The latter can be used when computational time requirements prevail over simulation realism, or when the interest relies in the pure collective behavior, independently on the agents' dyanamics.
The graphical tools supported for drone swarm simulations are:
- run-time 3D swarm viewer
- run-time state variable plotter
- offline 3D swarm viewer with wakes
- offline state variable plotter
- offline performance analyser
The following examples are provided:
- Olfati Saber's swarming algorithm
- Vasarhelyi's version swarming algorithm
The following illustrations represent:
- a swarm of 5 drones with quadcopter dynamics,
- a swarm of 25 drones with point mass dynamics before and after convergence to the equilibrium configuration.
Also drone-swarm simulations can be run from a dedicated GUI. In this case, parameters that can be set are: drone types, simulation time, debug plotting, map plotting, number of agents of the swarm, swarming algorithm, preferred inter-agent distance, preferred orientation, preferred speed. The GUI allows for run-time changes of some parameters, such as the swarm direction.
To start off with your first drone swarm simulation, open the project folder swarmlab in Matlab (see picture aside). Then, add all folders and subfolders to the current path (select the swarmlab folder → right-click → Add to Path → Selected Folders and Subfolders). You have two ways of running your simulations, either via the provided GUIs or by calling an example script.
- For the GUI, type
GUI_droneorGUI_swarmon the Matlab command view, select the parameters you want and slide toOnthe Start Simulation button. - For running an example, type
example_vasarhelyiFor editing the example scripts, go to examples → examples_swarm, and open the example_vasarhelyi.m script.
Finally, simply run the script and pay attention to the prompted instructions!
Thanks to Victor Delafontaine, Andrea Giordano, and Anthony De Bortoli for their valuable contribution. Thanks to Dario Floreano and Fabrizio Schiano for their wise advice.
Please, cite us with:
@INPROCEEDINGS{9340854,
author={Soria, Enrica and Schiano, Fabrizio and Floreano, Dario},
booktitle={2020 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},
title={SwarmLab: a Matlab Drone Swarm Simulator},
year={2020},
volume={},
number={},
pages={8005-8011},
doi={10.1109/IROS45743.2020.9340854}}
This software is provided under MIT License (MIT). Copyright (c) 2020 Enrica Soria.