sliding_puzzle 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b1d7484d10c76bbf7e0f8be38bb08988ea6a5973e4d523c8cbbd114a5516c1dc
+  data.tar.gz: 850ae2da5a00df634aa1e7ef850ad2171a33a912925ad61c9a0999b697577269
+SHA512:
+  metadata.gz: 8185f6328ed9afca9cdff45dd7fad6e9e6c8e270e7a0cea049eac5a3ff4ce0023e8e9604e93f6a35c4084fcfe51091db51a267daccbd64e9059c24319b69c6cd
+  data.tar.gz: 94215e1af28e0f89f6acf436e2c71d214093fa42221078b2a7dad5ec3914eb6e6cf16a4f29e0f283b7603a1e584e7b88658ef5cf3274c6437973cf6454dec7c6

data/README.md

@@ -0,0 +1,269 @@
+## Sliding Puzzle ##
+
+A Ruby gem for manipulating and solving sliding tile puzzles.
+
+**TODO - this gem is a work in progress**
+
+### Overview ###
+
+You might have come across sliding tile puzzles before. They're usually cheap,
+plastic-y toys that can be rearranged by sliding their tiles around. Here's an
+example containing a picture of a frog:
+
+<br/><p align="center">
+  <img src="https://raw.githubusercontent.com/tuzz/sliding_puzzle/master/frog.jpg" />
+</p><br/>
+
+One of the pieces is blank which means an adjacent tile can move into its place.
+After repeating this a few times, these puzzles can be tricky to solve. We can
+also think of these puzzles as grids of numbers:
+
+<br/><p align="center">
+  <img src="https://raw.githubusercontent.com/tuzz/sliding_puzzle/master/grid.jpg" />
+</p><br/>
+
+The challenge is to find a sequence of moves to rearrange the 'start state' into
+the 'goal state' in as few moves as possible. This gem lets you play with these
+puzzles and it solves them in an optimal number of moves.
+
+In this example the blank is in the the upper-left corner of the goal state, but
+it's arbitrary where it's located.
+
+### Usage ###
+
+Puzzles are represented as arrays of numbers:
+
+```ruby
+puzzle = SlidingPuzzle.new(
+  [1, 2, 0], # <-- the 0 represents blank
+  [3, 4, 5],
+  [6, 7, 8],
+)
+```
+
+You can slide tiles around and print the result:
+
+```ruby
+puzzle.slide!(:right)
+puzzle.print
+# [1, 0, 2]
+# [3, 4, 5]
+# [6, 7, 8]
+```
+
+The `#slide` method will return a new `SlidingPuzzle` whereas `#slide!` will
+mutate the existing one.
+
+### Moves ###
+
+You can return an array of possible moves for a sliding puzzle:
+
+```ruby
+puzzle = SlidingPuzzle.new(
+  [1, 2, 0],
+  [3, 4, 5],
+  [6, 7, 8],
+)
+
+puzzle.moves
+#=> [:right, :up]
+```
+
+If you try a move that isn't valid, an error is raised:
+
+```ruby
+puzzle.slide(:left)
+# SlidingPuzzle::InvalidMoveError, "unable to slide left"
+```
+
+### Scrambling ###
+
+You can scramble a puzzle:
+
+```ruby
+puzzle.scramble!
+```
+
+By default, this will perform 100 random moves, but you can set this:
+
+```ruby
+puzzle.scramble!(moves: 3)
+```
+
+The `#scramble` method will return a new `SlidingPuzzle` whereas `#scramble!`
+will mutate the existing one.
+
+### Dimensions ###
+
+Puzzles can have different dimensions:
+
+```ruby
+two_by_four = SlidingPuzzle.new(
+  [1, 2, 3, 4],
+  [5, 6, 7, 0],
+)
+
+two_by_four.slide!(:down)
+two_by_four.print
+# [1, 2, 3, 0]
+# [5, 6, 7, 4]
+```
+
+Puzzles must be rectangular and contain a single blank.
+
+### Solving ###
+
+Finding the shortest solution for a sliding puzzle is
+[a hard problem](https://en.wikipedia.org/wiki/15_puzzle#Solvability). This gem
+provides 'oracles' to find these solutions:
+
+```ruby
+goal_state = SlidingPuzzle.new(
+  [1, 2, 0],
+  [3, 4, 5],
+  [6, 7, 8],
+)
+
+oracle = SlidingPuzzle.oracle(goal_state)
+```
+
+This 'oracle' finds the shortest solution from any start state:
+
+```ruby
+start_state = SlidingPuzzle.new(
+  [1, 4, 2],
+  [3, 7, 5],
+  [6, 0, 8],
+)
+
+oracle.solve(start_state)
+#=> [:down, :down, :left]
+```
+
+### Oracles ###
+
+Oracles aren't magic. They are the result of precomputing solutions in advance.
+This gem provides oracles for puzzles with up to eight tiles:
+
+```ruby
+goal_state = SlidingPuzzle.new(
+  [1, 2, 3, 4],
+  [5, 0, 6, 7],
+)
+
+oracle = SlidingPuzzle.oracle(goal_state)
+```
+
+The numbers of the goal state must be sequential, but the blank can be anywhere.
+
+The `#oracle` method will return `nil` for a puzzle with more than eight tiles,
+or if the numbers aren't sequential.
+
+### Impossible puzzles ###
+
+Some starting positions are
+[impossible to solve](https://en.wikipedia.org/wiki/15_puzzle#Solvability). For
+example, if you swap any two tiles from the goal state, there's no way to solve
+the puzzle:
+
+```ruby
+unsolvable = SlidingPuzzle.new(
+  [2, 1, 0],
+  [3, 4, 5],
+  [6, 7, 8],
+)
+
+oracle.solve(unsolvable)
+#=> nil
+```
+
+In total, there are [N!](https://en.wikipedia.org/wiki/Factorial) possible
+configurations for a puzzle with N tiles (including the blank), but only half of
+these are solvable.
+
+For the 3x3 puzzle, there are 9! / 2 = 181,400 solvable configurations.
+
+### Precomputing ###
+
+For dimensions with no oracles, you can precompute your own:
+
+```ruby
+goal_state = SlidingPuzzle.new(
+  [0, 1,  2, 3],
+  [4, 5,  6, 7],
+  [8, 9, 10, 11],
+)
+
+oracle = SlidingPuzzle.precompute(goal_state)
+```
+
+You can then write the result to a file:
+
+```ruby
+oracle.write("path/to/file")
+```
+
+And read it in later:
+
+```ruby
+oracle = SlidingPuzzle.read("path/to/file")
+
+start_state = SlidingPuzzle.new(
+  [1, 5,  2,  3],
+  [4, 0,  6,  7],
+  [8, 9, 10, 11],
+)
+
+oracle.solve(start_state)
+#=> [:down, :right]
+```
+
+For puzzles with greater than 12 tiles, you won't be able to precompute an
+oracle in a reasonable amount of time. The 4x4 puzzle will take more than 40,000
+times longer to precompute than the 3x4 puzzle and require terrabytes of RAM.
+The `debug` flag will reveal if it's ever likely to finish:
+
+```ruby
+SlidingPuzzle.precompute(goal_state, debug: true)
+# queue size: 1
+# queue size: 2
+# queue size: 3
+# ...
+```
+
+If it just keeps growing, it's unlikely to finish.
+
+### Other methods ###
+
+There are a few other methods that may be useful:
+
+```ruby
+# Get the number on the first row and second column:
+puzzle.get(0, 1)
+#=> 5
+
+# Find the row and column of the number 5:
+puzzle.find(5)
+#=> [0, 1]
+
+# Return a clone of the array of tiles:
+puzzle.tiles
+#=> [[1, 5,  2,  3], [4, 0,  6,  7], [8, 9, 10, 11]]
+
+# Return a clone of the puzzle:
+puzzle.clone
+#=> #<SlidingPuzzle:object_id>
+```
+
+### Ideas to try ###
+
+I hope you have fun with this gem. Here are some things to try:
+
+1) Find an algorithm to solve a puzzle without using an oracle
+2) Compare the number of moves your algorithm makes with the oracle
+3) Write a web server for interacting with sliding puzzles
+4) Read
+[more](https://www.ijcai.org/Proceedings/03/Papers/267.pdf)
+[about](https://www.ijcai.org/Proceedings/03/Papers/267.pdf)
+techniques for coping with larger dimensions
+5) Write a user interface to slide tiles around

data/lib/sliding_puzzle/base.rb

@@ -0,0 +1,136 @@
+class SlidingPuzzle
+  def self.oracle(goal_state)
+    Oracle.lookup(goal_state)
+  end
+
+  def self.precompute(goal_state, **options)
+    Oracle.precompute(goal_state, **options)
+  end
+
+  def self.read(path)
+    Oracle.read(path)
+  end
+
+  def initialize(*tiles)
+    self.tiles = flatten_tiles(tiles)
+    self.max_row = @tiles.size - 1
+    self.max_column = @tiles.first.size - 1
+
+    must_be_rectangular!
+    must_contain_one_blank!
+  end
+
+  def slide!(direction)
+    unless moves.include?(direction)
+      raise InvalidMoveError, "unable to slide #{direction}"
+    end
+
+    x1, y1 = find(0)
+    x2, y2 = x1, y1
+
+    y2 += 1 if direction == :left
+    y2 -= 1 if direction == :right
+    x2 += 1 if direction == :up
+    x2 -= 1 if direction == :down
+
+    @tiles[x1][y1], @tiles[x2][y2] = @tiles[x2][y2], @tiles[x1][y1]
+    self
+  end
+
+  def slide(direction)
+    clone.slide!(direction)
+  end
+
+  def clone
+    self.class.new(*tiles)
+  end
+
+  def print
+    Kernel.print @tiles.map(&:inspect).join("\n")
+  end
+
+  def moves
+    row, column = find(0)
+    moves = []
+
+    moves.push(:left) unless column == max_column
+    moves.push(:right) unless column.zero?
+    moves.push(:up) unless row == max_row
+    moves.push(:down) unless row.zero?
+
+    moves
+  end
+
+  def scramble!(moves: 100)
+    moves.times do
+      slide!(self.moves.sample)
+    end
+
+    self
+  end
+
+  def scramble(moves: 100)
+    clone.scramble!(moves: moves)
+  end
+
+  def tiles
+    JSON.parse(JSON.generate(@tiles))
+  end
+
+  def get(row, column)
+    @tiles[row][column]
+  end
+
+  def find(number)
+    tiles.each.with_index do |numbers, row|
+      numbers.each.with_index do |n, column|
+        return [row, column] if n == number
+      end
+    end
+
+    nil
+  end
+
+  def ==(other)
+    tiles == other.tiles
+  end
+
+  alias :eql? :==
+
+  def hash
+    tiles.hash
+  end
+
+  private
+
+  def flatten_tiles(tiles)
+    if tiles[0].is_a?(Array) && tiles[0][0].is_a?(Array)
+      tiles.flatten(1)
+    else
+      tiles
+    end
+  end
+
+  def must_be_rectangular!
+    sizes = tiles.map(&:size)
+
+    if sizes.uniq.size > 1
+      raise NotRectangularError, "puzzle must be rectangular"
+    end
+  end
+
+  def must_contain_one_blank!
+    blanks = tiles.flatten.count(0)
+
+    unless blanks == 1
+      raise BlankError, "puzzle must contain a single blank"
+    end
+  end
+
+  attr_accessor :max_row, :max_column
+  attr_writer :tiles
+
+  class InvalidMoveError < StandardError; end
+  class NotRectangularError < StandardError; end
+  class BlankError < StandardError; end
+end

data/lib/sliding_puzzle/oracle.rb

@@ -0,0 +1,109 @@
+class SlidingPuzzle
+  class Oracle
+    OPPOSITES = {
+      left: :right,
+      right: :left,
+      up: :down,
+      down: :up,
+    }
+
+    def self.precompute(goal_state, debug: false)
+      goal_state = goal_state.clone
+
+      queue = [goal_state]
+      lookup_table = { goal_state => :goal }
+
+      until queue.empty?
+        puts "queue size: #{queue.size}" if debug
+        puzzle = queue.shift
+
+        puzzle.moves.each do |direction|
+          next_puzzle = puzzle.slide(direction)
+
+          unless lookup_table[next_puzzle]
+            lookup_table[next_puzzle] = OPPOSITES[direction]
+            queue.push(next_puzzle)
+          end
+        end
+      end
+
+      new(lookup_table)
+    end
+
+    def self.precompute_all(max_tiles: 8, directory: "oracles", debug: false)
+      FileUtils.mkdir_p("oracles")
+
+      1.upto(5) do |rows|
+        1.upto(5) do |columns|
+          number_of_tiles = rows * columns - 1
+          next if number_of_tiles > max_tiles
+
+          numbers = 1.upto(number_of_tiles).to_a
+
+          0.upto(number_of_tiles) do |position|
+            numbers_with_blank = numbers.dup.insert(position, 0)
+            tiles = numbers_with_blank.each_slice(columns).to_a
+
+            goal_state = SlidingPuzzle.new(tiles)
+            path = "#{directory}/#{basename(goal_state)}.dat"
+
+            print "Precomputing #{path}... " if debug
+
+            oracle = precompute(goal_state)
+            oracle.write(path)
+
+            puts "Done." if debug
+          end
+        end
+      end
+    end
+
+    def self.lookup(goal_state)
+      filename = "#{basename(goal_state)}.dat"
+      path = File.expand_path("#{__dir__}/../../oracles/#{filename}")
+
+      read(path) if File.exist?(path)
+    end
+
+    def self.basename(puzzle)
+      puzzle.tiles.map { |row| row.join(",") }.join(":")
+    end
+
+    def initialize(lookup_table)
+      self.lookup_table = lookup_table
+    end
+
+    def solve(sliding_puzzle)
+      moves = []
+      next_puzzle = sliding_puzzle
+
+      loop do
+        direction = lookup_table[next_puzzle]
+
+        return nil unless direction
+        return moves if direction == :goal
+
+        moves.push(direction)
+        next_puzzle = next_puzzle.slide(direction)
+      end
+    end
+
+    def write(path)
+      data = Marshal.dump(self)
+      gzip = Zlib::Deflate.deflate(data)
+
+      File.open(path, "wb") { |f| f.write(gzip) }
+    end
+
+    def self.read(path)
+      gzip = File.binread(path)
+      data = Zlib::Inflate.inflate(gzip)
+
+      Marshal.load(data)
+    end
+
+    private
+
+    attr_accessor :lookup_table
+  end
+end

data/lib/sliding_puzzle.rb

@@ -0,0 +1,6 @@
+require "json"
+require "zlib"
+require "fileutils"
+
+require "sliding_puzzle/base"
+require "sliding_puzzle/oracle"

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: sliding_puzzle
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Chris Patuzzo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-01-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.3
+description: A Ruby gem for manipulating and solving sliding tile puzzles.
+email: chris@patuzzo.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/sliding_puzzle.rb
+- lib/sliding_puzzle/base.rb
+- lib/sliding_puzzle/oracle.rb
+homepage: https://github.com/tuzz/sliding_puzzle
+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.7.3
+signing_key: 
+specification_version: 4
+summary: Sliding Puzzle
+test_files: []