A faithful implementation of the boid flocking algorithm as described in The computational beauty of flocking: Boids revisited (Bajec, Zimic, and Mraz, 2007).
👆 Click the image to watch the full video on YouTube 👆
This project implements the mathematical model of boid behavior with:
- Support for both 2D and 3D simulations
- Precise implementation of separation, alignment, and cohesion drives
- Configurable perception parameters (distance, field of view)
- Visualization tools for generating animations
The implementation follows the formal model from the paper, with each component (perception, drives, action selection) implemented as described in the mathematical formalism.
For details on the mathematical model, see notes/mathematical_model.md.
# Clone the repository
git clone https://github.com/keithSchumacher/classic_boids.git
cd classic_boids
# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Install in development mode
pip install -e .from classic_boids.core.simulation_runner import run_2d_simulation, run_3d_simulation
# Run a 2D simulation
csv_path = run_2d_simulation(num_boids=20, num_steps=200)
# Run a 3D simulation
csv_path = run_3d_simulation(num_boids=20, num_steps=200)from classic_boids.utils.animate_boids import animate_boids
from classic_boids.utils.animate_boids_3d import animate_boids_3d
# Generate 2D animation
animate_boids(csv_file="path/to/simulation_results.csv")
# Generate 3D animation
animate_boids_3d(csv_file="path/to/simulation_results_3d.csv")Generate sample data and animations with:
# Generate 2D sample data and animation
python -m src.classic_boids.utils.generate_sample_2d_data
# Generate 3D sample data and animation
python -m src.classic_boids.utils.generate_sample_3d_dataclassic_boids/
├── src/classic_boids/
│ ├── core/ # Core implementation of the boid model
│ │ ├── vector.py # Vector operations
│ │ ├── protocols.py # Type definitions and protocols
│ │ ├── boid.py # Boid class implementation
│ │ ├── perception.py # Perception functions
│ │ ├── drive.py # Drive functions
│ │ └── ...
│ ├── utils/ # Utility functions
│ │ ├── animate_boids.py # 2D animation
│ │ ├── animate_boids_3d.py # 3D animation
│ │ └── ...
├── tests/ # Unit tests
├── artifacts/ # Generated data and animations
└── notes/ # Documentation
Run the test suite with:
python -m pytest tests/- Mathematical Model - Detailed explanation of the mathematical formalism
- Generating Artifacts - Guide to generating simulation data and animations
- Angular Offset in 3D - Explanation of angular calculations in 3D space
- Camera Parameters and Perception - Details on perception model
MIT