Boid Simulation

A predator-prey flocking simulation using the Boids algorithm, implemented in C++23 with OpenGL visualization.

simulation.mov

Quick Start

Using Docker (Headless Only)

Docker is available for running tests and headless experiments. The graphical simulation (./main) requires OpenGL/GLFW and must be run natively on the host machine.

# Run all tests (118 tests)
docker compose run --rm test

# Run headless experiments (outputs to ./output/)
docker compose run --rm experiment

# Run with custom config
docker compose run --rm experiment config/sweep.yaml output/sweep_results.csv

# Generate coverage report (outputs to ./coverage-report/)
docker compose run --rm coverage

Note: To run the graphical simulation with visualization, use the native build below.

Native Build (macOS) — Required for Graphical Simulation

# Install dependencies
brew install googletest yaml-cpp glew glfw libomp

# Build and run graphical simulation
make all && ./main
# or simply:
make run

# Run tests
make test

# Generate coverage report
make coverage
open build/coverage/html/index.html

# Build with OpenMP parallelization
make PARALLEL=1 run

Native Build (Linux)

# Install dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y build-essential clang libglew-dev libglfw3-dev \
    libgtest-dev libyaml-cpp-dev libomp-dev llvm cmake

# Build Google Test from sources
cd /usr/src/googletest
sudo cmake -DCMAKE_CXX_COMPILER=clang++ .
sudo make && sudo make install && sudo ldconfig

# Build and test using Linux makefile
cd /path/to/assignment1
cp makefile.docker makefile
make test
make run

---

Features

• Flocking Behaviors: Separation, alignment, cohesion (Reynolds' Boids)
• Predator-Prey Dynamics: Prey flee from predators, predators chase prey
• Toroidal World: Wrap-around boundaries for seamless movement
• Spatial Indexing: KD-tree for efficient neighbor queries
• Metrics: Polarization, cluster detection, formation tracking
• OpenMP Support: Parallel simulation (make PARALLEL=1)
• Experiment Runner: Batch parameter sweeps with CSV output

---

Build Targets

Target	Command	Description
run	make run	Build and run the simulation with visualization
test	make test	Build and run all 118 unit tests
coverage	make coverage	Run tests with LLVM coverage, generate HTML
experiment	make experiment	Build experiment runner for batch simulations
clean	make clean	Remove all build artifacts

---

Project Structure

assignment1/
├── src/                    # Source files
│   ├── vec2.hpp            # 2D vector math
│   ├── boid.cpp/hpp        # Base boid class
│   ├── prey.cpp/hpp        # Prey behavior (flocking + flee)
│   ├── predator.cpp/hpp    # Predator behavior (chase)
│   ├── simulation.hpp      # Main simulation loop
│   ├── kdtree_boid.hpp     # Spatial indexing (KD-tree)
│   ├── flock_metrics.hpp   # Analysis metrics
│   ├── config.hpp          # YAML configuration loader
│   └── experiment.hpp      # Batch experiment runner
├── tests/                  # Unit tests (9 test files, 118 tests)
├── config/                 # YAML configuration files
├── scripts/                # Python analysis scripts
│   └── plot_results.py     # Visualization of experiment results
├── docs/                   # Documentation
│   └── TESTING.md          # Testing guide and platform setup
├── Dockerfile              # Multi-stage Docker build
├── docker-compose.yml      # Docker services (test, coverage, experiment)
├── makefile                # macOS build (Homebrew paths)
└── makefile.docker         # Linux build (standard paths)

---

Configuration

Simulations are configured via YAML files in config/:

simulation:
  width: 800
  height: 600
  num_prey: 100
  num_predators: 3

prey:
  max_speed: 4.0
  perception_radius: 50.0
  separation_weight: 1.5
  alignment_weight: 1.0
  cohesion_weight: 1.0

predator:
  max_speed: 3.5
  chase_radius: 100.0

---

Documentation

• Testing Documentation - Test coverage, running tests, platform-specific setup

---

Dependencies

Dependency	Purpose
Google Test	Unit testing framework
yaml-cpp	YAML configuration parsing
GLEW	OpenGL extension loading
GLFW	Window/input handling
libomp	OpenMP parallelization (optional)
LLVM	Coverage instrumentation

See TESTING.md for platform-specific installation instructions.