graph_matching 0.0.1

data/lib/graph_matching/algorithm/mwmg_delta_assertions.rb

@@ -0,0 +1,94 @@
+module GraphMatching
+  module Algorithm
+    # Can be mixed into MWMGeneral to add runtime assertions
+    # about the data structures used for delta2/delta3 calculations.
+    #
+    # > Check delta2/delta3 computation after every substage;
+    # > only works on integer weights, slows down the algorithm to O(n^4).
+    # > (Van Rantwijk, mwmatching.py, line 34)
+    #
+    module MWMGDeltaAssertions
+      def calc_delta_with_assertions(*args)
+        # > Verify data structures for delta2/delta3 computation.
+        # > (Van Rantwijk, mwmatching.py, line 739)
+        check_delta2
+        check_delta3
+        calc_delta_without_assertions(*args)
+      end
+
+      # > Check optimized delta2 against a trivial computation.
+      # > (Van Rantwijk, mwmatching.py, line 580)
+      def check_delta2
+        (0 ... @nvertex).each do |v|
+          if @label[@in_blossom[v]] == MWMGeneral::LBL_FREE
+            bd = nil
+            bk = nil
+            @neighb_end[v].each do |p|
+              k = p / 2 # Note: floor division
+              w = @endpoint[p]
+              if @label[@in_blossom[w]] == MWMGeneral::LBL_S
+                d = slack(k)
+                if bk.nil? || d < bd
+                  bk = k
+                  bd = d
+                end
+              end
+            end
+            option1 = bk.nil? && @best_edge[v].nil?
+            option2 = !@best_edge[v].nil? && bd == slack(@best_edge[v])
+            unless option1 || option2
+              fail "Assertion failed: Free vertex #{v}"
+            end
+          end
+        end
+      end
+
+      # > Check optimized delta3 against a trivial computation.
+      # > (Van Rantwijk, mwmatching.py, line 598)
+      def check_delta3
+        bk = nil
+        bd = nil
+        tbk = nil
+        tbd = nil
+        (0 ... 2 * @nvertex).each do |b|
+          if @blossom_parent[b].nil? && @label[b] == MWMGeneral::LBL_S
+            blossom_leaves(b).each do |v|
+              @neighb_end[v].each do |p|
+                k = p / 2 # Note: floor division
+                w = @endpoint[p]
+                if @in_blossom[w] != b &&
+                    @label[@in_blossom[w]] == MWMGeneral::LBL_S
+                  d = slack(k)
+                  if bk.nil? || d < bd
+                    bk = k
+                    bd = d
+                  end
+                end
+              end
+            end
+            unless @best_edge[b].nil?
+              i, j = @edges[@best_edge[b]].to_a
+              unless @in_blossom[i] == b || @in_blossom[j] == b
+                fail 'Assertion failed'
+              end
+              unless @in_blossom[i] != b || @in_blossom[j] != b
+                fail 'Assertion failed'
+              end
+              unless @label[@in_blossom[i]] == MWMGeneral::LBL_S &&
+                  @label[@in_blossom[j]] == MWMGeneral::LBL_S
+                fail 'Assertion failed'
+              end
+              if tbk.nil? || slack(@best_edge[b]) < tbd
+                tbk = @best_edge[b]
+                tbd = slack(@best_edge[b])
+              end
+            end
+          end
+        end
+        unless bd == tbd
+          fail 'Assertion failed'
+        end
+      end
+    end
+  end
+end

data/lib/graph_matching/assertion.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+module GraphMatching
+  # Provides expressive methods for common runtime assertions, e.g.
+  #
+  #   assert(banana).is_a(Fruit)
+  #
+  class Assertion
+    attr_reader :obj
+
+    def initialize(obj)
+      @obj = obj
+    end
+
+    def eq(other)
+      unless obj == other
+        fail "Expected #{other}, got #{obj}"
+      end
+    end
+
+    def gte(other)
+      unless obj >= other
+        fail "Expected #{obj} to be >= #{other}"
+      end
+    end
+
+    # rubocop:disable Style/PredicateName
+    def is_a(klass)
+      unless obj.is_a?(klass)
+        fail TypeError, "Expected #{klass}, got #{obj.class}"
+      end
+    end
+    # rubocop:enable Style/PredicateName
+
+    def not_nil
+      if obj.nil?
+        fail "Unexpected nil"
+      end
+    end
+  end
+end

data/lib/graph_matching/core_ext/set.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+
+require 'set'
+
+# There are some methods we'd like to use which were not added
+# until ruby 2.1.  Fortunately, they are implemented in ruby,
+# so we can simply copy them.  If we ever drop support for ruby 2.0,
+# this file can be deleted.
+
+unless Set.instance_methods.include?(:intersect?)
+
+  # no-doc
+  class Set
+    # Returns true if the set and the given set have at least one
+    # element in common.
+    # http://www.ruby-doc.org/stdlib-2.2.0/libdoc/set/rdoc/Set.html#method-i-intersect-3F
+    def intersect?(set)
+      unless set.is_a?(Set)
+        fail ArgumentError, "value must be a set"
+      end
+      if size < set.size
+        any? { |o| set.include?(o) }
+      else
+        set.any? { |o| include?(o) }
+      end
+    end
+
+    # Returns true if the set and the given set have no element in
+    # common. This method is the opposite of intersect?.
+    # http://www.ruby-doc.org/stdlib-2.2.0/libdoc/set/rdoc/Set.html#method-i-disjoint-3F
+    def disjoint?(set)
+      !intersect?(set)
+    end
+  end
+
+end

data/lib/graph_matching/directed_edge_set.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+module GraphMatching
+  # A `DirectedEdgeSet` is simply a set of directed edges in a
+  # graph.  Whether the graph is actually directed or not is
+  # irrelevant, we can still discuss directed edges in an undirected
+  # graph.
+  #
+  # The naive implementation would be to use ruby's `Set` and RGL's
+  # `DirectedEdge`.  This class is optimized to use a 2D array
+  # instead.  The sub-array at index i represents a set (or subset)
+  # of vertexes adjacent to i.
+  #
+  class DirectedEdgeSet
+    def initialize(graph_size)
+      @edges = Array.new(graph_size + 1) { [] }
+    end
+
+    def add(v, w)
+      edges[v] << w
+    end
+
+    def adjacent_vertices(v)
+      edges[v]
+    end
+
+    private
+
+    attr_reader :edges
+  end
+end

data/lib/graph_matching/errors.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+module GraphMatching
+  class GraphMatchingError < StandardError
+  end
+
+  # no-doc
+  class InvalidVertexNumbering < GraphMatchingError
+    def initialize(msg = nil)
+      msg ||= <<-EOS
+Expected vertexes to be consecutive positive integers \
+starting with zero
+      EOS
+      super(msg)
+    end
+  end
+
+  class DisconnectedGraph < GraphMatchingError
+  end
+
+  class NotBipartite < GraphMatchingError
+  end
+end

data/lib/graph_matching/graph/bigraph.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+require 'rgl/bipartite'
+require_relative 'graph'
+require_relative '../algorithm/mcm_bipartite'
+
+module GraphMatching
+  module Graph
+    # A bipartite graph (or bigraph) is a graph whose vertices can
+    # be divided into two disjoint sets U and V such that every
+    # edge connects a vertex in U to one in V.
+    class Bigraph < Graph
+      def maximum_cardinality_matching
+        Algorithm::MCMBipartite.new(self).match
+      end
+
+      # `partition` either returns two disjoint (complementary)
+      # proper subsets of vertexes or raises a NotBipartite error.
+      #
+      # An empty graph is partitioned into two empty sets.  This
+      # seems natural, but unfortunately is not the behavior of
+      # RGL's new `bipartite_sets` function.  So, we have to check
+      # for the empty case, but at least we don't have to implement
+      # the algorithm ourselves anymore!
+      #
+      def partition
+        if empty?
+          [Set.new, Set.new]
+        else
+          arrays = bipartite_sets
+          fail NotBipartite if arrays.nil?
+          [Set.new(arrays[0]), Set.new(arrays[1])]
+        end
+      end
+    end
+  end
+end

data/lib/graph_matching/graph/graph.rb

@@ -0,0 +1,63 @@
+# encoding: utf-8
+
+require 'rgl/adjacency'
+require 'rgl/connected_components'
+require 'set'
+require_relative '../algorithm/mcm_general'
+require_relative '../ordered_set'
+
+autoload(:SecureRandom, 'securerandom')
+
+module GraphMatching
+  module Graph
+    # Base class for all graphs.
+    class Graph < RGL::AdjacencyGraph
+      def self.[](*args)
+        super.tap(&:vertexes_must_be_integers)
+      end
+
+      def initialize(*args)
+        super
+        vertexes_must_be_integers
+      end
+
+      # `adjacent_vertex_set` is the same as `adjacent_vertices`
+      # except it returns a `Set` instead of an `Array`.  This is
+      # an optimization, performing in O(n), whereas passing
+      # `adjacent_vertices` to `Set.new` would be O(2n).
+      def adjacent_vertex_set(v)
+        s = Set.new
+        each_adjacent(v) do |u| s.add(u) end
+        s
+      end
+
+      def connected?
+        count = 0
+        each_connected_component { count += 1 }
+        count == 1
+      end
+
+      def maximum_cardinality_matching
+        Algorithm::MCMGeneral.new(self).match
+      end
+
+      def max_v
+        vertexes.max
+      end
+
+      def print
+        base_filename = SecureRandom.hex(16)
+        Visualize.new(self).png(base_filename)
+      end
+
+      def vertexes
+        to_a
+      end
+
+      def vertexes_must_be_integers
+        return if vertices.none? { |v| !v.is_a?(Integer) }
+        fail ArgumentError, 'All vertexes must be integers'
+      end
+    end
+  end
+end

data/lib/graph_matching/graph/weighted.rb

@@ -0,0 +1,112 @@
+# encoding: utf-8
+
+module GraphMatching
+  module Graph
+    # The `Weighted` module is mixed into undirected graphs to
+    # support edge weights.  Directed graphs are not supported.
+    #
+    # Data Structure
+    # --------------
+    #
+    # Weights are stored in a 2D array.  The weight of an edge i,j
+    # is stored twice, at `[i][j]` and `[j][i]`.
+    #
+    # Storing the weight twice wastes memory.  A symmetrical matrix
+    # can be stored in a 1D array (http://bit.ly/1DMfLM3)
+    # However, translating the 2D coordinates into a 1D index
+    # marginally increases the cost of access, and this is a read-heavy
+    # structure, so maybe the extra memory is an acceptable trade-off.
+    # It's also conceptually simpler, for what that's worth.
+    #
+    # If directed graphs were supported (they are not) this 2D array
+    # would be an obvious choice.
+    #
+    # Algorithms which operate on weighted graphs are tightly
+    # coupled to this data structure due to optimizations.
+    #
+    module Weighted
+      def self.included(base)
+        base.extend ClassMethods
+        base.class_eval do
+          attr_accessor :weight
+        end
+      end
+
+      # no-doc
+      module ClassMethods
+        # `.[]` is the recommended, convenient constructor for
+        # weighted graphs.  Each argument should be an array with
+        # three integers; the first two represent the edge, the
+        # third, the weight.
+        def [](*args)
+          assert_weighted_edges(args)
+          weightless_edges = args.map { |e| e.slice(0..1) }
+          g = super(*weightless_edges.flatten)
+          g.init_weights
+          args.each do |edge|
+            i, j, weight = edge[0] - 1, edge[1] - 1, edge[2]
+            g.weight[i][j] = weight
+            g.weight[j][i] = weight
+          end
+          g
+        end
+
+        # `assert_weighted_edges` asserts that `ary` is an array
+        # whose elements are all arrays of exactly three elements.
+        # (The first two represent the edge, the third, the weight)
+        def assert_weighted_edges(ary)
+          return if ary.is_a?(Array) && ary.all?(&method(:weighted_edge?))
+          fail 'Invalid array of weighted edges'
+        end
+
+        # `weighted_edge?` returns true if `e` is an array whose
+        # first two elements are integers, and whose third element
+        # is a real number.
+        def weighted_edge?(e)
+          e.is_a?(Array) &&
+            e.length == 3 &&
+            e[0, 2].all? { |i| i.is_a?(Integer) } &&
+            e[2].is_a?(Integer) || e[2].is_a?(Float)
+        end
+      end
+
+      def init_weights
+        @weight = Array.new(num_vertices) { |_| Array.new(num_vertices) }
+      end
+
+      def max_w
+        edges.map { |edge| w(edge.to_a) }.max
+      end
+
+      # Returns the weight of an edge.  Accessing `#weight` is much
+      # faster, so this method should only be used where
+      # clarity outweighs performance.
+      def w(edge)
+        i, j = edge
+        fail ArgumentError, "Invalid edge: #{edge}" if i.nil? || j.nil?
+        fail "Edge not found: #{edge}" unless has_edge?(*edge)
+        init_weights if @weight.nil?
+        @weight[i - 1][j - 1]
+      end
+
+      # `set_w` sets a single weight.  It not efficient, and is
+      # only provided for situations where constructing the entire
+      # graph with `.[]` is not convenient.
+      def set_w(edge, weight)
+        if edge[0].nil? || edge[1].nil?
+          fail ArgumentError, "Invalid edge: #{edge}"
+        end
+        unless weight.is_a?(Integer)
+          fail TypeError, "Edge weight must be integer"
+        end
+        init_weights if @weight.nil?
+        i, j = edge[0] - 1, edge[1] - 1
+        fail "Edge not found: #{edge}" unless has_edge?(*edge)
+        @weight[i] ||= []
+        @weight[j] ||= []
+        @weight[i][j] = weight
+        @weight[j][i] = weight
+      end
+    end
+  end
+end

data/lib/graph_matching/graph/weighted_bigraph.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+
+require_relative 'weighted'
+require_relative '../algorithm/mwm_bipartite'
+
+module GraphMatching
+  module Graph
+    # A bigraph whose edges have weights.  See `Weighted`.
+    class WeightedBigraph < Bigraph
+      include Weighted
+
+      def maximum_weighted_matching
+        Algorithm::MWMBipartite.new(self).match
+      end
+    end
+  end
+end