matching

matching / StableRoommateAlgorithm / 0.1.1

README.md

0. TL;DR

This algorithm gives you a stable matching for a given set of elements.

1. Introduction

The stable roommate problem (also known as stable matching problem) is the problem of of finding a stable matching in which there is no pair of elements where both members prefer their partner in a different matching over their partner in the stable matching. Unlike in the stable marriage problem, the stable roommates problem allows matches between any two elements, not just between classes of “men” and “women”.

This algorithm requires a list of preferred elements for each element.

One example of a use-case could be matching roommates in a dormitory. Given the preference lists for each person, the algorithm will return a stable matching if it exists.

This algorithm does not guarantee a stable matching for all possible combinations of preference lists.

Input

  • (Required): A dictionary of preference lists.

Output

  • A dictionary of stable matches if it exists.

2. Dictionary of desired matches

A dictionary of preference lists: A dictionary of lists. (key = "preferences")

Example of a dictionary of optimal preference lists:

{
    "preferences": {
        "Charlie": ["Peter", "Paul", "Sam", "Kelly", "Elise"],
        "Peter": ["Kelly", "Elise", "Sam", "Paul", "Charlie"],
        "Elise": ["Peter", "Sam", "Kelly", "Charlie", "Paul"],
        "Paul": ["Elise", "Charlie", "Sam", "Peter", "Kelly"],
        "Kelly": ["Peter", "Charlie", "Sam", "Elise", "Paul"],
        "Sam": ["Charlie", "Paul", "Kelly", "Elise", "Peter"]
    }
}

3. Output

A dictionary of stable matches optimized for the optimal dictionary: Returns a list of matches between two sets that are optimized for the given optimal labelled list. (key = "matches")

Example of Output:

{
    'Sam': 'Elise',
    'Charlie': 'Paul',
    'Kelly': 'Peter',
    'Elise': 'Sam',
    'Paul': 'Charlie',
    'Peter': 'Kelly'
}

4. Examples

Example 1:

  • Parameter 1: A dictionary of preference lists.
{
    "preferences": {
        "Charlie": ["Peter", "Paul", "Sam", "Kelly", "Elise"],
        "Peter": ["Kelly", "Elise", "Sam", "Paul", "Charlie"],
        "Elise": ["Peter", "Sam", "Kelly", "Charlie", "Paul"],
        "Paul": ["Elise", "Charlie", "Sam", "Peter", "Kelly"],
        "Kelly": ["Peter", "Charlie", "Sam", "Elise", "Paul"],
        "Sam": ["Charlie", "Paul", "Kelly", "Elise", "Peter"]
    }
}

Output:

{
    'Sam': 'Elise',
    'Charlie': 'Paul',
    'Kelly': 'Peter',
    'Elise': 'Sam',
    'Paul': 'Charlie',
    'Peter': 'Kelly'
}

Example 2:

  • Parameter 1: A dictionary of preference lists.
{
    "preferences": {
        "A": ["B", "D", "F", "C", "E"],
        "B": ["D", "E", "F", "A", "C"],
        "C": ["D", "E", "F", "A", "B"],
        "D": ["F", "C", "A", "E", "B"],
        "E": ["F", "C", "D", "B", "A"],
        "F": ["A", "B", "D", "C", "E"]
    }
}

Output:

{
    'A': 'F',
    'C': 'D',
    'B': 'E',
    'E': 'B',
    'D': 'C',
    'F': 'A'
}

5. Credits

The implementation done here is the algorithm known as the Irving Algorithm. For more information, please refer to Robert W Irving, An efficient algorithm for the “stable roommates” problem, Journal of Algorithms, Volume 6, Issue 4, 1985, Pages 577-595, ISSN 0196-6774, http://dx.doi.org/10.1016/0196-6774(85)90033-1