Skip to content

01_STAR — single-winner STAR Voting

One ballot, two rounds: score everyone 0–5, then an automatic runoff between the top two scorers.

A STAR Voting ballot: five candidates — Andre, Blake, Carmen, David, Erin — each scored 0 to 5. Instructions at top: give your favorite five stars, give your last choice zero or leave blank, equal scores are allowed, score other candidates as desired. This voter marks Andre 5, Blake 0, Carmen 4, David 4, Erin 1. Footer: the two highest scoring candidates are finalists, your full vote goes to the finalist you prefer, and the finalist with the most votes wins.

The ballot (Equal Vote) — note Carmen and David both score 4: equal scores are allowed, so you are never forced to invent a preference you don't feel. And Erin's 1 still outranks Blake's 0 — the ballot records how much you like each candidate, not just the order.

The library's headline method: STAR (Score Then Automatic Runoff) for one seat. You score every candidate 0–5; the two highest-scoring candidates become finalists, and an automatic runoff gives each ballot's full vote to whichever finalist it scored higher. Two rounds, one ballot.

Everything about STAR lives in this one folder: the concept explanations in 01_Learn/, and the runnable examples — tiny elections you can tabulate yourself, each isolating one idea — in the subfolders below. New to STAR? Read the concepts first:

The learning path

Follow the examples roughly in this order. The levels (101 → 201 → 301) match the authoritative curriculum — start there for the full sequence with pacing notes.

Voting 101 — the basics (the ballot, the two rounds, the spoiler)

  1. The ballot and the two rounds. Five coworkers, three lunches — the compromise everyone likes wins, shown on real BetterVoting results → the team-lunch example. (The running example paired with STAR — start here.)
  2. The broad compromise, again. A second three-candidate case to make the pattern stick → three candidates.
  3. How you're allowed to vote. Bullet votes, equal scores, low-score "protest" ballots, the eight-style gallery → ballot styles.
  4. The headline lesson — top scorer ≠ winner. STAR's single most important behavior, as a 3→9-candidate progression with a control case → Runoff Reversal.
  5. The spoiler, in numbers. Vote-splitting and the compromise winner → the vote-splitting scenarios · cross-method: the split-voting set.

Voting 201 — reading results & trusting the count

  1. Read the full audit report. The minimal on-screen report vs the complete _tabulated.txt (preference matrix + score distribution + the runoff/Condorcet blocks) → the _tabulated/ siblings in Runoff Reversal.
  2. A real election, end to end. A real 461-ballot BetterVoting STAR race, raw ballots → winner, read section by section → "What Makes the Best Pet?".
  3. Edge cases & trust. How ties resolve → the tie-break ladder · abstain / blank / zero handling.

Voting 301 — criteria & edge behavior

  1. The Majority Criterion (and the "relaxed" version) → the two 5-voter elections.
  2. The "dead rung" — when STAR's five-star tiebreaker can't fire and the tie falls to the lot → the dead-rung case.
  3. None of the Above — a protest electorate where NOTA actually wins → the NOTA election.
  4. The honest limits & the reversal debate → STAR's honest limits · the second-round FAQ.
  5. Practice — predict, then peek. Fourteen worked problems with hidden, tested solutions — reading drills, criteria probes (consistency, participation, later-no-harm), strategy gambles, the real 1994 Olympics ballots, a Ranked Robin cycle, build-your-own constructions, a multi-winner wing (Bloc vs proportional, STV transfers), and Approval's threshold dilemma → the exercises set.

How this folder is arranged

Five numbered buckets, in reading order. Every method folder in the library uses the same five, so once you know the shape here you know it for Bloc STAR, Proportional STAR, Approval and Ranked Robin too. Difficulty is not in the folder names — a case can be 101 for its basic idea and 301 for the deep dive — so levels are marked per set, and the authoritative sequence stays in the curriculum.

Bucket What lives there
01 Learn The concept pages: what STAR is, how the two rounds count, the properties and the honest limits. Start here if you're reading, not running.
02 Examples The teaching progression — the smallest elections, one new idea each — plus the headline lesson, Runoff Reversal.
03 Criteria What STAR guarantees and where it doesn't: Majority, favorite betrayal, IIA, the Test of Balance, NOTA, and the whole tie-breaking cascade.
04 Real elections Live BetterVoting races imported and reconciled against the engine — including the divergences that turn out to be BV bugs.
05 Practice Predict-then-peek problems with tested answer keys.
09 Parked Kept, but off the learning path.

The sets, by level

Set Bucket Level What it teaches
The teaching progression 02 101 The core sequence: the team-lunch example → three candidates → ballot styles → abstentions → quorum → vote-splitting → display options (one idea at a time).
Runoff Reversal — top scorer ≠ winner 02 101→301 Real BetterVoting elections where the runoff confirms or overturns the score leader — STAR's headline lesson, plus the convincing-vs-jarring reversal pair.
Equal and opposite 03 201 The Test of Balance: two exact-opposite ballots cancel completely, and the winner never moves.
The tie-break ladder 03 201 The happy path: ties the deterministic rungs settle before the lot is ever reached.
The Majority Criterion 03 301 Two 5-voter elections isolating STAR's Majority-Criterion behavior (and the Relaxed Majority Criterion).
Favorite betrayal 03 301 The rare construction where STAR's FBC leak shows with numbers — and scoring your favorite lower pays.
IIA & the cycle spoiler 03 301 In a genuine Condorcet cycle, a candidate who cannot win still changes who does — on sincere ballots.
The dead rung — when the tiebreak can't fire 03 301 The "dead rung": when no tied candidate holds a 5, the five-star tiebreak reads 0–0 and the lot decides.
None of the Above 03 301 BV215 — a protest election where None of the Above tops the scores and wins the runoff.
"What Makes the Best Pet?" 04 201 A real 461-ballot BV race imported and reconciled line by line — the whole pipeline, raw ballots to winner.
Runoff reversals on BV 04 201 The headline behavior on real ballots: BV's own screenshots beside the engine's report.
Abstain, blank & zero handling 04 201 BetterVoting's abstain/blank/zero handling reproduced and cross-checked — the "0 tallied votes yet a winner" divergence.
Exercises — predict, then peek 05 201→301 Fourteen worked problems with collapsible solutions: district consistency, the tenth-ballot participation paradox, five-verdicts-one-electorate, the 1994 Olympics ballots, center squeeze, bullet-vote backfire, the Equal Support reading drill, build-your-own reversal, a Ranked Robin cycle ladder, later-no-harm both ways, recruit-a-spoiler, Bloc-vs-proportional seats, the Approval threshold dilemma, and the STV transfer machine.

Parked, not on the learning path: two-candidate STAR — deliberately-trivial two-candidate cases. With only two candidates the runoff just echoes the scores, so there's nothing distinctive to learn; kept for completeness and as engine test fixtures. And flat scores & ties — eight ballots engineered to tie at every locus, swept on one page; the tie-breaking that teaches is the ladder and the dead rung.

Run a file yourself

From the engine directory:

python starvote_larry_hastings.py "01_STAR/02_Examples/cases/02a_c3_b1_three-candidates.yaml"

Every file writes a full audit report to its _tabulated.txt sibling — watch for the [Runoff Reversal] block, which prints whenever the score leader and the runoff winner differ.

file: README.md