gratr19 0.4.4

data/README

@@ -0,0 +1,335 @@
+= GRAph Theory in Ruby (GRATR)
+
+link:../gratr.jpg GRATR is a framework for graph data structures and algorithms.
+
+This project is a fork of Horst Duchene's RGL library. 
+
+The design of the library is much influenced by the Boost Graph Library (BGL)
+which is written in C++ heavily using its template mechanism. Refer to
+http://www.boost.org/libs/graph/doc for further links and documentation on graph
+data structures and algorithms and the design rationales of BGL.
+
+A comprehensive summary of graph terminology can be found in the the graph
+section of the <em>Dictionary of Algorithms and Data Structures</em> at
+http://www.nist.gov/dads/HTML/graph.html.
+
+There are two Arc classes, GRATR::Arc and GRATR::Edge.
+
+GRATR::Digraph and it's pseudonym GRATR::DirectedGraph are classes that have single directed edges
+between vertices and loops are forbidden.  GRATR::DirectedPseudoGraph allows for
+multiple directed edges between vertices and loops are forbidden.
+GRATR::DirectedMultiGraph allows for multiple directed edges between vertices and
+loops on vertices.
+
+GRATR::UndirectedGraph, GRATR::UndirectedPseudoGraph and GRATR::UndirectedMultiGraph are similar
+but all edges are undirected.
+
+These classes are all available with a <tt>require 'gratr'</tt> statement in your Ruby code. If one wishes
+to pull the classes into the current namespace, i.e. drop the <tt>GRATR::</tt> from all
+class statements and use <tt>require 'gratr/import'</tt> instead.
+
+== Design principles
+
+This document concentrates on the special issues of the implementation in
+Ruby. The main design goals directly taken from the BGL design are:
+
+* An interface for how the structure of a graph can be accessed using a generic
+  interface that hides the details of the graph data structure
+  implementation. This interface is defined by the module Graph, which should be
+  included in concrete classes.
+
+* A standardized generic interface for traversing graphs using standard 
+  Ruby block iterators.
+
+* Implementation is separated from interface, and hidden from the average user. 
+  An advanced user could also easily override the internals with a different
+  implementation if need be.
+
+GRATR provides some general purpose graph classes that conform to this interface,
+but they are not meant to be the *only* graph classes. As in BGL I believe that
+the main contribution of the GRATR is the formulation of this interface.
+
+The BGL graph interface and graph components are generic in the sense of the C++
+Standard Template Library (STL). In Ruby other techniques are available to
+express the generic character of the algorithms and data structures mainly using
+mixins and iterators. The BGL documentation mentions three means to achieve
+genericity:
+
+* Algorithm/Data-Structure Interoperability
+* Extension through Function Objects and Visitors
+* Element Type Parameterization
+* Vertex and Arc Property Multi-Parameterization
+
+The first is easily achieved in GRATR using mixins, which of course is not as
+efficient than C++ templates (but much more readable :-). The second one is
+even more easily implemented using standard iterators with blocks.
+The third one is no issue since Ruby is dynamically typed: Each object can
+be a graph vertex (even nil!). There is no need for a vertex (or even edge type). A 
+label interface is provided for end users as well. One could simply use
+a hash externally, but the future development of network graphs will require
+a weight or capacity property to be accessible. 
+
+=== Algorithms
+
+This version of GRATR contains a core set of algorithm patterns:
+
+* Breadth First Search  Graph[1,2,1,3,1,4,2,5].bfs => [1, 2, 3, 4, 5]
+* Depth First Search    Graph[1,2,1,3,1,4,2,5].dfs => [1, 2, 5, 3, 4]
+* A* Search
+* Lexicographic Search
+* Dijkstra's Algorithm
+* Floyd-Warshall
+* Triangulation and Comparability detection
+
+The algorithm patterns by themselves do not compute any meaningful quantities
+over graphs, they are merely building blocks for constructing graph
+algorithms. The graph algorithms in GRATR currently include:
+
+* Topological Sort     (topsort)
+* Strongly Connected Components (strong_connect)
+* Transitive Closure (transitive_closure)
+
+=== Data Structures
+
+GRATR currently provides one graph module that implement a generalized adjacency
+list and an edge list adaptor.
+
+* GRATR::AdjacencyGraph
+
+The GRATR::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.
+
+=== GEM Installation
+
+Download the GEM file and install it with ..
+
+  % gem install gratr-VERSION.gem
+
+or directly with 
+
+  % gem install gratr
+
+Use the correct version number for VERSION (e.g. 0.2.x).  You may need root
+privileges to install.
+
+=== Running tests
+
+GRATR comes with a Rakefile which automatically runs the tests. Goto the
+installation directory and start rake:
+
+ % gem env
+ Rubygems Environment:
+  - VERSION: 0.8.3 (0.8.3)
+  - INSTALLATION DIRECTORY: /usr/lib/ruby/gems/1.8
+  - GEM PATH:
+     - /usr/lib/ruby/gems/1.8
+  - REMOTE SOURCES:
+     - http://gems.rubyforge.org
+
+ % cd /usr/lib/ruby/gems/1.8/gems/gratr-0.2.2/
+ % r40> rake
+  (in /usr/lib/ruby/gems/1.8/gems/gratr-0.2.2)
+  ruby1.8 -Ilib:tests -e0  -rtests/TestGraphXML  -rtests/TestComponents  -rtests/TestDirectedGraph  -rtests/TestArc  -rtests/TestImplicit  -rtests/TestTransitiveClosure  -rtests/TestTraversal  -rtests/TestUnDirectedGraph
+ Loaded suite -e
+ Started
+ ........................................................................................................
+ Finished in 0.736444 seconds.
+
+ 40 tests, 421 assertions, 0 failures, 0 errors
+
+=== Normal Installation
+
+You have to install stream library before. You can than install GRATR with the
+following command:
+
+  % ruby install.rb
+
+from its distribution directory. To uninstall it use
+
+  % ruby install.rb -u
+  
+The rdoc is useful as well:
+
+  % rake rdoc
+
+== Example irb session with GRATR
+
+  irb> require 'gratr/import'
+  => true
+  irb> dg = Digraph[1,2, 2,3, 2,4, 4,5, 6,4, 1,6]
+  => GRATR::Digraph[[2, 3], [1, 6], [2, 4], [4, 5], [1, 2], [6, 4]] 
+
+A few properties of the graph 
+
+  irb> dg.directed?
+  => true
+  irb> dg.vertex?(4)
+  => true
+  irb> dg.edge?(2,4)
+  => true
+  irb> dg.edge?(4,2)
+  => false
+  irb> dg.vertices
+  => [5, 6, 1, 2, 3, 4]
+
+Every object could be a vertex (there is no class Vertex), even the class
+object _Object_:
+
+  irb> dg.vertex? Object
+  => false
+  irb> UndirectedGraph.new(dg).edges.sort.to_s
+  => "(1=2)(2=3)(2=4)(4=5)(1=6)(4=6)"
+
+Add inverse edge (4-2) to directed graph:
+
+  irb> dg.add_edge! 4,2
+  => GRATR::Digraph[[2, 3], [1, 6], [4, 2], [2, 4], [4, 5], [1, 2], [6, 4]]
+  
+(4-2) == (2-4) in the undirected graph:
+
+  irb> UndirectedGraph.new(dg).edges.sort.to_s
+  => "(1=2)(2=3)(2=4)(4=5)(1=6)(4=6)"
+
+(4-2) != (2-4) in directed graphs:
+
+  irb> dg.edges.sort.to_s
+  => "(1-2)(1-6)(2-3)(2-4)(4-2)(4-5)(6-4)"
+  irb> dg.remove_edge! 4,2
+  => GRATR::Digraph[[2, 3], [1, 6], [2, 4], [4, 5], [1, 2], [6, 4]] 
+
+<em>Topological sort</em> is realized with as iterator:
+
+  irb> dg.topsort         
+  => [1, 2, 3, 6, 4, 5]
+  irb> y=0; dg.topsort {|v| y+=v}; y
+  => 21
+
+    # Use DOT to visualize this graph:
+    irb> require 'gratr/dot'
+    irb> dg.write_to_graphic_file('jpg','visualize')
+    "graph.jpg"
+
+The result: link:../examples/visualize.jpg  
+
+Here's an example showing the module inheritance hierarchy:
+
+  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(/GRATR/)}
+  module_graph.induced_subgraph(gv).write_to_graphic_file('jpg','module_graph')
+
+The result: link:../examples/module_graph.jpg  
+
+Look for more in the examples directory.
+
+== Credits
+
+Many thanks to Robert Feldt which also worked on a graph library
+(http://rockit.sf.net/subprojects/graphr) who pointed me to BGL and many other
+graph resources. Manuel Simoni found a subtle bug in a preliminary version
+announced at http://rubygarden.com/ruby?RubyAlgorithmPackage/Graph.
+
+Robert kindly allowed to integrate his work on graphr, which I did not yet
+succeed. Especially his work to output graphs for
+GraphViz[http://www.research.att.com/sw/tools/graphviz/download.html] is much
+more elaborated than the minimal support in dot.rb.
+
+Jeremy Siek one of the authors of the nice book "The Boost Graph Library (BGL)"
+(http://www.boost.org/libs/graph/doc) kindly allowed to use the
+BGL documentation as a _cheap_ reference for GRATR. He and Robert also gave
+feedback and many ideas for GRATR.
+
+Dave Thomas for RDoc[http://rdoc.sourceforge.net] which generated what you read
+and Matz for Ruby. Dave included in the latest version of RDoc (alpha9) the
+module dot/dot.rb which I use instead of Roberts module to visualize graphs
+(see gratr/dot.rb).
+
+Horst Duchene for RGL which provided the basis for this library and his vision.
+
+Rick Bradley who reworked the library and added many graph theoretic constructs.
+
+== Known Bugs
+
+* Some of the digraph distance algorithms need reworked to work for pseudo and multi graphs.
+
+== To Do
+
+* Primal Dual for combinatorial optimization problems
+* Min-Max Flow 
+* Near optimal traveling salesman problem
+* Orientation of undirected graphs
+
+== Release Notes
+
+The core interface is about to be updated to allow for cleaner dependency injects. Luke Kanies has also contributed
+several optimizations for speed and logged some bugs. This will result in a 0.5 release coming soon. 
+
+=== 0.4.3
+
+* Fixed bug in dot output dependency.
+* Changed method.call to send in a couple places.
+* Fixed bug in unconnected vertices for reversal. Ticket #7237
+* Fixed bugs in A* Search. Ticket #7250.
+
+=== 0.4.2
+
+* Fixed bug in parallel edge adjacency detection.
+* Fix to allow symbols to be passed through to dot for labels.
+* Changed naming to use Arcs for Digraphs and Edges for Undirected Graphs.
+* Added a gem release.
+
+=== 0.4.1
+
+* Got reflection working for graphs
+* Fixed major bugs in multi and pseudo graph handling
+
+=== 0.4.0
+
+Initial release of fork from RGL library.
+
+== Copying
+
+Copyright (c) 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 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.
+
+== Support
+
+Please contact me at mailto:shawn@garbett.org with bug reports
+suggestions, and other comments. If you send patches, it would help if
+they were generated using "diff -u".

data/examples/graph_self.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/ruby -I../lib
+
+require 'gratr/import'
+require 'gratr/dot'
+
+# This program gives an example of dynamic analysis of a program's call stack,
+# that exports to dot and creates a jpg visualization of the call diagram.
+
+class GraphSelf
+  
+  # Setup some data to call Dijkstra's Algorithm
+  def initialize
+    @d = Digraph[ [:a,:b] => 9, [:a,:e] => 3,
+                  [:b,:c] => 2, [:b,:e] => 6,
+                  [:c,:d] => 1,
+                  [:d,:c] => 2,
+                  [:e,:b] => 2, [:e,:f] => 1,
+                  [:f,:c] => 2, [:f,:d] => 7, [:f,:e] => 2 ]
+
+    @call_stack = []
+    @call_graph = Digraph.new
+  end
+  
+  # Get the call graph variable
+  def call_graph() @call_graph; end
+  
+  # Turn capturing of call graph on
+  def capture_func
+    Proc.new do |event, f, l, id, b, klass|
+      # Only interested in the GRATR library itself
+      if ( klass.to_s =~ /GRATR/ ) 
+        case event.to_s
+          when /call/ 
+            method = "#{klass.to_s.split('::')[1]}.#{id}" # Removes GRATR:: 
+            @call_graph.add_edge!(@call_stack[-1],method) if @call_stack[-1] 
+            @call_stack.push(method)
+          when /return/ : @call_stack.pop
+        end
+      end
+    end
+  end 
+
+  # Run a capture of the call graph for Dijkstra's algorithm  
+  def run
+    set_trace_func capture_func
+    @d.dijkstras_algorithm(:a)
+    set_trace_func nil
+    self
+  end
+   
+end
+
+# Run a capture and generate the resulting jpg file
+GraphSelf.new.run.call_graph.write_to_graphic_file('jpg','self_graph')

data/examples/module_graph.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/ruby -I../lib
+
+require 'gratr/import'
+require 'gratr/dot'
+
+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(/GRATR/)}
+module_graph.induced_subgraph(gv).write_to_graphic_file('jpg','module_graph')

data/examples/visualize.rb

@@ -0,0 +1,8 @@
+#!/usr/bin/ruby -I../lib
+
+require 'gratr/import'
+require 'gratr/dot'
+
+dg = Digraph[1,2, 2,3, 2,4, 4,5, 6,4, 1,6]
+
+dg.write_to_graphic_file('jpg','visualize')

data/install.rb

@@ -0,0 +1,49 @@
+#! /usr/bin/env ruby
+
+require 'getoptlong'
+require 'rbconfig'
+require 'ftools'
+require 'find'
+
+SRC_BASE = 'lib'
+SRC = 'gratr'
+
+
+INSTDIR = File.join Config::CONFIG['sitedir']
+DESTDIR = File.join INSTDIR, SRC
+
+opts = GetoptLong.new( [ "--uninstall",	"-u",		GetoptLong::NO_ARGUMENT ] )
+
+def install
+  begin
+    File.makedirs( DESTDIR )
+    pwd = Dir.pwd
+    Dir.chdir(SRC_BASE)
+	Dir['*.rb'].each do |file|
+      dst = File.join( INSTDIR, file )
+      File.install(file, dst, 0644, true)
+    end
+    Find.find(SRC) do |file|
+      dst = File.join( INSTDIR, file )
+      File.install(file, dst, 0644, true) if file =~ /.rb$/
+    end
+    Dir.chdir(pwd)
+  rescue
+    puts $!
+  end
+end
+
+def uninstall
+  begin
+    puts "Deleting:"
+    Find.find(DESTDIR) { |file| File.rm_f file,true }
+    Dir.delete DESTDIR
+  rescue
+  end
+end
+
+if (opt = opts.get) and opt[0] =~ /^-?-u/
+  uninstall
+else
+  install
+end