Crate ranked_voting

The ranked_voting crate provides a thoroughly tested implementation of the Instant-Runoff Voting algorithm, which is also called ranked-choice voting in the United States, preferential voting in Australia or alternative vote in the United Kingdom.

This library can be used in multiple flavours:

• as a simple library for most cases (see the run_election1 function)

• as a command-line utility that provides fast and easy election results that can then be displayed or exported. The section timrcv provides a manual.

• as a more complex library that can handle all the diversity of implementations. It provides for example multiple ways to deal with blank or absentee ballots, undeclared candidates, etc. If you are attempting to replicate the results of a specific elections, you should carefully check the voting rules and use the configuration accordingly. If you are doing so, you should check run_election and VoteRules

timrcv

timrcv is a command-line program to run an instant runoff election. It can accomodate all common formats from vendors or public offices. This document presents a tutorial on how to use it.

Installation

Download the latest release from the releases page. Pre-compiled versions are available for Windows, MacOS and Linux.

Quick start with existing data

If you are running a poll and are collecting data using Microsoft Forms, Google Form, Qualtrics, look at the quick start using Google Forms.

If you have very simple needs and you can collect data in a small text file, timrcv accepts a simple format of comma-separated values.

To get started, let us say that you have a file with the following records of votes (example.csv). Each line corresponds to a vote, and A,B,C and D are the candidates:

A,B,,D
A,C,B,
B,A,D,C
B,C,A,D
C,A,B,D
D,B,A,C

Each line is a recorded vote. The first line A,B,,D says that this voter preferred candidate A over everyone else (his/her first choice), followed by B as a second choice and finally D as a last choice.

Running a vote with the default options is simply:

timrcv --input example.csv

Output:

[ INFO  ranked_voting] run_voting_stats: Processing 6 votes
[ INFO  ranked_voting] Processing 6 aggregated votes
[ INFO  ranked_voting] Candidate: 1: A
[ INFO  ranked_voting] Candidate: 2: B
[ INFO  ranked_voting] Candidate: 3: C
[ INFO  ranked_voting] Candidate: 4: D
[ INFO  ranked_voting] Round 1 (winning threshold: 4)
[ INFO  ranked_voting]       2 B -> running
[ INFO  ranked_voting]       2 A -> running
[ INFO  ranked_voting]       1 C -> running
[ INFO  ranked_voting]       1 D -> eliminated:1 -> B,
[ INFO  ranked_voting] Round 2 (winning threshold: 4)
[ INFO  ranked_voting]       3 B -> running
[ INFO  ranked_voting]       2 A -> running
[ INFO  ranked_voting]       1 C -> eliminated:1 -> A,
[ INFO  ranked_voting] Round 3 (winning threshold: 4)
[ INFO  ranked_voting]       3 A -> running
[ INFO  ranked_voting]       3 B -> eliminated:3 -> A,
[ INFO  ranked_voting] Round 4 (winning threshold: 4)
[ INFO  ranked_voting]       6 A -> elected

timrcv supports many options (input and output formats, validation of the candidates, configuration of the tabulating process, …). Look at the configuration section of the manual for more details.

Modules

manual

This is the long-form manual for ranked_voting and timrcv.

quick_start

Quick start with Google Forms

Structs

Ballot

A ballot submitted by a voter.

Builder

A builder for adding votes.

EliminationStats

Statistics for the elimination of the candidates.

RoundStats

Statistics for one round

VoteRules

The rules that control the voting process.

VotingResult

The result, in case of a successful election.

Enums

BallotChoice

All the possible states corresponding to a choice in a ballot.

DuplicateCandidateMode

Strategy on how to deal with duplicated names.

EliminationAlgorithm

The elimination algorithm to apply.

MaxSkippedRank

Controls how to deal with skipping blank or undervote pieces.

OverVoteRule

How to deal with overvotes.

TieBreakMode

The different modes to break a tie in case of multiple counts.

VotingErrors

Errors that prevent the algorithm from completing successfully.

WinnerElectionMode

The sort of election to run. For now, only elections with a single winner are implemented.

Functions

run_election

Runs an election using the instant-runoff voting algorithm.

run_election1

Runs an election (simple interface) using the instant-runoff voting algorithm.