bipartite_graph 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9a66f77f8c4a20067ac92fc48800665accb90811
+  data.tar.gz: b4bab5f71d800b0da8fc8bff0c347b39e70eb1e4
+SHA512:
+  metadata.gz: 8f448ee0be1644f62e2365cfcdfc433f45309a8393cef8986491dc9129f4c795ca2757bd0aa059c9c652fa6ea08cc2d792287a515e3784d96a824d6b696c42a2
+  data.tar.gz: e32b1adc8829db74a08d1ac12c4fb54eaf56d4c7d3830991fc8031abe4712456e23380accb4304069ece23a269a1bac52363aad6ab5ec7e6d97e766fb7f92db1

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.0.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in bipartite_graph.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Tom Close
+
+MIT License
+
+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,47 @@
+# BipartiteGraph
+
+Finds maximum matchings in weighted bipartite graphs, using the
+[Hungarian algorithm](http://en.wikipedia.org/wiki/Hungarian_algorithm).
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'bipartite_graph'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bipartite_graph
+
+## Usage
+
+```ruby
+graph = BipartiteGraph.new
+
+graph.add_edge('x1', 'y1', 1)
+graph.add_edge('x1', 'y2', 6)
+graph.add_edge('x2', 'y2', 8)
+graph.add_edge('x2', 'y3', 6)
+graph.add_edge('x3', 'y1', 4)
+graph.add_edge('x3', 'y3', 1)
+
+matching = graph.max_weight_matching
+
+matching.edges.map { |e| [e.from, e.to] } #=> ['x1', 'y2'], ['x2', 'y3'], ['x3', 'y1']
+
+matching.edges.sum(&:weight) #=> 16
+
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/tomclose/bipartite_graph/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

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

data/bin/bundler

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'bundler' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('bundler', 'bundler')

data/bin/htmldiff

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'htmldiff' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('diff-lcs', 'htmldiff')

data/bin/ldiff

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'ldiff' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('diff-lcs', 'ldiff')

data/bin/rake

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rake', 'rake')

data/bin/rspec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/bipartite_graph.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bipartite_graph/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bipartite_graph"
+  spec.version       = BipartiteGraph::VERSION
+  spec.authors       = ["Tom Close"]
+  spec.email         = ["tom.close@cantab.net"]
+  spec.summary       = %q{Finds maximum matchings in weighted bipartite graphs}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/lib/bipartite_graph/alternating_tree.rb

@@ -0,0 +1,53 @@
+module BipartiteGraph
+  # an alternating tree isn't a graph in its own right
+  # it's a subgraph - you can't add things that aren't in the main graph
+  class AlternatingTree
+    attr_accessor :root, :graph
+    def initialize(graph, root)
+      raise "Root can't be nil" if root.nil?
+      @root = root
+      @graph = graph
+
+      @node_map = {}
+      @node_map[root] = [nil, nil]
+    end
+
+    def has_node?(node)
+      @node_map.has_key?(node)
+    end
+
+    def nodes
+      @node_map.keys
+    end
+
+    def sources
+      graph.sources.select {|node| has_node?(node) }
+    end
+    def sinks
+      graph.sinks.select {|node| has_node?(node) }
+    end
+
+    def add_edge(edge)
+      #raise "Tree has no existing node #{edge.from}" unless has_node?(edge.from)
+      #raise "Tree already contains node #{edge.to}" if has_node?(edge.to)
+      if has_node?(edge.from)
+        @node_map[edge.to] = [edge.from, edge]
+      elsif has_node?(edge.to)
+        @node_map[edge.from] = [edge.to, edge]
+      else
+        raise "Nodes not in tree: #{edge.from} or #{edge.to}"
+      end
+    end
+
+    def path_to(leaf)
+      path = []
+      next_node, edge = @node_map[leaf]
+      while edge
+        path << edge
+        next_node, edge = @node_map[next_node]
+      end
+      path.reverse
+    end
+  end
+
+end

data/lib/bipartite_graph/edge.rb

@@ -0,0 +1,3 @@
+module BipartiteGraph
+  Edge = Struct.new(:from, :to, :weight)
+end

data/lib/bipartite_graph/edge_set.rb

@@ -0,0 +1,48 @@
+module BipartiteGraph
+  class EdgeSet
+    include Enumerable
+    attr_reader :edges, :filter
+
+    def initialize(edges = Set.new, filter = {})
+      @edges = edges
+      @filter = filter
+    end
+
+    def <<(edge)
+      add(edge)
+    end
+
+    def add(edge)
+      edges.add(edge)
+    end
+
+    def delete(edge)
+      edges.delete(edge)
+    end
+
+    def length
+      to_a.length
+    end
+
+    def from(node_or_nodes)
+      from_set = Set.new(Array(node_or_nodes))
+      self.class.new(edges, filter.merge({ from: from_set }))
+    end
+
+    def not_to(node_or_nodes)
+      not_to_set = Set.new(Array(node_or_nodes))
+      self.class.new(edges, filter.merge({ not_to: not_to_set }))
+    end
+
+    def each
+      from_set   = filter[:from]
+      not_to_set = filter[:not_to]
+      edges.each do |edge|
+        from_cond   = !from_set   || from_set.include?(edge.from)
+        not_to_cond = !not_to_set || !not_to_set.include?(edge.to)
+
+        yield edge if from_cond && not_to_cond
+      end
+    end
+  end
+end

data/lib/bipartite_graph/graph.rb

@@ -0,0 +1,34 @@
+module BipartiteGraph
+  class Graph
+    attr_reader :sources, :sinks, :edges, :nodes
+    def initialize
+      clear
+    end
+
+    def clear
+      @nodes   = Set.new
+      @sources = Set.new
+      @sinks   = Set.new
+      @edges   = EdgeSet.new
+    end
+
+    def add_edge(from, to, weight=1)
+      @sources << from
+      @sinks << to
+      @nodes = @sources + @sinks
+
+      edge = Edge.new(from, to, weight)
+      @edges << edge
+      edge
+    end
+
+    def node_for(key)
+      @nodes[key]
+    end
+
+
+    def max_weight_matching
+      HungarianAlgorithm.new(self).solution
+    end
+  end
+end

data/lib/bipartite_graph/hungarian_algorithm.rb

@@ -0,0 +1,161 @@
+module BipartiteGraph
+  class HungarianAlgorithm
+    attr_reader :labelling, :matching, :graph
+
+    def initialize(graph)
+      @graph = graph
+      @labelling = Labelling.new(graph)
+      @matching = create_initial_matching
+    end
+
+
+    def create_initial_matching
+      eq_graph = labelling.equality_graph
+
+      matching = Matching.new(graph)
+
+      eq_graph.sources.each do |source|
+        eq_graph.edges.from(source).each do |edge|
+          included = matching.has_node?(edge.to)
+
+          if !included
+            matching.add_edge(edge)
+            next
+          end
+        end
+      end
+      matching
+    end
+
+    class Labelling
+      # subgraph of edges where weight = sum of end labels
+      attr_reader :equality_graph, :graph, :labels
+
+      def initialize(graph)
+        @labels = {}
+        @graph = graph
+        @equality_graph = Subgraph.new(graph)
+
+        graph.sources.each do |node|
+          edges = graph.edges.from(node)
+          max_weight = edges.map(&:weight).max
+          @labels[node] = max_weight
+        end
+
+        graph.sinks.each do |node|
+          @labels[node] = 0
+        end
+
+        recalculate_equality_graph
+      end
+
+      def label_for(node)
+        @labels[node]
+      end
+
+      def recalculate_equality_graph
+        equality_graph.clear
+
+        graph.edges.select {|e| e.weight == labels[e.from] + labels[e.to]}.each do |edge|
+          equality_graph.add_edge(edge)
+        end
+      end
+
+      def update(nodes_to_increase, nodes_to_decrease, change)
+        raise "Change must be positive" unless change > 0
+        nodes_to_increase.each { |n| labels[n] += change }
+        nodes_to_decrease.each { |n| labels[n] -= change }
+
+        recalculate_equality_graph #could be cleverer about this ..
+      end
+    end
+
+    class Matching
+      attr_reader :edges, :graph
+
+      def initialize(graph)
+        @graph = graph
+        @edges = EdgeSet.new
+      end
+
+      def edge_for(node)
+        @edges.find {|edge| edge.to == node || edge.from == node }
+      end
+
+      def has_node?(node)
+        !!edge_for(node)
+      end
+
+      def sources
+        graph.sources.select {|node| has_node?(node) }
+      end
+
+      def perfect?
+        2 * edges.length == graph.nodes.length
+      end
+
+      def add_edge(edge)
+        edges << edge
+      end
+
+      def delete_edge(edge)
+        edges.delete(edge)
+      end
+
+      def apply_alternating_path(path)
+        path.each_with_index do |edge, i|
+          i.even? ? add_edge(edge) : delete_edge(edge)
+        end
+      end
+    end
+
+    def solution
+      while !matching.perfect?
+        root = (graph.sources - matching.sources).first
+        add_to_matching(root)
+      end
+
+      matching
+    end
+
+    def equality_graph
+      labelling.equality_graph
+    end
+
+    def add_to_matching(root)
+      tree = AlternatingTree.new(graph, root)
+      matching_found = false
+
+      while !matching_found
+        new_edge = equality_graph.edges.from(tree.sources).not_to(tree.sinks).first
+
+        if new_edge.nil?
+          augment_labelling_using(tree)
+        else
+          tree.add_edge(new_edge)
+          new_sink = new_edge.to
+
+          existing_edge = matching.edge_for(new_sink)
+          if existing_edge
+            tree.add_edge(existing_edge)
+          else
+            matching.apply_alternating_path(tree.path_to(new_edge.to))
+            matching_found = true
+          end
+        end
+      end
+    end
+
+    def augment_labelling_using(tree)
+      target_edges = graph.edges.from(tree.sources).not_to(tree.sinks)
+
+      slack = target_edges.map do |edge|
+        labelling.label_for(edge.from) + labelling.label_for(edge.to) - edge.weight
+      end
+
+      max_decrease = slack.min
+
+      labelling.update(tree.sinks, tree.sources, max_decrease)
+    end
+  end
+end

data/lib/bipartite_graph/subgraph.rb

@@ -0,0 +1,34 @@
+module BipartiteGraph
+  class Subgraph
+    attr_reader :sources, :sinks, :edges, :graph, :nodes
+    def initialize(graph)
+      @graph = graph
+      clear
+    end
+
+    def clear
+      @sources = Set.new
+      @sinks   = Set.new
+      @nodes   = Set.new
+      @edges   = EdgeSet.new
+    end
+
+    def add_edge(edge)
+      @edges << edge
+      @sources << edge.from
+      @sinks   << edge.to
+      @nodes = @sources + @sinks
+    end
+
+    def has_node?(node)
+      nodes.include?(node)
+    end
+
+    def sources
+      graph.sources.select {|node| has_node?(node) }
+    end
+    def sinks
+      graph.sinks.select {|node| has_node?(node) }
+    end
+  end
+end

data/lib/bipartite_graph/version.rb

@@ -0,0 +1,3 @@
+module BipartiteGraph
+  VERSION = "0.0.1"
+end

data/lib/bipartite_graph.rb

@@ -0,0 +1,17 @@
+require "bipartite_graph/version"
+require "bipartite_graph/graph"
+require "bipartite_graph/edge"
+require "bipartite_graph/edge_set"
+require "bipartite_graph/hungarian_algorithm"
+require "bipartite_graph/alternating_tree"
+require "bipartite_graph/subgraph"
+
+module BipartiteGraph
+
+
+  def self.new
+    Graph.new
+  end
+
+
+end

data/spec/acceptance/weighted_matching_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+describe "weighted matchings" do
+  describe "simple example 1" do
+    #http://www.cse.ust.hk/~golin/COMP572/Notes/Matching.pdf
+    let(:graph) { BipartiteGraph.new }
+
+    before do
+      [
+        ['x1', 'y1', 1],
+        ['x1', 'y2', 6],
+        ['x2', 'y2', 8],
+        ['x2', 'y3', 6],
+        ['x3', 'y1', 4],
+        ['x3', 'y3', 1]
+      ].each { |from, to, weight| graph.add_edge(from, to, weight) }
+    end
+
+    it "finds the solution" do
+      matching = graph.max_weight_matching.edges.map {|e| [e.from, e.to] }
+
+      expect(matching).to match_array([
+        ['x1', 'y2'], ['x2', 'y3'], ['x3', 'y1']
+      ])
+    end
+  end
+
+  describe "simple example 2" do
+    let(:graph) { BipartiteGraph.new }
+
+    before do
+      [
+        ['x1', 'y1', 3],
+        ['x1', 'y2', 1],
+        ['x2', 'y1', 11],
+        ['x2', 'y2', 8],
+        ['x2', 'y3', 6],
+        ['x3', 'y1', 10],
+        ['x3', 'y2', 9],
+        ['x3', 'y3', 8],
+        ['x3', 'y4', 7],
+        ['x4', 'y3', 6],
+        ['x4', 'y4', 4],
+      ].each { |from, to, weight| graph.add_edge(from, to, weight) }
+    end
+
+    it "finds the solution" do
+      matching = graph.max_weight_matching.edges.map {|e| [e.from, e.to] }
+
+      expect(matching).to match_array([
+        ['x1', 'y2'], ['x2', 'y1'], ['x3', 'y4'], ['x4', 'y3']
+      ])
+    end
+  end
+
+end

data/spec/bipartite_graph_spec.rb

@@ -0,0 +1,12 @@
+require 'spec_helper'
+
+describe BipartiteGraph do
+  it 'has a version number' do
+    expect(BipartiteGraph::VERSION).not_to be nil
+  end
+
+  it "has a new method" do
+    expect(BipartiteGraph.new).not_to be nil
+
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'bipartite_graph'

data/spec/unit/alternating_tree_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+describe "AlternatingTree" do
+  let(:graph) { BipartiteGraph.new }
+  let(:edge1) { graph.add_edge('Abe', 'Homer') }
+  let(:edge2) { graph.add_edge('Homer', 'Bart') }
+  let(:edge3) { graph.add_edge('Homer', 'Lisa') }
+  let(:edge4) { graph.add_edge('Homer', 'Maggie') }
+
+  let(:tree) { BipartiteGraph::AlternatingTree.new(graph, 'Abe') }
+  describe "empty" do
+    it "includes the root" do
+      expect(tree.has_node?("Abe")).to be true
+    end
+  end
+
+  describe "with edges" do
+    before do
+      tree.add_edge edge1
+      tree.add_edge edge2
+      tree.add_edge edge3
+      tree.add_edge edge4
+    end
+
+    it "#nodes" do
+      expect(tree.nodes).to match_array(%w(Abe Homer Bart Lisa Maggie))
+    end
+
+    it "#has_node?" do
+      expect(tree.has_node?("Bart")).to  be true
+      expect(tree.has_node?("Marge")).to be false
+    end
+
+    it "path_to" do
+      expect(tree.path_to("Maggie")).to eq([edge1, edge4])
+    end
+  end
+end

data/spec/unit/edge_set_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+describe 'EdgeSet' do
+  let(:edge_set) { BipartiteGraph::EdgeSet.new }
+
+  let(:edge1) { BipartiteGraph::Edge.new('0C0', '1C0') }
+  let(:edge2) { BipartiteGraph::Edge.new('0C0', '1C1') }
+  let(:edge3) { BipartiteGraph::Edge.new('1C0', '2C0') }
+  let(:edge4) { BipartiteGraph::Edge.new('1C0', '2C1') }
+  let(:edge5) { BipartiteGraph::Edge.new('1C1', '2C1') }
+  let(:edge6) { BipartiteGraph::Edge.new('1C1', '2C2') }
+
+  before do
+    edge_set << edge1
+    edge_set << edge2
+    edge_set << edge3
+    edge_set << edge4
+    edge_set << edge5
+    edge_set << edge6
+  end
+
+  describe "enumerablility" do
+    it "(for example) can be converted to an array" do
+      expect(edge_set.to_a).to match_array([edge1, edge2, edge3, edge4, edge5, edge6])
+    end
+
+    it "(for example) can be mapped" do
+      expect(edge_set.map(&:from)).to match_array(%w(0C0 0C0 1C0 1C0 1C1 1C1))
+    end
+
+    it "(for example) can do an any?" do
+      expect(edge_set.any? {|e| e.to == '2C2'}).to be true
+    end
+  end
+
+  describe "length" do
+    it "will give its length" do
+      expect(edge_set.length).to eq(6)
+    end
+  end
+
+  describe "filtering" do
+    let(:filtered_edge_set) { edge_set.from('1C1').not_to('2C1') }
+
+    it "returns an edge set" do
+      expect(filtered_edge_set).to be_a BipartiteGraph::EdgeSet
+    end
+
+    it "filters appropriately" do
+      expect(filtered_edge_set.to_a).to match_array([edge6])
+    end
+  end
+
+end

data/spec/unit/hungarian_algorithm_spec.rb

@@ -0,0 +1,89 @@
+require 'spec_helper'
+
+describe "hungarian algorithm" do
+
+  let(:simple_example_edges) do
+    #http://www.cse.ust.hk/~golin/COMP572/Notes/Matching.pdf
+    [
+      ['x1', 'y1', 1],
+      ['x1', 'y2', 6],
+      ['x2', 'y2', 8],
+      ['x2', 'y3', 6],
+      ['x3', 'y1', 4],
+      ['x3', 'y3', 1]
+    ]
+  end
+
+  let(:simple_example_solution) do
+    [
+      ['x1', 'y2'],
+      ['x2', 'y3'],
+      ['x3', 'y1']
+    ]
+  end
+
+  let(:graph) { BipartiteGraph.new }
+  before do
+    simple_example_edges.each do |from, to, weight|
+      graph.add_edge(from, to, weight)
+    end
+  end
+  let(:alg) { BipartiteGraph::HungarianAlgorithm.new(graph) }
+
+  describe "setup" do
+
+    it "calculates an initial labelling" do
+      expect(alg.labelling.labels).to eq({
+        'x1' => 6, 'x2' => 8, 'x3' => 4, 'y1' => 0, 'y2' => 0, 'y3' => 0
+      })
+    end
+
+    it "calculates the equality graph" do
+      expect(alg.labelling.equality_graph.edges.map {|e| [e.from, e.to] }).to match_array([
+        ['x1', 'y2'], ['x2', 'y2'], ['x3', 'y1']
+      ])
+    end
+
+    it "calculates an initial matching" do
+      matching = alg.matching.edges.map {|e| "#{e.from} -> #{e.to}" }.sort
+
+      allowed_matching1 = ['x1 -> y2', 'x3 -> y1']
+      allowed_matching2 = ['x2 -> y2', 'x3 -> y1']
+
+      expect([allowed_matching1, allowed_matching2]).to include(matching)
+    end
+  end
+
+  describe "full iteration" do
+    before do
+      # have to assume we started with matching1 for algorithm to progress like this
+      matching = alg.matching.edges.map {|e| "#{e.from} -> #{e.to}" }.sort
+      allowed_matching1 = ['x1 -> y2', 'x3 -> y1']
+      expect(matching).to eq(allowed_matching1)
+
+      alg.add_to_matching('x2')
+    end
+
+    it "updates the labelling" do
+      expect(alg.labelling.labels).to eq({
+        'x1' => 4, 'x2' => 6, 'x3' => 4, 'y1' => 0, 'y2' => 2, 'y3' => 0
+      })
+    end
+
+    it "updates the equality graph" do
+      expect(alg.labelling.equality_graph.edges.map {|e| [e.from, e.to] }).to match_array([
+        ['x1', 'y2'], ['x2', 'y2'], ['x2', 'y3'], ['x3', 'y1']
+      ])
+    end
+
+    it "updates the matching" do
+      matching = alg.matching.edges.map {|e| "#{e.from} -> #{e.to}" }.sort
+
+      expect(matching).to eq(['x1 -> y2', 'x2 -> y3', 'x3 -> y1'])
+    end
+
+
+
+  end
+
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: bipartite_graph
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Tom Close
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- tom.close@cantab.net
+executables:
+- bundler
+- htmldiff
+- ldiff
+- rake
+- rspec
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/bundler
+- bin/htmldiff
+- bin/ldiff
+- bin/rake
+- bin/rspec
+- bipartite_graph.gemspec
+- lib/bipartite_graph.rb
+- lib/bipartite_graph/alternating_tree.rb
+- lib/bipartite_graph/edge.rb
+- lib/bipartite_graph/edge_set.rb
+- lib/bipartite_graph/graph.rb
+- lib/bipartite_graph/hungarian_algorithm.rb
+- lib/bipartite_graph/subgraph.rb
+- lib/bipartite_graph/version.rb
+- spec/acceptance/weighted_matching_spec.rb
+- spec/bipartite_graph_spec.rb
+- spec/spec_helper.rb
+- spec/unit/alternating_tree_spec.rb
+- spec/unit/edge_set_spec.rb
+- spec/unit/hungarian_algorithm_spec.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.4
+signing_key: 
+specification_version: 4
+summary: Finds maximum matchings in weighted bipartite graphs
+test_files:
+- spec/acceptance/weighted_matching_spec.rb
+- spec/bipartite_graph_spec.rb
+- spec/spec_helper.rb
+- spec/unit/alternating_tree_spec.rb
+- spec/unit/edge_set_spec.rb
+- spec/unit/hungarian_algorithm_spec.rb