plexus 0.5.4 → 0.5.5

data/lib/plexus/directed_graph/algorithms.rb

@@ -0,0 +1,95 @@
+module Plexus
+  # Digraph is a directed graph which is a finite set of vertices
+  # and a finite set of edges connecting vertices. It cannot contain parallel
+  # edges going from the same source vertex to the same target. It also
+  # cannot contain loops, i.e. edges that go have the same vertex for source
+  # and target.
+  #
+  # DirectedPseudoGraph is a class that allows for parallel edges, and
+  # DirectedMultiGraph is a class that allows for parallel edges and loops
+  # as well.
+  module DirectedGraphBuilder
+    module Algorithms
+      include Search
+      include StrongComponents
+      include Distance
+      include ChinesePostman
+
+      # A directed graph is directed by definition.
+      #
+      # @return [Boolean] always true
+      #
+      def directed?
+        true
+      end
+
+      # A digraph uses the Arc class for edges.
+      #
+      # @return [Plexus::MultiArc, Plexus::Arc] `Plexus::MultiArc` if the graph allows for parallel edges,
+      #   `Plexus::Arc` otherwise.
+      #
+      def edge_class
+        @parallel_edges ? Plexus::MultiArc : Plexus::Arc
+      end
+
+      # Reverse all edges in a graph.
+      #
+      # @return [DirectedGraph] a copy of the receiver for which the direction of edges has
+      #   been inverted.
+      #
+      def reversal
+        result = self.class.new
+        edges.inject(result) { |a,e| a << e.reverse}
+        vertices.each { |v| result.add_vertex!(v) unless result.vertex?(v) }
+        result
+      end
+
+      # Check whether the graph is oriented or not.
+      #
+      # @return [Boolean]
+      #
+      def oriented?
+        e = edges
+        re = e.map { |x| x.reverse}
+        not e.any? { |x| re.include?(x)}
+      end
+
+      # Balanced is the state when the out edges count is equal to the in edges count.
+      #
+      # @return [Boolean]
+      #
+      def balanced?(v)
+        out_degree(v) == in_degree(v)
+      end
+
+      # Returns out_degree(v) - in_degree(v).
+      #
+      def delta(v)
+        out_degree(v) - in_degree(v)
+      end
+
+      def community(node, direction)
+        nodes, stack = {}, adjacent(node, :direction => direction)
+        while n = stack.pop
+          unless nodes[n.object_id] || node == n
+            nodes[n.object_id] = n
+            stack += adjacent(n, :direction => direction)
+          end
+        end
+        nodes.values
+      end
+
+      def descendants(node)
+        community(node, :out)
+      end
+
+      def ancestors(node)
+        community(node, :in)
+      end
+
+      def family(node)
+        community(node, :all)
+      end
+    end
+  end
+end

data/lib/plexus/directed_graph/distance.rb

@@ -0,0 +1,167 @@
+module Plexus
+  module DirectedGraphBuilder
+
+    # This module provides algorithms computing distance between
+    # vertices.
+    module Distance
+      
+      # Shortest path computation.
+      #
+      # From: Jorgen Band-Jensen and Gregory Gutin,
+      # [*Digraphs: Theory, Algorithms and Applications*](http://www.springer.com/mathematics/numbers/book/978-1-84800-997-4), pg. 53-54.
+      # Complexity `O(n+m)`.
+      #
+      # Requires the graph to be acyclic. If the graph is not acyclic,
+      # then see {Distance#dijkstras_algorithm} or {Distance#bellman_ford_moore}
+      # for possible solutions.
+      #
+      # @param [vertex] start the starting vertex 
+      # @param [Proc, #[]] weight can be a `Proc`, or anything else accessed using the `[]`
+      #   operator. If not a `Proc`, and if no label accessible through `[]`, it will
+      #   default to using the value stored in the label for the {Arc}. If a `Proc`, it will 
+      #   pass the edge to the proc and use the resulting value.
+      # @param [Integer] zero used for math systems with a different definition of zero
+      #
+      # @return [Hash] a hash with the key being a vertex and the value being the
+      # distance. A missing vertex from the hash is equivalent to an infinite distance.
+      def shortest_path(start, weight = nil, zero = 0)
+        dist = { start => zero }
+        path = {}
+        topsort(start) do |vi|
+          next if vi == start
+          dist[vi], path[vi] = adjacent(vi, :direction => :in).map do |vj|
+            [dist[vj] + cost(vj,vi,weight), vj] 
+          end.min { |a,b| a[0] <=> b[0]}
+        end; 
+        dist.keys.size == vertices.size ? [dist, path] : nil
+      end   
+      
+      # Finds the distance from a given vertex in a weighted digraph
+      # to the rest of the vertices, provided all the weights of arcs
+      # are non-negative.
+      #
+      # If negative arcs exist in the graph, two basic options exist:
+      #
+      # * modify all weights to be positive using an offset (temporary at least)
+      # * use the {Distance#bellman_ford_moore} algorithm.
+      #
+      # Also, if the graph is acyclic, use the {Distance#shortest_path algorithm}.
+      #
+      # From: Jorgen Band-Jensen and Gregory Gutin,
+      # [*Digraphs: Theory, Algorithms and Applications*](http://www.springer.com/mathematics/numbers/book/978-1-84800-997-4), pg. 53-54.
+      #
+      # Complexity `O(n*log(n) + m)`.
+      # 
+      # @param [vertex] s
+      # @param [Proc, #[]] weight can be a `Proc`, or anything else accessed using the `[]`
+      #   operator. If not a `Proc`, and if no label accessible through `[]`, it will
+      #   default to using the value stored in the label for the {Arc}. If a `Proc`, it will 
+      #   pass the edge to the proc and use the resulting value.
+      # @param [Integer] zero used for math systems with a different definition of zero
+      # @return [Hash] a hash with the key being a vertex and the value being the
+      #   distance. A missing vertex from the hash is equivalent to an infinite distance.
+      def dijkstras_algorithm(s, weight = nil, zero = 0)
+        q = vertices; distance = { s => zero }
+        path = {}
+        while not q.empty?
+          v = (q & distance.keys).inject(nil) { |a,k| (!a.nil?) && (distance[a] < distance[k]) ? a : k} 
+          q.delete(v)
+          (q & adjacent(v)).each do |u|
+            c = cost(v, u, weight)
+            if distance[u].nil? or distance[u] > (c + distance[v])
+              distance[u] = c + distance[v]
+              path[u] = v
+            end
+          end
+        end
+        [distance, path]
+      end
+
+      # Finds the distances from a given vertex in a weighted digraph
+      # to the rest of the vertices, provided the graph has no negative cycle.
+      #
+      # If no negative weights exist, then {Distance#dijkstras_algorithm} is more
+      # efficient in time and space. Also, if the graph is acyclic, use the
+      # {Distance#shortest_path} algorithm.
+      #
+      # From: Jorgen Band-Jensen and Gregory Gutin,
+      # [*Digraphs: Theory, Algorithms and Applications*](http://www.springer.com/mathematics/numbers/book/978-1-84800-997-4), pg. 56-58..
+      #
+      # Complexity `O(nm)`.
+      #
+      # @param [vertex] s
+      # @param [Proc, #[]] weight can be a `Proc`, or anything else accessed using the `[]`
+      #   operator. If not a `Proc`, and if no label accessible through `[]`, it will
+      #   default to using the value stored in the label for the {Arc}. If a `Proc`, it will 
+      #   pass the edge to the proc and use the resulting value.
+      # @param [Integer] zero used for math systems with a different definition of zero
+      # @return [Hash] a hash with the key being a vertex and the value being the
+      #   distance. A missing vertex from the hash is equivalent to an infinite distance.
+      def bellman_ford_moore(start, weight = nil, zero = 0)
+        distance = { start => zero }
+        path = {}
+        2.upto(vertices.size) do
+          edges.each do |e|
+            u, v = e[0], e[1]
+            unless distance[u].nil?
+              c = cost(u, v, weight) + distance[u]
+              if distance[v].nil? or c < distance[v]
+                distance[v] = c
+                path[v] = u
+              end 
+            end        
+          end
+        end
+        [distance, path]
+      end
+      
+      # Uses the Floyd-Warshall algorithm to efficiently find
+      # and record shortest paths while establishing at the same time
+      # the costs for all vertices in a graph.
+      #
+      # See S.Skiena, *The Algorithm Design Manual*, Springer Verlag, 1998 for more details.
+      #
+      # O(n^3) complexity in time.
+      #  
+      # @param [Proc, nil] weight specifies how an edge weight is determined.
+      #   If it's a `Proc`, the {Arc} is passed to it; if it's `nil`, it will just use
+      #   the value in the label for the Arc; otherwise the weight is
+      #   determined by applying the `[]` operator to the value in the 
+      #   label for the {Arc}.
+      # @param [Integer] zero defines the zero value in the math system used.
+      #   This allows for no assumptions to be made about the math system and
+      #   fully functional duck typing.
+      # @return [Array(matrice, matrice, Hash)] a pair of matrices and a hash of delta values. 
+      #   The matrices will be indexed by two vertices and are implemented as a Hash of Hashes.
+      #   The first matrix is the cost, the second matrix is the shortest path spanning tree.
+      #   The delta (difference of number of in-edges and out-edges) is indexed by vertex.
+      def floyd_warshall(weight = nil, zero = 0)
+        c     = Hash.new { |h,k| h[k] = Hash.new }
+        path  = Hash.new { |h,k| h[k] = Hash.new }
+        delta = Hash.new { |h,k| h[k] = 0 }
+        edges.each do |e| 
+          delta[e.source] += 1
+          delta[e.target] -= 1
+          path[e.source][e.target] = e.target      
+          c[e.source][e.target] = cost(e, weight)
+        end
+        vertices.each do |k|
+          vertices.each do |i|
+            if c[i][k]
+              vertices.each do |j|
+                if c[k][j] && 
+                    (c[i][j].nil? or c[i][j] > (c[i][k] + c[k][j]))
+                  path[i][j] = path[i][k]
+                  c[i][j] = c[i][k] + c[k][j]
+                  return nil if i == j and c[i][j] < zero
+                end
+              end
+            end  
+          end
+        end
+        [c, path, delta]
+      end
+
+    end # Distance
+  end # DirectedGraph
+end # Plexus

data/lib/plexus/dot.rb

@@ -0,0 +1,94 @@
+module Plexus
+  module Dot
+
+    #FIXME: don't really understood where we stand with the dot generators.
+    # RDoc ships with a dot.rb which seems pretty efficient.
+    # Are these helpers still needed, and if not, how should we replace them?
+
+    # Creates a DOT::DOTDigraph for directed graphs or a DOT::DOTSubgraph for
+    # undirected graphs.
+    #
+    # @param [Hash] params can contain any graph property specified in
+    #   rdot.rb. If an edge or vertex label is a kind of Hash, then the keys
+    #   which match dot properties will be used as well.
+    # @return [DOT::DOTDigraph, DOT::DOTSubgraph]
+    def to_dot_graph(params = {})
+      params['name'] ||= self.class.name.gsub(/:/, '_')
+      fontsize         = params['fontsize'] ? params['fontsize'] : '8'
+      graph            = (directed? ? DOT::DOTDigraph : DOT::DOTSubgraph).new(params)
+      edge_klass       =  directed? ? DOT::DOTDirectedArc : DOT::DOTArc
+
+      vertices.each do |v|
+        name = v.to_s || v.__id__.to_s
+        name = name.dup.gsub(/"/, "'")
+
+        params = { 'name'     => '"'+ name +'"',
+                   'fontsize' => fontsize,
+                   'label'    => name}
+
+        v_label = vertex_label(v)
+        params.merge!(v_label) if v_label and v_label.kind_of? Hash
+
+        graph << DOT::DOTNode.new(params)
+      end
+
+      edges.each do |e|
+        if e.source.to_s.nil?
+          source_label = e.source.__id__.to_s
+        else
+          source_label = e.source.to_s.dup
+        end
+
+        if e.target.to_s.nil?
+          target_label = e.target.__id__.to_s
+        else
+          target_label = e.target.to_s.dup
+        end
+
+        source_label.gsub!(/"/, "'")
+        target_label.gsub!(/"/, "'")
+
+        params = { 'from'     => '"'+ source_label + '"',
+                   'to'       => '"'+ target_label + '"',
+                   'fontsize' => fontsize }
+
+        e_label = edge_label(e)
+        params.merge!(e_label) if e_label and e_label.kind_of? Hash
+
+        graph << edge_klass.new(params)
+      end
+
+      graph
+    end
+
+    # Output the dot format as a string
+    def to_dot(params = {})
+      to_dot_graph(params).to_s
+    end
+
+    # Call +dotty+ for the graph which is written to the file 'graph.dot'
+    # in the # current directory.
+    def dotty(params = {}, dotfile = 'graph.dot')
+      File.open(dotfile, 'w') {|f| f << to_dot(params) }
+      system('dotty', dotfile)
+    end
+
+    # Use +dot+ to create a graphical representation of the graph. Returns the
+    # filename of the graphics file.
+    def write_to_graphic_file(fmt = 'png', dotfile = 'graph')
+      src = dotfile + '.dot'
+      dot = dotfile + '.' + fmt
+
+      # DOT::DOTSubgraph creates subgraphs, but that's broken.
+      buffer = self.to_dot
+      buffer.gsub!(/^subgraph/, "graph")
+
+      File.open(src, 'w') {|f| f << buffer << "\n"}
+      system( "dot -T#{fmt} #{src} -o #{dot}" )
+
+      dot
+    end
+    alias as_dot_graphic write_to_graphic_file
+
+  end # Dot
+end # module Plexus

data/lib/plexus/edge.rb

@@ -0,0 +1,38 @@
+module Plexus
+  # An undirected edge is simply an undirected pair (source, target) used in
+  # undirected graphs. Edge[u,v] == Edge[v,u]
+  class Edge < Arc
+
+    # Equality allows for the swapping of source and target
+    def eql?(other)
+      super or (self.class == other.class and target == other.source and source == other.target)
+    end
+    alias == eql?
+
+    # Hash is defined such that source and target can be reversed and the
+    # hash value will be the same
+    def hash
+      source.hash ^ target.hash
+    end
+
+    # Sort support
+    def <=>(rhs)
+      [[source,target].max, [source,target].min] <=> [[rhs.source,rhs.target].max, [rhs.source,rhs.target].min]
+    end
+
+    # Edge[1,2].to_s => "(1=2)"
+    # Edge[2,1].to_s => "(1=2)"
+    # Edge[2,1,'test'].to_s => "(1=2 test)"
+    def to_s
+      l = label ? " '#{label.to_s}'" : ''
+      s = source.to_s
+      t = target.to_s
+      "(#{[s,t].min}=#{[s,t].max}#{l})"
+    end
+
+  end
+
+  class MultiEdge < Edge
+    include ArcNumber
+  end
+end

data/lib/plexus/ext.rb

@@ -0,0 +1,79 @@
+class Object
+  # Get the singleton class of the object.
+  # Depending on the object which requested its singleton class,
+  # a `module_eval` or a `class_eval` will be performed.
+  # Object of special constant type (`Fixnum`, `NilClass`, `TrueClass`,
+  # `FalseClass` and `Symbol`) return `nil` as they do not have a
+  # singleton class.
+  #
+  # @return the singleton class
+  def singleton_class
+    if self.respond_to? :module_eval
+      self.module_eval("class << self; self; end")
+    elsif self.respond_to? :instance_eval
+      begin
+        self.instance_eval("class << self; self; end")
+      rescue TypeError
+        nil
+      end
+    end
+  end
+
+  # Check wether the object is of the specified kind.
+  # If the receiver has a singleton class, will also perform
+  # the check on its singleton class' ancestors, so as to catch
+  # any included modules for object instances.
+  #
+  # Example:
+  #
+  #     class A; include Digraph; end
+  #     a.singleton_class.ancestors
+  #     # => [Plexus::GraphAPI, Plexus::DirectedGraph::Algorithms, ...
+  #           Plexus::Labels, Enumerable, Object, Plexus, Kernel, BasicObject]
+  #     a.is_a? Plexus::Graph
+  #     # => true
+  #
+  # @param [Class] klass
+  # @return [Boolean]
+  def is_a? klass
+    sc = self.singleton_class
+    if not sc.nil?
+      self.singleton_class.ancestors.include?(klass) || super
+    else
+      super
+    end
+  end
+end
+
+class Module
+  # Helper which purpose is, given a class including a module,
+  # to make each methods defined within a module's submodule `ClassMethods`
+  # available as class methods to the receiving class.
+  #
+  # Example:
+  #
+  #     module A
+  #       extends_host
+  #       module ClassMethods
+  #         def selfy; puts "class method for #{self}"; end
+  #       end
+  #     end
+  #
+  #     class B; include A; end
+  #
+  #     B.selfy
+  #     # => class method for B
+  #
+  # @option *params [Symbol] :with (:ClassMethods) the name of the
+  #   module to extend the receiver with
+  def extends_host(*params)
+    args = (params.pop if params.last.is_a? Hash) || {}
+    @_extension_module = args[:with] || :ClassMethods
+
+    def included(base)
+      unless @_extension_module.nil?
+        base.extend(self.const_get(@_extension_module))
+      end
+    end
+  end
+end