routr 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
+  - ruby-head
+  - jruby-head
+  - ree

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in routr.gemspec
+gemspec
+
+gem 'rake'
+gem 'guard'
+gem 'guard-rspec'
+

data/Guardfile

@@ -0,0 +1,8 @@
+guard 'rspec', :all_on_start => true, :all_after_pass => true do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/routr/(.+)\.rb$})     { |m| "spec/unit/#{m[1]}_spec.rb" }
+  watch(%r{^lib/routr\.rb$})     { |m| "spec/integration" }
+  watch(%r{^lib/routr/interface\.rb$})     { |m| "spec/integration" }
+end
+
+

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2012 Levente Bagi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,76 @@
+# Routr
+
+[![Build Status](https://secure.travis-ci.org/bagilevi/routr.png)](http://travis-ci.org/bagilevi/routr)
+
+Implements Dijkstra's algorithm to find the shortest path in a graph.
+
+The cost of an edge can be more general than just a numeric value.
+You can inject a method for calculating the distance from source to the
+next node given the distance from source to the current node and the
+properties of an edge. A possible use case is the one used by PeerPost:
+nodes are people, an edge is a connection between specifying when those
+people regularly meet, you inject a method that calculates when people
+meet next after a specified time.
+
+# Usage
+
+```
+class MyInterface
+  NETWORK = {
+    'A' => { 'B' => 50, 'C' => 100 },
+    'B' => { 'D' => 50 },
+    'C' => { 'D' => 10 },
+    'D' => {}
+  }
+
+  # This will be used if :initial_distance is not supplied to calculate_route
+  def initial_distance
+    0
+  end
+
+  def neighbours_of(node_key)
+    NETWORK[node_key].keys
+  end
+
+  def calculate_new_distance(distance_so_far, a_key, b_key)
+    distance_so_far + NETWORK[a_key][b_key]
+  end
+end
+
+route = Routr.new(MyInterface.new).calculate_route(
+  :from => 'A',
+  :to => 'D',
+  :initial_distance => 0
+)
+
+route.hops.count       # => 2
+route.members.count    # => 3
+
+route.hops.first.from     # => 'A' 
+route.hops.first.to       # => 'B' 
+route.hops.first.distance # => 50
+route.hops.last.from      # => 'B' 
+route.hops.last.to        # => 'D' 
+route.hops.last.distance  # => 100
+
+route.members.first      # => 'A'
+route.members.last       # => 'D'
+
+route.distance   # => 100
+```
+
+If you have normal addible edge costs, you can replace the
+`calculate_new_distance` method with `edge_distance`:
+
+```
+def edge_cost(a_key, b_key)
+    NETWORK[a_key][b_key]
+  end
+```
+
+# License
+
+Copyright 2012, Levente Bagi
+
+Released under the MIT License, see the LICENSE file.
+

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "./spec/**/*_spec.rb" # don't need this, it's default.
+  # Put spec opts in a file named .rspec in root
+end
+

data/cruise_config.rb

@@ -0,0 +1,6 @@
+Project.configure do |project|
+  project.build_command = <<-COMMAND.split("\n").map(&:strip).join(' ')
+    sh -c "env RAILS_ENV=test bundle exec rspec"
+  COMMAND
+end
+

data/lib/routr.rb

@@ -0,0 +1,11 @@
+require "routr/version"
+
+module Routr
+  autoload :Interface, 'routr/interface'
+
+  class << self
+    def new(*args, &block)
+      Routr::Interface.new(*args, &block)
+    end
+  end
+end

data/lib/routr/calculator.rb

@@ -0,0 +1,161 @@
+module Routr
+  class Calculator
+
+    def initialize(graph)
+      @graph = graph
+    end
+
+    attr_reader :graph
+
+    # based of wikipedia's pseudocode: http://en.wikipedia.org/wiki/Dijkstra's_algorithm
+
+    def dijkstra(initial_node, initial_distance = 0)
+      debug
+      debug "== routing from #{initial_node.inspect}"
+      initialize_temporary_variables
+
+      set_distance(initial_node, initial_distance)
+      add_unvisited_node(initial_node)
+
+      while any_unvisited_nodes?
+        u = node_with_minimum_distance
+        break if not reachable? u
+        mark_as_visited u
+
+        with_each_neighbour_of u do |v| # for each neighbor v of u: where v has not yet been removed from Q.
+          debug "neighbour: #{v}"
+          new_distance = calculate_new_distance(best_distance_to(u), u, v)
+          if (best_distance_to(v) == :infinity) || (new_distance < best_distance_to(v))
+            set_best_distance_to(v, new_distance)
+            add_unvisited_node(v)
+            set_previous_node_to(v, u)
+          end
+        end
+        debug
+      end
+      debug "== end routing"
+    end
+
+    def shortest_path src, dest, initial_distance = 0, include_details = false
+      dijkstra src, initial_distance
+      path_to dest, include_details
+    end
+
+    def path_to(dest, include_details = false)
+      if reachable? dest
+        item = \
+          if include_details
+            {
+              :node => dest,
+              :distance => best_distance_to(dest)
+            }
+          else
+            dest
+          end
+        previous_path_to(dest, include_details) + [ item ]
+      end
+    end
+
+    def previous_path_to(dest, include_details = false)
+      if previous_node_to(dest).nil?
+        []
+      else
+        path_to(previous_node_to(dest), include_details)
+      end
+    end
+
+
+    private
+
+    def edge_cost a, b
+      (graph.edge_cost(a, b) || :infinity).tap { |cost|
+        debug "Edge cost #{a} -> #{b} = #{cost.inspect}"
+      }
+    end
+
+    def calculate_new_distance distance_so_far, a, b
+      if graph.respond_to?(:calculate_new_distance)
+        graph.calculate_new_distance distance_so_far, a, b
+      else
+        distance_so_far + edge_cost(a, b)
+      end.tap {|new_distance|
+        if new_distance < distance_so_far
+          raise "New distance < previous distance: #{new_distance.inspect} < #{distance_so_far.inspect}"
+        end
+      }
+    end
+
+    def initialize_temporary_variables
+      @d = {}
+      @prev = {}
+      @candidates = []
+    end
+
+    def best_distance_to(node)
+      debug "best_distance[#{node.inspect}] # -> #{@d[node].inspect}"
+      @d[node] || :infinity
+    end
+
+    def reachable?(node)
+      debug "reachable?(#{node.inspect})"
+      (best_distance_to(node) != :infinity)\
+      .tap {|r| debug "=> #{r.inspect}" }
+    end
+
+
+    # OPTIMIZE: maintain a sorted list, so we don't have to search the whole set every time
+    def node_with_minimum_distance # unvisited node with minimum distance
+      debug "node_with_minimum_distance"
+      @candidates.min_by{ |x| best_distance_to(x) }\
+      .tap{|x| debug "=> #{x.inspect}"}
+    end
+
+    def mark_as_visited node
+      @candidates = @candidates - [node]
+    end
+
+    def any_unvisited_nodes?
+      debug "any_unvisited_nodes?"
+      @candidates.any?\
+      .tap{|r| debug "=> #{r.inspect}" }
+    end
+
+    def add_unvisited_node node
+      debug "add_unvisited_node #{node.inspect}"
+      @candidates << node
+    end
+
+
+    def set_distance node, value
+      @d[node] = value           # Distance from source to source
+    end
+
+    def with_each_neighbour_of node, &block
+      graph.neighbours_of(node).tap{|neighbours| debug "Neighbours of: #{node} -> #{neighbours.inspect}"}.each(&block)
+    end
+
+    def set_best_distance_to node, new_distance
+      debug "best_distance[#{node.inspect}] = #{new_distance.inspect}"
+      @d[node] = new_distance
+    end
+
+    def set_previous_node_to node, previous_node
+      @prev[node] = previous_node
+    end
+
+    def previous_node_to(node)
+      @prev[node]
+    end
+
+    def debug *args
+      return
+      @i ||= 0
+      @i += 1
+      if @i < 1000
+        puts *args
+      end
+    end
+
+  end
+end
+

data/lib/routr/interface.rb

@@ -0,0 +1,62 @@
+require 'routr/calculator'
+module Routr
+  class Interface
+    def initialize interface
+      @interface = interface
+    end
+
+    def calculate_route attr
+      initial_distance = attr[:initial_distance] ||
+        (@interface.initial_distance if @interface.respond_to?(:initial_distance)) ||
+        0
+      raw_route = Routr::Calculator.new(@interface)\
+        .shortest_path(attr[:from], attr[:to], initial_distance, true)
+      route = Route.from_raw(raw_route)
+    end
+  end
+
+
+  class Route
+    attr_reader :hops, :members, :distance, :raw
+
+    def initialize(raw)
+      @raw = raw
+      raw ||= []
+      @hops = raw[0..-2].to_enum.with_index.map{|item, index|
+        Hop.new(
+          :from => raw[index][:node],
+          :to => raw[index + 1][:node],
+          :distance => raw[index + 1][:distance]
+        )
+      }
+      @members = raw.map{|item| item[:node]}
+    end
+
+    def self.from_raw(raw)
+      new(raw)
+    end
+
+    def distance
+      hops.last.distance
+    end
+
+    def found?
+      @hops.any?
+    end
+
+    def missing?
+      not found?
+    end
+  end
+
+
+  class Hop
+    attr_reader :from, :to, :distance
+    def initialize(attributes)
+      @from     = attributes[:from]
+      @to       = attributes[:to]
+      @distance = attributes[:distance]
+    end
+  end
+end
+

data/lib/routr/version.rb

@@ -0,0 +1,3 @@
+module Routr
+  VERSION = "0.0.1"
+end

data/routr.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "routr/version"
+
+Gem::Specification.new do |s|
+  s.name        = "routr"
+  s.version     = Routr::VERSION
+  s.authors     = ["Levente Bagi"]
+  s.email       = ["levente@picklive.com"]
+  s.homepage    = ""
+  s.summary     = %q{Finds the shortest path in a graph, allowing unusual cost definitions}
+  s.description = %q{Implements Dijkstra's algorithm to find the shortest path in a graph. The cost of an edge can be more general than just a numeric value.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec"
+end

data/spec/integration/routr_spec.rb

@@ -0,0 +1,122 @@
+require 'routr'
+
+describe Routr do
+  it "works for normal edge costs" do
+    class SimpleInterface
+      NETWORK = {
+        'A' => { 'B' => 50, 'C' => 100 },
+        'B' => { 'D' => 50 },
+        'C' => { 'D' => 10 },
+        'D' => {}
+      }
+
+      # This will be used if :initial_distance is not supplied to calculate_route
+      def initial_distance
+        0
+      end
+
+      def neighbours_of(node_key)
+        NETWORK[node_key].keys
+      end
+
+      def edge_cost(a_key, b_key)
+        NETWORK[a_key][b_key]
+      end
+    end
+      
+    route = Routr.new(SimpleInterface.new).calculate_route(
+      :from => 'A',
+      :to => 'D'
+    )
+
+    route.hops.count.should == 2
+    route.members.count.should == 3
+
+    route.hops.first.from.should == 'A' 
+    route.hops.first.to.should == 'B' 
+    route.hops.first.distance.should == 50
+    route.hops.last.from.should == 'B' 
+    route.hops.last.to.should == 'D' 
+    route.hops.last.distance.should == 100
+
+    route.members.first.should == 'A'
+    route.members.last.should == 'D'
+
+    route.distance.should == 100
+  end
+
+  it "works for custom edge costs" do
+
+    # This example uses a simplified version of time.
+    #
+    # The values denote a time in a day when the two nodes 'meet',
+    # where 1000 represents a whole day, i.e.
+    #
+    # A meets B at 500, 1500, 2500, etc.
+    # A meets C at 100, 1100, 2100, etc.
+    class CustomInterface
+      NETWORK = {
+        'A' => { 'B' => 300, 'C' => 600 },
+        'B' => { 'D' => 400 },
+        'C' => { 'D' => 700 },
+        'D' => {}
+      }
+
+      def neighbours_of(node_key)
+        NETWORK[node_key].keys
+      end
+
+      def calculate_new_distance(distance_so_far, a_key, b_key)
+        time_of_day = distance_so_far % 1000
+        beginning_of_day = distance_so_far - time_of_day
+        meeting_time = NETWORK[a_key][b_key]
+        if time_of_day <= meeting_time
+          beginning_of_day + meeting_time
+        else
+          beginning_of_day + 1000 + meeting_time
+        end
+      end
+    end
+          
+    route = Routr.new(CustomInterface.new).calculate_route(
+      :from => 'A',
+      :to => 'D',
+      :initial_distance => 50_564
+    )
+    route.members.should == %w(A C D)
+    route.distance.should == 50_700
+
+    route = Routr.new(CustomInterface.new).calculate_route(
+      :from => 'A',
+      :to => 'D',
+      :initial_distance => 50_900
+    )
+    route.members.should == %w(A B D)
+    route.distance.should == 51_400
+  end
+
+  it "returns a missing route if not found" do
+    route = Routr.new(SimpleInterface.new).calculate_route(
+      :from => 'D',
+      :to => 'A',
+      :initial_distance => 0
+    )
+    route.hops.should == []
+    route.members.should == []
+    route.found?.should be_false
+    route.missing?.should be_true
+  end
+
+  it "exposes the route as raw ruby" do
+    route = Routr.new(SimpleInterface.new).calculate_route(
+      :from => 'A',
+      :to => 'D'
+    )
+    route.raw.should == [
+      { :node => 'A', :distance => 0 },
+      { :node => 'B', :distance => 50 },
+      { :node => 'D', :distance => 100 },
+    ]
+  end
+end
+

data/spec/unit/calculator_spec.rb

@@ -0,0 +1,105 @@
+require "routr/calculator"
+
+describe Routr::Calculator do
+  it "calculates shortest path" do
+    graph = Graph.new(
+      :edges => [
+        ["a","b", 5],
+        ["b","c", 3],
+        ["c","d", 1],
+        ["a","d",10],
+        ["b","d", 2],
+        ["f","g", 1],
+      ]
+    )
+
+    r = Routr::Calculator.new(graph)
+    r.shortest_path("a", "a").should == %w(a)
+    r.shortest_path("a", "b").should == %w(a b)
+    r.shortest_path("a", "c").should == %w(a b c)
+    r.shortest_path("a", "d").should == %w(a b d)
+    r.shortest_path("a", "f").should == nil
+    r.shortest_path("a", "g").should == nil
+  end
+
+  it "calculates shortest path for graph with custom costs" do
+    graph = TimeGraph.new(
+      :edges => [
+        ["a","b","1200"], # a and b meet every day at 12:00 noon
+        ["b","c","1300"],
+        ["a","d","1215"],
+        ["d","c","1230"],
+        ["c","e","1245"],
+        ["f","g","1400"],
+        ["a","h","1100"],
+        ["h","i","1000"],
+      ]
+    )
+    #    h ---1000--- a ---1200--- b
+    #    |            |            |
+    #   1000         1215         1300
+    #    |            |            |
+    #    i            d ---1230--- c
+    #                              |
+    #                             1245
+    #    f ---1400--- g            |
+    #                              e
+    #
+    # Meeting times: 4 digits: hhmm (every day)
+    # Actual times: 6 digits: ddhhmm
+    # 001200 = day 0, 12:00 noon
+
+    r = Routr::Calculator.new(graph)
+    r.shortest_path("a", "a", "001200").should == %w(a)
+    r.shortest_path("a", "b", "001200").should == %w(a b)
+    r.shortest_path("a", "c", "001200").should == %w(a d c)
+    r.shortest_path("a", "d", "001200").should == %w(a d)
+    r.shortest_path("a", "e", "001200").should == %w(a d c e)
+    r.shortest_path("a", "f", "001200").should == nil
+    r.shortest_path("a", "g", "001200").should == nil
+    r.shortest_path("a", "h", "001200").should == %w(a h)
+    r.shortest_path("a", "i", "001200").should == %w(a h i)
+  end
+end
+
+
+class Graph
+  def initialize(attr)
+    @edges = {}
+    attr[:edges].each do |a, b, edge_info|
+      @edges[a] ||= {}
+      @edges[a][b] = edge_info
+    end
+  end
+
+  def edge_cost a, b
+    (@edges[a] && @edges[a][b]) || (@edges[b] && @edges[b][a])
+  end
+
+  def neighbours_of(node)
+    (
+      ( (@edges[node] && @edges[node].keys) || [] ) +
+      @edges.keys.select{|k| @edges[k].keys.include?(node)}
+    ).uniq
+  end
+
+end
+
+
+class TimeGraph < Graph
+  private :edge_cost
+
+  def calculate_new_distance time_so_far, a, b
+    meeting_time_i = edge_cost(a, b).to_i # it's not actually a cost, but that's where we store the meeting value
+    time_of_day_so_far_i = time_so_far.to_i % 10000
+
+    # meeting time today
+    new_time_i = time_so_far.to_i + (meeting_time_i - time_of_day_so_far_i)
+
+    # meeting time tomorrow
+    new_time_i += 10000 if time_of_day_so_far_i > meeting_time_i
+
+    new_time_i.to_s.rjust(6,"0")
+  end
+end
+

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification 
+name: routr
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Levente Bagi
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-03-29 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: Implements Dijkstra's algorithm to find the shortest path in a graph. The cost of an edge can be more general than just a numeric value.
+email: 
+- levente@picklive.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- Guardfile
+- LICENSE
+- README.md
+- Rakefile
+- cruise_config.rb
+- lib/routr.rb
+- lib/routr/calculator.rb
+- lib/routr/interface.rb
+- lib/routr/version.rb
+- routr.gemspec
+- spec/integration/routr_spec.rb
+- spec/unit/calculator_spec.rb
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.17
+signing_key: 
+specification_version: 3
+summary: Finds the shortest path in a graph, allowing unusual cost definitions
+test_files: 
+- spec/integration/routr_spec.rb
+- spec/unit/calculator_spec.rb