laser 0.7.0.pre1

data/lib/laser/third_party/rgl/base.rb

@@ -0,0 +1,228 @@
+# base.rb
+#
+# Module RGL defines the namespace for all modules and classes of the graph
+# library. The main module is RGL::Graph which defines the abstract behavior of
+# all graphs in the library.
+
+RGL_VERSION = "0.4.0"
+
+module RGL
+  class NotDirectedError < RuntimeError; end
+  class NotUndirectedError < RuntimeError; end
+
+  class NoVertexError < IndexError; end
+  class NoEdgeError < IndexError; end
+
+  # Module Edge includes classes for representing egdes of directed and
+  # undirected graphs. There is no need for a Vertex class, because every ruby
+  # object can be a vertex of a graph.
+  module Edge
+    # Simply a directed pair (source -> target). Most library functions try do
+    # omit to instantiate edges. They instead use two vertex parameters for
+    # representing edges (see each_edge). If a client wants to store edges
+    # explicitly DirecteEdge or UnDirectedEdge instances are returned
+    # (i.e. Graph#edges).
+    class DirectedEdge
+      attr_accessor :source, :target
+
+      # Can be used to create an edge from a two element array.
+      def self.[](*a)
+        new(a[0],a[1])
+      end
+
+      # Create a new DirectedEdge with source _a_ and target _b_.
+      def initialize (a,b)
+        @source, @target = a,b
+      end
+      
+      # Two directed edges (u,v) and (x,y) are equal iff u == x and v == y. eql?
+      # is needed when edges are inserted into a Set. eql? is aliased to ==.
+      def eql?(edge)
+        source == edge.source and target == edge.target
+      end
+      alias == eql?
+
+      # Returns (v,u) if self == (u,v).
+      def reverse
+        self.class.new(target, source)
+      end
+
+      # Edges can be indexed. edge[0] == edge.source, edge[n] == edge.target for
+      # all n>0. Edges can thus be used as a two element array.
+      def [](index); index.zero? ? source : target; end
+
+      # DirectedEdge[1,2].to_s == "(1-2)"
+      def to_s
+        "(#{source}-#{target})"
+      end
+      # Returns the array [source,target].
+      def to_a; [source,target]; end
+
+      # Sort support is dispatched to the <=> method of Array
+      def <=> e
+        self.to_a <=> e.to_a
+      end
+    end                         # DirectedEdge
+
+    # An undirected edge is simply an undirected pair (source, target) used in
+    # undirected graphs. UnDirectedEdge[u,v] == UnDirectedEdge[v,u]
+    class UnDirectedEdge < DirectedEdge
+      def eql?(edge)
+        super or (target == edge.source and source == edge.target)
+      end
+      
+      def hash
+        source.hash ^ target.hash
+      end
+      
+      # UnDirectedEdge[1,2].to_s == "(1=2)"
+      def to_s; "(#{source}=#{target})"; end
+    end
+
+  end                           # Edge
+
+  # In BGL terminology the module Graph defines the graph concept (see
+  # http://www.boost.org/libs/graph/doc/graph_concepts.html). We however do not
+  # distinguish between the IncidenceGraph, EdgeListGraph and VertexListGraph
+	# concepts, which would complicate the interface too much. These concepts are
+	# defined in BGL to differentiate between efficient access to edges and
+	# vertices.
+  #
+  # The RGL Graph concept contains only a few requirements that are common to
+	# all the graph concepts. These include, especially, the iterators defining
+	# the sets of vertices and edges (see each_vertex and each_adjacent). Most
+	# other functions are derived from these fundamental iterators, i.e.
+	# num_vertices or num_edges.
+  #
+  # Each graph is an enumerable of vertices.
+  module Graph
+    include Enumerable
+    include Edge
+
+    # The each_vertex iterator defines the set of vertices. This method must be
+    # defined by concrete graph classes. It defines the BGL VertexListGraph
+    # concept.
+    def each_vertex () # :yields: v
+      raise NotImplementedError
+    end
+
+    # The each_adjacent iterator defines the out edges of vertex _v_. This
+    # method must be defined by concrete graph classes. Its defines the BGL
+    # IncidenceGraph concept.
+    def each_adjacent (v) # :yields: v
+      raise NotImplementedError
+    end
+
+    # The each_edge iterator should provide efficient access to all edges of the
+    # graph. Its defines the EdgeListGraph concept.
+    #
+    # This method must _not_ be defined by concrete graph classes, because it
+    # can be implemented using each_vertex and each_adjacent. However for
+    # undirected graph the function is inefficient because we must not yield
+    # (v,u) if we already visited edge (u,v).
+    def each_edge (&block)
+      if directed?
+        each_vertex { |u|
+          each_adjacent(u) { |v| yield u,v }
+        }
+      else
+        each_edge_aux(&block)       # concrete graphs should to this better
+      end
+    end
+
+    # Vertices get enumerated. A graph is thus an enumerable of vertices.
+    # ---
+    # === Testing
+    def each(&block); each_vertex(&block); end
+
+    # Is the graph directed? The default returns false.
+    def directed?; false; end
+
+    # Returns true if _v_ is a vertex of the graph. Same as #include? inherited
+    # from Enumerable. Complexity is O(num_vertices) by default. Concrete graph
+    # may be better here (see AdjacencyGraph).
+    def has_vertex?(v); include?(v); end    # inherited from enumerable
+
+    # Returns true if the graph has no vertices, i.e. num_vertices == 0.
+    # ---
+    # === accessing vertices and edges
+    def empty?; num_vertices.zero?; end
+
+    # Return the array of vertices. Synonym for #to_a inherited by Enumerable.
+    def vertices; to_a; end
+
+    # Returns the class for edges: DirectedEdge or UnDirectedEdge.
+    def edge_class; directed? ? DirectedEdge : UnDirectedEdge; end
+
+    # Return the array of edges (DirectedEdge or UnDirectedEdge) of the graph
+    # using each_edge, depending whether the graph is directed or not.
+    def edges
+      result = []
+      c = edge_class
+      each_edge { |u,v| result << c.new(u,v) }
+      result
+    end
+
+    # Returns an array of vertices adjacent to vertex _v_.
+    def adjacent_vertices (v)
+      r = []
+      each_adjacent(v) { |u| r << u }
+      r
+    end
+
+    # Returns the number of out-edges (for directed graphs) or the number of
+		# incident edges (for undirected graphs) of vertex _v_.
+    def out_degree (v)
+      r = 0
+      each_adjacent(v) { |u| r += 1}
+      r
+    end
+
+    # Returns the number of vertices.
+    def size()                  # Why not in Enumerable?
+      inject(0) { |n, v| n + 1 }
+    end
+		alias :num_vertices :size
+
+    # Returns the number of edges.
+    def num_edges; r = 0; each_edge {|u,v| r +=1}; r; end
+
+    # Utility method to show a string representation of the edges of the graph.
+    def to_s
+      edges.sort.to_s
+    end
+
+    # Equality is defined to be same set of edges and directed?
+    def eql?(g)
+      equal?(g) or
+        begin
+          g.is_a?(Graph) and directed? == g.directed? and
+            g.inject(0) { |n, v| has_vertex?(v) or return false; n+1} ==
+            num_vertices and begin
+                               ng = 0
+                               g.each_edge { |u,v| has_edge? u,v or return false; ng += 1 }
+                               ng == num_edges
+                             end
+        end
+    end
+    alias == eql?
+
+    private
+
+    def each_edge_aux
+      # needed in each_edge
+      visited = Hash.new
+      each_vertex { |u|
+        each_adjacent(u) { |v|
+          edge = UnDirectedEdge.new u,v
+          unless visited.has_key? edge
+            visited[edge]=true
+            yield u, v
+          end
+        }
+      }
+    end
+  end                           # module Graph
+
+end                             # module RGL
+

data/lib/laser/third_party/rgl/bidirectional.rb

@@ -0,0 +1,39 @@
+require 'laser/third_party/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
+  # 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
+  # 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, &blk)
+      each_predecessor(v, &blk)
+    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}
+      r
+    end
+
+    # 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)
+      in_degree(v) + out_degree(v)
+    end
+  end
+end

data/lib/laser/third_party/rgl/condensation.rb

@@ -0,0 +1,47 @@
+require 'laser/third_party/rgl/base'
+require 'laser/third_party/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
+    # 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?
+
+      # 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
+      # instances will be used to map to the number, n, with which the elements
+      # of the set are associated.
+      inv_comp_map = {}
+      comp_map.each { |v, n| (inv_comp_map[n] ||= Set.new) << v }
+
+      # Create an ImplicitGraph where the nodes are the strongly connected
+      # components of this graph and the edges are the edges of this graph which
+      # cross between the strongly connected components.
+      ImplicitGraph.new do |g|
+        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
+                b.call(inv_comp_map[comp_map[w]])
+              end
+            end
+          end
+        end
+        g.directed = true
+      end
+    end
+  end
+end

data/lib/laser/third_party/rgl/connected_components.rb

@@ -0,0 +1,138 @@
+# connected_components.rb
+#
+# This file contains the algorithms for the connected components of an
+# undirected graph (each_connected_component) and strongly connected components
+# for directed graphs (strongly_connected_components).
+#
+require 'laser/third_party/rgl/traversal'
+
+module RGL
+
+  module Graph
+
+    # Compute the connected components of an undirected graph, using a
+    # 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.
+    #
+    # The function is implemented as an iterator which calls the client
+    # 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?
+      comp = []
+      vis  = DFSVisitor.new(self)
+      vis.set_finish_vertex_event_handler { |v| comp << v }
+      vis.set_start_vertex_event_handler { |v|
+        yield comp unless comp.empty?
+        comp = []
+      }
+      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)
+        super g
+        @root_map           = {}
+        @comp_map           = {}
+        @discover_time_map  = {}
+        @dfs_time           = 0
+        @c_index            = 0
+        @stack              = []
+      end
+
+      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)
+        # 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
+            w = @stack.pop
+            @comp_map[w] = @c_index
+          end until w == v
+          @c_index += 1
+        end
+      end
+
+      # Return the number of components found so far.
+
+      def num_comp
+        @c_index
+      end
+
+      private
+
+      def min_discover_time (u, v)
+        @discover_time_map[u] < @discover_time_map[v] ? u : v
+      end
+
+    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
+    # 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
+    # from v to u. That is to say, u and v are reachable from each other.
+    # 
+    # @Article{Tarjan:1972:DFS,
+    #   author =       "R. E. Tarjan",
+    #   key =          "Tarjan",
+    #   title =        "Depth First Search and Linear Graph Algorithms",
+    #   journal =      "SIAM Journal on Computing",
+    #   volume =       "1",
+    #   number =       "2",
+    #   pages =        "146--160",
+    #   month =        jun,
+    #   year =         "1972",
+    #   CODEN =        "SMJCAT",
+    #   ISSN =         "0097-5397 (print), 1095-7111 (electronic)",
+    #   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?
+      vis = TarjanSccVisitor.new(self)
+      depth_first_search(vis) { |v| }
+      vis
+    end
+
+  end                           # module Graph
+end                             # module RGL