gratr 0.4.2

data/README

@@ -0,0 +1,328 @@
+= 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.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/Rakefile

@@ -0,0 +1,220 @@
+# Rakefile for GRATR        -*- ruby -*-
+begin
+  require 'rubygems'
+  require 'rake/gempackagetask'
+rescue Exception
+  nil
+end
+
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+# Determine the current version of the software
+
+if `ruby -Ilib -rgratr/base -e'puts GRATR_VERSION'` =~ /\S+$/
+  PKG_VERSION = $&
+else
+  PKG_VERSION = "0.0.0"
+end
+
+SUMMARY = "Graph Theory Ruby library"
+SOURCES = FileList['lib/**/*.rb']
+RDOC_DIR = './gratr'
+
+# The default task is run if rake is given no explicit arguments.
+
+desc "Default Task"
+task :default => :test
+
+# Define a test task.
+
+Rake::TestTask.new { |t|
+  t.libs << "tests"
+  t.pattern = 'tests/Test*.rb'
+  t.verbose = true
+}
+
+task :test
+
+# Define a test that will run all the test targets.
+desc "Run all test targets"
+task :testall => [:test ]
+
+# Install gratr using the standard install.rb script.
+
+desc "Install the application"
+task :install do
+  ruby "install.rb"
+end
+
+# CVS Tasks ----------------------------------------------------------
+
+desc "Tag all the CVS files with the latest release number (TAG=x)"
+task :tag do
+  rel = "REL_" + PKG_VERSION.gsub(/\./, '_')
+  rel << ENV['TAG'] if ENV['TAG']
+  puts rel
+  sh %{cvs commit -m 'pre-tag commit'}
+  sh %{cvs tag #{rel}}
+end
+
+# Create a task to build the RDOC documentation tree.
+
+rd = Rake::RDocTask.new("rdoc") { |rdoc|
+  rdoc.rdoc_dir = RDOC_DIR
+  rdoc.title    = SUMMARY
+  rdoc.options << '--line-numbers' << '--inline-source' <<
+     '--main' << 'README'
+  rdoc.rdoc_files.include(SOURCES, 'README' ) #, 'examples/examples.rb')
+}
+
+# ====================================================================
+# Create a task that will package the gratr software into distributable
+# tar, zip and gem files.
+
+PKG_FILES = FileList[
+  'install.rb',
+  '[A-Z]*',
+  'tests/**/*.rb',
+  'examples/**/*'
+] + SOURCES
+
+if ! defined?(Gem)
+  puts "Package Target requires RubyGEMs"
+else
+  spec = Gem::Specification.new do |s|
+    
+    #### Basic information.
+
+    s.name = 'gratr'
+    s.version = PKG_VERSION
+    s.summary = SUMMARY
+
+    s.description = <<-EOF
+    GRATR is a framework for graph data structures and algorithms.
+
+    This library is a fork of RGL. This version utilizes
+    Ruby blocks and duck typing to greatly simplfy the code. It also supports
+    export to DOT format for display as graphics.
+
+    GRATR currently contains a core set of algorithm patterns:
+
+     * Breadth First Search 
+     * Depth First Search 
+     * A* Search
+     * Floyd-Warshall
+     * Best First Search
+     * Djikstra's Algorithm
+     * Lexicographic Search
+
+    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 
+     * Strongly Connected Components 
+     * Transitive Closure
+     * Rural Chinese Postman
+     * Biconnected
+    EOF
+
+    #### Which files are to be included in this gem?  Everything!  (Except CVS directories.)
+    s.files = PKG_FILES.to_a
+
+    #### Load-time details: library and application (you will need one or both).
+
+    s.require_path = 'lib'                         # Use these for libraries.
+    s.autorequire = 'gratr'
+
+    #### Documentation and testing.
+
+    s.has_rdoc = true
+    s.extra_rdoc_files = ['README']
+    s.rdoc_options <<
+      '--title' <<  'GRATR - Ruby Graph Library' <<
+      '--main' << 'README' <<
+      '--line-numbers'
+
+    #### Author and project details.
+    s.author = "Shawn Garbett"
+    s.email = "shawn@garbett.org"
+    s.homepage = "http://gratr.rubyforge.org"
+    s.rubyforge_project = "gratr"
+    
+  end
+
+  Rake::GemPackageTask.new(spec) do |pkg|
+    #pkg.need_zip = true
+    pkg.need_tar = true
+  end
+end
+
+# TAGS ---------------------------------------------------------------
+
+file 'tags' => SOURCES do
+  print "Running ctags..."
+  sh %{ctags #{SOURCES.join(' ')}}             # vi tags
+  puts "done."
+end
+
+file 'TAGS' => SOURCES do
+  sh %{ctags -e #{SOURCES.join(' ')}}          # emacs TAGS
+end
+
+# Misc tasks =========================================================
+
+def count_lines(filename)
+  lines = 0
+  codelines = 0
+  open(filename) { |f|
+    f.each do |line|
+      lines += 1
+      next if line =~ /^\s*$/
+      next if line =~ /^\s*#/
+      codelines += 1
+    end
+  }
+  [lines, codelines]
+end
+
+def show_line(msg, lines, loc)
+  printf "%6s %6s   %s\n", lines.to_s, loc.to_s, msg
+end
+
+desc "Count lines in the main files"
+task :lines do
+  total_lines = 0
+  total_code = 0
+  show_line("File Name", "LINES", "LOC")
+  SOURCES.each do |fn|
+    lines, codelines = count_lines(fn)
+    show_line(fn, lines, codelines)
+    total_lines += lines
+    total_code  += codelines
+  end
+  show_line("TOTAL", total_lines, total_code)
+end
+
+ARCHIVEDIR = '/mnt/flash'
+
+task :archive => [:package] do
+  cp FileList["pkg/*.tgz", "pkg/*.zip", "pkg/*.gem"], ARCHIVEDIR
+end
+
+desc "Copy rdoc html to rubyforge"
+task :rdoc2rf => [:rdoc] do
+  sh "scp -r #{RDOC_DIR} monora@rubyforge.org:/var/www/gforge-projects/gratr"
+  sh "scp examples/*.jpg monora@rubyforge.org:/var/www/gforge-projects/gratr/examples"
+end
+
+STATS_DIRECTORIES = [
+  %w(Libraries          lib/gratr),
+  %w(Unit\ tests        tests),
+].collect { |name, dir| [ name, "./#{dir}" ] }.select { |name, dir| File.directory?(dir) }
+
+desc "Report code statistics (KLOCs, etc) from the application"
+task :stats do
+  require 'stats/code_statistics'
+  CodeStatistics.new(*STATS_DIRECTORIES).to_s
+end