ElectoralSim Documentation
Welcome to the ElectoralSim documentation. This toolkit provides a comprehensive framework for simulating electoral systems, voter behavior, and political dynamics.
Quick Links
What is ElectoralSim?
ElectoralSim is an agent-based modeling toolkit for electoral simulations, built on top of Mesa with Polars DataFrames. It enables researchers and developers to:
- Simulate elections at scale (1M+ voters) with multiple electoral systems
- Model voter behavior using established political science theories
- Analyze electoral outcomes with standard metrics (Gallagher, ENP, VSE)
- Run parameter sweeps for sensitivity analysis with the batch runner
- Study coalition dynamics and government stability
- Explore opinion dynamics through social network models
- Use CLI tools for batch simulations and analysis
Core Concepts
ElectionModel
The central class that orchestrates simulations. It manages voter agents, party agents, electoral rules, and behavior models.
BehaviorEngine
A pluggable system for combining multiple voter utility models (proximity, valence, retrospective, strategic voting).
OpinionDynamics
Social network-based opinion evolution using models like Bounded Confidence and Noisy Voter.
Country Presets
Pre-configured setups for 11 countries including India, USA, UK, Germany, and the EU Parliament.
Getting Started
from electoral_sim import ElectionModel
model = ElectionModel(n_voters=100_000, seed=42)
results = model.run_election()
print(f"Turnout: {results['turnout']:.1%}")
See the Quick Start Guide for more examples.