Aluxian / StableMarriageProblem / 0.1.0

In mathematics, economics, and computer science, the stable marriage problem (SMP) is the problem of finding a stable matching between two sets of elements given a set of preferences for each element. A matching is a mapping from the elements of one set to the elements of the other set. A matching is stable whenever it is not the case that both:

  • some given element A of the first matched set prefers some given element B of the second matched set over the element to which A is already matched, and
  • B also prefers A over the element to which B is already matched

In other words, a matching is stable when there does not exist any alternative pairing (A, B) in which both A and B are individually better off than they would be with the element to which they are currently matched.

The stable marriage problem is commonly stated as:

Given n men and n women, where each person has ranked all members of the opposite sex with a unique number between 1 and n in order of preference, marry the men and women together such that there are no two people of opposite sex who would both rather have each other than their current partners. If there are no such people, all the marriages are "stable". (It is assumed that the participants are binary gendered and that marriages are not same-sex).


Input should be an object of class Map<String,List<String>>, in which each key is a node name, and its value is an ordered list of names denoting preferences (the first element being the highest preference). The structure of the problem implies that the input contain 2n elements, n of which are “male” and include each of the n “female” nodes in their preference list, and vice versa. Output Map<String,String> where each key is paired with its value.

Note that the algorithm is not symmetric in its optimality: as implemented,

  • it is optimal for the "suitors", but the stable, suitor-optimal solution
  • may or may not be optimal for the "reviewers".