Introducing: Instant-runoff voting simulator

💬 4

I built a simulator showing how instant-runoff voting (called preferential voting in Australia) works step-by-step. Try it now.

The simulator in action
The simulator in action

I hope that, by being an interactive, animated, round-by-round visualisation of the ballot distribution process, this simulation gives you a deeper understanding of how instant-runoff voting works.

The rules coded into the simulator, are those used for the House of Representatives in Australian federal elections, as specified in the Electoral Act 1918 (Cth) s274.

There are other tools around that do basically the same thing as this simulator. Kudos to the authors of those tools. However, they only output a text log or a text-based table, they don't provide any visualisation or animation of the vote-counting process. And they spit out the results for all rounds all at once, they don't show (quite as clearly) how the results evolve from one round to the next.

Source code is all up on GitHub. It's coded in vanilla JS, with the help of the lovely Papa Parse library for CSV handling. I made a nice flowchart version of the code too.

See an interactive version of this flowchart on code2flow
See an interactive version of this flowchart on code2flow

With a federal election coming up, here in Australia, in just a few days' time, this simulator means there's now one less excuse for any of my fellow citizens to not know how the voting system works. And, in this election more than ever, it's vital that you properly understand why every preference matters, and how you can make every preference count.

Post a comment



Hi Jeremy,

Just want to let you know that there's a bug in the runoff simulator. Before Round 6, there are 5 A ballots, 2 B ballots, 6 D ballots, but after Round 6, the 6 D ballots get distributed not the B ballots.

Here's the test case.

a       b       c       d       e       f       g       h
4       7       8       5       2       6       1       3
1       8       7       2       6       5       4       3
3       1       8       5       6       7       2       4
3       7       5       1       8       6       2       4
3       2       5       1       6       7       4       8
1       8       7       4       2       5       3       6
2       5       3       6       7       8       1       4
2       1       8       3       4       6       5       7
3       8       7       1       5       4       2       6
8       3       5       2       4       1       7       6
8       6       7       2       5       4       3       1
4       7       6       1       3       2       8       5
1       8       3       7       2       5       4       6


Hi David,

Thanks for testing out my simulator. You're quite right, it's a bug.

Turns out that the bug is entirely caused by the fact that I didn't account for candidates that receive zero "Vote 1"'s. Such candidates should be eliminated in the first round, at the same time as when the "undistributed" pile is emptied and removed.

I've updated the code to do just that. And I added your sample data as another one of the built-in CSV's. You can see the code change here.

Appreciate you reporting this!


Hi Jeremy,

Thanks for addressing it quickly. You might be interested to know that my sample data was an actual vote held amongst some expeditioners at one of the Australian Antarctic bases at the moment (where I am at). When I ran it the results looked a bit funny hence did a step through and found the bug.

Thanks for putting something like this online - helps our democracy / civics along!


Hi David,

Wow, are you serious, you're in Antarctica right now?! And you have internet access? And you voted? And you're test driving peoples' random coding projects and reporting bugs? That's amazing!

Only 30 minutes to go, and election results will start coming in. You never know, there might be a pleasant change by the time you get back to the Australian mainland!