graphshaper 0.0.2 → 0.1

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - jruby-19mode
+  - rbx-19mode

data/README.md

@@ -1,6 +1,8 @@
 # Graphshaper
 
-Graphshaper can generate realistic, scale-free graphs of any size.
+[![Build Status](https://secure.travis-ci.org/moonglum/graphshaper.png?branch=master)](http://travis-ci.org/moonglum/graphshaper)
+
+Graphshaper can generate realistic, scale-free graphs of any size. It is tested with MRI Ruby (1.9.2. and 1.9.3) and the 1.9 versions of jRuby and Rubinius.
 
 ## Installation
 
@@ -18,11 +20,11 @@ Or install it yourself as:
 
 ## Usage
 
-The commandline tool expects one argument: The number of nodes you want your generated graph to have. For example:
+The commandline tool expects one argument: The number of vertices you want your generated graph to have. This will result in two CSV files containing your vertices and edges. For example:
 
     graphshaper 50
 
-You can also use the `Graphshaper::UndirectedGraph` class in your Rubycode. To find examples on how to do that please refer to the specs.
+You can also use the library in your Ruby Code. You can find the documentation [here](http://rubydoc.info/github/moonglum/graphshaper).
 
 ## Contributing
 

data/bin/graphshaper

@@ -4,14 +4,34 @@ require 'graphshaper'
 
 if ARGV.length == 0 || ARGV[0] == "--help"
   puts "  Usage: graphshaper SIZE"
+elsif ARGV[0].to_i < 21
+  puts "Please choose a size of at least 21"
 else
-  inner_nodes = 20
-  number_of_nodes = ARGV[0].to_i
+  number_of_vertices = ARGV[0].to_i
+  inner_vertices = 20
   
-  graph = Graphshaper::UndirectedGraph.without_orphans_with_order_of 20, edge_creation_logger: STDOUT
-  (number_of_nodes - inner_nodes).times do
+  edge_output_file = File.new "edges.csv", "w"
+  vertex_output_file = File.new "vertices.csv", "w"
+  
+  start_time = Time.now
+  graph = Graphshaper::UndirectedGraph.without_orphans_with_order_of inner_vertices, edge_creation_logger: edge_output_file, vertex_creation_logger: vertex_output_file
+  (number_of_vertices - inner_vertices).times do
     graph.add_vertex do |preferential_attachment|
       preferential_attachment > rand
     end
   end
+  end_time = Time.now
+  
+  ellapsed_time = end_time - start_time
+  
+  puts "#{graph.order} vertices (saved to vertices.csv)"
+  puts "#{graph.size} edges (saved to edges.csv)"
+  
+  if ellapsed_time < 2
+    puts "Generated in about one second"
+  elsif ellapsed_time < 60
+    puts "Generated in about #{ellapsed_time.round} seconds"
+  else
+    puts "Generated in about #{ellapsed_time.round / 60} minutes and #{ellapsed_time.round % 60} seconds"
+  end
 end

data/graphshaper.gemspec

@@ -15,5 +15,7 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Graphshaper::VERSION
   
-  gem.add_development_dependency 'rspec', "~> 2.9.0"
+  gem.add_development_dependency "rake", "~> 0.9.2.2"
+  gem.add_development_dependency "rspec", "~> 2.9.0"
+  gem.add_development_dependency "yard", "~> 0.7.5"
 end

data/lib/graphshaper/undirected_graph.rb

@@ -1,52 +1,91 @@
 require "set"
 
 module Graphshaper
+  
+  # A Graph is undirected when its edges do not have a direction.
   class UndirectedGraph
-    # Create a graph with a given number of vertices
+    
+    # Create a graph with a given number of vertices and no edges.
+    # 
+    # @param [Integer] number_of_vertices The number of vertices that the generated graph should have
+    # @param [Hash] options_hash The options to create an undirected graph
+    # @option options_hash [IO] :edge_creation_logger An IO object that should log every edge creation in the graph (default: no logging)
+    # @option options_hash [IO] ::vertex_creation_logger An IO object that should log every vertex creation in the graph (default: no logging)
     def initialize(number_of_vertices, options_hash = {})
-      @vertex_degrees = [0] * number_of_vertices
-      @edges = Set.new
-      @unconnected_vertices = Set.new (0...number_of_vertices).to_a
+      @edge_creation_logger = options_hash[:edge_creation_logger] if options_hash.has_key? :edge_creation_logger
+      @vertex_creation_logger = options_hash[:vertex_creation_logger] if options_hash.has_key? :vertex_creation_logger
       
-      if options_hash.has_key? :edge_creation_logger
-        @edge_creation_logger = options_hash[:edge_creation_logger]
-      end
+      @vertex_degrees = []
+      @unconnected_vertices = Set.new
+      
+      number_of_vertices.times { add_vertex }
+      @edges = Set.new
     end
     
+    # Create a graph with a given number of vertices. Then it adds random edges until the graph doesn't contain any orphans (vertices without edges).
+    # 
+    # @param [Integer] number_of_vertices The number of vertices that the generated graph should have
+    # @param [Hash] options_hash The options to create an undirected graph
+    # @option options_hash [IO] :edge_creation_logger An IO object that should log every edge creation in the graph (default: no logging)
+    # @option options_hash [IO] ::vertex_creation_logger An IO object that should log every vertex creation in the graph (default: no logging)
+    # @return [UndirectedGraph] The generated graph.
     def UndirectedGraph.without_orphans_with_order_of(number_of_vertices, options_hash = {})
       graph = self.new number_of_vertices, options_hash
       
       while graph.number_of_orphans > 0
-        a = rand(graph.order)
-        while a == (b = rand(graph.order)); end
+        vertex_orphan = graph.orphans.shuffle.first
+        while vertex_orphan == (random_vertex = rand(graph.order)); end
         
-        graph.add_edge a, b
+        graph.add_edge vertex_orphan, random_vertex
       end
       
       return graph
     end
     
-    # the number of vertices
+    # The number of vertices.
+    #
+    # @return [Integer] Number of vertices.
     def order
       @vertex_degrees.length
     end
     
-    # the number of edges
+    # The number of edges.
+    # 
+    # @return [Integer] Number of edges.
     def size
       @edges.length
     end
     
+    # Add a new vertex to the graph.
+    # If you call it with a block {|preferential_attachment| ... }, the block will be called for every existing vertex: An edge from the new vertex to this vertex will be created if and only if the block returns true.
+    # @yield [preferential_attachment] The block that tests if the edge should be added.
+    #
+    # @yieldparam [Float] preferential_attachment The preferential attachment of the existing vertex
+    # @yieldreturn [Boolean] Should the edge be added?
+    # 
+    # @return [Integer] ID of the newly created vertex.
     def add_vertex(&block)
+      new_vertex_id = @vertex_degrees.length
+      
       @vertex_degrees << 0
+      @unconnected_vertices << new_vertex_id
+      
+      @vertex_creation_logger << "#{new_vertex_id}\n" if @vertex_creation_logger
       
-      new_vertex_id = @vertex_degrees.length - 1
       if block_given? 
         each_vertex_with_preferential_attachment do |vertex_id, preferential_attachment|
           add_edge new_vertex_id, vertex_id if block.call(preferential_attachment)
         end
       end
+      
+      new_vertex_id
     end
     
+    # Add a new edge to the graph between two existing vertices.
+    # 
+    # @param [Integer] first_vertex_id
+    # @param [Integer] second_vertex_id
+    # @raise [RuntimeError] The method throws a RuntimeError if you try to add a self-referential edge or an edge with a non-existing vertex.
     def add_edge(first_vertex_id, second_vertex_id)
       if first_vertex_id == second_vertex_id
         raise "No Self-Referential Edge"
@@ -63,19 +102,40 @@ module Graphshaper
       end
     end
     
+    # Tests, if an edge between the two vertices exists.
+    #
+    # @param [Integer] first_vertex_id
+    # @param [Integer] second_vertex_id
+    # @return [Boolean] Does the vertex exist?
     def edge_between?(first_vertex_id, second_vertex_id)
       @edges.include? [first_vertex_id, second_vertex_id]
     end
     
-    # The number of vertices without edges
+    # The number of vertices without edges.
+    #
+    # @return [Integer] Number of vertices without edges.
     def number_of_orphans
-      @unconnected_vertices.length
+      @unconnected_vertices.to_a.length
     end
     
+    # The vertices without edges as an array.
+    #
+    # @return [Array<Integer>] IDs of the Vertices without edges.
+    def orphans
+      @unconnected_vertices.to_a
+    end
+    
+    # Return the vertex degree for the vertex with the given ID.
+    #
+    # @param [Integer] vertex_id
+    # @return [Integer] Degree of the given vertex
     def vertex_degree_for(vertex_id)
       @vertex_degrees[vertex_id]
     end
     
+    # Calculates the distribution of degrees in the graph. The value at the n-th position of the returned array is the number of vertices with n edges.
+    #
+    # @return [Array<Integer>] The degree distribution as an array of Integers.
     def degree_distribution
       degree_distribution = []
       @vertex_degrees.each do |vertex_degree|
@@ -87,15 +147,19 @@ module Graphshaper
       end
       degree_distribution
     end
-    
-    def calculate_vertex_degree_for(vertex_id)
-      @vertex_degrees[vertex_id]
-    end
-    
+        
+    # Return the sum of all degrees.
+    #
+    # @return [Integer] Sum of all degrees
     def sum_of_all_degrees
       @edges.length * 2
     end
     
+    # Iterate over all vertices of the graph. Call it with a block {|vertex_id, preferential_attachment| ... }.
+    # 
+    # @yield [vertex_id, preferential_attachment] The block that tests if the edge should be added.
+    # @yieldparam [Integer] vertex_id The preferential attachment of the existing vertex
+    # @yieldparam [Float] preferential_attachment The preferential attachment of the existing vertex
     def each_vertex_with_preferential_attachment(&block)
       if sum_of_all_degrees > 0
         preferential_attachments = @vertex_degrees.map { |degree| degree.round(1) / sum_of_all_degrees }
@@ -106,6 +170,5 @@ module Graphshaper
         end
       end
     end
-
   end
 end

data/lib/graphshaper/version.rb

@@ -1,3 +1,3 @@
 module Graphshaper
-  VERSION = "0.0.2"
+  VERSION = "0.1"
 end

data/spec/undirected_graph_spec.rb

@@ -17,6 +17,14 @@ describe Graphshaper::UndirectedGraph do
     edge_creation_logger.string.should ==("1,3\n2,3\n")
   end
   
+  it "should create a graph with a logger for vertex creation" do
+    vertex_creation_logger = StringIO.new
+    graph = Graphshaper::UndirectedGraph.new 5, vertex_creation_logger: vertex_creation_logger
+    
+    graph.add_vertex
+    vertex_creation_logger.string.should ==("0\n1\n2\n3\n4\n5\n")
+  end
+  
   describe "initialized graph" do
     before :each do
       @graph = Graphshaper::UndirectedGraph.new 5
@@ -101,14 +109,14 @@ describe Graphshaper::UndirectedGraph do
     
     it "should calculate the degree of 0 for every vertex in a graph without edges" do
       5.times do |vertex_id|
-        @graph.calculate_vertex_degree_for(vertex_id).should ==0
+        @graph.vertex_degree_for(vertex_id).should ==0
       end
     end
     
     it "should calculate the degree for a vertex with two edges" do
       @graph.add_edge 0,1
       @graph.add_edge 1,2
-      @graph.calculate_vertex_degree_for(1).should ==2
+      @graph.vertex_degree_for(1).should ==2
     end
     
     it "should calculate the sum of all degrees" do
@@ -147,12 +155,12 @@ describe Graphshaper::UndirectedGraph do
     it "should add a vertex to the graph with edges according to preferential attachment" do
       @graph.add_edge 0,1
       
-      # Two nodes with preferential_attachment of 0.5, all others with 0
+      # Two vertices with preferential_attachment of 0.5, all others with 0
       @graph.add_vertex do |preferential_attachment|
         preferential_attachment > 0.4
       end
       
-      # One more node
+      # One more vertex
       @graph.order.should ==(6)
       
       # Two additional edges

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphshaper
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: '0.1'
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-03 00:00:00.000000000Z
+date: 2012-04-04 00:00:00.000000000Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70350123480940 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2.2
+  type: :development
+  prerelease: false
+  version_requirements: *70350123480940
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70183947411400 !ruby/object:Gem::Requirement
+  requirement: &70350123480440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,7 +32,18 @@ dependencies:
         version: 2.9.0
   type: :development
   prerelease: false
-  version_requirements: *70183947411400
+  version_requirements: *70350123480440
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &70350123479980 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.7.5
+  type: :development
+  prerelease: false
+  version_requirements: *70350123479980
 description: Generate realistic graphs
 email:
 - me@moonglum.net
@@ -31,6 +53,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE
 - README.md
@@ -69,3 +92,4 @@ summary: Graphshaper can generate realistic, scale-free graphs of any size.
 test_files:
 - spec/spec_helper.rb
 - spec/undirected_graph_spec.rb
+has_rdoc: