stable-matching 0.1.0

data/lib/stable-matching/roommate/phase_i_runner.rb

@@ -0,0 +1,111 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+#
+# Implements Phase I of Irving's (1985) Stable Roommates algorithm.
+#
+# See:
+# - https://en.wikipedia.org/wiki/Stable_roommates_problem
+# - https://www.youtube.com/watch?v=9Lo7TFAkohEaccepted_proposal?
+#
+# In this round each member who has not had their proposal accepted "proposes"
+# to their top remaining preference
+#
+# Each recipient of a proposal can take one of 3 actions -
+#
+# 1. The recipient has not received a previous proposal and immediately accepts
+#
+# 2. The recipient prefers this new proposal over an existing one.
+#    The recipient "rejects" it's initial proposl and accepts this new one
+#
+# 3. The recipient prefers the existing proposal over the new one.
+#    The recipient "rejects" the new proposal
+#
+# In the above situations, every rejection is mutual - if `i` removes `j` from
+# its preference list, then `j` must also remove `i` from its list
+#
+# This cycle continues until one of two things happens
+#
+# A. Every member has had their proposal accepted
+#     -> Move on to Phase II
+# B. At least one member has exhausted their preference list
+#     -> No solution exists
+#
+#
+# === EXAMPLE
+#
+# Take the following preference lists
+#
+#   A => [B, D, F, C, E],
+#   B => [D, E, F, A, C],
+#   C => [D, E, F, A, B],
+#   D => [F, C, A, E, B],
+#   E => [F, C, D, B, A],
+#   F => [A, B, D, C, E]
+#
+# We always start with the first unmatched user. Initially this is "A".
+# The sequence of events are -
+#
+#   'A' proposes to 'B'
+#   'B' accepts 'A'
+#   'B' proposes to 'D'
+#   'D' accepts 'B'
+#   'C' proposes to 'D'
+#   'D' accepts 'C', rejects 'B'
+#   'B' proposes to 'E'
+#   'E' accepts 'B'
+#   'D' proposes to 'F'
+#   'F' accepts 'D'
+#   'E' proposes to 'F'
+#   'F' rejects
+#   'E' proposes to 'C'
+#   'C' accepts 'E'
+#   'F' proposes to 'A'
+#   'A' accepts 'F'
+#
+# The result of this phase is shown below.
+# A "-" indicates a proposal made and a "+" indicates a proposal accepted.
+# Rejected members are removed.
+#
+#   A => [-B, D, +F, C, E],
+#   B => [-E, F, +A, C],
+#   C => [-D, +E, F, A, B],
+#   D => [-F, +C, A, E],
+#   E => [-C, D, +B, A],
+#   F => [-A, B, +D, C]
+
+require_relative "../phase_runner"
+
+class StableMatching
+  class Roommate
+    class PhaseIRunner < StableMatching::PhaseRunner
+      def initialize(preference_table, opts = {})
+        @preference_table = preference_table
+        @logger = opts.fetch(:logger)
+      end
+
+      def run
+        while @preference_table.unmatched.any?
+          ensure_table_is_stable!
+
+          member = @preference_table.unmatched.first
+          top_choice = member.first_preference
+
+          simulate_proposal(member, top_choice)
+        end
+
+        # Check once more since final iteration may have left the table unstable
+        ensure_table_is_stable!
+      end
+
+      private
+
+      def ensure_table_is_stable!
+        return true if @preference_table.stable?
+        raise StableMatching::NoStableSolutionError, "No stable match found!"
+      end
+    end
+  end
+end

data/lib/stable-matching/roommate/phase_ii_runner.rb

@@ -0,0 +1,105 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+# Implements Phase II of Irving's (1985) Stable Roommates algorithm.
+#
+# See:
+# - https://en.wikipedia.org/wiki/Stable_roommates_problem
+# - https://www.youtube.com/watch?v=9Lo7TFAkohEaccepted_proposal?
+#
+# In this phase, each member that has accepted a proposal will remove those they
+# prefer less than their current proposer.
+#
+# At the end of one iteration, one of two states are possible -
+#
+#   A. At least one member has exhausted their preference list
+#       -> No solution exists
+#
+#   B. Some members have multiple preferences remaining
+#       -> Proceed to Phase III
+#
+#   C. All members have one preference remaining
+#       -> Solution has been found, no need to run Phase III
+#
+#
+# NOTE: For the ease of implementation, step (C) is implemented as the first
+# check in Phase III, although it is logically part of this step.
+#
+#
+# === EXAMPLE
+#
+# Assume the output of Phase I is
+#
+#   A => [-B, D, +F, C, E],
+#   B => [-E, F, +A, C],
+#   C => [-D, +E, F, A, B],
+#   D => [-F, +C, A, E],
+#   E => [-C, D, +B, A],
+#   F => [-A, B, +D, C]
+#
+# Where a "-" indicates a proposal made and a "+" indicates a proposal accepted.
+#
+# Rejections for Phase II would occur as follows. Note that all rejections are
+# mutual - if `i` removes `j` from its preference list, then `j` must also
+# remove `i` from its list
+#
+#   A accepted by B. B rejecting members less preferred than A: ["C"]
+#   B accepted by E. E rejecting members less preferred than B: ["A"]
+#   C accepted by D. D rejecting members less preferred than C: ["A", "E"]
+#   D accepted by F. F rejecting members less preferred than D: ["C"]
+#   E accepted by C. C rejecting members less preferred than E: ["A"]
+#   F accepted by A. A rejecting members less preferred than F: []
+#
+# The output of this phase is a further reduced table is as follows
+#
+#   A => [B, F],
+#   B => [E, F, A],
+#   C => [D, E],
+#   D => [F, C],
+#   E => [C, B],
+#   F => [A, B, D]
+#
+# Since at least one member has multiple preferences remaining, we proceed to
+# Phase III
+#
+
+require_relative "../phase_runner"
+
+class StableMatching
+  class Roommate
+    class PhaseIIRunner < StableMatching::PhaseRunner
+      def initialize(preference_table, opts = {})
+        @preference_table = preference_table
+        @logger = opts.fetch(:logger)
+      end
+
+      def run
+        @preference_table.members.each do |proposer|
+          acceptor, rejections =
+            determine_acceptor_and_their_rejections(proposer)
+
+          @logger.debug(
+            "#{proposer.name} accepted by #{acceptor.name}. "\
+            "#{acceptor.name} rejecting members less preferred than "\
+            "#{proposer.name}: #{rejections.map(&:name)}"
+          )
+
+          rejections.each { |rejected| acceptor.reject!(rejected) }
+        end
+      end
+
+      private
+
+      def determine_acceptor_and_their_rejections(proposer)
+        acceptor = proposer.current_acceptor
+        current_proposer_index = acceptor.preference_list.index(proposer)
+
+        rejections = acceptor.preference_list[current_proposer_index + 1..-1]
+
+        [acceptor, rejections]
+      end
+    end
+  end
+end

data/lib/stable-matching/roommate/phase_iii_runner.rb

@@ -0,0 +1,159 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+# Implements Phase II of Irving's (1985) Stable Roommates algorithm.
+#
+# See:
+# - https://en.wikipedia.org/wiki/Stable_roommates_problem
+# - https://www.youtube.com/watch?v=9Lo7TFAkohEaccepted_proposal?
+#
+# In this last phase we attempt to find any preference cycles and reject them.
+#
+# This is done by building a pair of members (Xi, Yi) as follows
+#
+#   - Xi is the first member with at least 2 preferences
+#   - Yi is null
+#   - Yi+1 is the 2nd preference of Xi
+#   - Xi+1 is the last preference of Yi+1
+#
+# Continue calculating pairs (Xi, Yi) until Xi repeats values. At this point a
+# cycle has been found.
+#
+# Mutually reject every pair (Xi, Yi)
+#
+# After this one of 3 possiblities exists -
+#
+#   A. At least one member has exhausted their preference list
+#       -> No solution exists
+#
+#   B. Some members have multiple preferences remaining
+#       -> Repeat the above process to eliminate further cycles
+#
+#   C. All members have one preference remaining
+#       -> Solution has been found
+#
+# === EXAMPLE
+#
+# Assume the reduced output of Phase II is
+#
+#   A => [B, F],
+#   B => [E, F, A],
+#   C => [D, E],
+#   D => [F, C],
+#   E => [C, B],
+#   F => [A, B, D]
+#
+# Start with "A" since it is the first member with at least two preferences.
+#
+# Build (Xi, Yi) pairs as follows
+#
+#   i      1   2   3   4
+#   -----+---+---+---+----
+#   x:   | A | D | E | A
+#   y:   | - | F | C | B
+#
+# Where -
+#
+#   'F' is the 2nd preference of 'A'
+#   'D' is the last preference of 'F'
+#   'C' is the 2nd preference of 'D'
+#   etc...
+#
+# As soon as we see "A" again, we stop since we have found a cycle.
+#
+# Now we will mutually reject the following pairs, as definied by the inner
+# pairings
+#
+#   - (D, F)
+#   - (E, C)
+#   - (A, B)
+#
+# At this point, no preference list is exhausted and some have more than one
+# preference remaining. We need to find and eliminate more preference cycles.
+#
+#   i      1   2
+#   -----+---+---
+#   x:   | B | B
+#   y:   | - | F
+#
+# Now we will mutually reject
+#
+#   - (F, B)
+#
+# This gives us the stable solution below, since each roommate has exactly one
+# preference remaining
+#
+#   A => [F],
+#   B => [E],
+#   C => [D],
+#   D => [C],
+#   E => [B],
+#   F => [A]
+
+require_relative "../phase_runner"
+
+class StableMatching
+  class Roommate
+    class PhaseIIIRunner < StableMatching::PhaseRunner
+      def initialize(preference_table, opts = {})
+        @preference_table = preference_table
+        @logger = opts.fetch(:logger)
+      end
+
+      def run
+        # The output of previous phase may have resulted in a complete
+        # table, in which case this step doesn't need to be run
+        return @preference_table if @preference_table.complete?
+
+        while table_is_stable? && !@preference_table.complete?
+          x = [@preference_table.members_with_multiple_preferences.first]
+          y = [nil]
+
+          until any_repeats?(x)
+            # require 'pry'; binding.pry if x.last.second_preference.nil?
+            y << x.last.second_preference
+            x << y.last.last_preference
+          end
+
+          detect_and_reject_cycles(x, y)
+        end
+      end
+
+      private
+
+      def any_repeats?(arr)
+        arr.uniq.count != arr.count
+      end
+
+      def detect_and_reject_cycles(x, y)
+        x, y = retrieve_cycle(x, y)
+
+        msg = "Found cycle: "
+        y.each_with_index { |_, i| msg << "(#{x[i].name}, #{y[i].name})" }
+        @logger.debug(msg)
+
+        x.each_with_index do |r1, i|
+          r2 = y[i]
+          @logger.debug("Mutually rejecting '#{r1.name}', '#{r2.name}'")
+          r2.reject!(r1)
+        end
+      end
+
+      def retrieve_cycle(x, y)
+        repeated_member = x.detect { |i| x.count(i) > 1 }
+
+        first_index = 1
+        last_index = x.count - x.reverse.index(repeated_member) - 1
+
+        [x[first_index..last_index], y[first_index..last_index]]
+      end
+
+      def table_is_stable?
+        return true if @preference_table.stable?
+        raise StableMatching::NoStableSolutionError, "No stable match found!"
+      end
+    end
+  end
+end

data/lib/stable-matching/roommate/preference_table.rb

@@ -0,0 +1,20 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+require_relative "../preference_table"
+
+class StableMatching
+  class Roommate
+    class PreferenceTable < StableMatching::PreferenceTable
+      def stable?
+        members.all? { |member| !member.preference_list.empty? }
+      end
+
+      def members_with_multiple_preferences
+        members.select { |member| member.preference_list.count > 1 }
+      end
+    end
+  end
+end

data/lib/stable-matching/roommate/validator.rb

@@ -0,0 +1,26 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+require_relative "../validator"
+
+class StableMatching
+  class Roommate
+    class Validator < StableMatching::Validator
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def validate!
+        case
+        when !hash_of_arrays?         then handle_not_hash_of_arrays
+        when empty?                   then handle_empty
+        when !strings_or_integers?    then handle_not_strings_or_integers
+        when !even_sized?             then handle_not_even_sized
+        when !symmetrical?            then handle_not_symmetrical
+        end
+
+        raise ::StableMatching::InvalidPreferences, @error if @error
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+    end
+  end
+end

data/lib/stable-matching/stable_matching.rb

@@ -0,0 +1,11 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+class StableMatching
+  class Error < StandardError; end
+
+  class NoStableSolutionError < Error; end
+  class InvalidPreferences < Error; end
+end

data/lib/stable-matching/validator.rb

@@ -0,0 +1,93 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+class StableMatching
+  class Validator
+    def self.validate!(preference_table)
+      new(preference_table).validate!
+    end
+
+    def initialize(preference_table)
+      @preference_table = preference_table
+    end
+
+    # @abstract Subclass is expected to implement #validate!
+    # @!method validate!
+    #    Validate the structure and content of the `preference_table`
+
+    private
+
+    def hash_of_arrays?
+      return false unless @preference_table.is_a?(Hash)
+      @preference_table.values.each { |p| return false unless p.is_a?(Array) }
+
+      true
+    end
+
+    def handle_not_hash_of_arrays
+      @error = "Expecting a preference table hash of arrays"
+    end
+
+    def empty?
+      return true if @preference_table.empty?
+
+      @preference_table.each_value.any?(&:empty?)
+    end
+
+    def handle_empty
+      @error = "Preferences table can not empty"
+    end
+
+    def strings_or_integers?
+      @preference_table.each do |key, array|
+        @member_klass ||= key.class
+
+        return false unless valid_member?(key)
+        array.each { |value| return false unless valid_member?(value) }
+      end
+
+      true
+    end
+
+    def handle_not_strings_or_integers
+      @error = "All keys must be String or Integer"
+    end
+
+    def even_sized?
+      @preference_table.keys.size.even?
+    end
+
+    def handle_not_even_sized
+      @error = "Preference table must have an even number of keys"
+    end
+
+    def symmetrical?
+      @preference_table.each do |name, preference_list|
+        expected_members = @preference_table.keys - [name]
+        actual_members = preference_list
+
+        next if expected_members.sort == actual_members.sort
+
+        @name = name
+        @extra = actual_members - expected_members
+        @missing = expected_members - actual_members
+        return false
+      end
+
+      true
+    end
+
+    def handle_not_symmetrical
+      @error = "Entry #{@name} has invalid preferences. "\
+        "The extra members are: #{@extra}. "\
+        "The missing members are: #{@missing}"
+    end
+
+    def valid_member?(member)
+      (member.is_a?(String) || member.is_a?(Integer)) &&
+        member.class == @member_klass
+    end
+  end
+end