Choose party-optimality

Many two-sided matching games allow for the optimality of its stable matching to be chosen. This is done using the optimal parameter in the corresponding class’ solve method where the party for whom the solution should be optimal is specified.

To see how this may change things, consider the example below.

from matching.games import StableMarriage

suitor_preferences = {
    "A": ["X", "Y", "Z"],
    "B": ["Y", "Z", "X"],
    "C": ["Y", "X", "Z"],
}

reviewer_preferences = {
    "X": ["B", "C", "A"],
    "Y": ["A", "C", "B"],
    "Z": ["A", "B", "C"],
}

In the case of SM, the choices are "suitor" or "reviewer".

game = StableMarriage.create_from_dictionaries(
    suitor_preferences, reviewer_preferences
)

game.solve(optimal="suitor")

{A: X, B: Z, C: Y}

game = StableMarriage.create_from_dictionaries(
    suitor_preferences, reviewer_preferences
)

game.solve(optimal="reviewer")

{A: Y, B: Z, C: X}