stable-matching 0.1.0

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

@@ -0,0 +1,64 @@
+# 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 Marriage
+    class PreferenceTable < StableMatching::PreferenceTable
+      attr_accessor :partner_table
+
+      def self.initialize_pair(raw_preference_table_a, raw_preference_table_b)
+        table_a = new(raw_preference_table_a)
+        table_b = new(raw_preference_table_b)
+
+        table_a.partner_table = table_b
+        table_b.partner_table = table_a
+
+        [table_a, table_b]
+      end
+
+      def initialize(raw_preference_table)
+        members = initialize_members_from(raw_preference_table)
+
+        @raw_preference_table = raw_preference_table
+
+        # Avoid calling the parent initializer, but we still need to set
+        # the delegated object. Thankfully SimpleDelegator offers a method
+        # to set this directly
+        __setobj__(members)
+      end
+
+      def partner_table=(partner_table)
+        @partner_table = partner_table
+
+        @raw_preference_table.each do |name, raw_preference_list|
+          generate_preference_list(
+            find_member_by_name(name),
+            raw_preference_list,
+            partner_table
+          )
+        end
+      end
+
+      def unmatched
+        have_accepted = partner_table.members.select(&:accepted_proposal?)
+        have_been_accepted = have_accepted.map(&:current_proposer)
+
+        members - have_been_accepted
+      end
+
+      private
+
+      def generate_preference_list(member, raw_preference_list, partner_table)
+        member_list = raw_preference_list.map do |name|
+          partner_table.name_to_member_mapping[name]
+        end
+
+        member.preference_list = PreferenceList.new(member_list)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+require_relative "../validator"
+
+class StableMatching
+  class Marriage
+    class Validator < StableMatching::Validator
+      def self.validate_pair!(alpha_preferences, beta_preferences)
+        new(alpha_preferences, beta_preferences).validate!
+        new(beta_preferences, alpha_preferences).validate!
+      end
+
+      def initialize(preference_table, partner_table)
+        @preference_table = preference_table
+        @partner_table = partner_table
+      end
+
+      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 !symmetrical?            then handle_not_symmetrical
+        end
+
+        raise ::StableMatching::InvalidPreferences, @error if @error
+      end
+
+      private
+
+      def symmetrical?
+        @preference_table.each do |name, preference_list|
+          expected_members = @partner_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
+    end
+  end
+end

data/lib/stable-matching/member.rb

@@ -0,0 +1,82 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+class StableMatching
+  class Member
+    attr_reader :name, :received_proposals_from, :accepted_proposal_from
+    attr_writer :preference_list
+
+    def initialize(name)
+      @name = name
+      @accepted_proposal_from = nil
+    end
+
+    def to_s
+      name
+    end
+
+    def preference_list
+      if @preference_list.nil?
+        raise "preference list not set for member: #{name}"
+      end
+
+      @preference_list
+    end
+
+    def current_proposer
+      @accepted_proposal_from
+    end
+
+    def current_acceptor
+      preference_list.detect do |member|
+        member.accepted_proposal_from == self
+      end
+    end
+
+    def accepted_proposal?
+      !current_proposer.nil?
+    end
+
+    def would_prefer?(new_proposer)
+      return true unless accepted_proposal?
+      preference_of(new_proposer) > preference_of(current_proposer)
+    end
+
+    def accept_proposal_from!(member)
+      @accepted_proposal_from = member
+    end
+
+    def reject!(member)
+      @accepted_proposal_from = nil if current_proposer == member
+
+      # Delete each member from the other member's preference list
+      preference_list.delete(member)
+      member.preference_list.delete(self)
+    end
+
+    def first_preference
+      preference_list.first
+    end
+
+    def second_preference
+      preference_list[1]
+    end
+
+    def last_preference
+      preference_list.last
+    end
+
+    private
+
+    def preference_of(member)
+      index = preference_list.index(member)
+      return if index.nil?
+
+      # Return the preference as the inverse of the index so a smaller index
+      # has a greater preference
+      preference_list.size - index
+    end
+  end
+end

data/lib/stable-matching/phase_runner.rb

@@ -0,0 +1,44 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+class StableMatching
+  class PhaseRunner
+    private
+
+    def simulate_proposal(proposer, proposed)
+      @logger.debug("'#{proposer.name}' proposes to '#{proposed.name}'")
+
+      case
+      when !proposed.accepted_proposal?
+        accept(proposer, proposed)
+      when proposed.would_prefer?(proposer)
+        accept_better_proposal(proposer, proposed)
+      else
+        reject(proposer, proposed)
+      end
+    end
+
+    def accept(proposer, proposed)
+      @logger.debug("'#{proposed.name}' accepts '#{proposer.name}'")
+
+      proposed.accept_proposal_from!(proposer)
+    end
+
+    def accept_better_proposal(proposer, proposed)
+      @logger.debug(
+        "'#{proposed.name}' accepts '#{proposer.name}', "\
+        "rejects '#{proposed.current_proposer.name}'"
+      )
+
+      proposed.reject!(proposed.current_proposer)
+      proposed.accept_proposal_from!(proposer)
+    end
+
+    def reject(proposer, proposed)
+      @logger.debug("'#{proposed.name}' rejects '#{proposer.name}'")
+      proposed.reject!(proposer)
+    end
+  end
+end

data/lib/stable-matching/preference_list.rb

@@ -0,0 +1,18 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+require "delegate"
+
+class StableMatching
+  class PreferenceList < SimpleDelegator
+    def initialize(preference_list)
+      super(preference_list)
+    end
+
+    def to_s
+      map(&:name).to_s
+    end
+  end
+end

data/lib/stable-matching/preference_table.rb

@@ -0,0 +1,80 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+require "delegate"
+require "pp"
+
+require_relative "member"
+require_relative "preference_list"
+
+class StableMatching
+  class PreferenceTable < SimpleDelegator
+    attr_reader :name_to_member_mapping
+
+    def initialize(raw_preference_table)
+      members = initialize_members_from(raw_preference_table)
+
+      raw_preference_table.each do |name, raw_preference_list|
+        generate_preference_list(
+          find_member_by_name(name),
+          raw_preference_list
+        )
+      end
+
+      super(members)
+    end
+
+    def to_s
+      members.map { |m| "#{m.name} => #{m.preference_list}" }.join(", ")
+    end
+
+    def print
+      table = {}
+      members.each { |m| table[m.name] = m.preference_list.map(&:name) }
+
+      pp(table)
+    end
+
+    def unmatched
+      have_accepted = members.select(&:accepted_proposal?)
+      have_been_accepted = have_accepted.map(&:current_proposer)
+
+      members - have_been_accepted
+    end
+
+    def complete?
+      # Does every member have only one preference remaining?
+      counts = members.map { |member| member.preference_list.count }
+      counts.uniq == [1]
+    end
+
+    def members
+      __getobj__
+    end
+
+    private
+
+    def find_member_by_name(name)
+      @name_to_member_mapping[name]
+    end
+
+    def initialize_members_from(raw_preference_table)
+      @name_to_member_mapping = {}
+
+      raw_preference_table.keys.each do |name|
+        @name_to_member_mapping[name] = Member.new(name)
+      end
+
+      @name_to_member_mapping.values
+    end
+
+    def generate_preference_list(member, raw_preference_list)
+      member_list =
+        raw_preference_list.map { |name| find_member_by_name(name) }
+
+      member.preference_list = PreferenceList.new(member_list)
+    end
+  end
+end

data/lib/stable-matching/roommate.rb

@@ -0,0 +1,124 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+require_relative "stable_matching"
+require_relative "logging_helper"
+
+require_relative "roommate/validator"
+require_relative "roommate/preference_table"
+require_relative "roommate/phase_i_runner"
+require_relative "roommate/phase_ii_runner"
+require_relative "roommate/phase_iii_runner"
+
+class StableMatching
+  # Provides a solution to the Stable Roommate problem by implementing
+  # the Irving algorithm
+  #
+  # Takes as input the preferences of each member and produces a mathematically
+  # optimal matching/pairing between members.
+  #
+  # Example Input:
+  #
+  #    preferences = {
+  #      "A" => ["B", "D", "C"],
+  #      "B" => ["D", "A", "C"],
+  #      "C" => ["D", "A", "B"],
+  #      "D" => ["C", "A", "B"]
+  #    }
+  #
+  # Example Output:
+  #
+  #    {"A"=>"B", "B"=>"A", "C"=>"D", "D"=>"C"}
+  class Roommate
+    include StableMatching::LoggingHelper
+
+    # Runs the algorithm with the specified inputs.
+    #
+    # This is a class level shortcut to initialize a new
+    # +StableMatching::Roommate+ instance and calls +solve!+ on it.
+    #
+    # <b>Inputs:</b>
+    #
+    # <tt>preference_table</tt>::
+    #     A +Hash+ of +Array+ values specifying the preferences of the group
+    #
+    # <b>Output:</b>
+    # A +Hash+ mapping members to other members.
+    def self.solve!(preference_table)
+      new(preference_table).solve!
+    end
+
+    # Initializes a `StableMatching::Roommate` object.
+    #
+    #
+    # <b>Inputs:</b>
+    #
+    # <tt>preference_table</tt>::
+    #     A +Hash+ of +Array+ values specifying the preferences of the group.
+    #     +Array+ can contain +String+ or +Integer+ entries.
+    # <tt>opts[:logger]</tt>::
+    #     +Logger+ instance to use for logging
+    #
+    # <b>Output:</b>
+    #
+    # +StableMatching::Roommate+ instance
+    def initialize(preference_table, opts = {})
+      @orig_preference_table = preference_table
+      set_logger(opts)
+    end
+
+    # Runs the algorithm on the preference_table.
+    # Also validates the preference_table and raises an error if invalid.
+    #
+    # The roommate algorithm is not guranteed to find a solution in all cases
+    # and will raise an error if a solution is mathematically unstable (does
+    # not exist).
+    #
+    # <b>Output:</b>
+    #
+    # A +Hash+ mapping members to other members.
+    #
+    # <b>Raises:</b>
+    #
+    # <tt>StableMatching::InvalidPreferences</tt>::
+    #     When preference_table is of invalid format
+    # <tt>StableMatching::NoStableSolutionError</tt>::
+    #     When no mathematically stable solution can be found
+    def solve!
+      validate!
+
+      @logger.debug("Running Phase I")
+      PhaseIRunner.new(preference_table, logger: @logger).run
+
+      @logger.debug("Running Phase II")
+      PhaseIIRunner.new(preference_table, logger: @logger).run
+
+      @logger.debug("Running Phase III")
+      PhaseIIIRunner.new(preference_table, logger: @logger).run
+
+      build_solution
+    end
+
+    private
+
+    def validate!
+      Validator.validate!(@orig_preference_table)
+    end
+
+    def preference_table
+      @preference_table ||= PreferenceTable.new(@orig_preference_table)
+    end
+
+    def build_solution
+      solution = {}
+
+      preference_table.members.each do |member|
+        solution[member.name] = member.first_preference.name
+      end
+
+      solution
+    end
+  end
+end