0. TL;DR

This algorithm gives you the optimal matching for a preferred set.

1. Introduction

The stable marriage problem (also known as stable matching problem) is the problem of finding a stable matching between two equally sized sets of elements given an ordering of preferences for each element. This is the McVitie-Wilson version of the Gale-Shapley Algorithm.

This algorithm requires two sets of items where the algorithm gives the optimal matching for one of the groups.

One example of a use-case could be matching customers with taxi drivers. You can get the optimal matching in favor of the customers by passing it under the "optimal" key. If not, you can pass the taxi drivers instead. It will express one matching among all other possible matches that is the most favorable to the preferred set of items.

The algorithm will produce stable matches in all cases, but will always express a positive preference for a given match.

If you get the same match after switching the preferred set of items, this means that you have a super-stable matching. A matching is super-stable if there is no couple each of whom either strictly prefers the other to his/her partner or is indifferent between them.

Input

(Required): Optimal (preferred) dictionary of desired matches.
(Required): Pessimal dictionary desired matches.

Output

A dictionary of stable matches optimized for the optimal dictionary.

2. Dictionary of desired matches

Optimal (preferred) dictionary of desired matches: A dictionary of lists. Algorithms optimizes the matching in favor of these lists. (key = "optimal")

Example dictionary of optimal (preferred) desired matches:

{
    "optimal": {
        "reese": ["morgan", "groves", "carter", "shaw"],
        "finch": ["morgan", "carter", "shaw", "groves"],
        "fusco": ["shaw", "carter", "groves", "morgan"],
        "elias": ["groves", "carter", "shaw", "morgan"]
    }
}

Pessimal dictionary of desired matches: A dictionary of lists. Algorithms doesn't optimize the matching in favor of these lists (key = "pessimal")

Example dictionary of pessimal desired matched:

{
    "pessimal":{
        "carter": ["reese", "fusco", "elias", "finch"],
        "shaw": ["elias", "reese", "fusco", "finch"],
        "groves": ["reese", "fusco", "elias", "finch"],
        "morgan": ["finch", "fusco", "elias", "reese"]
    }
}

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:

{
    "matches":{
        "fusco":"shaw",
        "reese":"morgan",
        "elias":"groves",
        "finch":"carter"}
}

4. Examples

Example 1:

Parameter 1: Optimal list of strings
Parameter 2: Pessimal list of strings

{
    "optimal": {
        "reese": ["morgan", "groves", "carter", "shaw"],
        "finch": ["morgan", "carter", "shaw", "groves"],
        "fusco": ["shaw", "carter", "groves", "morgan"],
        "elias": ["groves", "carter", "shaw", "morgan"]
    },
    "pessimal":{
        "carter": ["reese", "fusco", "elias", "finch"],
        "shaw": ["elias", "reese", "fusco", "finch"],
        "groves": ["reese", "fusco", "elias", "finch"],
        "morgan": ["finch", "fusco", "elias", "reese"]
    }
}

Output:

{
    "matches":{
        "fusco":"shaw",
        "reese":"morgan",
        "elias":"groves",
        "finch":"carter"}
}

Example 2:

Parameter 1: Optimal list of strings
Parameter 2: Pessimal list of strings

{
    "optimal":{
      "carter": ["reese", "fusco", "elias", "finch"],
      "shaw": ["elias", "reese", "fusco", "finch"],
      "groves": ["reese", "fusco", "elias", "finch"],
      "morgan": ["finch", "fusco", "elias", "reese"]
    },
    "pessimal": {
        "reese": ["morgan", "groves", "carter", "shaw"],
        "finch": ["morgan", "carter", "shaw", "groves"],
        "fusco": ["shaw", "carter", "groves", "morgan"],
        "elias": ["groves", "carter", "shaw", "morgan"]
    }
}

Output:

{
  "matches": {
    "groves": "reese",
    "carter": "fusco",
    "morgan": "finch",
    "shaw": "elias"
  }
}

5. Credits

The implementation done here is the algorithm known as McVitie-Wilson version of the Gale-Shapley Algorithm. For more information, please refer to D. G. McVitie and L. B. Wilson. 1971. The stable marriage problem. Commun. ACM 14, 7 (July 1971), 486-490. DOI=http://dx.doi.org/10.1145/362619.362631

matching / StableMarriageAlgorithm / 0.1.2

Comments

Loading comments