rgl 0.4.0 → 0.5.0

data/lib/rgl/bellman_ford.rb

@@ -0,0 +1,115 @@
+require 'rgl/dijkstra_visitor'
+require 'rgl/edge_properties_map'
+require 'rgl/path_builder'
+
+require 'delegate'
+require 'algorithms'
+
+module RGL
+
+  # Bellman-Ford shortest paths algorithm has the following event points:
+  #
+  #  * examine_edge
+  #  * edge_relaxed
+  #  * edge_not_relaxed
+  #  * edge_minimized
+  #  * edge_not_minimized
+  #
+  class BellmanFordVisitor < DijkstraVisitor
+
+    def_event_handlers :edge_minimized, :edge_not_minimized
+
+    def initialize(graph)
+      super(graph)
+
+      # by default, through an exception if a negative-weight cycle is detected
+      @edge_not_minimized_event_handler = lambda do |u, v|
+        raise ArgumentError.new("there is a negative-weight cycle including edge (#{u}, #{v})")
+      end
+    end
+
+  end
+
+  class BellmanFordAlgorithm
+
+    # Initializes Bellman-Ford algorithm for a _graph_ with provided edges weights map.
+    #
+    def initialize(graph, edge_weights_map, visitor)
+      @graph            = graph
+      @edge_weights_map = EdgePropertiesMap.new(edge_weights_map, @graph.directed?)
+      @visitor          = visitor
+    end
+
+    # Finds the shortest path form the _source_ to every other vertex of the graph.
+    #
+    # 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)
+      init(source)
+      relax_edges
+      PathBuilder.new(source, @visitor.parents_map).paths(@graph.vertices)
+    end
+
+    private
+
+    def init(source)
+      @visitor.set_source(source)
+    end
+
+    def relax_edges
+      (@graph.size - 1).times do
+        @graph.each_edge do |u, v|
+          relax_edge(u, v)
+          relax_edge(v, u) unless @graph.directed?
+        end
+      end
+
+      @graph.each_edge do |u, v|
+        if @visitor.distance_map[u] + @edge_weights_map.edge_property(u, v) < @visitor.distance_map[v]
+          @visitor.handle_edge_not_minimized(u, v)
+        else
+          @visitor.handle_edge_minimized(u, v)
+        end
+      end
+    end
+
+    def relax_edge(u, v)
+      @visitor.handle_examine_edge(u, v)
+
+      new_v_distance = @visitor.distance_map[u] + @edge_weights_map.edge_property(u, v)
+
+      if new_v_distance < @visitor.distance_map[v]
+        @visitor.distance_map[v] = new_v_distance
+        @visitor.parents_map[v]  = u
+
+        @visitor.handle_edge_relaxed(u, v)
+      else
+        @visitor.handle_edge_not_relaxed(u, v)
+      end
+    end
+
+  end # class BellmanFordAlgorithm
+
+  module Graph
+
+    # 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].
+    #
+    # Unlike Dijkstra algorithm, Bellman-Ford shortest paths algorithm works with negative edge weights.
+    #
+    # Raises ArgumentError if an edge weight is undefined.
+    #
+    # Raises ArgumentError or the graph has negative-weight cycles. This behavior can be overridden my a custom handler
+    # for visitor's _edge_not_minimized_ event.
+    #
+    def bellman_ford_shortest_paths(edge_weights_map, source, visitor = BellmanFordVisitor.new(self))
+      BellmanFordAlgorithm.new(self, edge_weights_map, visitor).shortest_paths(source)
+    end
+
+  end # module Graph
+
+end # module RGL

data/lib/rgl/bidirectional.rb

@@ -3,38 +3,45 @@ require 'rgl/base'
 module RGL
 
   # BGL defines the concept BidirectionalGraph as follows:
-  # 
+  #
   # The BidirectionalGraph concept refines IncidenceGraph and adds the
-  # requirement for efficient access to the in-edges of each vertex.  This
+  # requirement for efficient access to the in-edges of each vertex. This
   # concept is separated from IncidenceGraph because, for directed graphs,
   # efficient access to in-edges typically requires more storage space,
-  # and many algorithms do not require access to in-edges.  For undirected
+  # and many algorithms do not require access to in-edges. For undirected
   # graphs, this is not an issue; because the in_edges() and out_edges()
   # functions are the same, they both return the edges incident to the vertex.
+  #
   module BidirectionalGraph
+
     include Graph
 
     # Iterator providing access to the in-edges (for directed graphs) or incident
     # edges (for undirected graphs) of vertex _v_. For both directed and
     # undirected graphs, the target of an out-edge is required to be vertex _v_
     # and the source is required to be a vertex that is adjacent to _v_.
-    def each_in_neighbor (v)
+    #
+    def each_in_neighbor(v)
       raise NotImplementedError
       yield u
     end
-    
+
     # Returns the number of in-edges (for directed graphs) or the number of
     # incident edges (for undirected graphs) of vertex _v_.
-    def in_degree (v)
-      r = 0;
-      each_in_neighbor(v) { |u| r += 1}
+    #
+    def in_degree(v)
+      r = 0
+      each_in_neighbor(v) { |u| r += 1 }
       r
     end
 
-    # Returns the number of in-edges plus out-edges (for directed graphs) or the 
+    # Returns the number of in-edges plus out-edges (for directed graphs) or the
     # number of incident edges (for undirected graphs) of vertex _v_.
-    def degree (v)
+    #
+    def degree(v)
       in_degree(v) + out_degree(v)
     end
+
   end
+
 end

data/lib/rgl/bipartite.rb

@@ -0,0 +1,87 @@
+require 'rgl/base'
+require 'rgl/traversal'
+
+module RGL
+
+  module Graph
+
+    # Separates graph's vertices into two disjoint sets so that every edge of the graph connects vertices from different
+    # sets. If it's possible, the graph is bipartite.
+    #
+    # Returns an array of two disjoint vertices sets (represented as arrays) if the graph is bipartite. Otherwise,
+    # returns nil.
+    #
+    def bipartite_sets
+      raise NotUndirectedError.new('bipartite sets can only be found for an undirected graph') if directed?
+
+      bfs = BipartiteBFSIterator.new(self)
+
+      # if necessary, we start BFS from each vertex to make sure
+      # that all connected components of the graph are processed
+      each_vertex do |u|
+        next if bfs.finished_vertex?(u)
+
+        bfs.reset_start(u)
+        bfs.move_forward_until { @found_odd_cycle }
+
+        return if bfs.found_odd_cycle
+      end
+
+      bfs.bipartite_sets_map.inject([[], []]) do |sets, (vertex, set)|
+        sets[set] << vertex
+        sets
+      end
+    end
+
+    # Returns true if the graph is bipartite. Otherwise returns false.
+    #
+    def bipartite?
+      !bipartite_sets.nil?
+    end
+
+  end # module Graph
+
+  class BipartiteBFSIterator < BFSIterator
+
+    attr_reader :bipartite_sets_map, :found_odd_cycle
+
+    def reset
+      super
+
+      @bipartite_sets_map = {}
+      @found_odd_cycle = false
+    end
+
+    def set_to_begin
+      super
+
+      @bipartite_sets_map[@start_vertex] = 0
+    end
+
+    def reset_start(new_start)
+      @start_vertex = new_start
+      set_to_begin
+    end
+
+    def handle_tree_edge(u, v)
+      @bipartite_sets_map[v] = (@bipartite_sets_map[u] + 1) % 2 unless u.nil?  # put v into the other set
+    end
+
+    def handle_back_edge(u, v)
+      verify_odd_cycle(u, v)
+    end
+
+    def handle_forward_edge(u, v)
+      verify_odd_cycle(u, v)
+    end
+
+    private
+
+    def verify_odd_cycle(u, v)
+      u_set = @bipartite_sets_map[u]
+      @found_odd_cycle = true if u_set && u_set == @bipartite_sets_map[v]
+    end
+
+  end # class BipartiteBFSIterator
+
+end # module RGL

data/lib/rgl/condensation.rb

@@ -1,23 +1,28 @@
 require 'rgl/base'
+require 'rgl/connected_components'
 require 'rgl/implicit'
 
 module RGL
+
   module Graph
+
     # Returns an RGL::ImplicitGraph where the strongly connected components of
     # this graph are condensed into single nodes represented by Set instances
-    # containing the members of each strongly connected component.  Edges
+    # containing the members of each strongly connected component. Edges
     # between the different strongly connected components are preserved while
     # edges within strongly connected components are omitted.
     #
     # Raises RGL::NotDirectedError if run on an undirected graph.
+    #
     def condensation_graph
       raise NotDirectedError,
-        "condensation_graph only supported for directed graphs" unless directed?
+            "condensation_graph only supported for directed graphs" unless directed?
 
       # Get the component map for the strongly connected components.
       comp_map = strongly_connected_components.comp_map
+
       # Invert the map such that for any number, n, in the component map a Set
-      # instance is created containing all of the nodes which map to n.  The Set
+      # instance is created containing all of the nodes which map to n. The Set
       # instances will be used to map to the number, n, with which the elements
       # of the set are associated.
       inv_comp_map = {}
@@ -30,18 +35,22 @@ module RGL
         g.vertex_iterator do |b|
           inv_comp_map.each_value(&b)
         end
+
         g.adjacent_iterator do |scc, b|
           scc.each do |v|
             each_adjacent(v) do |w|
               # Do not make the cluster reference itself in the graph.
-              if comp_map[v] != comp_map[w] then
+              if comp_map[v] != comp_map[w]
                 b.call(inv_comp_map[comp_map[w]])
               end
             end
           end
         end
+
         g.directed = true
       end
     end
+
   end
+
 end

data/lib/rgl/connected_components.rb

@@ -11,7 +11,7 @@ module RGL
   module Graph
 
     # Compute the connected components of an undirected graph, using a
-    # DFS (Depth-first search)-based approach.  A _connected component_ of
+    # DFS (Depth-first search)-based approach. A _connected component_ of
     # an undirected graph is a set of vertices that are all reachable
     # from each other.
     #
@@ -19,32 +19,35 @@ module RGL
     # with an array of vertices for each component.
     #
     # It raises an exception if the graph is directed.
-
+    #
     def each_connected_component
       raise NotUndirectedError,
-        "each_connected_component only works " +
-        "for undirected graphs." if directed?
+            "each_connected_component only works " +
+                "for undirected graphs." if directed?
+
       comp = []
       vis  = DFSVisitor.new(self)
       vis.set_finish_vertex_event_handler { |v| comp << v }
-      vis.set_start_vertex_event_handler { |v|
+
+      vis.set_start_vertex_event_handler do |v|
         yield comp unless comp.empty?
         comp = []
-      }
+      end
+
       depth_first_search(vis) { |v| }
       yield comp unless comp.empty?
     end
 
     # This GraphVisitor is used by strongly_connected_components to compute
     # the strongly connected components of a directed graph.
-
+    #
     class TarjanSccVisitor < DFSVisitor
 
       attr_reader :comp_map
 
       # Creates a new TarjanSccVisitor for graph _g_, which should be directed.
-
-      def initialize (g)
+      #
+      def initialize(g)
         super g
         @root_map           = {}
         @comp_map           = {}
@@ -54,25 +57,28 @@ module RGL
         @stack              = []
       end
 
-      def handle_examine_vertex (v)
-        @root_map[v] =  v
-        @comp_map[v] =  -1
-        @dfs_time    += 1
+      def handle_examine_vertex(v)
+        @root_map[v] = v
+        @comp_map[v] = -1
+        @dfs_time += 1
         @discover_time_map[v] = @dfs_time
         @stack.push(v)
       end
 
-      def handle_finish_vertex (v)
+      def handle_finish_vertex(v)
         # Search adjacent vertex w with earliest discover time
         root_v = @root_map[v]
+
         graph.each_adjacent(v) do |w|
           if @comp_map[w] == -1
             root_v = min_discover_time(root_v, @root_map[w])
           end
         end
+
         @root_map[v] = root_v
-        if root_v == v                  # v is topmost vertex of a SCC
-          begin                         # pop off all vertices until v
+
+        if root_v == v # v is topmost vertex of a SCC
+          begin # pop off all vertices until v
             w = @stack.pop
             @comp_map[w] = @c_index
           end until w == v
@@ -81,32 +87,32 @@ module RGL
       end
 
       # Return the number of components found so far.
-
+      #
       def num_comp
         @c_index
       end
 
       private
 
-      def min_discover_time (u, v)
+      def min_discover_time(u, v)
         @discover_time_map[u] < @discover_time_map[v] ? u : v
       end
 
-    end		# class TarjanSccVisitor
+    end # class TarjanSccVisitor
 
     # This is Tarjan's algorithm for strongly connected components, from his
-    # paper "Depth first search and linear graph algorithms".  It calculates
-    # the components in a single application of DFS.  We implement the
+    # paper "Depth first search and linear graph algorithms". It calculates
+    # the components in a single application of DFS. We implement the
     # algorithm with the help of the DFSVisitor TarjanSccVisitor.
     #
     # === Definition
-    # 
+    #
     # A _strongly connected component_ of a directed graph G=(V,E) is a
     # maximal set of vertices U which is in V, such that for every pair of
-    # vertices u and  v in U, we have both a path from u to v and a path
+    # vertices u and v in U, we have both a path from u to v and a path
     # from v to u. That is to say, u and v are reachable from each other.
-    # 
-    # @Article{Tarjan:1972:DFS,
+    #
+    # @Article!{Tarjan:1972:DFS,
     #   author =       "R. E. Tarjan",
     #   key =          "Tarjan",
     #   title =        "Depth First Search and Linear Graph Algorithms",
@@ -121,18 +127,20 @@ module RGL
     #   bibdate =      "Thu Jan 23 09:56:44 1997",
     #   bibsource =    "Parallel/Multi.bib, Misc/Reverse.eng.bib",
     # }
-    # 
+    #
     # The output of the algorithm is recorded in a TarjanSccVisitor _vis_.
     # vis.comp_map will contain numbers giving the component ID assigned to
     # each vertex. The number of components is vis.num_comp.
-
+    #
     def strongly_connected_components
       raise NotDirectedError,
-        "strong_components only works for directed graphs." unless directed?
+            "strong_components only works for directed graphs." unless directed?
+
       vis = TarjanSccVisitor.new(self)
       depth_first_search(vis) { |v| }
       vis
     end
 
-  end                           # module Graph
-end                             # module RGL
+  end # module Graph
+
+end # module RGL