stable-matching 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9f33d15fb7603874a410eac7e811c303aef3dec6
+  data.tar.gz: 32087ed764d51a24b8c791b8d68b933590388088
+SHA512:
+  metadata.gz: 5ec63ba206e500f249d7b69c4cde8d7938e3a0447332c8533b67d181760e9b03189d33bc70033c5887aa124fe3476af2c064e9e361d717591497a309fcc7edf0
+  data.tar.gz: f7b2ce792d35b420fad9bc2d8fc39b48a1db369bb0bb30763250944245dd5f75ad12b2f133ff6257a8c0478270333b3746633ea8c3464413d9c3a95ef9c7078a

data/.gitignore

@@ -0,0 +1,15 @@
+.DS_Store
+
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/spec/examples.txt
+
+# Custom
+TODO

data/.gitlab-ci.yml

@@ -0,0 +1,28 @@
+variables:
+  RUNNING_ON_CI_SERVER: 1
+
+cache:
+  key: "$CI_BUILD_REF_NAME"
+  paths:
+    - /cache
+
+before_script:
+  # System
+  - apt-get update -qq
+
+  # Ruby
+  - ruby -v
+  - which ruby
+
+  # Ruby Gems
+  - 'echo ''gem: --no-ri --no-rdoc'' > ~/.gemrc'
+  - gem install bundler
+  - bundle install --path=/cache --without production --jobs $(nproc) "${FLAGS[@]}"
+
+rspec:
+  script:
+    - bundle exec rspec --color --require spec_helper --format progress --no-profile
+
+rubocop:
+  script:
+    - bundle exec rubocop --display-cop-names

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--require spec_helper
+--format progress
+--no-profile

data/.rubocop.yml

@@ -0,0 +1,31 @@
+AllCops:
+  Exclude:
+    - "stable-matching.gemspec"
+    - "bin/*"
+Metrics/AbcSize:
+  Enabled: false
+Layout/DotPosition:
+  EnforcedStyle: leading
+Layout/MultilineOperationIndentation:
+  Enabled: true
+  EnforcedStyle: indented
+Style/BlockComments:
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+Style/EmptyCaseCondition:
+  Enabled: false
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+Metrics/BlockLength:
+  ExcludedMethods:
+    - context
+    - describe
+    - it
+    - feature
+    - shared_examples
+    - shared_examples_for
+    - namespace
+    - task
+    - proc
+    - draw

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2018 Abhishek Chandrasekhar
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,154 @@
+
+
+# Stable Matching
+
+![Stable Matching](https://gitlab.com/abhchand/stable-matching/raw/master/meta/logo.png)
+
+[![Build Status](https://gitlab.com/abhchand/stable-matching/badges/master/build.svg)](https://gitlab.com/abhchand/stable-matching/pipelines)
+
+A ruby implementation of various stable matching algorithms.
+
+# Background
+
+This gem provides ruby implementations of algorithms that solve the following matching problems:
+
+- [Stable Roommates Problem](https://en.wikipedia.org/wiki/Stable_roommates_problem)
+- [Stable Marriage Problem](https://en.wikipedia.org/wiki/Stable_marriage_problem)
+
+# Install
+
+In your Gemfile:
+
+```
+source "https://rubygems.org"
+
+...
+
+gem "stable-matching"
+```
+
+Then run:
+
+```
+bundle install
+```
+
+# Quick Start
+
+## Stable Roommates
+
+See or run `bin/stable-roommates-example` for an example usage.
+
+Specify an input of ordered preferences as a hash of arrays. Keys may be `String` or `Integer` and preference table must include an even number of members.
+
+``` ruby
+preference_table = {
+  1 => [3, 4, 2, 6, 5],
+  2 => [6, 5, 4, 1, 3],
+  3 => [2, 4, 5, 1, 6],
+  4 => [5, 2, 3, 6, 1],
+  5 => [3, 1, 2, 4, 6],
+  6 => [5, 1, 3, 4, 2]
+}
+
+StableRoommate.solve!(preference_table)
+#=> {1=>6, 2=>4, 3=>5, 4=>2, 5=>3, 6=>1}
+```
+
+The implementation of this algorithm is *not* guranteed to return a mathematically stable solution and may raise an error if no solution is found (see Errors below).
+
+## Stable Marriage
+
+See or run `bin/stable-marriage-example` for an example usage
+
+Specify an input of ordered preferences as a hash of arrays for two groups. Keys may be `String` or `Integer`
+
+```
+alpha_preferences = {
+  "A" => ["O", "M", "N", "L", "P"],
+  "B" => ["P", "N", "M", "L", "O"],
+  "C" => ["M", "P", "L", "O", "N"],
+  "D" => ["P", "M", "O", "N", "L"],
+  "E" => ["O", "L", "M", "N", "P"],
+}
+
+beta_preferences = {
+  "L" => ["D", "B", "E", "C", "A"],
+  "M" => ["B", "A", "D", "C", "E"],
+  "N" => ["A", "C", "E", "D", "B"],
+  "O" => ["D", "A", "C", "B", "E"],
+  "P" => ["B", "E", "A", "C", "D"],
+}
+
+puts StableMarriage.solve!(alpha_preferences, beta_preferences,)
+#=> {"A"=>"O", "B"=>"P", "C"=>"N", "D"=>"M", "E"=>"L", "L"=>"E", "M"=>"D", "N"=>"C", "O"=>"A", "P"=>"B"}
+```
+
+The implementation of this algorithm is always guranteed to return a mathematically stable solution.
+
+# Errors
+
+Your process should be prepared to handle the following errors when calling the stable matching library
+
+```
+StableMatching::Error
+  |- StableMatching::NoStableSolutionError
+  |- StableMatching::InvalidPreferences
+```
+
+# Logging
+
+You may optionally pass a logger that will output the progress of the algorithm.
+
+To utilize this option you'll have to instantiate an algorithm object yourself with a `:logger` option and then call `#solve!`.
+
+``` ruby
+logger = Logger.new(STDOUT)
+logger.level = Logger::DEBUG
+
+StableRoommate.new(preference_table, logger: logger).solve!
+```
+
+# Benchmark / Performance
+
+Below are some benchmarks for runtimes captured on a machine running OS X 10.11.5 (El Capitan) / 2.5 GHz Intel Core i7.
+
+You can run `bin/benchmark` on any machine to regenerate these benchmarks
+
+Note: Many combinatorics algorithms run in quadratic time (`O(n^2)`) and therfore performance degrades significantly when processing a large number of members.
+
+### Stable Roommates
+
+```
+  N  | Avg Runtime (sec)
+-----|------------------
+  10 |            0.103
+ 100 |            1.075
+ 250 |           17.372
+```
+
+### Stable Marriage
+
+```
+   N  | Avg Runtime (sec)
+------|------------------
+   10 |            0.004
+  100 |            0.053
+ 1000 |            0.334
+```
+
+# Issues
+
+Feel free to submit issues and enhancement requests.
+
+# Contributing
+
+All contributions to this project are welcome.
+
+Code changes follow the "fork-and-pull" Git workflow.
+
+ 1. **Fork** the repository
+ 2. **Clone** the project to your own machine
+ 3. **Commit** changes to your own branch
+ 4. **Push** your work back up to your fork
+ 5. Submit a **Pull request** so that your changes can be reviewed!

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/circle.yml

@@ -0,0 +1,3 @@
+dependencies:
+  pre:
+    - gem install bundler --pre

data/lib/stable-matching/logging_helper.rb

@@ -0,0 +1,16 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+require "logger"
+
+class StableMatching
+  module LoggingHelper
+    # rubocop:disable Style/AccessorMethodName
+    def set_logger(opts = {})
+      @logger = opts.key?(:logger) ? opts[:logger] : Logger.new(nil)
+    end
+    # rubocop:enable Style/AccessorMethodName
+  end
+end

data/lib/stable-matching/marriage.rb

@@ -0,0 +1,135 @@
+# 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 "marriage/validator"
+require_relative "marriage/preference_table"
+require_relative "marriage/phase_i_runner"
+
+class StableMatching
+  # Provides a solution to the Stable Marriage problem by implementing
+  # the Gale-Shapley algorithm
+  #
+  # Takes as input the preferences of two groups - alpha and beta - and
+  # produces a mathematically optimal matching/pairing between the two groups.
+  #
+  # Example Input:
+  #
+  #    alpha_preferences = {
+  #      "A" => ["M", "N", "L"],
+  #      "B" => ["N", "M", "L"],
+  #      "C" => ["M", "L", "N"],
+  #    }
+  #
+  #    beta_preferences = {
+  #      "L" => ["B", "C", "A"],
+  #      "M" => ["B", "A", "C"],
+  #      "N" => ["A", "C", "B"],
+  #    }
+  #
+  # Example Output:
+  #
+  #    {"A"=>"M", "B"=>"N", "C"=>"L", "L"=>"C", "M"=>"A", "N"=>"B"}
+  class Marriage
+    include StableMatching::LoggingHelper
+
+    # Runs the algorithm with the specified inputs.
+    #
+    # This is a class level shortcut to initialize a new
+    # +StableMatching::Marriage+ instance and calls +solve!+ on it.
+    #
+    # <b>Inputs:</b>
+    #
+    # <tt>alpha_preferences</tt>::
+    #     A +Hash+ of +Array+ values specifying the preferences of the alpha
+    #     group
+    # <tt>beta_preferences</tt>::
+    #     A +Hash+ of +Array+ values specifying the preferences of the beta
+    #     group
+    #
+    # <b>Output:</b>
+    # A +Hash+ mapping alpha members to beta and beta members to alpha members.
+    def self.solve!(alpha_preferences, beta_preferences)
+      new(alpha_preferences, beta_preferences).solve!
+    end
+
+    # Initializes a `StableMatching::Marriage` object.
+    #
+    #
+    # <b>Inputs:</b>
+    #
+    # <tt>alpha_preferences</tt>::
+    #     A +Hash+ of +Array+ values specifying the preferences of the alpha
+    #     group. +Array+ can contain +String+ or +Integer+ entries.
+    # <tt>beta_preferences</tt>::
+    #     A +Hash+ of +Array+ values specifying the preferences of the beta
+    #     group. +Array+ can contain +String+ or +Integer+ entries.
+    # <tt>opts[:logger]</tt>::
+    #     +Logger+ instance to use for logging
+    #
+    # <b>Output:</b>
+    #
+    # +StableMatching::Marriage+ instance
+    def initialize(alpha_preferences, beta_preferences, opts = {})
+      @orig_alpha_preferences = alpha_preferences
+      @orig_beta_preferences = beta_preferences
+
+      @alpha_preferences, @beta_preferences =
+        PreferenceTable.initialize_pair(alpha_preferences, beta_preferences)
+
+      set_logger(opts)
+    end
+
+    # Runs the algorithm on the alpha and beta preference sets.
+    # Also validates the preference sets and raises an error if invalid.
+    #
+    # <b>Output:</b>
+    #
+    # A +Hash+ mapping alpha members to beta and beta members to alpha members.
+    #
+    # <b>Raises:</b>
+    #
+    # <tt>StableMatching::InvalidPreferences</tt>::
+    #     When alpha or beta preference groups are of invalid format
+    def solve!
+      validate!
+
+      @logger.info("Running Phase I")
+      PhaseIRunner.new(alpha_preferences, beta_preferences, logger: @logger).run
+
+      build_solution
+    end
+
+    private
+
+    def validate!
+      Validator.validate_pair!(@orig_alpha_preferences, @orig_beta_preferences)
+    end
+
+    def alpha_preferences
+      @alpha_preferences ||= PreferenceTable.new(@orig_alpha_preferences)
+    end
+
+    def beta_preferences
+      @beta_preferences ||= PreferenceTable.new(@orig_beta_preferences)
+    end
+
+    def build_solution
+      solution = {}
+
+      @alpha_preferences.members.each do |partner|
+        solution[partner.name] = partner.current_acceptor.name
+      end
+
+      @beta_preferences.members.each do |partner|
+        solution[partner.name] = partner.current_proposer.name
+      end
+
+      solution
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# Provides a ruby implementation of several common matching algorithms
+#
+# Author::    Abhishek Chandrasekhar  (mailto:me@abhchand.me)
+# License::   MIT
+
+# Implements the Gale-Shapley (1962) algorithm.
+#
+# Calculates a stable match between two groups - alpha and beta - given their
+# individual preference lists for members of the other group
+#
+# See:
+#   https://en.wikipedia.org/wiki/Stable_marriage_problem#Solution
+#   https://www.youtube.com/watch?v=GsBf3fJFpSw
+#
+# 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
+#
+# Note: Rejections are mutual. If `i` removes `j` from their preference list,
+#       then `j` must also remove `i` from its list
+#
+# This cycle continues until every alpha/beta has a match.
+#
+# Mathematically, every participant is guranteed a match so this algorithm
+# always converges on a solution.
+#
+#
+# === EXAMPLE
+#
+# Take the following preference lists
+#
+# alpha preferences:
+#   A => [O, M, N, L, P]
+#   B => [P, N, M, L, O]
+#   C => [M, P, L, O, N]
+#   D => [P, M, O, N, L]
+#   E => [O, L, M, N, P]
+#
+# beta preferences:
+#   L => [D, B, E, C, A]
+#   M => [B, A, D, C, E]
+#   N => [A, C, E, D, B]
+#   O => [D, A, C, B, E]
+#   P => [B, E, A, C, D]
+#
+# We always start with the first unmatched user. Initially this is "A" (We only
+# cycle through alphas since they propose to the betas).
+# The sequence of events are -
+#
+#   'A' proposes to 'O'
+#   'O' accepts 'A'
+#   'B' proposes to 'P'
+#   'P' accepts 'B'
+#   'C' proposes to 'M'
+#   'M' accepts 'C'
+#   'D' proposes to 'P'
+#   'P' rejects 'D'
+#   'E' proposes to 'O'
+#   'O' rejects 'E'
+#   'D' proposes to 'M'
+#   'M' accepts 'D', rejects 'C'
+#   'E' proposes to 'L'
+#   'L' accepts 'E'
+#   'C' proposes to 'P'
+#   'P' rejects 'C'
+#   'C' proposes to 'L'
+#   'L' rejects 'C'
+#   'C' proposes to 'O'
+#   'O' rejects 'C'
+#   'C' proposes to 'N'
+#   'N' accepts 'C'
+#
+# At this point there are no alpha users left unmatched (and by definition, no
+# corresponding beta users left unmatched). All alpha members have had their
+# proposals accepted by a beta user.
+#
+# The resulting solution is
+#
+#   A => O
+#   B => P
+#   C => N
+#   D => M
+#   E => L
+#   L => E
+#   M => D
+#   N => C
+#   O => A
+#   P => B
+#
+
+require_relative "../phase_runner"
+
+class StableMatching
+  class Marriage
+    class PhaseIRunner < StableMatching::PhaseRunner
+      def initialize(alpha_preferences, beta_preferences, opts = {})
+        @alpha_preferences = alpha_preferences
+        @beta_preferences = beta_preferences
+
+        @logger = opts.fetch(:logger)
+      end
+
+      def run
+        while @alpha_preferences.unmatched.any?
+          @alpha_preferences.unmatched.each do |partner|
+            top_choice = partner.first_preference
+            simulate_proposal(partner, top_choice)
+          end
+        end
+      end
+    end
+  end
+end