rgl 0.4.0 → 0.5.0

data/lib/rgl/dijkstra.rb

@@ -0,0 +1,158 @@
+require 'rgl/dijkstra_visitor'
+require 'rgl/edge_properties_map'
+require 'rgl/path_builder'
+
+require 'delegate'
+require 'algorithms'
+
+module RGL
+
+  class DijkstraAlgorithm
+
+    # Distance combinator is a lambda that accepts the distance (usually from the source) to vertex _u_ and the weight
+    # of the edge connecting vertex _u_ to another vertex _v_ and returns the distance to vertex _v_ if it's reached
+    # through the vertex _u_. By default, the distance to vertex _u_ and the edge's weight are summed.
+    DEFAULT_DISTANCE_COMBINATOR = lambda { |distance, edge_weight| distance + edge_weight }
+
+    # Initializes Dijkstra's algorithm for a _graph_ with provided edges weights map.
+    #
+    def initialize(graph, edge_weights_map, visitor, distance_combinator = nil)
+      @graph               = graph
+      @edge_weights_map    = build_edge_weights_map(edge_weights_map)
+      @visitor             = visitor
+      @distance_combinator = distance_combinator || DEFAULT_DISTANCE_COMBINATOR
+    end
+
+    # Finds the shortest path from the _source_ to the _target_ in the graph.
+    #
+    # Returns the shortest path, if it exists, as an Array of vertices. Otherwise, returns nil.
+    #
+    def shortest_path(source, target)
+      init(source)
+      relax_edges(target, true)
+      PathBuilder.new(source, @visitor.parents_map).path(target)
+    end
+
+    # Finds the shortest path form the _source_ to every other vertex of the graph and builds shortest paths map.
+    #
+    # Returns the shortest paths map that contains the shortest path (if it exists) from the source to any vertex of the
+    # graph.
+    #
+    def shortest_paths(source)
+      find_shortest_paths(source)
+      PathBuilder.new(source, @visitor.parents_map).paths(@graph.vertices)
+    end
+
+    # Finds the shortest path from the _source_ to every other vertex.
+    #
+    def find_shortest_paths(source)
+      init(source)
+      relax_edges
+    end
+
+    private
+
+    def init(source)
+      @visitor.set_source(source)
+
+      @queue = Queue.new
+      @queue.push(source, 0)
+    end
+
+    def relax_edges(target = nil, break_on_target = false)
+      until @queue.empty?
+        u = @queue.pop
+
+        break if break_on_target && u == target
+
+        @visitor.handle_examine_vertex(u)
+
+        @graph.each_adjacent(u) do |v|
+          relax_edge(u, v) unless @visitor.finished_vertex?(v)
+        end
+
+        @visitor.color_map[u] = :BLACK
+        @visitor.handle_finish_vertex(u)
+      end
+    end
+
+    def relax_edge(u, v)
+      @visitor.handle_examine_edge(u, v)
+
+      new_v_distance = @distance_combinator.call(@visitor.distance_map[u], @edge_weights_map.edge_property(u, v))
+
+      if new_v_distance < @visitor.distance_map[v]
+        old_v_distance = @visitor.distance_map[v]
+
+        @visitor.distance_map[v] = new_v_distance
+        @visitor.parents_map[v]  = u
+
+        if @visitor.color_map[v] == :WHITE
+          @visitor.color_map[v] = :GRAY
+          @queue.push(v, new_v_distance)
+        elsif @visitor.color_map[v] == :GRAY
+          @queue.decrease_key(v, old_v_distance, new_v_distance)
+        end
+
+        @visitor.handle_edge_relaxed(u, v)
+      else
+        @visitor.handle_edge_not_relaxed(u, v)
+      end
+    end
+
+    def build_edge_weights_map(edge_weights_map)
+      edge_weights_map.is_a?(EdgePropertiesMap) ? edge_weights_map : NonNegativeEdgePropertiesMap.new(edge_weights_map, @graph.directed?)
+    end
+
+    class Queue < SimpleDelegator # :nodoc:
+
+      def initialize
+        @heap = Containers::Heap.new { |a, b| a.distance < b.distance }
+        super(@heap)
+      end
+
+      def push(vertex, distance)
+        @heap.push(vertex_key(vertex, distance), vertex)
+      end
+
+      def decrease_key(vertex, old_distance, new_distance)
+        @heap.change_key(vertex_key(vertex, old_distance), vertex_key(vertex, new_distance))
+      end
+
+      def vertex_key(vertex, distance)
+        VertexKey.new(vertex, distance)
+      end
+
+      VertexKey = Struct.new(:vertex, :distance)
+
+    end
+
+  end # class DijkstraAlgorithm
+
+  module Graph
+
+    # Finds the shortest path from the _source_ to the _target_ in the graph.
+    #
+    # If the path exists, returns it as an Array of vertices. Otherwise, returns nil.
+    #
+    # Raises ArgumentError if edge weight is negative or undefined.
+    #
+    def dijkstra_shortest_path(edge_weights_map, source, target, visitor = DijkstraVisitor.new(self))
+      DijkstraAlgorithm.new(self, edge_weights_map, visitor).shortest_path(source, target)
+    end
+
+    # Finds the shortest paths from the _source_ to each vertex of the graph.
+    #
+    # Returns a Hash that maps each vertex of the graph to an Array of vertices that represents the shortest path
+    # from the _source_ to the vertex. If the path doesn't exist, the corresponding hash value is nil. For the _source_
+    # vertex returned hash contains a trivial one-vertex path - [source].
+    #
+    # Raises ArgumentError if edge weight is negative or undefined.
+    #
+    def dijkstra_shortest_paths(edge_weights_map, source, visitor = DijkstraVisitor.new(self))
+      DijkstraAlgorithm.new(self, edge_weights_map, visitor).shortest_paths(source)
+    end
+
+  end # module Graph
+
+end # module RGL

data/lib/rgl/dijkstra_visitor.rb

@@ -0,0 +1,42 @@
+require 'rgl/base'
+require 'rgl/graph_visitor'
+
+module RGL
+
+  # Dijkstra shortest path algorithm has the following event points:
+  #
+  #  * examine_vertex
+  #  * examine_edge
+  #  * edge_relaxed
+  #  * edge_not_relaxed
+  #  * finish_vertex
+  #
+  class DijkstraVisitor
+
+    include GraphVisitor
+
+    attr_accessor :distance_map, :parents_map
+
+    def_event_handlers :edge_relaxed, :edge_not_relaxed
+
+    # Returns visitor into initial state.
+    #
+    def reset
+      super
+
+      @distance_map = Hash.new(INFINITY)
+      @parents_map  = {}
+    end
+
+    # Initializes visitor with a new source.
+    #
+    def set_source(source)
+      reset
+
+      color_map[source]    = :GRAY
+      distance_map[source] = 0
+    end
+
+  end # DijkstraVisitor
+
+end # RGL

data/lib/rgl/dot.rb

@@ -1,6 +1,6 @@
 # dot.rb
 #
-# $Id: dot.rb,v 1.8 2008/08/26 20:07:09 javanthropus Exp $
+# $Id$
 #
 # Minimal Dot support, based on Dave Thomas's dot module (included in rdoc).
 # rdot.rb is a modified version which also contains support for undirected
@@ -12,50 +12,57 @@ module RGL
 
   module Graph
 
-  # Return a RGL::DOT::Digraph for directed graphs or a DOT::Subgraph for an
-  # undirected Graph.  _params_ can contain any graph property specified in
-  # rdot.rb.
+    # Return a RGL::DOT::Digraph for directed graphs or a DOT::Graph for an
+    # undirected Graph. _params_ can contain any graph property specified in
+    # rdot.rb.
+    #
+    def to_dot_graph(params = {})
+      params['name'] ||= self.class.name.gsub(/:/, '_')
+      fontsize       = params['fontsize'] ? params['fontsize'] : '8'
+      graph          = (directed? ? DOT::Digraph : DOT::Graph).new(params)
+      edge_class     = directed? ? DOT::DirectedEdge : DOT::Edge
 
-  def to_dot_graph (params = {})
-    params['name'] ||= self.class.name.gsub(/:/,'_')
-    fontsize   = params['fontsize'] ? params['fontsize'] : '8'
-    graph      = (directed? ? DOT::Digraph : DOT::Subgraph).new(params)
-    edge_class = directed? ? DOT::DirectedEdge : DOT::Edge
-    each_vertex do |v|
-      name = v.to_s
-      graph << DOT::Node.new('name'     => name,
-                             'fontsize' => fontsize,
-                             'label'    => name)
-    end
-    each_edge do |u,v|
-      graph << edge_class.new('from'     => u.to_s,
-                              'to'       => v.to_s,
-                              'fontsize' => fontsize)
+      each_vertex do |v|
+        name = v.to_s
+        graph << DOT::Node.new(
+            'name'     => name,
+            'fontsize' => fontsize,
+            'label'    => name
+        )
+      end
+
+      each_edge do |u, v|
+        graph << edge_class.new(
+            'from'     => u.to_s,
+            'to'       => v.to_s,
+            'fontsize' => fontsize
+        )
       end
+
       graph
     end
 
     # Output the DOT-graph to stream _s_.
-
-    def print_dotted_on (params = {}, s = $stdout)
+    #
+    def print_dotted_on(params = {}, s = $stdout)
       s << to_dot_graph(params).to_s << "\n"
     end
 
     # Call dotty[http://www.graphviz.org] for the graph which is written to the
-    # file 'graph.dot' in the # current directory.
-
-    def dotty (params = {})
+    # file 'graph.dot' in the current directory.
+    #
+    def dotty(params = {})
       dotfile = "graph.dot"
-      File.open(dotfile, "w") {|f|
+      File.open(dotfile, "w") do |f|
         print_dotted_on(params, f)
-      }
+      end
       system("dotty", dotfile)
     end
 
     # Use dot[http://www.graphviz.org] to create a graphical representation of
-    # the graph.  Returns the filename of the graphics file.
-
-    def write_to_graphic_file (fmt='png', dotfile="graph")
+    # the graph. Returns the filename of the graphics file.
+    #
+    def write_to_graphic_file(fmt='png', dotfile="graph")
       src = dotfile + ".dot"
       dot = dotfile + "." + fmt
 
@@ -63,9 +70,10 @@ module RGL
         f << self.to_dot_graph.to_s << "\n"
       end
 
-      system( "dot -T#{fmt} #{src} -o #{dot}" )
+      system("dot -T#{fmt} #{src} -o #{dot}")
       dot
     end
 
-  end                           # module Graph
-end                             # module RGL
+  end # module Graph
+
+end # module RGL

data/lib/rgl/edge_properties_map.rb

@@ -0,0 +1,55 @@
+module RGL
+
+  class EdgePropertiesMap
+
+    def initialize(edge_properties_map, directed)
+      @edge_properties_map = edge_properties_map
+      @directed = directed
+
+      check_properties
+    end
+
+    def edge_property(u, v)
+      if @directed
+        property = @edge_properties_map[[u, v]]
+      else
+        property = @edge_properties_map[[u, v]] || @edge_properties_map[[v, u]]
+      end
+
+      validate_property(property, u, v)
+
+      property
+    end
+
+    private
+
+    def check_properties
+      @edge_properties_map.each { |(u, v), property| validate_property(property, u, v) } if @edge_properties_map.respond_to?(:each)
+    end
+
+    def validate_property(property, u, v)
+      report_missing_property(property, u, v)
+    end
+
+    def report_missing_property(property, u, v)
+      raise ArgumentError.new("property of edge (#{u}, #{v}) is not defined") unless property
+    end
+
+  end # EdgePropertiesMap
+
+  class NonNegativeEdgePropertiesMap < EdgePropertiesMap
+
+    private
+
+    def validate_property(property, u, v)
+      super
+      report_negative_property(property, u, v)
+    end
+
+    def report_negative_property(property, u, v)
+      raise ArgumentError.new("property of edge (#{u}, #{v}) is negative") if property < 0
+    end
+
+  end
+
+end

data/lib/rgl/edmonds_karp.rb

@@ -0,0 +1,136 @@
+require 'rgl/edge_properties_map'
+require 'rgl/traversal'
+
+module RGL
+
+  class EdmondsKarpAlgorithm
+
+    # Initializes Edmonds-Karp algorithm for a _graph_ with provided edges capacities map.
+    #
+    def initialize(graph, edge_capacities_map)
+      raise NotDirectedError.new('Edmonds-Karp algorithm can only be applied to a directed graph') unless graph.directed?
+
+      @graph = graph
+      validate_edge_capacities(edge_capacities_map)
+      @edge_capacities_map = NonNegativeEdgePropertiesMap.new(edge_capacities_map, true)
+    end
+
+    # Finds the maximum flow from the _source_ to the _sink_ in the graph.
+    #
+    # Returns flows map as a hash that maps each edge of the graph to a flow through that edge that is required to reach
+    # the maximum total flow.
+    #
+    def maximum_flow(source, sink)
+      raise ArgumentError.new("source and sink can't be equal") if source == sink
+
+      @flow_map = Hash.new(0)
+      @residual_capacity_map = lambda { |u, v| @edge_capacities_map.edge_property(u, v) - @flow_map[[u, v]] }
+
+      loop do
+        bfs = EdmondsKarpBFSIterator.new(@graph, source, sink, @residual_capacity_map)
+
+        bfs.move_forward_until { bfs.color_map[sink] == :GRAY }
+
+        if bfs.color_map[sink] == :WHITE
+          break # no more augmenting paths
+        else
+          min_residual_capacity = INFINITY
+
+          augmenting_path = [sink]
+
+          while augmenting_path.first != source
+            v = augmenting_path.first
+            u = bfs.parents_map[v]
+
+            augmenting_path.unshift(u)
+            min_residual_capacity = [min_residual_capacity, @residual_capacity_map[u, v]].min
+          end
+
+          augmenting_path.each_cons(2) do |(u, v)|
+            @flow_map[[u, v]] += min_residual_capacity
+            @flow_map[[v, u]] -= min_residual_capacity
+          end
+        end
+      end
+
+      @flow_map
+    end
+
+    private
+
+    def validate_edge_capacities(edge_capacities_map)
+      @graph.each_edge do |u, v|
+        raise ArgumentError.new("reverse edge for (#{u}, #{v}) is missing") unless @graph.has_edge?(v, u)
+        validate_capacity(u, v, edge_capacities_map)
+      end
+    end
+
+    def validate_capacity(u, v, edge_capacities_map)
+      capacity         = get_capacity(u, v, edge_capacities_map)
+      reverse_capacity = get_capacity(v, u, edge_capacities_map)
+
+      validate_negative_capacity(u, v, capacity)
+      validate_negative_capacity(v, u, reverse_capacity)
+
+      raise ArgumentError.new("either (#{u}, #{v}) or (#{v}, #{u}) should have 0 capacity") unless [capacity, reverse_capacity].include?(0)
+    end
+
+    def get_capacity(u, v, edge_capacities_map)
+      edge_capacities_map.fetch([u, v]) { raise ArgumentError.new("capacity for edge (#{u}, #{v}) is missing") }
+    end
+
+    def validate_negative_capacity(u, v, capacity)
+      raise ArgumentError.new("capacity of edge (#{u}, #{v}) is negative") unless capacity >= 0
+    end
+
+    class EdmondsKarpBFSIterator < BFSIterator
+
+      attr_accessor :parents_map
+
+      def initialize(graph, start, stop, residual_capacities)
+        super(graph, start)
+        @residual_capacities = residual_capacities
+        @stop_vertex = stop
+      end
+
+      def reset
+        super
+        @parents_map = {}
+      end
+
+      def follow_edge?(u, v)
+        # follow only edges with positive residual capacity
+        super && @residual_capacities[u, v] > 0
+      end
+
+      def handle_tree_edge(u, v)
+        super
+        @parents_map[v] = u
+      end
+
+    end # class EdmondsKarpBFSIterator
+
+  end # class EdmondsKarpAlgorithm
+
+  module Graph
+
+    # Finds the maximum flow from the _source_ to the _sink_ in the graph.
+    #
+    # Returns flows map as a hash that maps each edge of the graph to a flow through that edge that is required to reach
+    # the maximum total flow.
+    #
+    # For the method to work, the graph should be first altered so that for each directed edge (u, v) it contains reverse
+    # edge (u, v). Capacities of the primary edges should be non-negative, while reverse edges should have zero capacity.
+    #
+    # Raises ArgumentError if the graph is not directed.
+    #
+    # Raises ArgumentError if a reverse edge is missing, edge capacity is missing, an edge has negative capacity, or a
+    # reverse edge has positive capacity.
+    #
+    def maximum_flow(edge_capacities_map, source, sink)
+      EdmondsKarpAlgorithm.new(self, edge_capacities_map).maximum_flow(source, sink)
+    end
+
+  end # module Graph
+
+end