gastar 1.0.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    OTgxNmZlMjM1OWRiNjI3NTU4MDViNDJhYWE0MzQ3YWZmODRiNzcwOA==
+  data.tar.gz: !binary |-
+    NWZhMWUxMmYxYTYzMDE5NDBkM2YzNjU3MThjYjljNGZlN2ZjNGFmZA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NTNmNGU5OGFiODBmODA4MDUxYTFlNGYxZmVlN2Y0NDRjNDc3NWNlMGNmY2Vh
+    MmQ0NTFhODExNzJhNjNlNzk1ZDVhNWUzMzVhZDVkNTJiNWNhYjk4ODI4ZGJm
+    OWRiMjJmMGI4NThkNzdhODVmZTNlYmFkYzc4YWY4ZjIxNjU3MDk=
+  data.tar.gz: !binary |-
+    ZmYwMzViMjAzMjllNWRmNGY1ZmIyZGVjOTU1ODAyNzk4YmI5Yjc2NDExZTBm
+    NzYzNWQzOTk1ZDdlZTg1YmQyMWQ1OTIwNTYwMTFkOTE4NTJmMjQ0NGU0NmQ3
+    MmZiYzc1Y2RiZDVjNTQ0M2Q0N2EzMjVmMDY3ZTczMDJjNzkzZWM=

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in gastar.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Jonas Tingeborn
+
+MIT License
+
+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,81 @@
+# Gastar
+
+Generic A* (A-Star) search implementation for Ruby
+
+It is more or less a straight Ruby implementation of Justin Poliey's Python
+implementation. 
+
+To read more about the fine algoritm for finding the shortest path between
+nodes (cities, trade stops etc), read Justin's [blog post]
+(http://scriptogr.am/jdp/post/pathfinding-with-python-graphs-and-a-star)
+on the matter and check out the rather fine [Wikipedia article]
+(http://en.wikipedia.org/wiki/A*_search_algorithm).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'gastar'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install gastar
+
+## Usage
+
+Example use:
+
+    require 'gastar'
+    
+    # Implement the abstract node class.
+    # Note: All attributes below are custom for this implementation and none are
+    # needed nor used by the actual AStar seach algorithm. They're my domain atts.
+    class Node < AStarNode
+      attr_reader :name, :x, :y
+      def initialize(name, x, y)
+        super()
+        @name, @x, @y = name, x, y
+      end
+      def move_cost(other) 1 end
+      def to_s() name end
+    end
+    
+    # Also implement an algorithm for estimating cost of reaching the destination
+    class Space < AStar
+      def heuristic(node, start, goal)
+        Math.sqrt( (goal.x - node.x)**2 + (goal.y - node.y)**2 )
+      end
+    end
+    
+    # Create a graph as an ordinary hashmap, with the key being a node and the
+    # value a list of other nodes that can be reached from the key-node.
+    
+    sun = Node.new "Sundsvall",  9, 10
+    upp = Node.new "Uppsala",    9,  6
+    sth = Node.new "Stockholm", 10,  5
+    jon = Node.new "Jonkoping",  4,  3
+    got = Node.new "Goteborg",   1,  3
+    mal = Node.new "Malmo",      2,  1
+  
+    cities = {
+      sun => [upp],
+      sth => [sun,jon,upp],
+      jon => [sth,got,mal],
+      upp => [sth,sun],
+      mal => [jon],
+      got => [jon]
+    }
+  
+    puts Space.new(cities).search(sun, mal)
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/example/example_runner.rb

@@ -0,0 +1,79 @@
+require_relative "../lib/gastar"
+
+##########################################################
+# Example implementations
+##########################################################
+
+class AStarGrid < AStar
+  def heuristic(node, start, goal)
+    Math.sqrt((goal.x - node.x)**2 + (goal.y - node.y)**2)
+  end
+end
+
+class AStarGridNode < AStarNode
+  attr_reader :x, :y
+  def initialize(x, y)
+    super()
+    @x, @y = x, y
+  end
+  def move_cost(other)
+    diagonal = (self.x - other.x).abs == 1 and (self.y - other.y).abs == 1
+    diagonal ? 14 : 10
+  end
+  def to_s
+    "(%d,%d)" % [x,y]
+  end
+end
+
+##########################################################
+# Example graph generator and use of the search algoritm
+##########################################################
+
+def make_graph(width, height)
+  nodes = width.times.map{|x| height.times.map{|y| AStarGridNode.new(x, y) } }
+  graph = {}
+  width.times.to_a.product(height.times.to_a).each do |x, y|
+    node = nodes[x][y]
+    graph[node] = []
+    [-1, 0, 1].product([-1, 0, 1]).each do |i, j|
+      next unless 0 <= x + i && x + i < width
+      next unless 0 <= y + j && y + j < height
+      graph[nodes[x][y]] << nodes[x+i][y+j]
+    end
+  end
+  [graph, nodes]
+end
+
+def render(width,height,start, goal, path)
+  vertices = path.map{|step| [step.x, step.y] }
+  height.times.each do |y|
+    width.times.each do |x|
+      if [start.x, start.y] == [x,y]
+        print "S"
+      elsif [goal.x, goal.y] == [x,y]
+        print "G"
+      elsif vertices.include?([x,y])
+        print "+"
+      else
+        print "."
+      end
+    end
+    puts
+  end
+end
+
+def main
+  width, height = 16,10
+  graph, nodes = make_graph(width, height)
+  paths = AStarGrid.new(graph)
+  start, goal = nodes[1][2], nodes[ 12][7]
+  path = paths.search(start, goal)
+  unless path
+    puts "No path found"
+  else
+    puts "Path found:", path.join(" ")
+    render(width,height,start, goal, path)
+  end
+end
+
+main if __FILE__ == $0  

data/gastar.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'gastar/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "gastar"
+  spec.version       = Gastar::VERSION
+  spec.authors       = ["Jonas Tingeborn"]
+  spec.email         = ["tinjon@gmail.com"]
+  spec.description   = %q{A generic A* implementation}
+  spec.summary       = %q{A generic A* implementation}
+  spec.homepage      = "https://github.com/jojje/gastar"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

data/lib/gastar.rb

@@ -0,0 +1,120 @@
+require "set"
+require_relative "gastar/version"
+
+# A generic implementation of the A* search algoritm.
+#
+# A* is a search algoritm and this is a ruby implementation of it.
+# The implementation is such that you wrap the objects you want to find
+# paths between, add them to a Hash where the keys are nodes and values
+# neighbours of the corresponding nodes. You then provide this graph (hash)
+# when you instantiate the +AStar+ search class.
+#
+# To find the shortest path, or most profitable between two nodes, you supply
+# the start and goal nodes to the +#search+ method and if a path can be found
+# a list of the nodes making up the journey will be provided back. If no path
+# can be found, nil is returned.
+#
+# For implementation examples, refer to the rspec and test runner in the spec
+# directory.
+#
+# Credits:
+# The gem is mostly a rubification of Justin Poliey's Python implementation.
+# Check out his excellent post on the subject at:
+#  http://scriptogr.am/jdp/post/pathfinding-with-python-graphs-and-a-star
+#
+
+class AStar
+  # Populate the search space and indicate whether searching should maximize
+  # estimated cost for moving between nodes, or whether it should be
+  # minimized.
+  #
+  # Arguments:
+  # +graph+ is a the search space on which the path finding should operate.
+  # It's a plain hash with AStar nodes as keys and also for neighbor as the
+  # values. The value of each hash entry should be a list of neighbors.
+  # E.g. {node => [neighbour node, neighbour node]}
+  #
+  # +maximize_cost+ indicates that higher heuristic values and costs are better,
+  # such as higher profits. Normally it's less that's desired, for example for
+  # distance routing in euclidean space. This an optional argument and the
+  # default is to minimize cost (false).
+  #
+  def initialize(graph, maximize_cost=false)
+    @graph = graph
+    @maximize_cost = maximize_cost
+  end
+
+  # Abstract method that an implementor must provide in a derived class.
+  # This function should return the estimated cost (a number) for getting to
+  # the goal node. In eucledian space (2D/3D), most likely the trigonometric
+  # distance (Pythagorean theorem). For other uses some other function may be
+  # appropriate.
+  #
+  # Arguments:
+  # +node+  is the current node for which cost to the goal should be estimated.
+  # +start+ is the starting node. May or may not be useful to you, but is
+  #         provided all the same.
+  # +goal+  is the final destination node towards which the distance / cost
+  # should be estimated.
+  def heuristic(node, start, goal)
+    raise NotImplementedError
+  end
+
+  # Performs the actual path-finding. Takes two AStarNodes. 
+  # +start+, is the origin for the search and +goal+ where we want to get to.
+  # Returns the nodes (steps) including the start and goal nodes, that should
+  # be traversed if we were to follow the path.
+  def search(start, goal)
+    openset = Set.new
+    closedset = Set.new
+    current = start
+    openset_min_max = @maximize_cost ? openset.method(:max_by) : openset.method(:min_by)
+
+    openset.add(current)
+    while not openset.empty?
+      current = openset_min_max.call{|o| o.g + o.h }
+      if current == goal
+        path = []
+        while current.parent
+          path << current
+          current = current.parent
+        end
+        path << current
+        return path.reverse
+      end
+      openset.delete(current)
+      closedset.add(current)
+      @graph[current].each do |node|
+        next if closedset.include? node
+
+        if openset.include? node
+          new_g = current.g + current.move_cost(node)
+          if node.g > new_g
+            node.g = new_g
+            node.parent = current
+          end
+        else
+          node.g = current.g + current.move_cost(node)
+          node.h = heuristic(node, start, goal)
+          node.parent = current
+          openset.add(node)
+        end
+      end
+    end
+    return nil
+  end
+
+end
+
+# Abstract class where you implement the move_cost function
+# which specifies how expensive it is to get from the
+# current node to the +other+ node.
+class AStarNode
+  attr_accessor :g, :h, :parent
+  def initialize
+    @g, @h, @parent = 0, 0, nil
+  end
+  def move_cost(other)
+    raise NotImplementedError
+  end
+end

data/lib/gastar/version.rb

@@ -0,0 +1,3 @@
+module Gastar
+  VERSION = "1.0.0"
+end

data/spec/gastar_spec.rb

@@ -0,0 +1,46 @@
+require_relative '../lib/gastar'
+
+class Node < AStarNode
+  attr_reader :name, :x, :y
+  def initialize(name, x, y)
+    super()
+    @name, @x, @y = name, x, y
+  end
+  def move_cost(other) 1 end
+  def to_s() name end
+end
+
+class Space < AStar
+  def heuristic(node, start, goal)
+    Math.sqrt( (goal.x - node.x)**2 + (goal.y - node.y)**2 )
+  end
+end
+
+describe "AStar implementation" do
+
+  it "finds the shorted path between cities" do
+
+    sun = Node.new "Sundsvall",  9, 10
+    upp = Node.new "Uppsala",    9,  6
+    sth = Node.new "Stockholm", 10,  5
+    jon = Node.new "Jonkoping",  4,  3
+    got = Node.new "Gothenburg", 1,  3
+    mal = Node.new "Malmo",      2,  1
+
+    cities = {
+      sun => [upp],
+      sth => [sun,jon,upp],
+      jon => [sth,got,mal],
+      upp => [sth,sun],
+      mal => [jon],
+      got => [jon]
+    }
+
+    expected = [sun, upp, sth, jon, mal]
+    actual   = Space.new(cities).search(sun, mal)
+
+    actual.should eql(expected)
+
+  end
+end
+  

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: gastar
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jonas Tingeborn
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-08-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A generic A* implementation
+email:
+- tinjon@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- example/example_runner.rb
+- gastar.gemspec
+- lib/gastar.rb
+- lib/gastar/version.rb
+- spec/gastar_spec.rb
+homepage: https://github.com/jojje/gastar
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.6
+signing_key: 
+specification_version: 4
+summary: A generic A* implementation
+test_files:
+- spec/gastar_spec.rb
+has_rdoc: