tuomas-knights_tour 0.2.5

data/CHANGELOG.rdoc

@@ -0,0 +1,24 @@
+=== 0.2.5 released 2009-01-14
+
+* Small code beautifications.
+
+=== 0.2.4 released 2008-12-10
+
+* Small code optimization.
+
+=== 0.2.3 released 2008-12-11
+
+* Small documentation improvements.
+* Refactored code.
+
+=== 0.2.2 released 2008-12-10
+
+* Small socumentation improvements.
+
+=== 0.2.1 released 2008-12-10
+
+* Refactored code.
+
+=== 0.2.0 released 2008-12-10
+
+* First revision that solves the problem correctly. :)

data/Manifest.txt

@@ -0,0 +1,7 @@
+CHANGELOG.rdoc
+Manifest.txt
+README.rdoc
+Rakefile
+bin/knights_tour
+lib/knights_tour.rb
+spec/knights_tour_spec.rb

data/README.rdoc

@@ -0,0 +1,82 @@
+= Knight's Tour
+
+A program that attempts to find a solution to the
+{Knight's Tour problem}[http://en.wikipedia.org/wiki/Knight%27s_Tour].
+I was inspired to do this by finding
+{a Python implementation}[http://ttsiodras.googlepages.com/knightstour.html].
+
+The program's algorithm is a recursive backtracking search that returns the
+first solution to the problem (if the algorithm finds one). It utilizes
+{Warnsdorff's heuristics}[http://mathworld.wolfram.com/KnightsTour.html] to
+avoid dead ends, making the search faster in general.
+
+== Installation
+
+Install the software as a RubyGem from GitHub:
+
+  $ sudo gem install tuomas-knights_tour --source http://gems.github.com
+
+The software is compatible with Ruby 1.9.1.
+
+== Usage
+
+Change the working directory of your command line shell into the project's
+root directory and enter
+
+  $ ./bin/knights_tour
+
+The command attempts to solve the problem on a board of size 8x8, the knight
+located initially at position 0,0 (the top-left corner). If the program
+finds a solution, it displays a result similar to the following:
+
+  +---+---+---+---+---+---+---+---+
+  |  1| 62| 13| 36|  3| 38| 31| 28|
+  +---+---+---+---+---+---+---+---+
+  | 14| 35|  2| 63| 32| 29|  4| 39|
+  +---+---+---+---+---+---+---+---+
+  | 61| 12| 59| 34| 37| 42| 27| 30|
+  +---+---+---+---+---+---+---+---+
+  | 50| 15| 64| 43| 58| 33| 40|  5|
+  +---+---+---+---+---+---+---+---+
+  | 11| 60| 49| 54| 41| 24| 45| 26|
+  +---+---+---+---+---+---+---+---+
+  | 16| 51| 18| 57| 44| 55|  6| 23|
+  +---+---+---+---+---+---+---+---+
+  | 19| 10| 53| 48| 21|  8| 25| 46|
+  +---+---+---+---+---+---+---+---+
+  | 52| 17| 20|  9| 56| 47| 22|  7|
+  +---+---+---+---+---+---+---+---+
+
+The size of the board and the start position of the knight are configurable.
+For all the options, see
+
+  $ ./bin/knights_tour -h
+
+== Contacting
+
+Please send feedback by email to Tuomas Kareinen < tkareine (at) gmail (dot)
+com >.
+
+== Legal notes
+
+This software is licensed under the terms of the "MIT license":
+
+Copyright (c) 2008-2009 Tuomas Kareinen.
+
+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/Rakefile

@@ -0,0 +1,48 @@
+require "rubygems"
+
+require "hoe"
+require "./lib/knights_tour"
+Hoe.new("knights_tour", KnightsTour::Meta::VERSION.to_s) do |p|
+  p.author = "Tuomas Kareinen"
+  p.email = "tkareine@gmail.com"
+  p.url = "http://github.com/tuomas/knights_tour"
+  p.summary =<<-END
+A program that attempts to find a solution to the Knight's Tour problem.
+  END
+  p.readme_file = "README.rdoc"
+  p.history_file = "CHANGELOG.rdoc"
+  p.extra_rdoc_files = FileList["*.rdoc", "lib/**/*.rb"]
+  p.extra_deps = [["trollop", ">= 1.10.0"]]
+  p.extra_dev_deps = [["rspec", ">= 1.2.0"]]
+  p.rubyforge_name = "searchable-rec"
+end
+
+require "rake/rdoctask"
+require "lib/knights_tour"
+desc "Create documentation."
+Rake::RDocTask.new(:rdoc) do |rd|
+  rd.title = "Knight's Tour #{KnightsTour::Meta::VERSION}"
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("*.rdoc", "lib/**/*.rb")
+  rd.rdoc_dir = "rdoc"
+end
+
+require "spec/rake/spectask"
+desc "Run specs."
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = FileList["spec/**/*.rb"]
+  t.spec_opts = ["--format", "specdoc"]
+  #t.warning = true
+end
+
+desc "Find code smells."
+task :roodi do
+  sh("roodi '**/*.rb'")
+end
+
+desc "Search unfinished parts of source code."
+task :todo do
+  FileList["**/*.rb"].egrep /#.*(TODO|FIXME)/
+end
+
+task :default => :spec

data/bin/knights_tour

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+
+require "rubygems"
+require "trollop"
+require File.dirname(__FILE__) << "/../lib/knights_tour"
+
+# Parse the command line arguments and invoke the application.
+
+include KnightsTour
+
+options = Trollop::options do
+  version Meta.version
+
+  banner <<-EOS
+A program that attempts to find a solution to the Knight's Tour problem.
+
+Usage:
+
+  #{File.basename($0)} [OPTIONS] [SIZE]
+
+Where SIZE (default: 8,8) sets the size of the board to ROWS x COLS.
+
+Options:
+  EOS
+
+  opt :start_at, "Set the initial position of the knight (default: 0,0)",
+      :type     => :string,
+      :required => false
+end
+
+begin
+  app_params = {}
+  app_params[:size]     = ARGV.shift unless ARGV.empty?
+  app_params[:start_at] = options[:start_at] if options[:start_at]
+
+  app = Application.new(app_params)
+rescue ArgumentError => e
+  Trollop::die e.to_s
+end
+
+$stdout.puts app.solve

data/lib/knights_tour.rb

@@ -0,0 +1,192 @@
+module KnightsTour
+  module Meta #:nodoc:
+    module VERSION #:nodoc:
+      MAJOR = 0
+      MINOR = 2
+      PATCH = 5
+
+      def self.to_s
+        [ MAJOR, MINOR, PATCH ].join(".")
+      end
+    end
+
+    COPYRIGHT = "Copyright (c) Tuomas Kareinen"
+
+    LICENSE = "Licensed under the terms of the \"MIT license\". See README.rdoc."
+
+    def self.version
+      "#{File.basename($0)} #{Meta::VERSION}\n#{Meta::COPYRIGHT}\n#{Meta::LICENSE}"
+    end
+  end
+
+  class Application
+    def initialize(params = {})
+      @board_size = parse_board_size(params[:size] || [8, 8])
+      @knight_starts_at = parse_position_on_board(
+          params[:start_at] || [0, 0],
+          @board_size)
+    end
+
+    def solve
+      @solution ||= StringResult.new(traverse(
+                      Knight.new(@board_size, @knight_starts_at)))
+    end
+
+    private
+
+    def parse_pair(param)
+      unless param.is_a?(Array)
+        param = param.to_s.split(",")
+      end
+      [param[0].to_i, param[1].to_i]
+    end
+
+    def parse_board_size(size)
+      size = parse_pair(size)
+      unless size[0] > 0 && size[1] > 0
+        raise ArgumentError,
+              "Board size must be a pair of positive (non-zero) " \
+              "integers, separated by a comma"
+      end
+      size
+    end
+
+    def parse_position_on_board(position, board_size)
+      position = parse_pair(position)
+      unless (0...board_size[0]).include?(position[0]) &&
+             (0...board_size[1]).include?(position[1])
+        raise ArgumentError,
+              "Position must be a pair of positive integers within the " \
+              "size limits of the board, separated by a comma " \
+              "(for example, 0,5 is acceptable for board size 6,6)"
+      end
+      position
+    end
+
+    # Traverse the knight on the board.
+    #
+    # The algorithm is a recursive backtracking search for a first solution
+    # to the problem. The board is copied and modified by moving the knight
+    # to a new position in each recursive step of the algorithm, instead of
+    # modifying a single shared board in place.
+    def traverse(knight)
+      #$stdout.puts StringResult.new(board)  # debug
+
+      unless knight.traversed?
+        next_positions = knight.find_next_positions
+        next_positions.each do |next_position|
+          knight = traverse(knight.dup.traverse_to(next_position))
+          unless knight.nil?
+            return knight   # return the first solution found
+          end
+        end
+      end
+
+      knight  # no solutions found, or already found one
+    end
+  end
+
+  class Knight
+    ## as [x, y] pairs
+    LEGAL_STEPS = [ [-2,  1], [-1,  2], [ 1,  2], [ 2,  1],
+                    [ 2, -1], [ 1, -2], [-1, -2], [-2, -1] ]
+
+    attr_reader :board, :steps_taken, :current_position
+
+    def initialize(board_size, start_at)
+      @board = Array.new(board_size[0]) { Array.new(board_size[1], 0) }
+      @steps_taken = 0
+      traverse_to(start_at)
+    end
+
+    def initialize_copy(other)
+      @board = Marshal.load(Marshal.dump(other.board))
+      @steps_taken = other.steps_taken
+    end
+
+    def traversed?
+      last_step = @board.size * @board[0].size
+      @steps_taken == last_step
+    end
+
+    def traverse_to(new_position)
+      @steps_taken += 1
+      @current_position = new_position
+      @board[@current_position[0]][@current_position[1]] = @steps_taken
+      self
+    end
+
+    def find_next_positions
+      sort_by_warnsdorffs_heuristics(find_next_positions_at(@current_position))
+    end
+
+    private
+
+    # Optimization by applying Warnsdorff's heuristics: attempt to avoid
+    # dead ends by favoring positions with the lowest number of next
+    # available positions (thus, isolated positions become visited first).
+    #
+    # References:
+    #   <http://mathworld.wolfram.com/KnightsTour.html>
+    #   <http://web.telia.com/~u85905224/knight/eWarnsd.htm>
+    def sort_by_warnsdorffs_heuristics(positions)
+      positions.sort_by do |position|
+        find_next_positions_at(position).size
+      end
+    end
+
+    def find_next_positions_at(position)
+      positions = LEGAL_STEPS.map do |step|
+        position_after_step(position, step)
+      end
+      positions.reject { |pos| pos.nil? || (@board[pos[0]][pos[1]] > 0) }
+    end
+
+    def position_after_step(from, step)
+      x_pos = from[0] + step[0]
+      y_pos = from[1] + step[1]
+
+      if (0...@board.size).include?(x_pos) &&
+         (0...@board[0].size).include?(y_pos)
+        [x_pos, y_pos]
+      else
+        nil
+      end
+    end
+  end
+
+  class StringResult
+    def initialize(result)
+      if result.is_a?(Knight)
+        @result = board_to_s(result.board, result.steps_taken)
+      else
+        @result = "No solution found."
+      end
+    end
+
+    def to_s
+      @result
+    end
+
+    private
+
+    def board_to_s(board, steps_taken)
+      square_width = steps_taken.to_s.length + 1
+      separator_str = separator(square_width, board[0].size)
+
+      output = ""
+
+      board.each do |row|
+        output << separator_str
+        row_output = row.map { |step| "%#{square_width}s" % step }.join("|")
+        output << "|#{row_output}|\n"
+      end
+
+      output << separator_str
+    end
+
+    def separator(board_width, cols)
+      ("+" << "-" * board_width) * cols << "+\n"
+    end
+  end
+end

data/spec/knights_tour_spec.rb

@@ -0,0 +1,172 @@
+require File.dirname(__FILE__) << "/../lib/knights_tour"
+
+include KnightsTour
+
+describe Application do
+  it "should accept valid non-default board size" do
+    lambda { Application.new(:size => -1)  }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => 0)   }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => 1)   }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => "1") }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [-1, -1]) }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [-1, 0])  }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [0, -1])  }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [0, 0])   }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [0, 1])   }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [1, 0])   }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [1, 1]) }.should_not raise_error(ArgumentError)
+    lambda { Application.new(:size => [3, 4]) }.should_not raise_error(ArgumentError)
+    lambda { Application.new(:size => [5, 5]) }.should_not raise_error(ArgumentError)
+  end
+
+  it "should accept valid non-default start positions" do
+    lambda { Application.new(:size => [1, 1], :start_at => -1) }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [1, 1], :start_at => [ 0,  1]) }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [1, 1], :start_at => [ 1,  0]) }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [1, 1], :start_at => [ 1,  1]) }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [1, 1], :start_at => [ 3,  4]) }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [3, 7], :start_at => [ 4,  2]) }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [3, 7], :start_at => [ 2,  7]) }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [3, 7], :start_at => [ 3,  7]) }.should raise_error(ArgumentError)
+    lambda { Application.new(:size => [1, 1], :start_at => [ 0,  0]) }.should_not raise_error(ArgumentError)
+    lambda { Application.new(:size => [1, 2], :start_at => [ 0,  1]) }.should_not raise_error(ArgumentError)
+    lambda { Application.new(:size => [2, 1], :start_at => [ 1,  0]) }.should_not raise_error(ArgumentError)
+    lambda { Application.new(:size => [2, 2], :start_at => [ 0,  0]) }.should_not raise_error(ArgumentError)
+    lambda { Application.new(:size => [2, 2], :start_at => [ 1,  1]) }.should_not raise_error(ArgumentError)
+    lambda { Application.new(:size => [3, 7], :start_at => [ 2,  4]) }.should_not raise_error(ArgumentError)
+    lambda { Application.new(:size => [5, 5], :start_at => [ 4,  4]) }.should_not raise_error(ArgumentError)
+    lambda { Application.new(:size => [8, 8], :start_at => [ 7,  6]) }.should_not raise_error(ArgumentError)
+  end
+
+  it "should solve a board with size 1,1" do
+    result = Application.new(:size => [1, 1]).solve
+    result.to_s.should == <<-END
++--+
+| 1|
++--+
+    END
+  end
+
+  it "should solve a board with size 5,5" do
+    result = Application.new(:size => [5, 5]).solve
+    result.to_s.should == <<-END
++---+---+---+---+---+
+|  1| 14|  9| 20|  3|
++---+---+---+---+---+
+| 24| 19|  2| 15| 10|
++---+---+---+---+---+
+| 13|  8| 25|  4| 21|
++---+---+---+---+---+
+| 18| 23|  6| 11| 16|
++---+---+---+---+---+
+|  7| 12| 17| 22|  5|
++---+---+---+---+---+
+    END
+  end
+
+  it "should solve a board with size of 5,5, in start position 2,2" do
+    result = Application.new(:size => [5, 5], :start_at => [2, 2]).solve
+    result.to_s.should == <<-END
++---+---+---+---+---+
+| 21| 12|  7|  2| 19|
++---+---+---+---+---+
+|  6| 17| 20| 13|  8|
++---+---+---+---+---+
+| 11| 22|  1| 18|  3|
++---+---+---+---+---+
+| 16|  5| 24|  9| 14|
++---+---+---+---+---+
+| 23| 10| 15|  4| 25|
++---+---+---+---+---+
+    END
+  end
+
+  it "should solve a board with size of 3,7, in start position 2,4" do
+    result = Application.new(:size => [3, 7], :start_at => [2, 4]).solve
+    result.to_s.should == <<-END
++---+---+---+---+---+---+---+
+| 11| 14| 17| 20|  3|  8|  5|
++---+---+---+---+---+---+---+
+| 16| 21| 12|  9|  6| 19|  2|
++---+---+---+---+---+---+---+
+| 13| 10| 15| 18|  1|  4|  7|
++---+---+---+---+---+---+---+
+    END
+  end
+
+  it "should cache the result" do
+    app = Application.new(:size => [1, 1])
+    result = []
+    result << app.solve
+    result << app.solve
+    result[0].should == result[1]
+  end
+end
+
+describe Knight do
+  before(:each) do
+    @knight = Knight.new([5, 5], [0, 0])
+    # broken board state, but it does not matter for testing
+    @knight.instance_variable_set(
+      :@board,
+      [ [  1,  0,  0, 12,  3 ],
+        [  0, 11,  2,  7, 18 ],
+        [  0,  0,  0,  0, 13 ],
+        [ 10, 15,  6,  0,  8 ],
+        [  0, 19,  9, 14,  5 ] ])
+    @knight.instance_variable_set(:@current_position, [1, 4])
+    @knight.instance_variable_set(:@steps_taken, 18)
+  end
+
+  it "should find next positions available" do
+    next_positions = @knight.send(:find_next_positions_at, @knight.current_position)
+    next_positions.sort!  # ensure the order is not correct already
+    next_positions.should == [ [0, 2], [2, 2], [3, 3] ]
+  end
+
+  it "should sort next positions by Warnsdorff's heuristics" do
+    next_positions = @knight.send(:find_next_positions_at, @knight.current_position)
+    next_positions.sort!  # ensure the order is not correct already
+    next_positions.should == [ [0, 2], [2, 2], [3, 3] ]
+    next_positions = @knight.send(:sort_by_warnsdorffs_heuristics, next_positions)
+    next_positions.should == [ [3, 3], [2, 2], [0, 2] ]
+  end
+
+  it "should find next positions, sorted" do
+    next_positions = @knight.find_next_positions
+    next_positions.should == [ [3, 3], [2, 2], [0, 2] ]
+  end
+end
+
+describe StringResult do
+  it "should show the result correctly for a failed result" do
+    StringResult.new(nil).to_s.should == "No solution found."
+  end
+
+  it "should show the result correctly for a trivial result" do
+    knight = Knight.new([1, 1], [0, 0])
+    knight.instance_variable_set(:@board, [[1]])
+    result = StringResult.new(knight)
+    result.to_s.should == <<-END
++--+
+| 1|
++--+
+    END
+  end
+
+  it "should show the result correctly for a non-trivial result" do
+    # in reality, this is not a solvable board size
+    knight = Knight.new([3, 3], [0, 0])
+    knight.instance_variable_set(:@board, [[1, 2, 3], [42, 56, 69], [0, 0, 119]])
+    knight.instance_variable_set(:@steps_taken, 119)
+    StringResult.new(knight).to_s.should == <<-END
++----+----+----+
+|   1|   2|   3|
++----+----+----+
+|  42|  56|  69|
++----+----+----+
+|   0|   0| 119|
++----+----+----+
+    END
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification 
+name: tuomas-knights_tour
+version: !ruby/object:Gem::Version 
+  version: 0.2.5
+platform: ruby
+authors: 
+- Tuomas Kareinen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-28 00:00:00 -07:00
+default_executable: knights_tour
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: trollop
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.10.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.11.0
+    version: 
+description: ""
+email: tkareine@gmail.com
+executables: 
+- knights_tour
+extensions: []
+
+extra_rdoc_files: 
+- Manifest.txt
+- CHANGELOG.rdoc
+- README.rdoc
+- lib/knights_tour.rb
+files: 
+- CHANGELOG.rdoc
+- Manifest.txt
+- README.rdoc
+- Rakefile
+- bin/knights_tour
+- lib/knights_tour.rb
+- spec/knights_tour_spec.rb
+has_rdoc: true
+homepage: http://github.com/tuomas/knights_tour
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: searchable-rec
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A program that attempts to find a solution to the Knight's Tour problem.
+test_files: []
+