/elsim

Election Simulator 3000: Simulates a variety of elections and voting methods

Primary LanguagePythonMIT LicenseMIT

Election Simulator 3000

CircleCI Actions Status

This is a library of functions for simulating thousands of elections held using different voting methods (Borda count, Approval voting, etc.) under different voter models (impartial culture, spatial model, etc.)

For example, it can be used to reproduce Figure 1 from Merrill 1984:

Or the table of Effectiveness from Weber 1977:

Standard Vote-for-half Borda
2 81.37 81.71 81.41
3 75.10 75.00 86.53
4 69.90 79.92 89.47
5 65.02 79.09 91.34
6 61.08 81.20 92.61
10 50.78 82.94 95.35
255 12.78 86.37 99.80

Goals

  • Fast (~25,000 elections per second on Core i7-9750H)
  • Flexible
  • Well-documented, easily-used and improved upon by other people
  • Well-tested and bug-free
  • Able to reproduce peer-reviewed research

Requirements

See requirements.txt. As of this README, it includes numpy and scipyfor the simulations, tabulate for printing example tables, joblib for parallelizing extreme examples, and pytest, hypothesis, and pytest-cov for running the tests. All should be installable through conda.

Optionally, elsim can use numba for speed. If not available, the code will still run, just more slowly.

Installation

One possibility is to install with pip:

pip install git+https://github.com/endolith/elsim.git

Documentation

Currently just the docstrings of the submodules and functions themselves, in numpydoc format.

Usage

Specify an election with three candidates (0, 1, 2), where two voters rank candidates 0 > 2 > 1, two voters rank candidates 1 > 2 > 0, and one ranks candidates 2 > 0 > 1:

>>> election = [[0, 2, 1],
                [0, 2, 1],
                [1, 2, 0],
                [1, 2, 0],
                [2, 0, 1]]

Calculate the winner using Black's method:

>>> from elsim.methods import black
>>> black(election)
2

Candidate 2 is the Condorcet winner, and wins under Black's method.

See /examples folder for more on what it can do, such as reproductions of previous research.

Tests

Tests can be run by installing the testing dependencies and then running pytest in the project folder.

Bugs / Requests

File issues on the Github issue tracker.

Similar projects

Election simulators

Voting system implementations