Wednesday, November 5, 2014

PyPair: A Python Library for Pairing Swiss Tournaments

Something I've spent a few hours on in the last month is a small python library, that I am calling PyPair, that allows you to easily manage a Swiss-System Tournament. For those unfamiliar with this concept:

"A Swiss-system tournament is a non-elimination tournament format. There are several rounds of competition, but considerably fewer rounds than in a round-robin tournament, so each competitor (team or individual) does not play every other competitor. Competitors meet one-to-one in each round and are paired using a predetermined set of rules designed to ensure that as far as possible a competitor plays competitors with the same current score, subject to not playing the same opponent more than once. The winner is the competitor with the highest aggregate points earned in all rounds."

A short example of using PyPair:
from pypair import Tournament

Players = { 1:"Tim",

to = Tournament()

for player in Players:
    to.addPlayer( player, Players[player] )

pairings1 = to.pairRound()

print pairings1
Yields the output:

{1: [1, 7], 2: [2, 6], 3: [3, 5]}

Which is a simple python dictionary where each key is a table number that corresponds to a list of the players playing at that table.

If you would like to see a more complex example see here.

If you are interested in the math behind the pairings, PyPair essentially does the following when you call the pairRound() function:

Group players by point totals
Starting with the group who has the most points:

  • Create a graph with all players in current point total
  • Connect players in the graph that have not played yet
  • Use a Blossom based algorithm to compute a maximal matching of the graph
  • Take any unpaired players and add them to the group with the next highest point total
Repeat until there are one/none unpaired players
If there is one unpaired player, assign a bye
Return a python dictionary of the pairings

The networks created by PyPair are implemented using the NetworkX library.

If you have any suggestions for improvement or find an issue feel free to open a ticket on GitHub or leave a comment below.

~Jeff Hoogland

1 comment:

  1. Hey Jeff,
    I'm working on something similar for a community Team Fortress 2 league and I think that it's awesome that you're sharing this!
    Even though I'm almost done with this part I'll take a look at your code and maybe take some inspiration.