Agent based imulation of Flock dynamic with Python. The scripts contained in this repository allow to simulate the flock behaviour given some basic rules, and visualizes it with an animation. This project also includes unit tests to ensure the correct functionality of the simulation.
- Installation
- Requirements
- Usage and examples
- Repository structure
- Documentation
- Scripts overview
- Theory background
To start using the repository, first clone it:
git clone https://github.com/MassimoMario/flock_simulation.git
This project requires Python ≥ 3.8 and the following libraries:
numpymatplotlibipythontqdmpytestpytest-cov
To install them you can run on the Bash:
pip install -r requirements.txt
The main script simulation.py can be runned from the command line providing different argument ending in different configuration.
For a complete list of parameters and their descriptions, run:
python simulation.py --help
Example of a simulation with a parameters that produce a good behaviour flock dynamic:
python simulation.py --N 300 --separation 11 --alignment 2.35 --coherence 1.1 --visual_range 30 --avoid_range 23
You can provide initial positions and velocities of N birds in two ways:
1️⃣ Providing individual values:
python simulation.py --N 3 --positions_i 1 1 --positions_i 50 50 --positions_i 30 55 --velocities_i 1 1 --velocities_i -5 5 --velocities_i -1.1 -2.3
[[1,1],[50,50],[30,55]] and an initial velocity array equal to [[1,1],[-5,5],[-1.1,-2.3]]
2️⃣ Providing a .npy file:
python simulation.py --N 3 --positions_file init_pos.npy --velocities_file init_vel.npy
You can provide simulation parameter from a .ini config file:
python simulation.py --config config/config_good_behaviour.ini
You can save the animation as a GIF and the resulting simulation arrays of bird positions and velocities as .npy files:
python simulation.py --save_anim True --save_ps_vs True
The saving key words are True/Yes, False/No.
The repository contains the following folders and files:
simulation.pyis the main script for simulating and animating the flock.scriptsfolder containing the flock class, the test script and the utils scriptsflock_class.pycontains the class Flock definition, where all the simulation computation are describedtest.pyis the unit test scripts made using pytestutils.pyscript contains the animation function and some useful functions for the configparser arguments interpretation
configfolder contains 3 configuration files.inito be used from command line as inputs insimulation.pyscriptrequirements.txtfile contains the list of dependencies required for the projectdocsfolder contains the source files used to generate the documentation.
The documentation can be seen at this link.
It's a Github page containing the html files generated using Sphinx starting from docstrings in the code.
docs folder contains the source files used to generate this documentation.
Script containing the Flock class definition. Each Flock object is an ensamble of N birds and can simulate their interaction and dynamic. The only methods accessible to the user are init_given_position, init_given_velocities which initialize the birds positions/velocities with given arrays, and simulate which simulate the flock dynamic given physic parameters such as separation, alignment, coherence and avoidance (see Theory background section).
Script containing the animation function, which animates and displays the flock dynamic with matplotlib.animation and IPython.display taking as input the resulting arrays of a Flock object simulation method. The script contains also some useful functions for the configparser arguments interpretation, which cast a string in the corresponding correct type in order to give it as input to the simulation.
Script containing unit tests for all methods in flock_class.py. The tests ensure correctness and stability of the code following the unit testing approach and are implemented using pytest.
Usage : To run all the tests, navigate in the scripts folder and run the test script:
cd scripts
pytest test.py
Since the Flock class needs a random seed to initialize an object, to provide it run:
SEED=42 pytest test.py
The default seed is 1999.
Coverage : To check the test coverage, use pytest-cov:
cd scripts
pytest --cov=flock_class test.py
It's the main script where all the required parameters are taken from command line using argparse or from a config file .ini using configparser library. In this script a flock dynamic is simulated and animated using a Flock object and the animation function from utils.py. The user can choose to save the animation if GIF format using the --save_anim argument in the command line.
The simulation is agent-based, it computes the interaction between birds and update their positions and velocities following some simple rules. The main paramaters of the simulation are separation, alignment, coherence and avoidance. Each of those parameters controls the strength of a force acting on each bird. See Theory background section for a mathematical description.
To simulate the collective emerging behaviour of a flock four simple rules have been taken into account that each bird must follow:
- Separation: move away from neighbour that is too near to avoid collision
- Alignment: adapt its velocity to the flock average velocity to move in the same direction as other birds
- Coherence: adapt its position to the flock average position moving toward the center of the flock to keep group toghether
- Avoidance: move away from obstacles/simulation barriers
 |
|---|
| Graphical representation of flock rules. From DataSctientest |
Mathematically, each rule is associated with a force and a scaling factor, and the simulation update is done using a pseudo accerelerated system formula.
First the flock mean position and velocity is computed, and
. Then for each bird
is computed the position of the nearest bird to
, named nearest(
).
For each bird and velocity
four forces are computed:
Where is the vector connecting each bird to the center of the simulation space.
The total force is used for updating birds position abd velocity: