munkres 0.1.0

data/History.txt

@@ -0,0 +1,6 @@
+=== 0.1.0 / 2010-01-26
+
+* 1 major enhancement
+
+  * Birthday!
+

data/README.txt

@@ -0,0 +1,64 @@
+= munkres
+
+http://github.com/pdamer/munkres
+
+== DESCRIPTION:
+
+A ruby implementation of the kuhn-munkres or 'hungarian' algorithm for bipartite matching.
+
+== FEATURES/PROBLEMS:
+
+Match groups together 1 to 1 
+
+== SYNOPSIS:
+
+Create a 2d matrix joining your two groups to match with each entry 
+being the cost of matching the corresponding members of the groups
+
+  require 'munkres'
+
+  cost_matrix = [[4,3],
+                 [3,0]]
+                 
+  m = Munkres.new(cost_matrix)
+  p m.find_pairings
+
+
+== REQUIREMENTS:
+
+Uses test/spec for testing.
+
+== INSTALL:
+
+sudo gem install munkres
+
+== DEVELOPERS:
+
+After checking out the source, run:
+
+  $ rake test
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010
+
+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/Rakefile

@@ -0,0 +1,33 @@
+require 'rubygems'
+require 'rake/testtask'
+require 'rake/gempackagetask'
+
+spec = Gem::Specification.new do |s|
+  s.name = "munkres"
+  s.version = "0.1.0"
+  s.author = "Paul Damer and Jim Wood"
+  s.email = 'pdamer@gmail.com'
+  s.homepage = "http://github.com/pdamer/munkres"
+  s.platform = Gem::Platform::RUBY
+  s.summary = "A Ruby implementation of the Hungarian Algorithm"
+  s.description = "A ruby implementation of the kuhn-munkres or 'hungarian' algorithm for bipartite matching."
+  s.rubyforge_project = "munkres"
+  s.test_files = ['test/munkres_test.rb']
+  s.files = %w[
+lib/munkres.rb
+test/munkres_test.rb
+README.txt
+Rakefile
+History.txt
+]
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_tar = true
+end
+
+Rake::TestTask.new() do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose = true
+end

data/lib/munkres.rb

@@ -0,0 +1,271 @@
+class Munkres
+  MODE_MINIMIZE_COST = 1
+  MODE_MAXIMIZE_UTIL = 2
+  
+  def initialize(matrix=[], mode=MODE_MINIMIZE_COST)
+    @matrix = matrix
+    @mode = mode
+    @original = Marshal.load(Marshal.dump(@matrix))
+    validate_and_pad
+    @covered_columns = []
+    @covered_rows = []
+    @starred_zeros = []
+    @primed_zeros = []
+    
+    class << @matrix
+      
+
+      def row(index)
+        self[index]
+      end
+
+      def column(index)
+        self.collect do |row|
+          row[index]
+        end
+      end
+
+      def columns
+        result = []
+        self.first.each_index do |i|
+          result << self.column(i)
+        end
+        result
+      end
+      
+      def each_column_index &block
+        column_indices.each &block
+      end
+      
+      def column_indices
+        @column_indices ||= (0...self.first.size).to_a
+      end
+      
+      def row_indices
+        @row_indices ||= (0...self.size).to_a
+      end
+    end
+    
+  end
+  
+  def find_pairings
+    create_zero_in_rows
+    star_zeros
+    cover_columns_with_stars
+    while not done?
+      p = cover_zeros_and_create_more
+      find_better_stars p
+      #create series
+      cover_columns_with_stars
+    end
+    @pairings = @starred_zeros.delete_if{|row_index,col_index| col_index >= @original.first.size || row_index >= @original.size}
+  end
+  
+  def total_cost_of_pairing
+    @pairings.inject(0) {|total, star| total + @original[star[0]][star[1]]}
+  end
+  
+  def pretty_print
+    print_col_row
+    @matrix.each_with_index do |row,row_index|
+      print @covered_rows.include?(row_index) ? "-" : " "
+      row.each_with_index do |value, col_index|
+        print value
+        print "*" if @starred_zeros.include? [row_index,col_index]
+        print "'" if @primed_zeros.include? [row_index,col_index]
+        print "\t"
+      end
+      print @covered_rows.include?(row_index) ? "-" : " "
+      print "\n"
+    end
+    print_col_row
+  end
+  
+  def print_col_row
+    print " "
+    @matrix.column_indices.each do |col_index|
+      print "|" if @covered_columns.include? col_index
+      print "\t"
+    end
+    print "\n"
+  end
+  
+  protected
+  
+  attr_accessor :matrix, :covered_columns, :covered_rows, :starred_zeros, :primed_zeros, :primed_starred_series
+  
+  def create_zero_in_rows
+    @matrix.each_with_index do |row,row_index|
+      min_val = min_or_zero(row)
+      row.each_with_index do |value, col_index|
+        @matrix[row_index][col_index] = value - min_val
+      end
+    end
+  end
+  
+  def star_zeros 
+    unstarred_columns = @matrix.column_indices
+    
+    @matrix.each_with_index do |row, row_index|
+      star = star_in_row?(row_index)
+      next if star
+      unstarred_columns.each do |col_index|
+          if (row[col_index] == 0 and !star_in_column?(col_index))
+          @starred_zeros << [row_index, col_index]
+          unstarred_columns -= [col_index]
+          break # go to next row
+        end
+      end
+    end
+  end
+  
+  def cover_columns_with_stars
+    cols = @starred_zeros.collect {|z| z[1]}
+    cols.uniq!
+    @covered_columns += cols
+  end
+  
+  def prime_first_uncovered_zero
+    my_cols = uncovered_columns #silly workaround to cache the list
+    
+    uncovered_rows.each do |row_index|
+      my_cols.each do |col_index|
+        if @matrix[row_index][col_index] == 0
+          @primed_zeros << [row_index, col_index]
+          return [row_index, col_index]
+        end
+      end
+    end
+    nil
+  end
+  
+  def smallest_uncovered_value
+    min_value = nil 
+    my_cols = uncovered_columns #silly workaround to cache the list
+    uncovered_rows.each do |row_index|
+      my_cols.each do |col_index|
+        value = @matrix[row_index][col_index]
+        min_value ||= value
+        min_value = value if value < min_value
+        return 0 if min_value == 0
+      end
+    end
+    min_value
+  end
+  
+  def add_and_subtract_for_step_6(delta=0)
+    covered_rows.each do |row_index|
+      covered_columns.each do |col_index|
+        @matrix[row_index][col_index] += delta
+      end
+    end
+
+
+    my_cols = uncovered_columns #silly workaround to cache the list
+    
+    uncovered_rows.each do |row_index|
+      my_cols.each do |col_index|
+        @matrix[row_index][col_index] -= delta
+      end
+    end
+  end
+  
+  def find_better_stars(first_zero)
+    primes_series = [first_zero]
+    stars_series = []
+    while next_star = @starred_zeros.detect{|row, col| col == primes_series.last[1] }
+      stars_series << next_star
+      primes_series << @primed_zeros.detect{|row, col| row == stars_series.last[0] }
+    end
+    stars_series.each do |star|
+      @starred_zeros.delete(star)
+    end
+    
+    primes_series.each do |prime|
+      @starred_zeros << prime
+    end
+    
+    @primed_zeros = []
+    @covered_columns = []
+    @covered_rows = []
+  end
+  
+  def done?
+    @matrix.column_indices.size == covered_columns.size
+  end
+  
+  def min_or_zero(collection)
+    collection.index(0) ? 0 : collection.min
+  end
+  
+  def star_in_row?(index)
+    @starred_zeros.any? {|row_index,col_index| row_index == index}
+  end
+  
+  def star_in_row(index)
+    #@starred_zeros.detect {|row_index,col_index| row_index == index}
+    @starred_zeros.assoc index
+  end  
+  
+  def star_in_column?(index)
+    @starred_zeros.any? {|row_index,col_index| col_index == index}
+  end
+  
+  def uncovered_rows
+    @matrix.row_indices - @covered_rows 
+  end
+  
+  def uncovered_columns
+    @matrix.column_indices - @covered_columns
+  end
+  
+  #step 4
+  def cover_zeros_and_create_more
+    loop do
+      while prime = prime_first_uncovered_zero
+        if star = star_in_row(prime[0]) 
+          @covered_rows << prime[0]
+          @covered_columns -= [star[1]] 
+        else
+          return prime
+        end
+      end
+      
+      add_and_subtract_for_step_6(smallest_uncovered_value)
+    end
+  end
+  
+  def validate_and_pad
+    raise(ArgumentError, "Munkres matrix is empty") unless @matrix.first
+    raise(ArgumentError, "Munkres first row is empty") unless @matrix.first.size > 0
+    raise(ArgumentError, "Munkres matrix is not rectangular", caller) if @matrix.any? {|row| row.size != @matrix.first.size } 
+    raise(ArgumentError, "Munkres matrix is wider than it is tall", caller) if @matrix.size < @matrix.first.size
+  
+    if @matrix.size > @matrix.first.size
+      number_of_cols = @matrix.first.size
+      @matrix.each_with_index do |row, row_index|
+        (number_of_cols...@matrix.size).each do |col_index|
+          @matrix[row_index][col_index] = 0
+        end
+      end
+    end
+    
+    if MODE_MAXIMIZE_UTIL == @mode
+      max_value = @matrix.flatten.max
+      @matrix.each_with_index do |row, row_index|
+        row.each_with_index do |value, col_index|
+          @matrix[row_index][col_index] = max_value - value
+        end
+      end
+    end
+    
+  end
+  
+end
+
+#for backwards compatiability with another library.
+class Munkres::Problem < Munkres
+  def solve
+    find_pairings
+  end
+end

data/test/munkres_test.rb

@@ -0,0 +1,234 @@
+require 'rubygems'
+require "test/spec"
+require "munkres"
+
+context "An empty Munkres instance" do
+  
+  setup do
+    @saved_protected_instance_methods = Munkres.protected_instance_methods
+    x = @saved_protected_instance_methods
+    Munkres.class_eval { public *x }
+    @m = Munkres.new [[0]]
+  end
+  
+  teardown do
+     x = @saved_protected_instance_methods
+     Munkres.class_eval { protected *x }
+   end
+  
+  specify "should track a matrix of values" do
+    @m.matrix.should == [[0]]
+  end
+  
+  specify "should track covered columns" do
+    @m.covered_columns.should == []
+  end
+  
+  specify "should track covered rows" do
+    @m.covered_rows.should == []
+  end
+  
+  specify "should track starred zeros" do
+    @m.starred_zeros.should == []
+  end
+  
+  specify "should track primed zeros" do
+    @m.primed_zeros.should == []
+  end
+end
+
+context "A Munkres solving instance" do
+  setup do
+    @saved_protected_instance_methods = Munkres.protected_instance_methods
+    x = @saved_protected_instance_methods
+    Munkres.class_eval { public *x }
+    @m = Munkres.new [[1,2,3],[2,4,6],[3,6,9]]
+  end
+  
+  teardown do
+    x = @saved_protected_instance_methods
+    Munkres.class_eval { protected *x }
+  end
+  
+  specify "create_zero_in_rows should create a zero in each row of the matrix" do
+    @m.create_zero_in_rows
+    @m.matrix.should == [[0,1,2],[0,2,4],[0,3,6]]
+  end
+  
+  specify "should be able to retrieve any row of the matrix" do
+    @m.matrix.row(2).should == [3,6,9]
+  end
+  
+  specify "should be able to retrieve any column of the matrix" do
+    @m.matrix.column(1).should == [2,4,6]
+  end
+  
+  specify "should be able to find the min value of any collection" do
+    @m.min_or_zero([3,0,2,1]).should == 0
+  end
+  
+  specify "star_zeros should star the first zero in this example" do
+    @m.create_zero_in_rows
+    @m.star_zeros
+    @m.starred_zeros.should == [[0,0]]
+  end  
+  
+  specify "star_in_column? should indicate a star in a column" do
+    @m.starred_zeros << [0,0]
+    @m.star_in_column?(0).should.be true
+    @m.star_in_column?(1).should.be false
+  end
+  
+  specify "star_in_row? should indicate a star in a row" do
+    @m.starred_zeros << [0,1]
+    @m.star_in_row?(0).should.be true
+    @m.star_in_row?(1).should.be false
+  end
+  
+  specify "cover_columns_with_stars should cover the first colum" do
+    @m.create_zero_in_rows
+    @m.star_zeros
+    @m.cover_columns_with_stars
+    @m.covered_columns.should == [0]
+  end
+  
+  specify "should be done if all columns are covered" do
+    @m.done?.should.be false
+    @m.covered_columns = [0,1,2]
+    @m.done?.should.be true
+  end
+  
+  specify "should be able to prime the first uncovered zero" do
+    @m.matrix[0][1] = 0
+    @m.matrix[1][1] = 0
+    @m.prime_first_uncovered_zero.should == [0,1]
+    @m.primed_zeros.should == [[0,1]]
+  end
+  
+  specify "should be able to find the smallest uncovered value" do
+    @m.covered_columns = [0,1]
+    @m.covered_rows = [0]
+    @m.smallest_uncovered_value.should == 6
+  end
+  
+  specify "should be able to add a value to covered rows an subtract it from uncovered columns" do
+    @m.covered_columns = [1]
+    @m.covered_rows = [0,2]
+    @m.add_and_subtract_for_step_6(2)
+    @m.matrix.should == [[1,4,3],[0,4,4],[3,8,9]]
+  end
+  
+  specify "should construct a series of primed and starred zeros and reset things" do
+    @m.matrix = [[0,0,1],[0,1,3],[0,2,5]]
+    @m.covered_rows = [0]
+    @m.starred_zeros = [[0,0]]
+    @m.primed_zeros = [[0,1], [1,0]]
+    @m.find_better_stars [1,0]
+    [[0,1], [1,0]].each {|star| @m.starred_zeros.should.include star } 
+    @m.primed_zeros.should.be.empty
+    @m.covered_rows.should.be.empty
+    @m.covered_columns.should.be.empty
+  end
+  
+  specify "should return a list of optimal pairings" do
+    optimal_pairings = [[0,2],[1,1],[2,0]]
+    @m.find_pairings.sort.should == optimal_pairings.sort
+  end
+  
+end
+
+context "An oddly shaped Munkres matrix" do 
+  setup do
+    @saved_protected_instance_methods = Munkres.protected_instance_methods
+    x = @saved_protected_instance_methods
+    Munkres.class_eval { public *x }
+  end
+  
+  teardown do
+    x = @saved_protected_instance_methods
+    Munkres.class_eval { protected *x }
+  end
+  
+  specify "should zero pad a tall skinny on initialize" do
+    m = Munkres.new [[1,2],[2,4],[3,6]]
+    
+    m.matrix.should == [[1,2,0],[2,4,0],[3,6,0]]
+  end
+  
+  specify "should raise an error for wide inputs" do
+    should.raise(ArgumentError) { Munkres.new [[1,2,3],[4,5,6]] }
+  end
+  
+  specify "should raise an error for irregular inputs" do
+    should.raise(ArgumentError) { Munkres.new [[1,2],[1,2,3]] }
+  end
+  
+  specify "should raise an error for an empty matrix" do
+    should.raise(ArgumentError) { Munkres.new [] }
+  end
+  
+  specify "should raise an error for an empty row" do
+    should.raise(ArgumentError) { Munkres.new [[],[]] }
+  end
+end
+    
+
+
+context "Complex examples with know solutions" do
+  specify "should solve first example" do
+    optimal_pairings = [[0,5],[1,1],[2,2],[3,3],[4,4],[5,0]]
+    m = Munkres.new [[3,4,5,6,2,1],[3,0,1,2,3,4],[7,6,0,2,1,1],[4,4,5,0,1,2],[0,1,0,1,0,0],[0,3,2,2,2,0]]
+    
+    m.find_pairings.sort.should == optimal_pairings.sort
+    
+  end
+
+  specify "should solve a larger example" do
+    optimal_pairings = []
+    m = Munkres.new [[4,1,2,3],
+    [6,9,2,4],
+    [1,0,3,7],
+    [10,4,6,6]]
+    m.find_pairings
+    m.total_cost_of_pairing.should == 10
+  end  
+  
+  specify "should solve a non-square example" do
+   optimal_pairings = [[[0, 3], [1, 2], [2, 1], [5, 0]],
+                       [[0, 1], [1, 2], [2, 0], [5, 3]]]    
+    m = Munkres.new [[4,1,2,3],
+    [6,9,2,4],
+    [1,0,3,7],
+    [10,4,6,6],
+    [5,7,5,9],
+    [2,2,14,3]]
+    optimal_pairings.sort.should.include m.find_pairings.sort
+    m.total_cost_of_pairing.should == 7
+  end
+  
+  specify "should solve a very large example" do
+    # Profile the code
+    #require 'ruby-prof'
+    
+    arr = []
+    100.times do |i|
+      arr[i] = []
+      100.times do |j|
+        arr[i][j] = rand 20
+      end
+    end
+    
+    #result = RubyProf.profile do
+      m = Munkres.new arr
+      m.find_pairings
+    #end
+
+    #printer = RubyProf::GraphHtmlPrinter.new(result)
+    #File.open('profile.html', 'w') do |file|
+    #  printer.print(file, {:min_percent => 30, :print_file => true})
+    #end
+    
+        
+  end
+  
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+name: munkres
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Paul Damer and Jim Wood
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-26 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: A ruby implementation of the kuhn-munkres or 'hungarian' algorithm for bipartite matching.
+email: pdamer@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/munkres.rb
+- test/munkres_test.rb
+- README.txt
+- Rakefile
+- History.txt
+has_rdoc: true
+homepage: http://github.com/pdamer/munkres
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: munkres
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A Ruby implementation of the Hungarian Algorithm
+test_files: 
+- test/munkres_test.rb