A comprehensive, educational web application for simulating and comparing 6 core electoral systems, with advanced computational features and visualizations.
- First-Past-the-Post (FPTP) - Simple plurality voting
Individual race simulation: Single-seat system where each district elects one member
- Instant-Runoff Voting (IRV/RCV) - Ranked elimination with transfers
Individual race simulation: Single-winner election using ranked choices to simulate runoffs - Single Transferable Vote (STV) - Multi-winner proportional
Legislative simulation: Fundamentally proportional and multi-winner, requires multiple seats to demonstrate vote transfers
- Party-List PR - Proportional seat allocation by party
Legislative simulation: Allocates seats proportionally using divisor methods at national/regional level Supports both Closed List (party-controlled) and Open List (voter influence on candidates)
- Mixed-Member Proportional (MMP) - Compensatory proportionality
Both simulation types: Combines district races (FPTP) with proportional top-up layer for overall proportionality - Parallel Voting (MMM) - Independent tiers
Both simulation types: District races plus separate proportional list without compensatory adjustment
For simplicity and focus, the following systems have been removed:
- Two-Round System (TRS) - Recommended alternative: Use IRV instead, which achieves similar majority-seeking goals through ranked-choice elimination
- Block Voting - May be re-implemented in future versions
- Limited Voting - May be re-implemented in future versions
- Approval Voting - May be re-implemented in future versions
Systems planned for future implementation:
- Borda Count - Positional voting system (n-1, n-2, ..., 0 points)
- Condorcet Method - Pairwise comparison winner
-
Install Python Dependencies
pip3 install -r requirements.txt
-
Start Backend Server (optional for advanced features)
python3 backend.py
-
Open Frontend
open index.html
# Unit tests
python3 test_calculators.py
# Integration tests
python3 test_integration.py- 📊 Pie Charts - Vote and seat distribution
- 📈 Comparison Bar Charts - Vote vs. seat share
- 🔄 Round-by-Round Flow - IRV/STV eliminations ⭐
- 📍 Ideological Spectrum - Left-right positioning ⭐
- 📉 Natural Thresholds - Effective minimums ⭐
- 📊 Loosemore-Hanby Index - Disproportionality metric
- ✅ Advanced STV with NumPy precision
- ✅ Strategic voting simulation
- ✅ Realistic ballot generation
- ✅ Multi-district MMP/Parallel ⭐
- ✅ Borda & Condorcet calculations ⭐
- ✅ Scenario save/load
- ✅ Batch processing
- Select electoral system
- Add parties and candidates
- Configure parameters (seats, thresholds)
- Input votes or rankings
- Calculate results
- Analyze visualizations and Arrow's Theorem
Full documentation: See /docs folder
- Arrow's Impossibility Theorem - Fairness criteria analysis
- Gibbard-Satterthwaite Theorem - Strategic voting risks
- Electoral Mathematics - Quotas, thresholds, allocation methods
- Real-world Examples - Historical cases and paradoxes
| Metric | Value |
|---|---|
| Electoral Systems | 13 |
| Backend APIs | 11 |
| Tests (Unit + Integration) | 14 (100% pass) |
| Visualizations | 7 types |
| Lines of Code | ~3,500 |
- ⭐ Percentage-Based Ballot Input - Enter percentages instead of absolute counts for ranked systems
- ⭐ Customizable Ballot Types - Choose 1-20 ballot patterns for IRV/STV/Borda/Condorcet
- ⭐ Chart.js Integration - Professional interactive charts with tooltips
- ⭐ Country Import - 16 countries with 84+ authentic political parties
- ⭐ Secure AI Analysis - Mistral AI integration with server-side API key
- ⭐ Auto-Fill Votes - One-click realistic vote generation
- ⭐ Borda Count
- ⭐ Condorcet Method
- ⭐ Multi-District Calculations
- ⭐ Strategic Voting Simulation
- ⭐ Realistic Ballot Generation
- ⭐ 100% Test Coverage
Educational use - Attribution appreciated
Version: 2.2.0
Status: ✅ Production Ready
Last Updated: November 27, 2025