stable_match 0.1.0 → 0.1.1

data/README.md

@@ -1,24 +1,45 @@
 # StableMatch
 
-TODO: Write a gem description
+A generic implementation of the Stable Match class of algorithms.
 
 ## Installation
 
+### Without Bundler
+
+Install it yourself:
+
+```
+$ gem install stable_match
+```
+
+### With Bundler
+
 Add this line to your application's Gemfile:
 
-    gem 'stable_match'
+```ruby
+gem 'stable_match'
+```
 
 And then execute:
 
-    $ bundle
+```
+$ bundle
+```
 
-Or install it yourself as:
+## Usage
 
-    $ gem install stable_match
+* See: `examples/example_1.rb`
+* Run: `rake example`
 
-## Usage
+TODO: Write more usage instructions here
+
+## References
 
-TODO: Write usage instructions here
+* [http://halfamind.aghion.com/the-national-resident-matching-programs-nrmp](http://halfamind.aghion.com/the-national-resident-matching-programs-nrmp)
+* [http://rosettacode.org/wiki/Stable_marriage_problem#Ruby](http://rosettacode.org/wiki/Stable_marriage_problem#Ruby)
+* [http://en.wikipedia.org/wiki/Stable_marriage_problem#Algorithm](http://en.wikipedia.org/wiki/Stable_marriage_problem#Algorithm)
+* [http://en.wikipedia.org/wiki/National_Resident_Matching_Program](http://en.wikipedia.org/wiki/National_Resident_Matching_Program)
+* [http://www.nrmp.org/res_match/about_res/algorithms.html](http://www.nrmp.org/res_match/about_res/algorithms.html)
 
 ## Contributing
 

data/Rakefile

@@ -13,11 +13,38 @@ task :example => "examples:any"
 
 namespace :test do
   desc "Run All The Tests"
-  task :all => [ "test:unit" ]
+  task :all do
+    suites = %w(
+      test:functional
+      test:unit
+    )
+
+    suites.each do | suite |
+      puts "=========================================="
+      puts "Running: #{ suite }"
+      puts "=========================================="
+      begin
+        Rake::Task[ suite ].invoke
+      rescue
+        puts "=========================================="
+        puts "FAILED: #{ suite }"
+      ensure
+        puts "=========================================="
+        puts "\n"
+      end
+    end
+  end
+
+  desc "Run The Functional Tests"
+  Rake::TestTask.new( :functional ) do | t |
+    t.libs    << [ "test" ]
+    t.pattern = "test/functional/**/*_test.rb"
+    t.verbose = true
+  end
 
   desc "Run The Unit Tests"
   Rake::TestTask.new( :unit ) do | t |
-    t.libs    = [ "test" ]
+    t.libs    << [ "test" ]
     t.pattern = "test/unit/**/*_test.rb"
     t.verbose = true
   end

data/examples/example_1.rb

@@ -1,6 +1,8 @@
 require "stable_match"
 
 class Test
+## This is a modified version of the example NRMP case
+#
   PROGRAMS = {
     'city'    => { :match_positions => 1, :preferences => ['garcia', 'hassan', 'eastman', 'brown', 'chen', 'davis', 'ford']},
     'general' => { :match_positions => 3, :preferences => ['brown', 'eastman', 'hassan', 'anderson', 'chen', 'davis', 'garcia']},

data/lib/stable_match/candidate.rb

@@ -91,12 +91,12 @@ module StableMatch
       require "yaml"
 
       {
-        :target              => target,
-        :match_positions     => match_positions,
-        :matches             => matches.map( &:target ),
-        :preference_position => preference_position,
-        :preferences         => preferences.map( &:target ),
-        :proposals           => proposals.map( &:target )
+        'target'              => target,
+        'match_positions'     => match_positions,
+        'matches'             => matches.map( &:target ),
+        'preference_position' => preference_position,
+        'preferences'         => preferences.map( &:target ),
+        'proposals'           => proposals.map( &:target )
       }.to_yaml
     end
 

data/lib/stable_match/runner.rb

@@ -24,23 +24,29 @@ module StableMatch
     fattr( :candidate_set2 ){ {} } # for Candidates
     fattr :set2                    # raw data
 
+  ## The way in which the run loop executes
+  #
+  # Should be either: symmetric OR asymmetric
+  #
+    fattr( :strategy ){ :symmetric }
+
   ## Runner::run
   #
   # Class-level factory method to construct, check, build and run a Runner instance
   #
-    def self.run( *args , &block )
-      runner = new *args , &block
+    def self.run( *args )
+      runner = new *args
       runner.check!
       runner.build!
       runner.run
     end
 
-    def initialize( *args , &block )
+    def initialize( *args )
       options = Map.opts args
       @set1   = options.set1 rescue args.shift or raise ArgumentError.new( "No `set1` provided!" )
       @set2   = options.set2 rescue args.shift or raise ArgumentError.new( "No `set2` provided!" )
 
-      yield self if block_given?
+      @strategy = options.strategy if options.get( :strategy )
     end
 
   ## Runner#build!
@@ -130,6 +136,7 @@ module StableMatch
       end
 
       {
+        'strategy'       => strategy.to_s,
         'candidate_set1' => inspection[ candidate_set1 ],
         'candidate_set2' => inspection[ candidate_set2 ]
       }.to_yaml
@@ -137,12 +144,19 @@ module StableMatch
 
   ## Runner#remaining_candidates
   #
+  # This method respects the runner's strategy!
+  #
   # List the remaining candidates that:
   # -> have remaining slots available for matches AND
   # -> have not already proposed to all of their preferences
   #
     def remaining_candidates
-      candidates.reject{ | candidate | candidate.full? || candidate.exhausted_preferences? }
+      case strategy.to_sym
+      when :symmetric
+        candidates.reject { | candidate | candidate.full? || candidate.exhausted_preferences? }
+      when :asymmetric
+        candidate_set1.values.reject { | candidate | candidate.full? || candidate.exhausted_preferences? }
+      end
     end
 
   ## Runner#run

data/lib/stable_match/version.rb

@@ -1,3 +1,3 @@
 module StableMatch
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/test/functional/nrmp_test.rb

@@ -0,0 +1,59 @@
+require "test_helper"
+
+class NationalResidentMatchingProgramFunctionalTest < MiniTest::Unit::TestCase
+  def test_case
+    programs = {
+      'mercy'   => { :match_positions => 2, :preferences => ['chen', 'garcia']},
+      'city'    => { :match_positions => 2, :preferences => ['garcia', 'hassan', 'eastman', 'anderson', 'brown', 'chen', 'davis', 'ford']},
+      'general' => { :match_positions => 2, :preferences => ['brown', 'eastman', 'hassan', 'anderson', 'chen', 'davis', 'garcia']},
+      'state'   => { :match_positions => 2, :preferences => ['brown', 'eastman', 'anderson', 'chen', 'hassan', 'ford', 'davis', 'garcia']}
+    }
+
+    applicants = {
+      'anderson' => { :match_positions => 1 , :preferences => ['city'] },
+      'brown'    => { :match_positions => 1 , :preferences => ['city', 'mercy'] },
+      'chen'     => { :match_positions => 1 , :preferences => ['city', 'mercy'] },
+      'davis'    => { :match_positions => 1 , :preferences => ['mercy', 'city', 'general', 'state'] },
+      'eastman'  => { :match_positions => 1 , :preferences => ['city', 'mercy', 'state', 'general'] },
+      'ford'     => { :match_positions => 1 , :preferences => ['city', 'general', 'mercy', 'state'] },
+      'garcia'   => { :match_positions => 1 , :preferences => ['city', 'mercy', 'state', 'general'] },
+      'hassan'   => { :match_positions => 1 , :preferences => ['state', 'city', 'mercy', 'general' ] }
+    }
+
+    programs_expectations = {
+      'mercy'   => [ 'chen' ],
+      'city'    => [ 'garcia' , 'eastman' ],
+      'general' => [ 'davis' ],
+      'state'   => [ 'ford' , 'hassan' ]
+    }
+
+    applicants_expectations = {
+      'anderson' => [],
+      'brown'    => [],
+      'chen'     => [ 'mercy' ],
+      'davis'    => [ 'general' ],
+      'eastman'  => [ 'city' ],
+      'ford'     => [ 'state' ],
+      'garcia'   => [ 'city' ],
+      'hassan'   => [ 'state' ]
+    }
+
+    runner = StableMatch.run applicants , programs , :strategy => :asymmetric
+
+    ## applicants
+    #
+      applicants_expectations.each do | applicant , expected_matches |
+        candidate      = runner.candidate_set1[ applicant ]
+        actual_matches = candidate.matches.map &:target
+        assert{ expected_matches.sort == actual_matches.sort }
+      end
+
+    ## programs
+    #
+      programs_expectations.each do | program , expected_matches |
+        candidate      = runner.candidate_set2[ program ]
+        actual_matches = candidate.matches.map &:target
+        assert{ expected_matches.sort == actual_matches.sort }
+      end
+  end
+end

data/test/test_helper.rb

@@ -4,7 +4,7 @@ gem "minitest"
 require "minitest/autorun"
 require "minitest/pride"
 
-support_dir = File.expand_path File.dirname( __FILE__ ) , "support"
-Dir[ "#{ support_dir }/**/*.rb" ].each { | f | require f }
-
 require "stable_match"
+
+support_dir = File.join File.expand_path( File.dirname __FILE__ ) , "support"
+Dir[ "#{ support_dir }/**/*.rb" ].each { | f | require f }

data/test/unit/{stable_match → lib/stable_match}/candidate_test.rb

@@ -1,6 +1,6 @@
 require "test_helper"
 
-class StableMatch::CandidateTest < MiniTest::Unit::TestCase
+class StableMatch::CandidateUnitTest < MiniTest::Unit::TestCase
   def setup
     @candidate1 = StableMatch::Candidate.new 1 , [ 2 , 3 ]
     @candidate2 = StableMatch::Candidate.new 2 , [ 1 , 3 ]

data/test/unit/{stable_match → lib/stable_match}/runner_test.rb

@@ -1,6 +1,6 @@
 require "test_helper"
 
-class StableMatch::RunnerTest < MiniTest::Unit::TestCase
+class StableMatch::RunnerUnitTest < MiniTest::Unit::TestCase
   def setup
     @set1 = { 1 => { :preferences => [ 2 ] } }
     @set2 = { 2 => { :preferences => [ 1 ] } }
@@ -27,6 +27,15 @@ class StableMatch::RunnerTest < MiniTest::Unit::TestCase
     assert{ runner.set2 == @set2 }
   end
 
+  def test_accepts_a_strategy_option
+    runner = assert{ StableMatch::Runner.new @set1 , @set2 , :strategy => :asymmetric }
+    assert{ :asymmetric == runner.strategy }
+  end
+
+  def test_default_strategy_is_symmetric
+    assert{ StableMatch::Runner.new( @set1 , @set2 ).strategy == :symmetric }
+  end
+
 ## Runner#build!
 #
   def test_build_creates_candidate_sets_from_each_raw_set
@@ -100,6 +109,20 @@ class StableMatch::RunnerTest < MiniTest::Unit::TestCase
     assert{ original_size > runner.remaining_candidates.size }
   end
 
+  def test_remaining_candidates_respects_the_run_strategy
+    runner = build_prepared_runner
+    assert{ runner.strategy == :symmetric }
+
+    all       = runner.candidates.map &:target
+    remaining = runner.remaining_candidates.map &:target
+    assert{ all.sort == remaining.sort }
+
+    runner.strategy :asymmetric
+    set1      = @set1.keys
+    remaining = runner.remaining_candidates.map &:target
+    assert{ set1.sort == remaining.sort }
+  end
+
 ## Runner#run
 #
   def test_has_a_run_loop

data/test/unit/lib/stable_match_test.rb

@@ -0,0 +1,7 @@
+require "test_helper"
+
+class StableMatchUnitTest < MiniTest::Unit::TestCase
+  def test_has_a_shortcut_method_create_and_run_a_runner
+    assert{ StableMatch.respond_to? :run }
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stable_match
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -14,7 +14,7 @@ date: 2012-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fattr
-  requirement: &70273026247540 !ruby/object:Gem::Requirement
+  requirement: &70346750299680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,10 +22,10 @@ dependencies:
         version: 2.2.1
   type: :runtime
   prerelease: false
-  version_requirements: *70273026247540
+  version_requirements: *70346750299680
 - !ruby/object:Gem::Dependency
   name: map
-  requirement: &70273026246260 !ruby/object:Gem::Requirement
+  requirement: &70346750298320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -33,10 +33,10 @@ dependencies:
         version: 5.5.0
   type: :runtime
   prerelease: false
-  version_requirements: *70273026246260
+  version_requirements: *70346750298320
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &70273026229780 !ruby/object:Gem::Requirement
+  requirement: &70346750281820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -44,10 +44,10 @@ dependencies:
         version: 2.12.1
   type: :development
   prerelease: false
-  version_requirements: *70273026229780
+  version_requirements: *70346750281820
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70273026228300 !ruby/object:Gem::Requirement
+  requirement: &70346750280460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -55,10 +55,10 @@ dependencies:
         version: 0.9.2.2
   type: :development
   prerelease: false
-  version_requirements: *70273026228300
+  version_requirements: *70346750280460
 - !ruby/object:Gem::Dependency
   name: rego
-  requirement: &70273026227040 !ruby/object:Gem::Requirement
+  requirement: &70346750279080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -66,7 +66,7 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *70273026227040
+  version_requirements: *70346750279080
 description: A generic implementation of the stable match algorightm.
 email:
 - cookrn@gmail.com
@@ -86,10 +86,12 @@ files:
 - lib/stable_match/runner.rb
 - lib/stable_match/version.rb
 - stable_match.gemspec
+- test/functional/nrmp_test.rb
 - test/support/minitest.rb
 - test/test_helper.rb
-- test/unit/stable_match/candidate_test.rb
-- test/unit/stable_match/runner_test.rb
+- test/unit/lib/stable_match/candidate_test.rb
+- test/unit/lib/stable_match/runner_test.rb
+- test/unit/lib/stable_match_test.rb
 homepage: https://github.com/cookrn/stable_match
 licenses: []
 post_install_message: 
@@ -104,7 +106,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 4207718686449127189
+      hash: 1686263240201859954
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -113,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 4207718686449127189
+      hash: 1686263240201859954
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.16
@@ -121,7 +123,9 @@ signing_key:
 specification_version: 3
 summary: stable_match v0.1.0
 test_files:
+- test/functional/nrmp_test.rb
 - test/support/minitest.rb
 - test/test_helper.rb
-- test/unit/stable_match/candidate_test.rb
-- test/unit/stable_match/runner_test.rb
+- test/unit/lib/stable_match/candidate_test.rb
+- test/unit/lib/stable_match/runner_test.rb
+- test/unit/lib/stable_match_test.rb