turbine-graph 0.1.0

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+group :extras do
+  gem 'guard',                   require: false
+  gem 'guard-rspec',             require: false
+  gem 'ruby_gntp',               require: false
+  gem 'rb-fsevent',  '~> 0.9.1', require: false
+  gem 'coolline',                require: false
+  gem 'simplecov',               require: false
+  gem 'yard',        '>= 0.8',   require: false
+  gem 'yard-tomdoc', '>= 0.5',   require: false
+  gem 'pry',                     require: false
+end
+
+gemspec

data/Guardfile

@@ -0,0 +1,6 @@
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+  watch(%r{^spec/factories/.*}) { "spec" }
+end

data/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2012, Anthony Williams and Quintel Intelligence
+All rights reserved.
+
+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,
+    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 Anthony 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 ANTHONY WILLIAMS 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,189 @@
+# Turbine [![Build Status](https://secure.travis-ci.org/quintel/turbine.png)](http://travis-ci.org/quintel/turbine)
+
+An in-memory directed graph written in Ruby to model an energy flow system,
+a family tree, or whatever you like!
+
+## Quick tour
+
+We start the console with `rake console:stub` and load the example graph:
+
+```ruby
+graph = Turbine.energy_stub
+# => #<Turbine::Graph (16 nodes, 16 edges)>
+```
+
+### Searching
+
+Now you can search for a node:
+
+```ruby
+graph.node(:space_heater_chp)
+# => #<Turbine::Node key=:space_heater_chp>
+```
+
+It will return nil when the collection is empty, or if no node with the given
+key exists:
+
+```ruby
+graph.node(:bob_ross)
+# => nil
+```
+
+### Traversing the graph
+
+Please see the [Terminology](#terminology) section if you are confused by the
+use of **in** and **out**.
+
+#### Adjacent nodes
+
+Traverse the graph by requesting the inward nodes of a node:
+
+```ruby
+graph.node(:space_heater_chp).in.to_a
+# => [#<Turbine::Node>, #<Turbine::Node>, ...]
+```
+
+Traverse the graph by requesting the outward nodes:
+
+```ruby
+graph.node(:space_heater_chp).out.to_a
+# => [#<Turbine::Node>, #<Turbine::Node>, ...]
+```
+
+#### Filtering nodes
+
+If you have a node and you want to get all the inward or outward nodes that
+have a certain label, you can use a filter:
+
+```ruby
+graph.node(:space_heater_chp).out(:electricity).to_a
+# => [#<Turbine::Node key=:useful_demand_elec>]
+
+graph.node(:space_heater_chp).out(:heat).to_a
+# => [<Turbine::Node key=:useful_demand_heat>}>]
+```
+
+#### Traversing edges
+
+You can do the same for edges with `in_edges` and `out_edges`:
+
+```ruby
+graph.node(:space_heater_chp).in_edges.to_a
+# => [ #<Turbine::Edge :space_heater_coal -:heat-> :useful_demand_heat>,
+#      #<Turbine::Edge :space_heater_gas -:heat-> :useful_demand_heat>,
+#      #<Turbine::Edge :space_heater_oil -:heat-> :useful_demand_heat>,
+#      #<Turbine::Edge :space_heater_chp -:heat-> :useful_demand_heat> ]
+```
+
+#### Chaining
+
+You can also chain and step through the connections:
+
+```ruby
+node = graph.nodes.first
+node.in.in.to_a
+# => [ #<Turbine::Node key=:final_demand_coal>,
+#      #<Turbine::Node key=:final_demand_gas>,
+#      #<Turbine::Node key=:final_demand_oil> ]
+```
+
+#### Ancestors and Descendants
+
+Alternatively, you can recursively fetch all ancestors or descendants of a
+Node:
+
+```ruby
+enum = node.ancestors.to_a
+# => [#<Turbine::Node>, #<Turbine::Node>, ...]
+```
+
+Just like with `in` and `out`, you may opt to filter the traversed nodes by
+the label of the connecting edge:
+
+```ruby
+enum = node.descendants(:likes)
+# => #<Enumerator: ...>
+```
+
+Ancestors and descendants are fetched using a breadth-first algorithm, but
+depth-first is also available:
+
+```ruby
+enum = Turbine::Traversal::DepthFirst(node, :in).to_enum
+# => #<Enumerator: ...>
+```
+
+Each adjacent node is visited no more than once during the traversal, i.e.
+loops are not followed.
+
+### Properties / Attributes
+
+You can set all kind of properties on a node:
+
+```ruby
+node = graph.nodes.first
+node.properties
+# => {} # no properties set!
+
+node.get(:preset_demand)
+# => nil # no property called :preset_demand set!
+
+node.set(:preset_demand, 1_000)
+# => 1000
+
+node.properties
+# => {:preset_demand=>1000}
+```
+
+## Terminology
+
+#### Node
+
+In graph theory, the term **Node** and **Vertex** are used interchangeably.
+Since we prefer shorter words over longer: we use node.
+
+#### Edges
+
+An **edge** (or sometimes called an **arc**) is a connection between two
+nodes.
+
+#### Directed graph
+
+Turbine is a directed graph, which means that the connection between two
+nodes always has a direction: it either goes from A to B or the other way
+round.
+
+#### In and out
+
+When Node A is connected to Node B:
+
+    A --> B
+
+A is said to be the **ancestor** of B, and B is called the **descendant** of
+A. Since we like to keep things as short as possible, we choose **in** and
+**out**: `A.out` results in `B`, and `B.in` results in `A`.
+
+Hence, we have the following truth table:
+
+         |  in | out
+    -----+-----+------
+      A  | nil |  B
+    -----+-----+------
+      B  |  A  | nil
+
+Still, it is up to the user to define what the direction signifies: in the
+case of an energy graph: the energy flows from a coal plant to the electricity
+grid. (some might argue that the demand flows from the grid to the power
+plant).
+
+In the case of the family graph, it is the ancestry of people:
+
+    parent -:child-> child
+
+If the relation is equal, there are two edges defined and a symmetrical
+relationship exists (Turbine does not support bi-directional edges):
+
+    person1 -:spouse-> person2
+    person2 -:spouse-> person1
+
+    i.e., person1 <-> person2

data/Rakefile

@@ -0,0 +1,126 @@
+require 'rake'
+require 'rake/clean'
+
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'turbine/version'
+
+CLOBBER.include %w( pkg *.gem doc coverage measurements )
+
+# Helpers --------------------------------------------------------------------
+
+require 'date'
+
+def replace_header(head, header_name, value)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{value}'" }
+end
+
+# Build Tasks ----------------------------------------------------------------
+
+desc 'Build the gem, and push to Github'
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+
+  sh "git commit --allow-empty -a -m 'Release #{Turbine::VERSION}'"
+  sh "git tag v#{Turbine::VERSION}"
+  sh "git push origin master"
+  sh "git push origin v#{Turbine::VERSION}"
+
+  puts "Push to Rubygems.org with"
+  puts "  gem push pkg/turbine-#{Turbine::VERSION}.gem"
+end
+
+desc 'Builds the gem'
+task :build => [:gemspec] do
+  sh "mkdir -p pkg"
+  sh "gem build turbine.gemspec"
+  sh "mv turbine-graph-#{Turbine::VERSION}.gem pkg"
+end
+
+desc 'Create a fresh gemspec'
+task :gemspec => :validate do
+  gemspec_file = File.expand_path('../turbine.gemspec', __FILE__)
+
+  # Read spec file and split out the manifest section.
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # Replace name version and date.
+  replace_header head, :name,              'turbine-graph'
+  replace_header head, :rubyforge_project, 'turbine-graph'
+  replace_header head, :version,            Turbine::VERSION
+  replace_header head, :date,               Date.today.to_s
+
+  # Determine file list from git ls-files.
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(doc|pkg|spec|tasks)/ }
+
+  # Format list for the gemspec.
+  files = files.map { |file| "    #{file}" }.join("\n")
+
+  # Piece file back together and write.
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+
+  puts "Updated #{gemspec_file}"
+end
+
+task :validate do
+  unless Dir['lib/*'] - %w(lib/turbine.rb lib/turbine)
+    puts 'The lib/ directory should only contain a turbine.rb file, and a ' \
+         'turbine/ directory'
+    exit!
+  end
+
+  unless Dir['VERSION*'].empty?
+    puts 'A VERSION file at root level violates Gem best practices'
+    exit!
+  end
+end
+
+# Coverage -------------------------------------------------------------------
+
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  exec 'bundle exec rspec'
+end
+
+# Documentation --------------------------------------------------------------
+
+begin
+  require 'yard'
+  require 'yard-tomdoc'
+  YARD::Rake::YardocTask.new do |doc|
+    doc.options << '--no-highlight'
+  end
+rescue LoadError
+  desc 'yard task requires that the yard gem is installed'
+  task :yard do
+    abort 'YARD is not available. In order to run yard, you must: gem ' \
+          'install yard'
+  end
+end
+
+# Console --------------------------------------------------------------------
+
+namespace :console do
+  task :run do
+    command = system("which pry > /dev/null 2>&1") ? 'pry' : 'irb'
+    exec "#{ command } -I./lib -r./lib/turbine.rb"
+  end
+
+  desc 'Open a pry or irb session with a stub graph on `Turbine.stub`'
+  task :stub do
+    command = system("which pry > /dev/null 2>&1") ? 'pry' : 'irb'
+    exec "#{ command } -I./lib -r./lib/turbine.rb -r./examples/family.rb -r./examples/energy.rb"
+  end
+end
+
+desc 'Open a pry or irb session preloaded with Turbine'
+task console: ['console:run']

data/examples/energy.rb

@@ -0,0 +1,80 @@
+require 'turbine'
+
+module Turbine
+
+  # This is a small Graph example, similar to the structure that is used
+  # in ETEngine in households.
+  #
+  # Overview:
+  # +------------------------------------------------------------------+
+  # | ud_heat <- sh_coal <- fd_coal                                    |
+  # |     \\\--- sh_oil  <- fd_oil                                     |
+  # |      \\--- sh_gas  <- fd_gas                                     |
+  # |       \--- sh_chp  <--/                                          |
+  # | ud_elec <--/                                                     |
+  # |       \--- sh_elec <- fd_elec <- lv <- mv <- hv <- coal plant    |
+  # |                                               \--- elec_import   |
+  # +------------------------------------------------------------------+
+  #
+  # Abbreviations used:
+  #   ud   = useful_demand
+  #   sh   = space_heater
+  #   fd   = final_demand
+  #   hv   = high voltage
+  #   mv   = medium voltage
+  #   lv   = low voltage
+  #   elec = electricity
+  #
+  def self.energy_stub
+    graph = Turbine::Graph.new
+
+    # Nodes ------------------------------------------------------------------
+
+    useful_demand_heat = graph.add(Turbine::Node.new(:useful_demand_heat))
+    useful_demand_elec = graph.add(Turbine::Node.new(:useful_demand_elec))
+
+    space_heater_coal  = graph.add(Turbine::Node.new(:space_heater_coal))
+    space_heater_gas   = graph.add(Turbine::Node.new(:space_heater_gas))
+    space_heater_oil   = graph.add(Turbine::Node.new(:space_heater_oil))
+    space_heater_chp   = graph.add(Turbine::Node.new(:space_heater_chp))
+    space_heater_elec  = graph.add(Turbine::Node.new(:space_heater_elec))
+
+    final_demand_coal  = graph.add(Turbine::Node.new(:final_demand_coal))
+    final_demand_gas   = graph.add(Turbine::Node.new(:final_demand_gas))
+    final_demand_oil   = graph.add(Turbine::Node.new(:final_demand_oil))
+    final_demand_elec  = graph.add(Turbine::Node.new(:final_demand_elec))
+
+    lv_network         = graph.add(Turbine::Node.new(:lv_network))
+    mv_network         = graph.add(Turbine::Node.new(:mv_network))
+    hv_network         = graph.add(Turbine::Node.new(:hv_network))
+
+    coal_plant         = graph.add(Turbine::Node.new(:coal_plant))
+    elec_import        = graph.add(Turbine::Node.new(:elec_import))
+
+    # Edges ------------------------------------------------------------------
+
+    elec_import.connect_to(hv_network,               :electricity)
+    coal_plant.connect_to(hv_network,                :electricity)
+
+    hv_network.connect_to(mv_network,                :electricity)
+    mv_network.connect_to(lv_network,                :electricity)
+    lv_network.connect_to(final_demand_elec,         :electricity)
+
+    final_demand_elec.connect_to(space_heater_elec,  :electricity)
+    final_demand_coal.connect_to(space_heater_coal,  :coal)
+    final_demand_gas.connect_to(space_heater_gas,    :gas)
+    final_demand_gas.connect_to(space_heater_chp,    :gas)
+    final_demand_oil.connect_to(space_heater_oil,    :oil)
+
+    space_heater_coal.connect_to(useful_demand_heat, :heat)
+    space_heater_gas.connect_to(useful_demand_heat,  :heat)
+    space_heater_oil.connect_to(useful_demand_heat,  :heat)
+
+    space_heater_chp.connect_to(useful_demand_heat,  :heat)
+    space_heater_chp.connect_to(useful_demand_elec,  :electricity)
+
+    space_heater_elec.connect_to(useful_demand_elec, :electricity)
+
+    graph
+  end #self.stub
+end #Module Turbine