Multi-agent Simulator

An open architecture multi-agent simulator for use by academic researchers. Implemented techniques currently include:

• Flocking (reynolds, starling, and olfati-saber)
• Structured swarming (lemniscates, encirclement)
• Shepherding
• Various lattice assembly techniques using pinning control

Agents make decentralized decisions asynchronously based on local information only. There is no global plan.

Notes:

• This latest release is a major overhaul of the codebase. Some modules are still being updated. Detailed development notes are available in devnotes.md.
• Inputs/outputs for the various modules are still being standardized.
• Learning modules are still untested.
• Now with virtual environment and requirements.txt for easier setup.

---

Methodology

The swarming techniques above are all implemented as high-level trajectory planners, assuming underlying double integrator dynamics. When quadcopter dynamics are applicable, these command signals - which take the form of accelerations in Cartesian space - are then converted into velocity setpoints. The quadcopters make use of 3 nested control loops (translational velocity, angular position, and angular velocity) to track the desired trajectory.

---

Project Structure

├── venv/                    # python virtual environment
├── requirements.txt         # python package dependencies
├── agents/                  # agent definitions
├── config/                  # location of configuration file
├── data/                    # data storage
├── experiments/             # consolidated data, configs, plots (when flagged)
├── learner/                 # learning-related modules
├── obstacles/               # obstacle definitions 
├── planner/                 # swarming techniques stored as "planners"
│   ├── trajectory.py        # placeholder for trajectory definitions
│   └── techniques/          # technique definitions
├── targets/                 # target definitions
├── utils/                   # utility scripts 
├── visualization/           # animations and plots
├── orchestrator.py          # master controller (integrates all other components)
├── main.py                  # main script

---

Setup

Activate the virtual environment:

source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

---

Operation

Most parameters are centralized in config/config.json. Some of the learning-related parameters are still stored within the specific modules as they are in development, but these will be moved into the config in later versions.

To run a simulation, adjust the parameters as desired and then run as follows from the root folder:

 python main.py

---

Examples

Assembly: 50 agents with conflicting initial lattice parameters automatically negotiating and assembling.

Assembly: 12 agents conflicting initial lattice parameters, showing sensor ranges.

Lattice variations: Other examples with quadcopters, obstacles, and various lattice types.

Dynamic Structures: Shepherding, encirclment, and lemniscate trajectories.

Malicious Agents: Compensating for the presence of malicious agents.

---

Some other special features:

• 2D and 3D simulations
• Various agent shapes (dots, prisms, ... etc)
• Double-integrator and quadcopter dynamics
• Interconnectedness is represented as a Graph
• Flocking with heterogeneous lattice scales
• Reinforcement learning to adjust flocking scale
• Lemniscates formed as twisted circles
• Malicious agents
• Various potential functions
• Linearization and Dimensionality Reduction using UMAP
• Learning and control of swarm orientation in lower-dimensional hypospace

---

References

1. Craig Reynolds, "Flocks, Herds, and Schools:A Distributed Behavioral Model", Computer Graphics, 21(4) (SIGGRAPH '87 Conference Proceedings), pages 25-34, 1987.
2. Reza Olfati-Saber, "Flocking for Multi-Agent Dynamic Systems: Algorithms and Theory", IEEE Transactions on Automatic Control, Vol. 51 (3), 2006.
3. H. Hildenbrandt, C. Carere, and C.K. Hemelrijk,"Self-organized aerial displays of thousands of starlings: a model", Behavioral Ecology, Volume 21, Issue 6, pages 1349–1359, 2010.
4. P. T. Jardine and S. N. Givigi, "Flocks, Mobs, and Figure Eights: Swarming as a Lemniscatic Arch", IEEE Transactions on Network Science and Engineering, 2022.
5. Kléber M. Cabral, Sidney N. Givigi, and Peter T. Jardine, Autonomous assembly of structures using pinning control and formation algorithms in 2020 IEEE International Systems Conference (SysCon), 07 Dec 2020
6. S. Van Havermaet et al. "Steering herds away from dangers in dynamic environments" in Royal Society Open Science, 2023
7. C. Zhang, H. Yang, B. Jiang and M. Cao, "Flocking Control Against Malicious Agent" in IEEE Transactions on Automatic Control, vol. 69, no. 5, pp. 3278-3285, May 2024
8. P. T. Jardine and S. Givigi, "Emergent homeomorphic curves in swarms" in Automatica, vol. 176, 2025
9. Credit goes to bobzwik for providing the majority of the Quadcopter dynamics module code under MIT licence, which I modified to suit this application (portions of the code are annotated appropriately)
10. Credit goes to ericjhkim for providing code for prism agent shape

Citing

The code is opensource but, if you reference this work in your own research, please cite me. I have provided an example bibtex citation below:

@techreport{Jardine-2025, title={Multi-agent Coordination Simulator}, author={Jardine, P.T.}, year={2025}, institution={Queen's University, Kingston, Ontario}, type={GitHub Repository}, }

Alternatively, you can cite any of my related papers, which are listed in Google Scholar.