Pairing up suitors and reviewers

Help our ensemble overcome their pride and prejudice… with maths

In this tutorial we will be setting up and solving an instance of SM.

In particular, we will be using an example adapted from the great literary work, Pride and Prejudice (Austen 1813), where four women (Charlotte, Elizabeth, Jane and Lydia) are being courted by four male suitors (Bingley, Collins, Darcy, and Wickham).

From here on out, we’ll refer to the men and women as suitors and reviewers, respectively.

Creating the players and their preferences

To begin, we create an instance of the Player class for each suitor and reviewer:

from matching import Player

suitors = [
    Player("Bingley"),
    Player("Collins"),
    Player("Darcy"),
    Player("Wickham"),
]

reviewers = [
    Player("Charlotte"),
    Player("Elizabeth"),
    Player("Jane"),
    Player("Lydia"),
]

To set a player’s preferences, we use the Player.set_prefs() method.

Each player’s preferences must be a list of all the Player instances in the other party ordered according to how much they like them. That is, put your favourite first, followed by your second, and so on until you’ve put your least favourite last.

Warning

The preference lists below are based on some very loose interpretations of the original text and the need to create full lists. Please do not come for me about them.

A nice way to do this is by unpacking suitors and reviewers:

bingley, collins, darcy, wickham = suitors
charlotte, elizabeth, jane, lydia = reviewers

bingley.set_prefs([jane, elizabeth, lydia, charlotte])
collins.set_prefs([elizabeth, jane, lydia, charlotte])
darcy.set_prefs([elizabeth, jane, charlotte, lydia])
wickham.set_prefs([lydia, jane, elizabeth, charlotte])

charlotte.set_prefs([collins, darcy, bingley, wickham])
elizabeth.set_prefs([wickham, darcy, bingley, collins])
jane.set_prefs([bingley, wickham, darcy, collins])
lydia.set_prefs([wickham, bingley, darcy, collins])

Running the game

With our now complete Player instances, we pass the lists of players to the StableMarriage class to create a game:

from matching.games import StableMarriage

game = StableMarriage(suitors, reviewers)

Then we can find a suitor-optimal, stable matching using the solve method:

game.solve()

{Bingley: Jane, Collins: Charlotte, Darcy: Elizabeth, Wickham: Lydia}

Huzzah! We have shown (with some inventive but necessary subtext) that Jane Austen successfully created a stable matching between her characters over a century before the maths had been figured out.

References

Austen, Jane. 1813. Pride and Prejudice. Whitehall, London, UK: T. Egerton, Military Library.