Matching: A Python library for solving matching games

Matching games allow for the allocation of resources and partnerships in a fair way. Typically, a matching game is defined by two sets of players that each have preferences over at least some of the elements of the other set. The objective of the game is then to find a mapping between the sets of players in which everyone is happy enough with their match. One of the most ubiquitous matching games is the Stable Marriage Problem (SM). In SM, there are two distinct player sets of size N : a set of suitors S and a set of reviewers R. Each suitor must strictly rank all of the reviewers, and vice versa. This arrangement of suitors, reviewers, and their preferences is called a game of size N (Gale & Shapley, 1962). In SM, a matching is any bijection M between S and R, and it is considered to be stable (i.e. no one has a reason to modify their current match) if it contains no blocking pairs. A blocking pair is defined as any pair (s, r) ∈ S × R that would rather be matched to one another than their current match. This definition differs between matching games but the spirit is the same in that a pair blocks a matching if their envy is mutually rational. Irrational envy would be where one player wishes to be matched to another over their current match but the other player does not (or cannot) reciprocate. Consider the game of size three shown in Figure 1 as an edgeless graph with suitors on the left and reviewers on the right. Beside each vertex is the name of the player and their associated ranking of the complementary set’s elements.


Summary
Matching games allow for the allocation of resources and partnerships in a fair way. Typically, a matching game is defined by two sets of players that each have preferences over at least some of the elements of the other set. The objective of the game is then to find a mapping between the sets of players in which everyone is happy enough with their match.
One of the most ubiquitous matching games is the Stable Marriage Problem (SM). In SM, there are two distinct player sets of size N : a set of suitors S and a set of reviewers R. Each suitor must strictly rank all of the reviewers, and vice versa. This arrangement of suitors, reviewers, and their preferences is called a game of size N (Gale & Shapley, 1962).
In SM, a matching is any bijection M between S and R, and it is considered to be stable (i.e. no one has a reason to modify their current match) if it contains no blocking pairs. A blocking pair is defined as any pair (s, r) ∈ S × R that would rather be matched to one another than their current match. This definition differs between matching games but the spirit is the same in that a pair blocks a matching if their envy is mutually rational. Irrational envy would be where one player wishes to be matched to another over their current match but the other player does not (or cannot) reciprocate.
Consider the game of size three shown in Figure 1 as an edgeless graph with suitors on the left and reviewers on the right. Beside each vertex is the name of the player and their associated ranking of the complementary set's elements.  Gale & Shapley (1962) presented an algorithm for finding a unique, stable and suitor-optimal matching to any instance of SM. The matching this algorithm produces is shown in Figure 2. While it is relatively easy to find solutions to games like this with pen and paper, instances of other matching games tend to have more players than this and require the use of software to be solved in reasonable time.

Statement of Need
Matching games have applications in many fields where relationships between rational agents must be managed. Some example applications include: being able to inform on healthcare finance policy (Agarwal, 2017); helping to reduce the complexity of automated wireless communication networks (Bayat, Li, Song, & Han, 2016); and education infrastructure (Chiarandini, Fagerberg, & Gualandi, 2019). Thus, having access to software implementations of algorithms that are able to solve such games is essential.
The only current adversary to Matching is MatchingR (Tilly & Janetos, 2018). MatchingR is a package written in C++ with an R interface and its content overlaps well with that of Matching. However, the lack of a Python interface makes it less relevant to researchers and other users as Python's popularity grows both in academia and industry.
MatchingR implements all of these except SA but also implements an algorithm for the indivisible goods trading problem.
In addition to this, Matching has been developed to a high degree of best practice in research software development (Jiménez et al., 2017), and is thoroughly documented: matching.readthedocs.io. The documentation has been written to maximise its effect as a resource for learning about matching games as well as for the software itself. Furthermore, the software is automatically tested using example, integration, and property-based unit tests with 100% coverage. The current version of Matching has also been archived on Zenodo (The Matching library developers, 2020); as has all of the data used in the documentation tutorials.
Matching has been designed to be used as a research tool and to aid in the education of game theory. It is currently being used by a number of undergraduate students and postgraduate researchers in universities around the world, and has been used to massively streamline the final year project allocation process for one of the largest schools at Cardiff University (as an instance of SA). Furthermore, Matching proved to be instrumental in the practical implementation of a novel initialisation method for a categoric clustering algorithm (Wilde, Knight, & Gillard, 2020). With Matching being written in Python, this tool is widely accessible by programmers and non-programmers alike as a readable, portable, and reproducible piece of software. Tilly, J., & Janetos, N. (2018). MatchingR: Matching algorithms in R and C++. GitHub repository. GitHub. Retrieved from https://github.com/jtilly/matchingR Wilde, H., Knight, V., & Gillard, J. (2020). A novel initialisation based on hospital-resident assignment for the k-modes algorithm. Retrieved from http://arxiv.org/abs/2002.02701