passagemath-polyhedra 10.6.37__cp314-cp314-musllinux_1_2_x86_64.whl

sage/game_theory/matching_game.py

@@ -0,0 +1,1181 @@
+# sage_setup: distribution = sagemath-polyhedra
+# sage.doctest: needs sage.graphs
+"""
+Matching games
+
+This module implements a class for matching games (stable marriage problems)
+[DI1989]_. At present the extended Gale-Shapley algorithm is implemented
+which can be used to obtain stable matchings.
+
+AUTHORS:
+
+- James Campbell and Vince Knight 06-2014: Original version
+"""
+
+# ****************************************************************************
+#       Copyright (C) 2014 James Campbell james.campbell@tanti.org.uk
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+from sage.structure.sage_object import SageObject
+from sage.rings.integer_ring import ZZ
+from copy import deepcopy
+from sage.graphs.bipartite_graph import BipartiteGraph
+
+
+class MatchingGame(SageObject):
+    r"""
+    A matching game.
+
+    A matching game (also called a stable matching problem) models a situation
+    in a population of `N` suitors and `N` reviewers. Suitors and reviewers
+    rank their preferences and attempt to find a match.
+
+    Formally, a matching game of size `N` is defined by two disjoint sets `S`
+    and `R` of size `N`. Associated to each element of `S` and `R` is a
+    preference list:
+
+    .. MATH::
+
+        f : S \to R^N
+        \text{ and }
+        g : R \to S^N.
+
+    Here is an example of matching game on 4 players:
+
+    .. MATH::
+
+        S = \{J, K, L, M\}, \\
+        R = \{A, B, C, D\}.
+
+    With preference functions:
+
+    .. MATH::
+
+        f(s) = \begin{cases}
+        (A, D, C, B) & \text{ if } s=J,\\
+        (A, B, C, D) & \text{ if } s=K,\\
+        (B, D, C, A) & \text{ if } s=L,\\
+        (C, A, B, D) & \text{ if } s=M,\\
+        \end{cases}
+
+        g(s) = \begin{cases}
+        (L, J, K, M) & \text{ if } s=A,\\
+        (J, M, L, K) & \text{ if } s=B,\\
+        (K, M, L, J) & \text{ if } s=C,\\
+        (M, K, J, L) & \text{ if } s=D.\\
+        \end{cases}
+
+    INPUT:
+
+    Two potential inputs are accepted (see below to see the effect of each):
+
+    - ``reviewer/suitors_preferences`` -- dictionary containing the
+      preferences of all players:
+
+      * key - each reviewer/suitors
+      * value - a tuple of suitors/reviewers
+
+    OR:
+
+    - ``integer`` -- integer simply representing the number of reviewers
+      and suitors
+
+    To implement the above game in Sage::
+
+        sage: suitr_pref = {'J': ('A', 'D', 'C', 'B'),
+        ....:               'K': ('A', 'B', 'C', 'D'),
+        ....:               'L': ('B', 'D', 'C', 'A'),
+        ....:               'M': ('C', 'A', 'B', 'D')}
+        sage: reviewr_pref = {'A': ('L', 'J', 'K', 'M'),
+        ....:                 'B': ('J', 'M', 'L', 'K'),
+        ....:                 'C': ('K', 'M', 'L', 'J'),
+        ....:                 'D': ('M', 'K', 'J', 'L')}
+        sage: m = MatchingGame([suitr_pref, reviewr_pref])
+        sage: m
+        A matching game with 4 suitors and 4 reviewers
+        sage: m.suitors()
+        ('J', 'K', 'L', 'M')
+        sage: m.reviewers()
+        ('A', 'B', 'C', 'D')
+
+    A matching `M` is any bijection between `S` and `R`. If `s \in S` and
+    `r \in R` are matched by `M` we denote:
+
+    .. MATH::
+
+        M(s) = r.
+
+    On any given matching game, one intends to find a matching that is stable.
+    In other words, so that no one individual has an incentive to break their
+    current match.
+
+    Formally, a stable matching is a matching that has no blocking pairs.
+    A blocking pair is any pair `(s, r)` such that `M(s) \neq r` but `s`
+    prefers `r` to `M(r)` and `r` prefers `s` to `M^{-1}(r)`.
+
+    To obtain the stable matching in Sage we use the ``solve`` method which
+    uses the extended Gale-Shapley algorithm [DI1989]_::
+
+        sage: m.solve()
+        {'J': 'A', 'K': 'C', 'L': 'D', 'M': 'B'}
+
+    Matchings have a natural representations as bipartite graphs::
+
+        sage: plot(m)                                                                   # needs sage.plot
+        Graphics object consisting of 13 graphics primitives
+
+    The above plots the bipartite graph associated with the matching.
+    This plot can be accessed directly::
+
+        sage: graph = m.bipartite_graph()
+        sage: graph
+        Bipartite graph on 8 vertices
+
+    It is possible to initiate a matching game without having to name each
+    suitor and reviewer::
+
+        sage: n = 8
+        sage: big_game = MatchingGame(n)
+        sage: big_game.suitors()
+        (1, 2, 3, 4, 5, 6, 7, 8)
+        sage: big_game.reviewers()
+        (-1, -2, -3, -4, -5, -6, -7, -8)
+
+    If we attempt to obtain the stable matching for the above game,
+    without defining the preference function we obtain an error::
+
+        sage: big_game.solve()
+        Traceback (most recent call last):
+        ...
+        ValueError: suitor preferences are not complete
+
+    To continue we have to populate the preference dictionary. Here
+    is one example where the preferences are simply the corresponding
+    element of the permutation group::
+
+        sage: from itertools import permutations
+        sage: suitr_preferences = list(permutations([-i-1 for i in range(n)]))
+        sage: revr_preferences = list(permutations([i+1 for i in range(n)]))
+        sage: for player in range(n):
+        ....:     big_game.suitors()[player].pref = suitr_preferences[player]
+        ....:     big_game.reviewers()[player].pref = revr_preferences[-player]
+        sage: big_game.solve()
+        {1: -1, 2: -8, 3: -6, 4: -7, 5: -5, 6: -4, 7: -3, 8: -2}
+
+    Note that we can also combine the two ways of creating a game. For example
+    here is an initial matching game::
+
+        sage: suitrs = {'Romeo': ('Juliet', 'Rosaline'),
+        ....:            'Mercutio': ('Juliet', 'Rosaline')}
+        sage: revwrs = {'Juliet': ('Romeo', 'Mercutio'),
+        ....:           'Rosaline': ('Mercutio', 'Romeo')}
+        sage: g = MatchingGame(suitrs, revwrs)
+
+    Let us assume that all of a sudden a new pair of suitors and reviewers is
+    added but their names are not known::
+
+        sage: g.add_reviewer()
+        sage: g.add_suitor()
+        sage: g.reviewers()
+        (-3, 'Juliet', 'Rosaline')
+        sage: g.suitors()
+        (3, 'Mercutio', 'Romeo')
+
+    Note that when adding a reviewer or a suitor all preferences are wiped::
+
+        sage: [s.pref for s in g.suitors()]
+        [[], [], []]
+        sage: [r.pref for r in g.reviewers()]
+        [[], [], []]
+
+    If we now try to solve the game we will get an error as we have not
+    specified the preferences which will need to be updated::
+
+        sage: g.solve()
+        Traceback (most recent call last):
+        ...
+        ValueError: suitor preferences are not complete
+
+    Here we update the preferences so that the new reviewers and suitors
+    do not affect things too much (they prefer each other and are the least
+    preferred of the others)::
+
+        sage: g.suitors()[1].pref = suitrs['Mercutio'] + (-3,)
+        sage: g.suitors()[2].pref = suitrs['Romeo'] + (-3,)
+        sage: g.suitors()[0].pref = (-3, 'Juliet', 'Rosaline')
+        sage: g.reviewers()[2].pref = revwrs['Rosaline'] + (3,)
+        sage: g.reviewers()[1].pref = revwrs['Juliet'] + (3,)
+        sage: g.reviewers()[0].pref = (3, 'Romeo', 'Mercutio')
+
+    Now the game can be solved::
+
+        sage: D = g.solve()
+        sage: D['Mercutio']
+        'Rosaline'
+        sage: D['Romeo']
+        'Juliet'
+        sage: D[3]
+        -3
+
+    Note that the above could be equivalently (and more simply) carried out
+    by simply updated the original preference dictionaries::
+
+        sage: for key in suitrs:
+        ....:     suitrs[key] = suitrs[key] + (-3,)
+        sage: for key in revwrs:
+        ....:     revwrs[key] = revwrs[key] + (3,)
+        sage: suitrs[3] = (-3, 'Juliet', 'Rosaline')
+        sage: revwrs[-3] = (3, 'Romeo', 'Mercutio')
+        sage: g = MatchingGame(suitrs, revwrs)
+        sage: D = g.solve()
+        sage: D['Mercutio']
+        'Rosaline'
+        sage: D['Romeo']
+        'Juliet'
+        sage: D[3]
+        -3
+
+    It can be shown that the Gale-Shapley algorithm will return the stable
+    matching that is optimal from the point of view of the suitors and is in
+    fact the worst possible matching from the point of view of the reviewers.
+    To quickly obtain the matching that is optimal for the reviewers we
+    use the ``solve`` method with the ``invert=True`` option::
+
+        sage: left_dict = {'a': ('A', 'B', 'C'),
+        ....:              'b': ('B', 'C', 'A'),
+        ....:              'c': ('B', 'A', 'C')}
+        sage: right_dict = {'A': ('b', 'c', 'a'),
+        ....:               'B': ('a', 'c', 'b'),
+        ....:               'C': ('a', 'b', 'c')}
+        sage: quick_game = MatchingGame([left_dict, right_dict])
+        sage: quick_game.solve()
+        {'a': 'A', 'b': 'C', 'c': 'B'}
+        sage: quick_game.solve(invert=True)
+        {'A': 'c', 'B': 'a', 'C': 'b'}
+
+    EXAMPLES:
+
+    8 player letter game::
+
+        sage: suitr_pref = {'J': ('A', 'D', 'C', 'B'),
+        ....:               'K': ('A', 'B', 'C', 'D'),
+        ....:               'L': ('B', 'D', 'C', 'A'),
+        ....:               'M': ('C', 'A', 'B', 'D')}
+        sage: reviewr_pref = {'A': ('L', 'J', 'K', 'M'),
+        ....:                 'B': ('J', 'M', 'L', 'K'),
+        ....:                 'C': ('K', 'M', 'L', 'J'),
+        ....:                 'D': ('M', 'K', 'J', 'L')}
+        sage: m = MatchingGame([suitr_pref, reviewr_pref])
+        sage: m.suitors()
+        ('J', 'K', 'L', 'M')
+        sage: m.reviewers()
+        ('A', 'B', 'C', 'D')
+
+    Also works for numbers::
+
+        sage: suit = {0: (3, 4),
+        ....:         1: (3, 4)}
+        sage: revr = {3: (0, 1),
+        ....:         4: (1, 0)}
+        sage: g = MatchingGame([suit, revr])
+
+    Can create a game from an integer. This gives default set of preference
+    functions::
+
+        sage: g = MatchingGame(3)
+        sage: g
+        A matching game with 3 suitors and 3 reviewers
+
+    We have an empty set of preferences for a default named set of
+    preferences::
+
+        sage: for s in g.suitors():
+        ....:     s, s.pref
+        (1, [])
+        (2, [])
+        (3, [])
+        sage: for r in g.reviewers():
+        ....:     r, r.pref
+        (-1, [])
+        (-2, [])
+        (-3, [])
+
+    Before trying to solve such a game the algorithm will check if it is
+    complete or not::
+
+        sage: g.solve()
+        Traceback (most recent call last):
+        ...
+        ValueError: suitor preferences are not complete
+
+    To be able to obtain the stable matching we must input the preferences::
+
+        sage: for s in g.suitors():
+        ....:   s.pref = (-1, -2, -3)
+        sage: for r in g.reviewers():
+        ....:   r.pref = (1, 2, 3)
+        sage: g.solve()
+        {1: -1, 2: -2, 3: -3}
+    """
+    def __init__(self, generator, revr=None):
+        r"""
+        Initialize a matching game and check the inputs.
+
+        TESTS::
+
+            sage: suit = {0: (3, 4), 1: (3, 4)}
+            sage: revr = {3: (0, 1), 4: (1, 0)}
+            sage: g = MatchingGame([suit, revr])
+            sage: TestSuite(g).run()
+
+            sage: g = MatchingGame(3)
+            sage: TestSuite(g).run()
+
+            sage: g2 = MatchingGame(QQ(3))
+            sage: g == g2
+            True
+
+        The above shows that the input can be either two  dictionaries
+        or an integer::
+
+            sage: g = MatchingGame(suit, 3)
+            Traceback (most recent call last):
+            ...
+            TypeError: generator must be an integer or a pair of 2 dictionaries
+
+            sage: g = MatchingGame(matrix(2, [1, 2, 3, 4]))
+            Traceback (most recent call last):
+            ...
+            TypeError: generator must be an integer or a pair of 2 dictionaries
+
+            sage: g = MatchingGame('1,2,3', 'A,B,C')
+            Traceback (most recent call last):
+            ...
+            TypeError: generator must be an integer or a pair of 2 dictionaries
+        """
+        self._suitors = []
+        self._reviewers = []
+        if revr is not None:
+            generator = [generator, revr]
+
+        if generator in ZZ:
+            for i in range(generator):
+                self.add_suitor()
+                self.add_reviewer()
+        elif isinstance(generator[0], dict) and isinstance(generator[1], dict):
+            for i in generator[0]:
+                self.add_suitor(i)
+            for k in generator[1]:
+                self.add_reviewer(k)
+
+            for i in self._suitors:
+                i.pref = generator[0][i._name]
+            for k in self._reviewers:
+                k.pref = generator[1][k._name]
+        else:
+            raise TypeError("generator must be an integer or a pair of 2 dictionaries")
+
+    def _repr_(self):
+        r"""
+        Return a basic representation of the game stating how many
+        players are in the game.
+
+        EXAMPLES:
+
+        Matching game with 2 reviewers and 2 suitors::
+
+            sage: M = MatchingGame(2)
+            sage: M
+            A matching game with 2 suitors and 2 reviewers
+        """
+        txt = 'A matching game with {} suitors and {} reviewers'
+        return txt.format(len(self._suitors), len(self._reviewers))
+
+    def _latex_(self):
+        r"""
+        Create the LaTeX representation of the dictionaries for suitors
+        and reviewers.
+
+        EXAMPLES::
+
+            sage: suit = {0: (3, 4), 1: (3, 4)}
+            sage: revr = {3: (0, 1), 4: (1, 0)}
+            sage: g = MatchingGame([suit, revr])
+            sage: latex(g)
+            \text{Suitors:}
+            \begin{aligned}
+            \\ 0 & \to (3, 4)
+            \\ 1 & \to (3, 4)
+            \end{aligned}
+            \text{Reviewers:}
+            \begin{aligned}
+            \\ 3 & \to (0, 1)
+            \\ 4 & \to (1, 0)
+            \end{aligned}
+        """
+        output = "\\text{Suitors:}\n\\begin{aligned}"
+        for suitor in self._suitors:
+            output += "\n\\\\ %s & \\to %s" % (suitor, suitor.pref)
+        output += "\n\\end{aligned}\n\\text{Reviewers:}\n\\begin{aligned}"
+        for reviewer in self._reviewers:
+            output += "\n\\\\ %s & \\to %s" % (reviewer, reviewer.pref)
+        return output + "\n\\end{aligned}"
+
+    def __eq__(self, other):
+        """
+        Check equality.
+
+            sage: suit = {0: (3, 4), 1: (3, 4)}
+            sage: revr = {3: (0, 1), 4: (1, 0)}
+            sage: g = MatchingGame([suit, revr])
+            sage: g2 = MatchingGame([suit, revr])
+            sage: g == g2
+            True
+
+        Here the two sets of suitors have different preferences::
+
+            sage: suit1 = {0: (3, 4), 1: (3, 4)}
+            sage: revr1 = {3: (1, 0), 4: (1, 0)}
+            sage: g1 = MatchingGame([suit1, revr1])
+            sage: suit2 = {0: (4, 3), 1: (3, 4)}
+            sage: revr2 = {3: (1, 0), 4: (1, 0)}
+            sage: g2 = MatchingGame([suit2, revr2])
+            sage: g == g2
+            False
+
+        Here the two sets of reviewers have different preferences::
+
+            sage: suit1 = {0: (3, 4), 1: (3, 4)}
+            sage: revr1 = {3: (0, 1), 4: (1, 0)}
+            sage: g1 = MatchingGame([suit1, revr1])
+            sage: suit2 = {0: (3, 4), 1: (3, 4)}
+            sage: revr2 = {3: (1, 0), 4: (0, 1)}
+            sage: g2 = MatchingGame([suit2, revr2])
+            sage: g == g2
+            False
+
+        Note that if two games are created with players ordered differently
+        they can still be equal::
+
+            sage: g1 = MatchingGame(1)
+            sage: g1.add_reviewer(-2)
+            sage: g1.add_reviewer(-3)
+            sage: g1.add_suitor(3)
+            sage: g1.add_suitor(2)
+            sage: g1.reviewers()
+            (-1, -2, -3)
+            sage: g1.suitors()
+            (1, 2, 3)
+
+            sage: g2 = MatchingGame(1)
+            sage: g2.add_reviewer(-2)
+            sage: g2.add_reviewer(-3)
+            sage: g2.add_suitor(2)
+            sage: g2.add_suitor(3)
+            sage: g2.reviewers()
+            (-1, -2, -3)
+            sage: g2.suitors()
+            (1, 2, 3)
+
+            sage: g1 == g2
+            True
+        """
+        return (isinstance(other, MatchingGame)
+                and set(self._suitors) == set(other._suitors)
+                and set(self._reviewers) == set(other._reviewers)
+                and all(r1.pref == r2.pref for r1, r2 in
+                        zip(set(self._reviewers), set(other._reviewers)))
+                and all(s1.pref == s2.pref for s1, s2 in
+                        zip(set(self._suitors), set(other._suitors))))
+
+    __hash__ = None
+    # not hashable because this is mutable.
+
+    def plot(self):
+        r"""
+        Create the plot representing the stable matching for the game.
+        Note that the game must be solved for this to work.
+
+        EXAMPLES:
+
+        An error is returned if the game is not solved::
+
+            sage: suit = {0: (3, 4),
+            ....:         1: (3, 4)}
+            sage: revr = {3: (0, 1),
+            ....:         4: (1, 0)}
+            sage: g = MatchingGame([suit, revr])
+            sage: plot(g)                                                               # needs sage.plot
+            Traceback (most recent call last):
+            ...
+            ValueError: game has not been solved yet
+
+            sage: g.solve()
+            {0: 3, 1: 4}
+            sage: plot(g)                                                               # needs sage.plot
+            Graphics object consisting of 7 graphics primitives
+        """
+        pl = self.bipartite_graph()
+        return pl.plot()
+
+    def bipartite_graph(self):
+        r"""
+        Construct a ``BipartiteGraph`` Object of the game.
+        This method is similar to the plot method.
+        Note that the game must be solved for this to work.
+
+        EXAMPLES:
+
+        An error is returned if the game is not solved::
+
+            sage: suit = {0: (3, 4),
+            ....:         1: (3, 4)}
+            sage: revr = {3: (0, 1),
+            ....:         4: (1, 0)}
+            sage: g = MatchingGame([suit, revr])
+            sage: g.bipartite_graph()
+            Traceback (most recent call last):
+            ...
+            ValueError: game has not been solved yet
+
+            sage: g.solve()
+            {0: 3, 1: 4}
+            sage: g.bipartite_graph()
+            Bipartite graph on 4 vertices
+        """
+        self._is_solved()
+        graph = BipartiteGraph(self._sol_dict)
+        return graph
+
+    def _is_solved(self):
+        r"""
+        Raise an error if the game has not been solved yet.
+
+        EXAMPLES::
+
+            sage: suit = {0: (3, 4),
+            ....:         1: (3, 4)}
+            sage: revr = {3: (0, 1),
+            ....:         4: (1, 0)}
+            sage: g = MatchingGame([suit, revr])
+            sage: g._is_solved()
+            Traceback (most recent call last):
+            ...
+            ValueError: game has not been solved yet
+            sage: g.solve()
+            {0: 3, 1: 4}
+            sage: g._is_solved()
+        """
+        suitor_check = all(s.partner for s in self._suitors)
+        reviewer_check = all(r.partner for r in self._reviewers)
+        if not suitor_check or not reviewer_check:
+            raise ValueError("game has not been solved yet")
+
+    def _is_complete(self):
+        r"""
+        Raise an error if all players do not have acceptable preferences.
+
+        EXAMPLES:
+
+        Not enough reviewers::
+
+            sage: suit = {0: (3, 4),
+            ....:         1: (3, 4)}
+            sage: revr = {3: (0, 1)}
+            sage: g = MatchingGame([suit, revr])
+            sage: g._is_complete()
+            Traceback (most recent call last):
+            ...
+            ValueError: must have the same number of reviewers as suitors
+
+        Not enough suitors::
+
+            sage: suit = {0: (3, 4)}
+            sage: revr = {1: (0, 2),
+            ....:         3: (0, 1)}
+            sage: g = MatchingGame([suit, revr])
+            sage: g._is_complete()
+            Traceback (most recent call last):
+            ...
+            ValueError: must have the same number of reviewers as suitors
+
+        Suitors preferences are incomplete::
+
+            sage: suit = {0: (3, 8),
+            ....:         1: (0, 0)}
+            sage: revr = {3: (0, 1),
+            ....:         4: (1, 0)}
+            sage: g = MatchingGame([suit, revr])
+            sage: g._is_complete()
+            Traceback (most recent call last):
+            ...
+            ValueError: suitor preferences are not complete
+
+        Reviewer preferences are incomplete::
+
+            sage: suit = {0: (3, 4),
+            ....:         1: (3, 4)}
+            sage: revr = {3: (0, 2, 1),
+            ....:         4: (1, 0)}
+            sage: g = MatchingGame([suit, revr])
+            sage: g._is_complete()
+            Traceback (most recent call last):
+            ...
+            ValueError: reviewer preferences are not complete
+
+        Suitor preferences have repetitions::
+
+            sage: suit = {0: (3,  4),
+            ....:         1: (3, 4)}
+            sage: revr = {3: (0, 0, 1),
+            ....:         4: (1, 0)}
+            sage: g = MatchingGame([suit, revr])
+            sage: g._is_complete()
+            Traceback (most recent call last):
+            ...
+            ValueError: reviewer preferences contain repetitions
+
+        Reviewer preferences have repetitions::
+
+            sage: suit = {0: (3,  4, 3),
+            ....:         1: (3, 4)}
+            sage: revr = {3: (0, 1),
+            ....:         4: (1, 0)}
+            sage: g = MatchingGame([suit, revr])
+            sage: g._is_complete()
+            Traceback (most recent call last):
+            ...
+            ValueError: suitor preferences contain repetitions
+        """
+        if len(self._suitors) != len(self._reviewers):
+            raise ValueError("must have the same number of reviewers as suitors")
+
+        for suitor in self._suitors:
+            if set(suitor.pref) != set(self._reviewers):
+                raise ValueError("suitor preferences are not complete")
+
+        for reviewer in self._reviewers:
+            if set(reviewer.pref) != set(self._suitors):
+                raise ValueError("reviewer preferences are not complete")
+
+        for reviewer in self._reviewers:
+            if len(set(reviewer.pref)) < len(reviewer.pref):
+                raise ValueError("reviewer preferences contain repetitions")
+
+        for suitor in self._suitors:
+            if len(set(suitor.pref)) < len(suitor.pref):
+                raise ValueError("suitor preferences contain repetitions")
+
+    def add_suitor(self, name=None):
+        r"""
+        Add a suitor to the game.
+
+        INPUT:
+
+        - ``name`` -- can be a string or a number; if left blank will
+          automatically generate an integer
+
+        EXAMPLES:
+
+        Creating a two player game::
+
+            sage: g = MatchingGame(2)
+            sage: g.suitors()
+            (1, 2)
+
+        Adding a suitor without specifying a name::
+
+            sage: g.add_suitor()
+            sage: g.suitors()
+            (1, 2, 3)
+
+        Adding a suitor while specifying a name::
+
+            sage: g.add_suitor('D')
+            sage: g.suitors()
+            (1, 2, 3, 'D')
+
+        Note that now our game is no longer complete::
+
+            sage: g._is_complete()
+            Traceback (most recent call last):
+            ...
+            ValueError: must have the same number of reviewers as suitors
+
+        Note that an error is raised if one tries to add a suitor
+        with a name that already exists::
+
+            sage: g.add_suitor('D')
+            Traceback (most recent call last):
+            ...
+            ValueError: a suitor with name "D" already exists
+
+        If we add a suitor without passing a name then the name
+        of the suitor will not use one that is already chosen::
+
+            sage: suit = {0: (-1,  -2),
+            ....:         2: (-2, -1)}
+            sage: revr = {-1: (0, 1),
+            ....:         -2: (1, 0)}
+            sage: g = MatchingGame([suit, revr])
+            sage: g.suitors()
+            (0, 2)
+
+            sage: g.add_suitor()
+            sage: g.suitors()
+            (0, 2, 3)
+        """
+        if name is None:
+            name = len(self._suitors) + 1
+            while name in self._suitors:
+                name += 1
+        if any(s._name == name for s in self._suitors):
+            raise ValueError('a suitor with name "{}" already exists'.format(name))
+
+        new_suitor = Player(name)
+        self._suitors.append(new_suitor)
+        for r in self._reviewers:
+            r.pref = []
+
+    def add_reviewer(self, name=None):
+        r"""
+        Add a reviewer to the game.
+
+        INPUT:
+
+        - ``name`` -- can be a string or number; if left blank will
+          automatically generate an integer
+
+        EXAMPLES:
+
+        Creating a two player game::
+
+            sage: g = MatchingGame(2)
+            sage: g.reviewers()
+            (-1, -2)
+
+        Adding a suitor without specifying a name::
+
+            sage: g.add_reviewer()
+            sage: g.reviewers()
+            (-1, -2, -3)
+
+        Adding a suitor while specifying a name::
+
+            sage: g.add_reviewer(10)
+            sage: g.reviewers()
+            (-1, -2, -3, 10)
+
+        Note that now our game is no longer complete::
+
+            sage: g._is_complete()
+            Traceback (most recent call last):
+            ...
+            ValueError: must have the same number of reviewers as suitors
+
+        Note that an error is raised if one tries to add a reviewer
+        with a name that already exists::
+
+            sage: g.add_reviewer(10)
+            Traceback (most recent call last):
+            ...
+            ValueError: a reviewer with name "10" already exists
+
+        If we add a reviewer without passing a name then the name
+        of the reviewer will not use one that is already chosen::
+
+            sage: suit = {0: (-1,  -3),
+            ....:         1: (-3, -1)}
+            sage: revr = {-1: (0, 1),
+            ....:         -3: (1, 0)}
+            sage: g = MatchingGame([suit, revr])
+            sage: g.reviewers()
+            (-1, -3)
+
+            sage: g.add_reviewer()
+            sage: g.reviewers()
+            (-1, -3, -4)
+        """
+        if name is None:
+            name = -len(self._reviewers) - 1
+            while name in self._reviewers:
+                name -= 1
+        if any(r._name == name for r in self._reviewers):
+            raise ValueError('a reviewer with name "{}" already exists'.format(name))
+
+        new_reviewer = Player(name)
+        self._reviewers.append(new_reviewer)
+        for s in self._suitors:
+            s.pref = []
+
+    def suitors(self):
+        """
+        Return the suitors of ``self``.
+
+        EXAMPLES::
+
+            sage: g = MatchingGame(2)
+            sage: g.suitors()
+            (1, 2)
+        """
+        return tuple(sorted(self._suitors, key=lambda s:str(s._name)))
+
+    def reviewers(self):
+        """
+        Return the reviewers of ``self``.
+
+        EXAMPLES::
+
+            sage: g = MatchingGame(2)
+            sage: g.reviewers()
+            (-1, -2)
+        """
+        return tuple(sorted(self._reviewers, key=lambda r:str(r._name)))
+
+    def solve(self, invert=False):
+        r"""
+        Compute a stable matching for the game using the Gale-Shapley
+        algorithm.
+
+        EXAMPLES::
+
+            sage: suitr_pref = {'J': ('A', 'D', 'C', 'B'),
+            ....:               'K': ('A', 'B', 'C', 'D'),
+            ....:               'L': ('B', 'C', 'D', 'A'),
+            ....:               'M': ('C', 'A', 'B', 'D')}
+            sage: reviewr_pref = {'A': ('L', 'J', 'K', 'M'),
+            ....:                 'B': ('J', 'M', 'L', 'K'),
+            ....:                 'C': ('M', 'K', 'L', 'J'),
+            ....:                 'D': ('M', 'K', 'J', 'L')}
+            sage: m = MatchingGame([suitr_pref, reviewr_pref])
+            sage: m.solve()
+            {'J': 'A', 'K': 'D', 'L': 'B', 'M': 'C'}
+
+            sage: suitr_pref = {'J': ('A', 'D', 'C', 'B'),
+            ....:               'K': ('A', 'B', 'C', 'D'),
+            ....:               'L': ('B', 'C', 'D', 'A'),
+            ....:               'M': ('C', 'A', 'B', 'D')}
+            sage: reviewr_pref = {'A': ('L', 'J', 'K', 'M'),
+            ....:                 'B': ('J', 'M', 'L', 'K'),
+            ....:                 'C': ('M', 'K', 'L', 'J'),
+            ....:                 'D': ('M', 'K', 'J', 'L')}
+            sage: m = MatchingGame([suitr_pref, reviewr_pref])
+            sage: m.solve(invert=True)
+            {'A': 'L', 'B': 'J', 'C': 'M', 'D': 'K'}
+
+            sage: suitr_pref = {1: (-1,)}
+            sage: reviewr_pref = {-1: (1,)}
+            sage: m = MatchingGame([suitr_pref, reviewr_pref])
+            sage: m.solve()
+            {1: -1}
+
+            sage: suitr_pref = {}
+            sage: reviewr_pref = {}
+            sage: m = MatchingGame([suitr_pref, reviewr_pref])
+            sage: m.solve()
+            {}
+
+        TESTS:
+
+        This also works for players who are both a suitor and reviewer::
+
+            sage: suit = {0: (3,4,2), 1: (3,4,2), 2: (2,3,4)}
+            sage: revr = {2: (2,0,1), 3: (0,1,2), 4: (1,0,2)}
+            sage: g = MatchingGame(suit, revr)
+            sage: g.solve()
+            {0: 3, 1: 4, 2: 2}
+        """
+        self._is_complete()
+
+        for s in self._suitors:
+            s.partner = None
+        for r in self._reviewers:
+            r.partner = None
+
+        if invert:
+            reviewers = deepcopy(self._suitors)
+            suitors = deepcopy(self._reviewers)
+        else:
+            suitors = deepcopy(self._suitors)
+            reviewers = deepcopy(self._reviewers)
+
+        while any(s.partner is None for s in suitors):
+            s = None
+            for x in suitors:
+                if x.partner is None:
+                    s = x
+                    break
+            r = next((x for x in reviewers if x == s.pref[0]), None)
+            if r.partner is None:
+                r.partner = s
+                s.partner = r
+            elif r.pref.index(s._name) < r.pref.index(r.partner._name):
+                r.partner.partner = None
+                r.partner = s
+                s.partner = r
+            else:
+                s.pref = s.pref[1:]
+
+        if invert:
+            suitors, reviewers = reviewers, suitors
+
+        for i, j in zip(self._suitors, suitors):
+            i.partner = j.partner
+        for i, j in zip(self._reviewers, reviewers):
+            i.partner = j.partner
+
+        self._sol_dict = {}
+        for s in self._suitors:
+            self._sol_dict[s] = [s.partner]
+        for r in self._reviewers:
+            self._sol_dict[r] = [r.partner]
+
+        if invert:
+            return {key: self._sol_dict[key][0] for key in self._reviewers}
+        return {key: self._sol_dict[key][0] for key in self._suitors}
+
+
+class Player:
+    r"""
+    A class to act as a data holder for the players used of the
+    matching games.
+
+    These instances are used when initiating players and to keep track of
+    whether or not partners have a preference.
+    """
+    def __init__(self, name):
+        r"""
+        TESTS::
+
+            sage: from sage.game_theory.matching_game import Player
+            sage: p = Player(10)
+            sage: p
+            10
+            sage: p.pref
+            []
+            sage: p.partner is None
+            True
+        """
+        self._name = name
+        self.pref = []
+        self.partner = None
+
+    def __hash__(self):
+        r"""
+        TESTS::
+
+            sage: from sage.game_theory.matching_game import Player
+            sage: p = Player(10)
+            sage: d = {p : (1, 2, 3)}
+            sage: d
+            {10: (1, 2, 3)}
+        """
+        return hash(self._name)
+
+    def __repr__(self):
+        r"""
+        TESTS::
+
+            sage: from sage.game_theory.matching_game import Player
+            sage: p = Player(10)
+            sage: p
+            10
+
+            sage: p = Player('Karl')
+            sage: p
+            'Karl'
+        """
+        return repr(self._name)
+
+    def __eq__(self, other):
+        r"""
+
+        Tests equality of two players. This only checks the name of the player
+        and not their preferences.
+
+        TESTS::
+
+            sage: from sage.game_theory.matching_game import Player
+            sage: p = Player(10)
+            sage: q = Player('Karl')
+            sage: p == q
+            False
+
+            sage: from sage.game_theory.matching_game import Player
+            sage: p = Player(10)
+            sage: q = Player(10)
+            sage: p == q
+            True
+
+            sage: from sage.game_theory.matching_game import Player
+            sage: p = Player(10)
+            sage: q = Player(10)
+            sage: p.pref = (1, 2)
+            sage: p.pref = (2, 1)
+            sage: p == q
+            True
+        """
+        if isinstance(other, Player):
+            return self._name == other._name
+        return self._name == other
+
+    def __lt__(self, other):
+        """
+        Test less than inequality of two players. Allows for players to be
+        sorted on their names.
+
+        TESTS::
+
+            sage: from sage.game_theory.matching_game import Player
+            sage: p = Player('A')
+            sage: q = Player('B')
+            sage: p < q
+            True
+            sage: q < p
+            False
+
+            sage: p = Player(0)
+            sage: q = Player(1)
+            sage: p < q
+            True
+            sage: q < p
+            False
+        """
+        if isinstance(other, Player):
+            return self._name < other._name
+        return self._name < other
+
+    def __gt__(self, other):
+        """
+        Test greater than inequality of two players. Allows for players to be
+        sorted on their names.
+
+        TESTS::
+
+            sage: from sage.game_theory.matching_game import Player
+            sage: p = Player('A')
+            sage: q = Player('B')
+            sage: p > q
+            False
+            sage: q > p
+            True
+
+            sage: p = Player(0)
+            sage: q = Player(1)
+            sage: p > q
+            False
+            sage: q > p
+            True
+        """
+        if isinstance(other, Player):
+            return self._name > other._name
+        return self._name > other
+
+    def __ge__(self, other):
+        """
+        Test greater than or equal inequality of two players. Allows for
+        players to be sorted on their names.
+
+        TESTS::
+
+            sage: from sage.game_theory.matching_game import Player
+            sage: p = Player('A')
+            sage: q = Player('B')
+            sage: p >= q
+            False
+            sage: q >= p
+            True
+
+            sage: p = Player(0)
+            sage: q = Player(1)
+            sage: p >= q
+            False
+            sage: q >= p
+            True
+
+            sage: p = Player(0)
+            sage: q = Player(0)
+            sage: p >= q
+            True
+
+            sage: p = Player('C')
+            sage: q = Player('C')
+            sage: p >= q
+            True
+        """
+        if isinstance(other, Player):
+            return self._name >= other._name
+        return self._name >= other
+
+    def __le__(self, other):
+        """
+        Test less than or equal inequality of two players. Allows for
+        players to be sorted on their names.
+
+        TESTS::
+
+            sage: from sage.game_theory.matching_game import Player
+            sage: p = Player('A')
+            sage: q = Player('B')
+            sage: p <= q
+            True
+            sage: q <= p
+            False
+
+            sage: p = Player(0)
+            sage: q = Player(1)
+            sage: p <= q
+            True
+            sage: q <= p
+            False
+
+            sage: p = Player(0)
+            sage: q = Player(0)
+            sage: p <= q
+            True
+
+            sage: p = Player('C')
+            sage: q = Player('C')
+            sage: p <= q
+            True
+        """
+        if isinstance(other, Player):
+            return self._name <= other._name
+        return self._name <= other
+
+    def __ne__(self, other):
+        """
+        Test inequality of two players. Allows for
+        players to be sorted on their names.
+
+        TESTS::
+
+            sage: from sage.game_theory.matching_game import Player
+            sage: p = Player('A')
+            sage: q = Player('B')
+            sage: p != q
+            True
+
+            sage: p = Player(0)
+            sage: q = Player(1)
+            sage: p != q
+            True
+
+            sage: p = Player(0)
+            sage: q = Player(0)
+            sage: p != q
+            False
+
+            sage: p = Player('C')
+            sage: q = Player('C')
+            sage: p != q
+            False
+        """
+        if isinstance(other, Player):
+            return self._name != other._name
+        return self._name != other