Collective Decision Model (Majority / Voter / Kuramoto)

A lightweight swarm simulation to study collective decision making and coordination under three canonical models:

• Majority Rule
• Voter
• Kuramoto (phase-based synchronization)

The simulator runs in pygame, logs per–consensus-checkpoint metrics to CSV, and renders comparison plots across agent sizes and target counts. A batch mode sweeps common configurations and writes all results under Data/.

---

Contents

• Features
• Repository Structure
• Quick Start
• CLI Usage
• Batch Sweep
• Outputs & File Naming
• Evaluation Metrics (Mathematical Framework)
• Plotting
• Configuration
• Troubleshooting
• Extending
• License

---

Features

• Flocking dynamics (cohesion / separation / alignment) + target pursuit + obstacle avoidance.
• Three decision / consensus models: Majority, Voter, Kuramoto.
• Periodic “consensus checkpoints” (every CONSENSUS_PERIOD steps) where metrics are sampled.
• Batch sweep across agents ∈ {10,20,30,40} × targets ∈ {2,10} × models.
• CSV logging and comparison plots:
  • Direction mismatch
  • Collision count
  • Phase synchronization (Kuramoto only)
  • Decision Making Accuracy (number of agents reached target per time step)

---

Repository Structure

.
├── Data/
│   └── data.txt
├── Environment/
│   ├── SimAgent.py
│   ├── SimEnv.py
│   ├── SimHurdle.py
│   └── __init__.py
├── Models/
│   ├── CollectiveDecisionModel.py
│   └── ModelAgent.py
├── Utils/
│   ├── utils.py
│   └── config.json
├── README.md
├── main.py
└── requirements.txt 

Quick Start

Run a single interactive sim (window opens) with a chosen model:

# Majority model
python main.py -m

# Voter model
python main.py -v

# Kuramoto model
python main.py -k

Limit the run length:

python main.py -k -t 600

Use previously saved initial conditions:

python main.py -o -k

(Use -n to generate new data, if your version supports it.)

CLI Usage

Common flags available in the current codebase (names may live in config.py or Utils/config.py):

• -m / --majority : Majority Rule
• -v / --voter : Voter Model
• -k / --kuramoto : Kuramoto Model
• -t / --max-steps <int> : Step cap (0 = until closed)
• --batch : Sweep (agents 10/20/30/40 × targets 2/10 × all models) and save CSV Examples:

# Batch sweep + CSV
python main.py --batch -t 600 --csv-out Data/sweep_results.csv

# Plot (from CSV) without re-simulating
python main.py --plot-only      --csv-in Data/sweep_results.csv   # direction mismatch
python main.py --plot-collision --csv-in Data/sweep_results.csv   # collisions
python main.py --plot-phase     --csv-in Data/sweep_results.csv   # phase sync (Kuramoto)