plexus 0.5.4 → 0.5.5

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,37 @@
+Copyright (c) 2010 Jean-Denis Vauguet <jd@vauguet.fr>
+
+Copyright (c) 2009 Bruce Williams
+
+Copyright (c) 2007,2006 Shawn Patrick Garbett
+
+Copyright (c) 2002,2004,2005 by Horst Duchene
+
+Copyright (c) 2000,2001  Jeremy Siek, Indiana University (jsiek@osl.iu.edu)
+
+All rights reserved.
+
+Jeremy Siek was one of the principal developers of the Boost Graph library.
+Since this work is derivative, his name is included in the copyright list.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice(s),
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name of the Bruce Williams nor the names of its contributors
+      may be used to endorse or promote products derived from this software
+      without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,208 @@
+# Plexus (was Graphy). A framework for graph theory, graph data structures and associated algorithms.
+
+Graph algorithms currently provided are:
+
+* Topological Sort
+* Strongly Connected Components
+* Transitive Closure
+* Rural Chinese Postman
+* Biconnected
+
+These are based on more general algorithm patterns:
+
+* Breadth First Search
+* Depth First Search
+* A* Search
+* Floyd-Warshall
+* Best First Search
+* Djikstra's Algorithm
+* Lexicographic Search
+
+## A quick Tour
+
+### Arcs
+
+There are two vertices bound classes, `Plexus::Arc` and `Plexus::Edge`. The
+former defines directional edges, the latter undirected edges.
+
+### Vertices
+
+Vertices can be any `Object`.
+
+### Graph Types
+
+There are a number of different graph types, each of which provide
+different features and constraints:
+
+`Plexus::Digraph` and its alias `Plexus::DirectedGraph`:
+
+* Single directed edges (arcs) between vertices
+* Loops are forbidden
+
+`Plexus::DirectedPseudoGraph`:
+
+* Multiple directed edges (arcs) between vertices
+* Loops are forbidden
+
+`Plexus::DirectedMultiGraph`:
+
+* Multiple directed edges (arcs) between vertices
+* Loops on vertices
+
+`Plexus::UndirectedGraph`, `Plexus::UndirectedPseudoGraph`, and
+`Graph::UndirectedMultiGraph` are similar but all edges are undirected.
+
+### Data Structures
+
+In order to modelize data structures, make use of the `Plexus::AdjacencyGraph`
+module which provides a generalized adjacency list and an edge list adaptor.
+
+The `Plexus::Digraph` class is the general purpose "swiss army knife" of graph
+classes, most of the other classes are just modifications to this class.
+It is optimized for efficient access to just the out-edges, fast vertex
+insertion and removal at the cost of extra space overhead, etc.
+
+## Example Usage
+
+Using IRB, first require the library:
+
+``` bash
+require 'rubygems' # only if you are using ruby 1.8.x
+require 'plexus'
+```
+
+If you'd like to include all the classes in the current scope (so you
+don't have to prefix with `Plexus::`), just:
+
+``` bash
+include Plexus
+```
+
+Let's play with the library a bit in IRB:
+
+``` bash
+>> dg = Digraph[1,2, 2,3, 2,4, 4,5, 6,4, 1,6]
+=> Plexus::Digraph[[2, 3], [1, 6], [2, 4], [4, 5], [1, 2], [6, 4]]
+```
+
+A few properties of the graph we just created:
+
+``` bash
+>> dg.directed?
+=> true
+>> dg.vertex?(4)
+=> true
+>> dg.edge?(2,4)
+=> true
+>> dg.edge?(4,2)
+=> false
+>> dg.vertices
+=> [1, 2, 3, 4, 5, 6]
+```
+
+Every object could be a vertex, even the class object `Object`:
+
+``` bash
+>> dg.vertex?(Object)
+=> false
+
+>> UndirectedGraph.new(dg).edges.sort.to_s
+=> "[Plexus::Edge[1,2,nil], Plexus::Edge[2,3,nil], Plexus::Edge[2,4,nil],
+      Plexus::Edge[4,5,nil], Plexus::Edge[1,6,nil], Plexus::Edge[6,4,nil]]"
+```
+
+Add inverse edge `(4-2)` to directed graph:
+
+``` bash
+>> dg.add_edge!(4,2)
+=> Plexus::DirectedGraph[Plexus::Arc[1,2,nil], Plexus::Arc[1,6,nil], Plexus::Arc[2,3,nil],
+                          Plexus::Arc[2,4,nil], Plexus::Arc[4,5,nil], Plexus::Arc[4,2,nil],
+                          Plexus::Arc[6,4,nil]]
+```
+
+`(4-2) == (2-4)` in the undirected graph (4-2 doesn't show up):
+
+``` bash
+    >> UndirectedGraph.new(dg).edges.sort.to_s
+    => "[Plexus::Edge[1,2,nil], Plexus::Edge[2,3,nil], Plexus::Edge[2,4,nil],
+         Plexus::Edge[4,5,nil], Plexus::Edge[1,6,nil], Plexus::Edge[6,4,nil]]"
+```
+
+`(4-2) != (2-4)` in directed graphs (both show up):
+
+``` bash
+>> dg.edges.sort.to_s
+=> "[Plexus::Arc[1,2,nil], Plexus::Arc[1,6,nil], Plexus::Arc[2,3,nil],
+      Plexus::Arc[2,4,nil], Plexus::Arc[4,2,nil], Plexus::Arc[4,5,nil],
+      Plexus::Arc[6,4,nil]]"
+
+>> dg.remove_edge! 4,2
+=> Plexus::DirectedGraph[Plexus::Arc[1,2,nil], Plexus::Arc[1,6,nil], Plexus::Arc[2,3,nil],
+                          Plexus::Arc[2,4,nil], Plexus::Arc[4,5,nil], Plexus::Arc[6,4,nil]]
+```
+
+Topological sorting is realized with an iterator:
+
+``` bash
+>> dg.topsort
+=> [1, 6, 2, 4, 5, 3]
+>> y = 0; dg.topsort { |v| y += v }; y
+=> 21
+```
+
+You can use DOT to visualize the graph:
+
+``` bash
+>> require 'plexus/dot'
+>> dg.write_to_graphic_file('jpg','visualize')
+```
+
+Here's an example showing the module inheritance hierarchy:
+
+``` bash
+>> module_graph = Digraph.new
+>> ObjectSpace.each_object(Module) do |m|
+>>   m.ancestors.each {|a| module_graph.add_edge!(m,a) if m != a}
+>> end
+>> gv = module_graph.vertices.select {|v| v.to_s.match(/Plexus/) }
+>> module_graph.induced_subgraph(gv).write_to_graphic_file('jpg','module_graph')
+```
+
+Look for more in the examples directory.
+
+## History
+
+This library is based on [GRATR][1] by Shawn Garbett (itself a fork of
+Horst Duchene's [RGL][2] library) which is heavily influenced by the [Boost][3]
+Graph Library (BGL).
+
+This fork attempts to modernize and extend the API and tests.
+
+## References
+
+For more information on Graph Theory, you may want to read:
+
+* the [documentation][3] for the Boost Graph Library
+* [the Dictionary of Algorithms and Data Structures][4]
+
+## Credits
+
+See CREDITS.markdown
+
+## TODO
+
+See TODO.markdown
+
+## CHANGELOG
+
+See CHANGELOG.markdown
+
+## License
+
+[MIT License](http://en.wikipedia.org/wiki/MIT_License). See the LICENSE file.
+
+[1]: http://gratr.rubyforge.org
+[2]: http://rgl.rubyforge.org
+[3]: http://www.boost.org/libs/graph/doc
+[4]: http://www.nist.gov/dads/HTML/graph.html
+

data/Rakefile

@@ -0,0 +1,25 @@
+# encoding: UTF-8
+require 'rubygems'
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rake'
+require 'rake/rdoctask'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Plexus'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/plexus.rb

@@ -0,0 +1,90 @@
+#--
+# Copyright (c) 2006 Shawn Patrick Garbett
+# Copyright (c) 2002,2004,2005 by Horst Duchene
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+#     * Redistributions of source code must retain the above copyright notice(s),
+#       this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright notice,
+#       this list of conditions and the following disclaimer in the documentation
+#       and/or other materials provided with the distribution.
+#     * Neither the name of the Shawn Garbett nor the names of its contributors
+#       may be used to endorse or promote products derived from this software
+#       without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#++
+
+require 'set'
+
+module Plexus
+  # Plexus internals: graph builders and additionnal behaviors
+  autoload :GraphAPI,                     'plexus/graph_api'
+
+  autoload :GraphBuilder,                 'plexus/graph'
+  autoload :AdjacencyGraphBuilder,        'plexus/adjacency_graph'
+
+  autoload :DirectedGraphBuilder,         'plexus/directed_graph'
+  autoload :DigraphBuilder,               'plexus/directed_graph'
+  autoload :DirectedPseudoGraphBuilder,   'plexus/directed_graph'
+  autoload :DirectedMultiGraphBuilder,    'plexus/directed_graph'
+
+  autoload :UndirectedGraphBuilder,       'plexus/undirected_graph'
+  autoload :UndirectedPseudoGraphBuilder, 'plexus/undirected_graph'
+  autoload :UndirectedMultiGraphBuilder,  'plexus/undirected_graph'
+
+  autoload :Arc,                          'plexus/arc'
+  autoload :ArcNumber,                    'plexus/arc_number'
+  autoload :Biconnected,                  'plexus/biconnected'
+  autoload :ChinesePostman,               'plexus/chinese_postman'
+  autoload :Common,                       'plexus/common'
+  autoload :Comparability,                'plexus/comparability'
+
+  autoload :Dot,                          'plexus/dot'
+  autoload :Edge,                         'plexus/edge'
+  autoload :Labels,                       'plexus/labels'
+  autoload :MaximumFlow,                  'plexus/maximum_flow'
+  #autoload :Rdot,                        'plexus/dot'
+  autoload :Search,                       'plexus/search'
+  autoload :StrongComponents,             'plexus/strong_components'
+
+  # Plexus classes
+  autoload :AdjacencyGraph,               'plexus/classes/graph_classes'
+  autoload :DirectedGraph,                'plexus/classes/graph_classes'
+  autoload :Digraph,                      'plexus/classes/graph_classes'
+  autoload :DirectedPseudoGraph,          'plexus/classes/graph_classes'
+  autoload :DirectedMultiGraph,           'plexus/classes/graph_classes'
+  autoload :UndirectedGraph,              'plexus/classes/graph_classes'
+  autoload :UndirectedPseudoGraph,        'plexus/classes/graph_classes'
+  autoload :UndirectedMultiGraph,         'plexus/classes/graph_classes'
+
+  # ruby stdlib extensions
+  require 'plexus/ext'
+  # ruby 1.8.x/1.9.x compatibility
+  require 'plexus/ruby_compatibility'
+end
+
+# Vendored libraries
+
+require 'pathname'
+path = Pathname.new(__FILE__)
+$LOAD_PATH.unshift(path + '../../vendor') # http://ruby.brian-amberg.de/priority-queue/
+$LOAD_PATH.unshift(path + '../../vendor/priority-queue/lib')
+
+require 'rdot'
+require 'facets/hash'
+
+require 'priority_queue/ruby_priority_queue'
+PriorityQueue = RubyPriorityQueue
+

data/lib/plexus/adjacency_graph.rb

@@ -0,0 +1,225 @@
+module Plexus
+
+  # This module provides the basic routines needed to implement the specialized builders:
+  # {DigraphBuilder}, {UndirectedGraphBuilder}, {DirectedPseudoGraphBuilder},
+  # {UndirectedPseudoGraphBuilder}, {DirectedMultiGraphBuilder} and {UndirectedMultiGraphBuilder}
+  # modules, each of them streamlining {AdjacencyGraphBuilder}'s behavior. Those
+  # implementations rely on the {GraphBuilder}, under the control of the {GraphAPI}.
+  module AdjacencyGraphBuilder
+
+    # Defines a useful `push` -> `add` alias for arrays.
+    class ArrayWithAdd < Array
+      alias add push
+    end
+
+    # This method is called by the specialized implementations
+    # upon graph creation.
+    #
+    # Initialization parameters can include:
+    #
+    # * an array of edges to add
+    # * one or several graphs to copy (will be merged if multiple)
+    # * `:parallel_edges` denotes that duplicate edges are allowed
+    # * `:loops denotes` that loops are allowed
+    #
+    # @param *params [Hash] the initialization parameters
+    #
+    def implementation_initialize(*params)
+      @vertex_dict = Hash.new
+      clear_all_labels
+
+      # FIXME: could definitely make use of the activesupport helper
+      # extract_options! and facets' reverse_merge! technique
+      # to handle parameters
+      args = (params.pop if params.last.is_a? Hash) || {}
+
+      # Basic configuration of adjacency.
+      @allow_loops    = args[:loops]          || false
+      @parallel_edges = args[:parallel_edges] || false
+      @edgelist_class = @parallel_edges ? ArrayWithAdd : Set
+      if @parallel_edges
+        @edge_number      = Hash.new
+        @next_edge_number = 0
+      end
+
+      # Copy any given graph into this graph.
+      params.select { |p| p.is_a? Plexus::GraphBuilder }.each do |g|
+        g.edges.each do |e|
+          add_edge!(e)
+          edge_label_set(e, edge_label(e)) if edge_label(e)
+        end
+        g.vertices.each do |v|
+          add_vertex!(v)
+          vertex_label_set(v, vertex_label(v)) if vertex_label(v)
+        end
+      end
+
+      # Add all array edges specified.
+      params.select { |p| p.is_a? Array }.each do |a|
+        0.step(a.size-1, 2) { |i| add_edge!(a[i], a[i+1]) }
+      end
+    end
+
+    # Returns true if v is a vertex of this Graph
+    # (an "O(1)" implementation of `vertex?`).
+    #
+    # @param [vertex] v
+    # @return [Boolean]
+    def vertex?(v)
+      @vertex_dict.has_key?(v)
+    end
+
+    # Returns true if [u,v] or u is an {Arc}
+    # (an "O(1)" implementation of `edge?`).
+    #
+    # @param [vertex] u
+    # @param [vertex] v (nil)
+    # @return [Boolean]
+    def edge?(u, v = nil)
+      u, v = u.source, u.target if u.is_a? Plexus::Arc
+      vertex?(u) and @vertex_dict[u].include?(v)
+    end
+
+    # Adds a vertex to the graph with an optional label.
+    #
+    # @param [vertex(Object)] vertex any kind of Object can act as a vertex
+    # @param [#to_s] label (nil)
+    def add_vertex!(vertex, label = nil)
+      @vertex_dict[vertex] ||= @edgelist_class.new
+      self[vertex] = label if label
+      self
+    end
+
+    # Adds an edge to the graph.
+    #
+    # Can be called in two basic ways, label is optional:
+    # @overload add_edge!(arc)
+    #   Using an explicit {Arc}
+    #   @param [Arc] arc an {Arc}[source, target, label = nil] object
+    #   @return [AdjacencyGraph] `self`
+    # @overload add_edge!(source, target, label = nil)
+    #   Using vertices to define an arc implicitly
+    #   @param [vertex] u
+    #   @param [vertex] v (nil)
+    #   @param [Label] l (nil)
+    #   @param [Integer] n (nil) {Arc arc} number of `(u, v)` (if `nil` and if `u`
+    #     has an {ArcNumber}, then it will be used)
+    #   @return [AdjacencyGraph] `self`
+    #
+    def add_edge!(u, v = nil, l = nil, n = nil)
+      n = u.number if u.class.include? ArcNumber and n.nil?
+      u, v, l = u.source, u.target, u.label if u.is_a? Plexus::Arc
+
+      return self if not @allow_loops and u == v
+
+      n = (@next_edge_number += 1) unless n if @parallel_edges
+      add_vertex!(u)
+      add_vertex!(v)
+      @vertex_dict[u].add(v)
+      (@edge_number[u] ||= @edgelist_class.new).add(n) if @parallel_edges
+
+      unless directed?
+        @vertex_dict[v].add(u)
+        (@edge_number[v] ||= @edgelist_class.new).add(n) if @parallel_edges
+      end
+
+      self[n ? edge_class[u,v,n] : edge_class[u,v]] = l if l
+      self
+    end
+
+    # Removes a given vertex from the graph.
+    #
+    # @param [vertex] v
+    # @return [AdjacencyGraph] `self`
+    def remove_vertex!(v)
+      # FIXME This is broken for multi graphs
+      @vertex_dict.delete(v)
+      @vertex_dict.each_value { |adjList| adjList.delete(v) }
+      @vertex_dict.keys.each do |u|
+        delete_label(edge_class[u,v])
+        delete_label(edge_class[v,u])
+      end
+      delete_label(v)
+      self
+    end
+
+    # Removes an edge from the graph.
+    #
+    # Can be called with both source and target as vertex,
+    # or with source and object of {Plexus::Arc} derivation.
+    #
+    # @overload remove_edge!(a)
+    #   @param [Plexus::Arc] a
+    #   @return [AdjacencyGraph] `self`
+    #   @raise [ArgumentError] if parallel edges are enabled
+    # @overload remove_edge!(u, v)
+    #   @param [vertex] u
+    #   @param [vertex] v
+    #   @return [AdjacencyGraph] `self`
+    #   @raise [ArgumentError] if parallel edges are enabled and the {ArcNumber} of `u` is zero
+    def remove_edge!(u, v = nil)
+      unless u.is_a? Plexus::Arc
+        raise ArgumentError if @parallel_edges
+        u = edge_class[u,v]
+      end
+      raise ArgumentError if @parallel_edges and (u.number || 0) == 0
+      return self unless @vertex_dict[u.source] # It doesn't exist
+      delete_label(u) # Get rid of label
+      if @parallel_edges
+        index = @edge_number[u.source].index(u.number)
+        raise NoArcError unless index
+        @vertex_dict[u.source].delete_at(index)
+        @edge_number[u.source].delete_at(index)
+      else
+        @vertex_dict[u.source].delete(u.target)
+      end
+      self
+    end
+
+    # Returns an array of vertices that the graph has.
+    #
+    # @return [Array] graph's vertices
+    def vertices
+      @vertex_dict.keys
+    end
+
+    # Returns an array of edges, most likely of class {Arc} or {Edge} depending
+    # upon the type of graph.
+    #
+    # @return [Array]
+    def edges
+      @vertex_dict.keys.inject(Set.new) do |a,v|
+        if @parallel_edges and @edge_number[v]
+          @vertex_dict[v].zip(@edge_number[v]).each do |w|
+            s, t, n = v, w[0], w[1]
+            a.add(edge_class[s, t, n, edge_label(s, t, n)])
+          end
+        else
+          @vertex_dict[v].each do |w|
+            a.add(edge_class[v, w, edge_label(v, w)])
+          end
+        end
+        a
+      end.to_a
+    end
+
+    # FIXME, EFFED UP (but why?)
+    #
+    # @fixme
+    def adjacent(x, options = {})
+      options[:direction] ||= :out
+      if !x.is_a?(Plexus::Arc) and (options[:direction] == :out || !directed?)
+        if options[:type] == :edges
+          i = -1
+          @parallel_edges ?
+            @vertex_dict[x].map { |v| e = edge_class[x, v, @edge_number[x][i+=1]]; e.label = self[e]; e } :
+            @vertex_dict[x].map { |v| e = edge_class[x, v];  e.label = self[e]; e }
+        else
+          @vertex_dict[x].to_a
+        end
+      else
+        graph_adjacent(x,options)
+      end
+    end
+  end
+end