knights_tour 0.3.5

data/CHANGELOG.rdoc

@@ -0,0 +1,50 @@
+=== 0.3.5 released 2009-09-16
+
+* Display proper version info on Ruby 1.8 when using option "-v".
+
+=== 0.3.4 released 2009-09-03
+
+* Slight documentation improvements.
+* Removed dependencies to Rubygems.
+
+=== 0.3.3 released 2009-04-17
+
+* Added missing Rakefile to the distribution gem.
+* Removed rspec as a dependency gem.
+
+=== 0.3.2 released 2009-03-31
+
+* Slight documentation improvements.
+
+=== 0.3.1 released 2009-03-28
+
+* Fixed usage documentation.
+
+=== 0.3.0 released 2009-03-28
+
+* The software is available as a RubyGem from GitHub.
+
+=== 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/MIT-LICENSE.txt

@@ -0,0 +1,19 @@
+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/README.rdoc

@@ -0,0 +1,66 @@
+= 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 Knight's Tour as a RubyGem from GitHub:
+
+  $ sudo gem install tuomas-knights_tour --source http://gems.github.com
+
+The program is compatible with Ruby 1.9.1.
+
+== Usage
+
+In the command line, run the program by entering
+
+  $ 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 command above is the same as invoking the program with
+
+  $ knights_tour -s 0,0 8,8
+
+The size of the board and the start position of the knight are configurable,
+however. For all the options, see
+
+  $ knights_tour -h
+
+== Contacting
+
+Please send feedback by email to Tuomas Kareinen < tkareine (at) gmail (dot)
+com >.
+
+== Legal notes
+
+Copyright (c) 2008-2009 Tuomas Kareinen. See MIT-LICENSE.txt in this
+directory.

data/Rakefile

@@ -0,0 +1,94 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "lib"))
+
+require "rubygems"
+
+full_name = "Knight's Tour"
+package_name = "knights_tour"
+require "#{package_name}"
+version = KnightsTour::VERSION
+
+require "rake/clean"
+
+require "rake/gempackagetask"
+spec = Gem::Specification.new do |s|
+  s.name = package_name
+  s.version = version
+  s.homepage = "http://github.com/tuomas/knights_tour"
+  s.summary = "Solves Knight's Tour problem."
+  s.description = "A program that attempts to find a solution to the Knight's Tour problem."
+
+  s.author = "Tuomas Kareinen"
+  s.email = "tkareine@gmail.com"
+
+  s.platform = Gem::Platform::RUBY
+  s.files = FileList["Rakefile", "MIT-LICENSE.txt", "*.rdoc", "bin/**/*", "lib/**/*", "spec/**/*"].to_a
+  s.executables = ["knights_tour"]
+
+  s.add_dependency("trollop", ">= 1.10.0")
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = FileList["MIT-LICENSE.txt", "*.rdoc"].to_a
+  s.rdoc_options << "--title"   << "#{full_name} #{version}" \
+                 << "--main"    << "README.rdoc" \
+                 << "--exclude" << "spec" \
+                 << "--line-numbers"
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = false
+  pkg.need_tar = true
+end
+
+desc "Generate a gemspec file"
+task :gemspec do
+  File.open("#{spec.name}.gemspec", "w") do |f|
+    f.write spec.to_ruby
+  end
+end
+
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{package_name}-#{version}.gem}
+end
+
+task :uninstall => [:clean] do
+  sh %{sudo gem uninstall #{package_name}}
+end
+
+require "rake/rdoctask"
+desc "Create documentation"
+Rake::RDocTask.new(:rdoc) do |rd|
+  rd.rdoc_dir = "rdoc"
+  rd.title = "#{full_name} #{version}"
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("MIT-LICENSE.txt", "*.rdoc", "lib/**/*.rb")
+  rd.options << "--line-numbers"
+end
+
+require "spec/rake/spectask"
+desc "Run specs"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = FileList["spec/**/*_spec.rb"]
+  t.spec_opts = ["--colour --format progress --loadby mtime"]
+  t.warning = true
+  t.libs << "lib"
+end
+
+desc "Run specs with RCov"
+Spec::Rake::SpecTask.new(:rcov) do |t|
+  t.spec_files = FileList["spec/**/*.rb"]
+  t.rcov = true
+  t.rcov_opts = ["--exclude", "spec"]
+  t.libs << "lib"
+end
+
+desc "Find code smells"
+task :roodi do
+  sh %{roodi "**/*.rb"}
+end
+
+desc "Search unfinished parts of source code"
+task :todo do
+  FileList["**/*.rb", "**/*.rdoc", "**/*.txt"].egrep /(TODO|FIXME)/
+end
+
+task :default => :spec

data/bin/knights_tour

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+
+require "trollop"
+require "knights_tour"
+
+# Parse the command line arguments and invoke the application.
+
+include KnightsTour
+
+options = Trollop::options do
+  version "#{File.basename($0)} #{KnightsTour::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
+
+puts app.solve

data/lib/knights_tour.rb

@@ -0,0 +1,172 @@
+module KnightsTour
+  VERSION = "0.3.5"
+
+  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)
+      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 "knights_tour"
+
+include KnightsTour
+
+describe KnightsTour::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 KnightsTour::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 KnightsTour::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,78 @@
+--- !ruby/object:Gem::Specification 
+name: knights_tour
+version: !ruby/object:Gem::Version 
+  version: 0.3.5
+platform: ruby
+authors: 
+- Tuomas Kareinen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-12 00:00:00 +03:00
+default_executable: 
+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: 
+description: A program that attempts to find a solution to the Knight's Tour problem.
+email: tkareine@gmail.com
+executables: 
+- knights_tour
+extensions: []
+
+extra_rdoc_files: 
+- MIT-LICENSE.txt
+- CHANGELOG.rdoc
+- README.rdoc
+files: 
+- Rakefile
+- MIT-LICENSE.txt
+- CHANGELOG.rdoc
+- README.rdoc
+- bin/knights_tour
+- lib/knights_tour.rb
+- spec/knights_tour_spec.rb
+has_rdoc: true
+homepage: http://github.com/tuomas/knights_tour
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --title
+- Knight's Tour 0.3.5
+- --main
+- README.rdoc
+- --exclude
+- spec
+- --line-numbers
+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: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Solves Knight's Tour problem.
+test_files: []
+