plexus 0.5.4 → 0.5.5

data/lib/plexus/arc.rb

@@ -0,0 +1,60 @@
+module Plexus
+  # Arc includes classes for representing egdes of directed and
+  # undirected graphs. There is no need for a Vertex class, because any ruby
+  # object can be a vertex of a graph.
+  #
+  # Arc's base is a Struct with a :source, a :target and a :label.
+  Struct.new("ArcBase", :source, :target, :label)
+
+  class Arc < Struct::ArcBase
+    def initialize(p_source, p_target, p_label = nil)
+      super(p_source, p_target, p_label)
+    end
+
+    # Ignore labels for equality.
+    def eql?(other)
+      self.class == other.class and target == other.target and source == other.source
+    end
+    alias == eql?
+
+    # Returns (v,u) if self == (u,v).
+    def reverse()
+      self.class.new(target, source, label)
+    end
+
+    # Sort support.
+    def <=>(rhs)
+      [source, target] <=> [rhs.source, rhs.target]
+    end
+
+    # Arc[1,2].to_s => "(1-2)"
+    # Arc[1,2,'test'].to_s => "(1-2 test)"
+    def to_s
+      l = label ? " '#{label.to_s}'" : ''
+      "(#{source}-#{target}#{l})"
+    end
+
+    # Hash is defined in such a way that label is not
+    # part of the hash value
+    # FIXME: I had to get rid of that in order to make to_dot_graph
+    # work, but I can't figure it out (doesn't show up in the stack!)
+    def hash
+      source.hash ^ (target.hash + 1)
+    end
+
+    # Shortcut constructor.
+    #
+    # Instead of Arc.new(1,2) one can use Arc[1,2].
+    def self.[](p_source, p_target, p_label = nil)
+      new(p_source, p_target, p_label)
+    end
+
+    def inspect
+      "#{self.class.to_s}[#{source.inspect},#{target.inspect},#{label.inspect}]"
+    end
+  end
+
+  class MultiArc < Arc
+    include ArcNumber
+  end
+end

data/lib/plexus/arc_number.rb

@@ -0,0 +1,50 @@
+module Plexus
+  # This module handles internal numbering of edges in order to differente between mutliple edges.
+  module ArcNumber
+    # Used to differentiate between mutli-edges
+    attr_accessor :number
+
+    def initialize(p_source, p_target, p_number, p_label = nil)
+      self.number = p_number
+      super(p_source, p_target, p_label)
+    end
+
+    # Returns (v,u) if self == (u,v).
+    def reverse
+      self.class.new(target, source, number, label)
+    end
+
+    # Allow for hashing of self loops.
+    def hash
+      super ^ number.hash
+    end
+
+    def to_s
+      super + "[#{number}]"
+    end
+
+    def <=>(rhs)
+      (result = super(rhs)) == 0 ? number <=> rhs.number : result
+    end
+
+    def inspect
+      "#{self.class.to_s}[#{source.inspect},#{target.inspect},#{number.inspect},#{label.inspect}]"
+    end
+
+    def eql?(rhs)
+      super(rhs) and (rhs.number.nil? or number.nil? or number == rhs.number)
+    end
+
+    def ==(rhs)
+      eql?(rhs)
+    end
+
+    # Shortcut constructor. Instead of Arc.new(1,2) one can use Arc[1,2]
+    def self.included(cl)
+      # FIXME: lacks a cl.class_eval, no?
+      def cl.[](p_source, p_target, p_number = nil, p_label = nil)
+        new(p_source, p_target, p_number, p_label)
+      end
+    end
+  end
+end

data/lib/plexus/biconnected.rb

@@ -0,0 +1,84 @@
+module Plexus
+
+  # Biconnected is a module for adding the biconnected algorithm to 
+  # UndirectedGraphs
+  module Biconnected
+
+    # biconnected computes the biconnected subgraphs
+    # of a graph using Tarjan's algorithm based on DFS. See: Robert E. Tarjan
+    # _Depth_First_Search_and_Linear_Graph_Algorithms_. SIAM Journal on 
+    # Computing, 1(2):146-160, 1972
+    #
+    # The output of the algorithm is a pair, the first value is an 
+    # array of biconnected subgraphs. The second is the set of
+    # articulation vertices.
+    #
+    # A connected graph is biconnected if the removal of any single vertex 
+    # (and all edges incident on that vertex) cannot disconnect the graph.
+    # More generally, the biconnected components of a graph are the maximal
+    # subsets of vertices such that the removal of a vertex from a particular
+    # component will not disconnect the component. Unlike connected components,
+    # vertices may belong to multiple biconnected components: those vertices
+    # that belong to more than one biconnected component are called articulation
+    # points or, equivalently, cut vertices. Articulation points are vertices
+    # whose removal would increase the number of connected components in the graph.
+    # Thus, a graph without articulation points is biconnected.
+    def biconnected
+      dfs_num     = 0
+      number      = {}; predecessor = {}; low_point   = {}
+      stack       = []; result      = []; articulation= []
+
+      root_vertex  = Proc.new {|v| predecessor[v]=v }
+      enter_vertex = Proc.new {|u| number[u]=low_point[u]=(dfs_num+=1) }
+      tree_edge  = Proc.new do |e|
+        stack.push(e)
+        predecessor[e.target] = e.source
+      end
+      back_edge  = Proc.new do |e|
+        if e.target != predecessor[e.source]
+          stack.push(e)
+          low_point[e.source] = [low_point[e.source], number[e.target]].min
+        end
+      end
+      exit_vertex = Proc.new do |u|
+        parent = predecessor[u]
+        is_articulation_point = false
+        if number[parent] > number[u]
+          parent = predecessor[parent]
+          is_articulation_point = true
+        end
+        if parent == u
+          is_articulation_point = false if (number[u] + 1) == number[predecessor[u]]
+        else
+          low_point[parent] = [low_point[parent], low_point[u]].min
+          if low_point[u] >= number[parent]
+            if number[parent] > number[predecessor[parent]]
+              predecessor[u] = predecessor[parent]
+              predecessor[parent] = u
+            end
+            result << (component = self.class.new)
+            while number[stack[-1].source] >= number[u]
+              component.add_edge!(stack.pop)
+            end
+            component.add_edge!(stack.pop)
+            if stack.empty?
+              predecessor[u] = parent
+              predecessor[parent] = u
+            end
+          end
+        end
+        articulation << u if is_articulation_point
+      end
+
+      # Execute depth first search
+      dfs({:root_vertex  => root_vertex,
+           :enter_vertex => enter_vertex, 
+           :tree_edge    => tree_edge,
+           :back_edge    => back_edge,
+           :exit_vertex  => exit_vertex})
+         
+      [result, articulation]
+    end # biconnected
+
+  end # Biconnected
+end # Plexus

data/lib/plexus/chinese_postman.rb

@@ -0,0 +1,91 @@
+module Plexus
+  module ChinesePostman    
+
+    # Returns the shortest walk that traverses all arcs at least
+    # once, returning to the specified start node.
+    def closed_chinese_postman_tour(start, weight=nil, zero=0)
+      cost, path, delta = floyd_warshall(weight, zero)
+      return nil unless cp_valid_least_cost? cost, zero
+      positive, negative = cp_unbalanced(delta)
+      f = cp_find_feasible(delta, positive, negative, zero)
+      while cp_improve(f, positive, negative, cost, zero); end
+      cp_euler_circuit(start, f, path)
+    end
+
+    private
+
+    def cp_euler_circuit(start, f, path) # :nodoc:
+      circuit = [u=v=start]
+      bridge_taken = Hash.new {|h,k| h[k] = Hash.new}
+      until v.nil?
+        if v=f[u].keys.detect {|k| f[u][k] > 0}
+          f[u][v] -= 1
+          circuit << (u = path[u][v]) while u != v 
+        else
+          unless bridge_taken[u][bridge = path[u][start]]
+            v = vertices.detect {|v1| v1 != bridge && edge?(u,v1) && !bridge_taken[u][v1]} || bridge
+            bridge_taken[u][v] = true
+            circuit << v            
+          end
+        end  
+        u=v
+      end; circuit
+    end
+
+    def cp_cancel_cycle(cost, path, f, start, zero) # :nodoc:
+      u = start; k = nil
+      begin
+        v = path[u][start]
+        k = f[v][u] if cost[u][v] < zero and (k.nil? || k > f[v][u])
+      end until (u=v) != start
+      u = start
+      begin
+        v = path[u][start]
+        cost[u][v] < zero ? f[v][u] -= k : f[u][v] += k
+      end until (u=v) != start
+      true # This routine always returns true to make cp_improve easier
+    end
+
+    def cp_improve(f, positive, negative, cost, zero) # :nodoc:
+      residual = self.class.new
+      negative.each do |u|
+        positive.each do |v|
+          residual.add_edge!(u,v,cost[u][v])
+          residual.add_edge!(v,u,-cost[u][v]) if f[u][v] != 0
+        end
+      end
+      r_cost, r_path, r_delta = residual.floyd_warshall(nil, zero)
+      i = residual.vertices.detect {|v| r_cost[v][v] and r_cost[v][v] < zero}
+      i ? cp_cancel_cycle(r_cost, r_path, f, i) : false
+    end
+
+    def cp_find_feasible(delta, positive, negative, zero) # :nodoc:
+      f = Hash.new {|h,k| h[k] = Hash.new}
+      negative.each do |i|
+        positive.each do |j|
+          f[i][j] = -delta[i] < delta[j] ? -delta[i] : delta[j]
+          delta[i] += f[i][j]
+          delta[j] -= f[i][j]
+        end
+      end; f
+    end
+
+    def cp_valid_least_cost?(c, zero) # :nodoc:
+      vertices.each do |i|
+        vertices.each do |j|
+          return false unless c[i][j] and c[i][j] >= zero
+        end
+      end; true
+    end
+
+    def cp_unbalanced(delta) # :nodoc:
+      negative = []; positive = []
+      vertices.each do |v|
+        negative << v if delta[v] < 0
+        positive << v if delta[v] > 0
+      end; [positive, negative]  
+    end
+
+  end # Chinese Postman
+end # Plexus
+

data/lib/plexus/classes/graph_classes.rb

@@ -0,0 +1,28 @@
+module Plexus
+  # A generic {GraphBuilder Graph} class you can inherit from.
+  class Graph;                         include GraphBuilder;                 end
+
+  # A generic {AdjacencyGraphBuilder AdjacencyGraph} class you can inherit from.
+  class AdjacencyGraph < Graph;        include AdjacencyGraphBuilder;        end
+
+  # A generic {DirectedGraphBuilder DirectedGraph} class you can inherit from.
+  class DirectedGraph < Graph;         include DirectedGraphBuilder;         end
+
+  # A generic {DigraphBuilder Digraph} class you can inherit from.
+  class Digraph < Graph;               include DigraphBuilder;               end
+
+  # A generic {DirectedPseudoGraphBuilder DirectedPseudoGraph} class you can inherit from.
+  class DirectedPseudoGraph < Graph;   include DirectedPseudoGraphBuilder;   end
+
+  # A generic {DirectedMultiGraphBuilder DirectedMultiGraph} class you can inherit from.
+  class DirectedMultiGraph < Graph;    include DirectedMultiGraphBuilder;    end
+
+  # A generic {UndirectedGraphBuilder UndirectedGraph} class you can inherit from.
+  class UndirectedGraph < Graph;       include UndirectedGraphBuilder;       end
+
+  # A generic {UndirectedPseudoGraphBuilder UndirectedPseudoGraph} class you can inherit from.
+  class UndirectedPseudoGraph < Graph; include UndirectedPseudoGraphBuilder; end
+
+  # A generic {UndirectedMultiGraphBuilder UndirectedMultiGraph} class you can inherit from.
+  class UndirectedMultiGraph < Graph;  include UndirectedMultiGraphBuilder;  end
+end

data/lib/plexus/common.rb

@@ -0,0 +1,63 @@
+module Plexus
+
+  # This class defines a cycle graph of size n.
+  # This is easily done by using the base Graph
+  # class and implemeting the minimum methods needed to
+  # make it work. This is a good example to look
+  # at for making one's own graph classes.
+  module CycleBuilder
+    def initialize(n)
+      @size = n;
+    end
+
+    def directed?
+      false
+    end
+
+    def vertices
+      (1..@size).to_a
+    end
+
+    def vertex?(v)
+      v > 0 and v <= @size
+    end
+
+    def edge?(u,v = nil)
+      u, v = [u.source, v.target] if u.is_a? Plexus::Arc
+      vertex?(u) && vertex?(v) && ((v-u == 1) or (u == @size && v = 1))
+    end
+
+    def edges
+      Array.new(@size) { |i| Plexus::Edge[i+1, (i+1) == @size ? 1 : i+2]}
+    end
+  end # CycleBuilder
+
+  # This class defines a complete graph of size n.
+  # This is easily done by using the base Graph
+  # class and implemeting the minimum methods needed to
+  # make it work. This is a good example to look
+  # at for making one's own graph classes.
+  module CompleteBuilder
+    include CycleBuilder
+
+    def initialize(n)
+      @size = n
+      @edges = nil
+    end
+
+    def edges
+      return @edges if @edges      # cache edges
+      @edges = []
+      @size.times do |u|
+        @size.times { |v| @edges << Plexus::Edge[u+1, v+1]}
+      end
+      @edges
+    end
+
+    def edge?(u, v = nil)
+      u, v = [u.source, v.target] if u.kind_of? Plexus::Arc
+      vertex?(u) && vertex?(v)
+    end
+  end # CompleteBuilder
+
+end # Plexus

data/lib/plexus/comparability.rb

@@ -0,0 +1,63 @@
+module Plexus
+  module Comparability
+    
+    # A comparability graph is an UndirectedGraph that has a transitive
+    # orientation. This returns a boolean that says if this graph
+    # is a comparability graph.
+    def comparability?() gamma_decomposition[1]; end
+    
+    # Returns an array with two values, the first being a hash of edges 
+    # with a number containing their class assignment, the second valud
+    # is a boolean which states whether or not the graph is a 
+    # comparability graph
+    #
+    # Complexity in time O(d*|E|) where d is the maximum degree of a vertex
+    # Complexity in space O(|V|+|E|)
+    def gamma_decomposition
+      k = 0; comparability=true; classification={}
+      edges.map {|edge| [edge.source,edge.target]}.each do |e|
+        if classification[e].nil?
+          k += 1
+          classification[e] = k; classification[e.reverse] = -k
+          comparability &&= plexus_comparability_explore(e, k, classification)
+        end
+      end; [classification, comparability]
+    end
+    
+    # Returns one of the possible transitive orientations of 
+    # the UndirectedGraph as a Digraph
+    def transitive_orientation(digraph_class=Digraph)
+      raise NotImplementError
+    end
+    
+   private
+   
+    # Taken from Figure 5.10, on pg. 130 of Martin Golumbic's, _Algorithmic_Graph_
+    # _Theory_and_Perfect_Graphs.
+    def plexus_comparability_explore(edge, k, classification, space='')
+      ret = plexus_comparability_explore_inner(edge, k, classification, :forward, space)
+      plexus_comparability_explore_inner(edge.reverse, k, classification, :backward, space) && ret
+    end
+    
+    def plexus_comparability_explore_inner(edge, k, classification, direction,space)
+      comparability = true  
+      adj_target = adjacent(edge[1])
+      adjacent(edge[0]).select do |mt|
+        (classification[[edge[1],mt]] || k).abs < k or
+        not adj_target.any? {|adj_t| adj_t == mt} 
+      end.each do |m|
+        e = (direction == :forward) ? [edge[0], m] : [m,edge[0]]
+        if classification[e].nil?
+          classification[e] = k
+          classification[e.reverse] = -k
+          comparability = plexus_comparability_explore(e, k, classification, '  '+space) && comparability
+        elsif classification[e] == -k
+          classification[e] = k
+          plexus_comparability_explore(e, k, classification, '  '+space)
+          comparability = false
+        end
+      end; comparability
+    end # plexus_comparability_explore_inner
+    
+  end # Comparability
+end # Plexus

data/lib/plexus/directed_graph.rb

@@ -0,0 +1,78 @@
+module Plexus
+
+  # This implements a directed graph which does not allow parallel
+  # edges nor loops. That is, only one arc per nodes couple,
+  # and only one parent per node. Mimics the typical hierarchy
+  # structure.
+  module DirectedGraphBuilder
+    include GraphBuilder
+
+    autoload :Algorithms, "plexus/directed_graph/algorithms"
+    autoload :Distance,   "plexus/directed_graph/distance"
+
+    # FIXME: DRY this snippet, I didn't find a clever way to
+    # to dit though
+    # TODO: well, extends_host_with do ... end would be cool,
+    # using Module.new.module_eval(&block) in the helper.
+    extends_host
+
+    module ClassMethods
+      def [](*a)
+        self.new.from_array(*a)
+      end
+    end
+
+    def initialize(*params)
+      # FIXME/TODO: setting args to the hash or {} while getting rid
+      # on the previous parameters prevents from passing another
+      # graph to the initializer, so you cannot do things like:
+      # UndirectedGraph.new(Digraph[1,2, 2,3, 2,4, 4,5, 6,4, 1,6])
+      # As args must be a hash, if we're to allow such syntax,
+      # we should provide a way to handle the graph as a hash
+      # member.
+      args = (params.pop if params.last.kind_of? Hash) || {}
+      args[:algorithmic_category] = DirectedGraphBuilder::Algorithms
+      super *(params << args)
+    end
+  end
+
+  # DirectedGraph is just an alias for Digraph should one desire
+  DigraphBuilder = DirectedGraphBuilder
+
+  # This is a Digraph that allows for parallel edges, but does not
+  # allow loops.
+  module DirectedPseudoGraphBuilder
+    include DirectedGraphBuilder
+    extends_host
+
+    module ClassMethods
+      def [](*a)
+        self.new.from_array(*a)
+      end
+    end
+
+    def initialize(*params)
+      args = (params.pop if params.last.kind_of? Hash) || {}
+      args[:parallel_edges] = true
+      super *(params << args)
+    end
+  end
+
+  # This is a Digraph that allows for both parallel edges and loops.
+  module DirectedMultiGraphBuilder
+    include DirectedPseudoGraphBuilder
+    extends_host
+
+    module ClassMethods
+      def [](*a)
+        self.new.from_array(*a)
+      end
+    end
+
+    def initialize(*params)
+      args = (params.pop if params.last.kind_of? Hash) || {}
+      args[:loops] = true
+      super *(params << args)
+    end
+  end
+end