xo 0.0.1 → 1.0.0

data/lib/xo.rb

@@ -1,24 +1,3 @@
-module XO
-
-  X = :x
-  O = :o
-
-  def self.is_token?(val)
-    [X, O].include?(val)
-  end
-
-  def self.other_token(token)
-    token == X ? O : (token == O ? X : token)
-  end
-
-  class << self
-    alias_method :is_player?, :is_token?
-    alias_method :other_player, :other_token
-  end
-
-  class Position < Struct.new(:row, :column); end
-end
-
 require 'xo/grid'
 require 'xo/evaluator'
 require 'xo/engine'

data/lib/xo/ai.rb

@@ -1,4 +1,2 @@
+require 'xo/ai/geometric_grid'
 require 'xo/ai/minimax'
-require 'xo/ai/expert'
-require 'xo/ai/novice'
-require 'xo/ai/advanced_beginner'

data/lib/xo/ai/geometric_grid.rb

@@ -0,0 +1,113 @@
+require 'xo/grid'
+
+module XO
+
+  module AI
+
+    # A geometric grid is a Tic-tac-toe grid ({XO::Grid}) with the added benefit that
+    # various geometric transformations (rotation and reflection) can be applied. It
+    # defines a concept of equivalence under these transformations. Geometric grids can
+    # be checked for equality and they define a hash function that allows them to be
+    # used as keys within a Hash.
+    class GeometricGrid < XO::Grid
+
+      # Rotate the geometric grid clockwise by 90 degrees.
+      #
+      #    0 | 1 | 2          6 | 3 | 0
+      #   ---+---+---        ---+---+---
+      #    3 | 4 | 5    =>    7 | 4 | 1
+      #   ---+---+---        ---+---+---
+      #    6 | 7 | 8          8 | 5 | 2
+      #
+      # @return [GeometricGrid]
+      def rotate
+        GeometricGrid.new(
+          "#{self[3, 1]}#{self[2, 1]}#{self[1, 1]}" +
+          "#{self[3, 2]}#{self[2, 2]}#{self[1, 2]}" +
+          "#{self[3, 3]}#{self[2, 3]}#{self[1, 3]}"
+        )
+      end
+
+      # Reflect the geometric grid in its vertical axis.
+      #
+      #    0 | 1 | 2          2 | 1 | 0
+      #   ---+---+---        ---+---+---
+      #    3 | 4 | 5    =>    5 | 4 | 3
+      #   ---+---+---        ---+---+---
+      #    6 | 7 | 8          8 | 7 | 6
+      #
+      # @return [GeometricGrid]
+      def reflect
+        GeometricGrid.new(
+          "#{self[1, 3]}#{self[1, 2]}#{self[1, 1]}" +
+          "#{self[2, 3]}#{self[2, 2]}#{self[2, 1]}" +
+          "#{self[3, 3]}#{self[3, 2]}#{self[3, 1]}"
+        )
+      end
+
+      # Determines whether or not this geometric grid has the same
+      # occupied positions as the given geometric grid.
+      #
+      # @param other [GeometricGrid]
+      # @return [Boolean]
+      def same?(other)
+        self.inspect == other.inspect
+      end
+
+      # Determines whether or not this geometric grid is equivalent to
+      # the given geometric grid.
+      #
+      # Two geometric grids are considered equivalent iff one is a
+      # rotation or reflection of the other.
+      #
+      # @param other [GeometricGrid] the other grid
+      # @return [Boolean]
+      def equivalent?(other)
+        return false unless other.instance_of?(self.class)
+
+        transformations.any? { |grid| other.same?(grid) }
+      end
+
+      # Redefines equality for a geometric grid.
+      #
+      # Two geometric grids are equal iff they are equivalent.
+      #
+      # @return [Boolean]
+      def ==(other)
+        equivalent?(other)
+      end
+      alias_method :eql?, :==
+
+      # Required if you want to be able to use a geometric grid as a key in a Hash.
+      #
+      # Equivalent grids must have the same hash.
+      #
+      # @return [Integer]
+      def hash
+        transformations.map(&:inspect).sort.uniq.join.hash
+      end
+
+      private
+
+        def transformations
+          rotations + rotations.map(&:reflect)
+        end
+
+        def rotations
+          [self, rot90, rot180, rot270]
+        end
+
+        def rot90
+          rotate
+        end
+
+        def rot180
+          rotate.rotate
+        end
+
+        def rot270
+          rotate.rotate.rotate
+        end
+    end
+  end
+end

data/lib/xo/ai/minimax.rb

@@ -1,125 +1,223 @@
-require 'ostruct'
+require 'singleton'
+
 require 'xo/evaluator'
+require 'xo/ai/geometric_grid'
+
+module XO
+
+  module AI
+
+    # This class provides an implementation of the
+    # {http://en.wikipedia.org/wiki/Minimax#Minimax_algorithm_with_alternate_moves minimax algorithm}. The minimax algorithm
+    # is a recursive search algorithm used to find the next move in a 2-player (or n-player) game.
+    #
+    # The search space forms a tree where the root is the empty grid and every other node is a possible grid configuration that
+    # can be reached by playing through a game of Tic-tac-toe.
+    #
+    # Given any node in the tree and an indication of whose turn it is to play next, all the node's children can be determined by
+    # making one move in each of its open positions. For example, given the node
+    #
+    #    x | o | x
+    #   ---+---+---
+    #      | x |
+    #   ---+---+---
+    #    o |   | o
+    #
+    # and knowing that it's {XO::Grid::O}'s (the min player) turn to play. Then, its children will be the 3 nodes
+    #
+    #        A             B             C
+    #
+    #    x | o | x     x | o | x     x | o | x
+    #   ---+---+---   ---+---+---   ---+---+---
+    #    o | x |         | x | o       | x |
+    #   ---+---+---   ---+---+---   ---+---+---
+    #    o |   | o     o |   | o     o | o | o
+    #
+    # since there are 3 open positions in which {XO::Grid::O} can make a move.
+    #
+    # Within the implementation, A and B will be considered intermediate nodes and so the search algorithm will have to continue until
+    # it can make a conclusive determination. That occurs when it reaches a terminal node, like C. In that case, the algorithm assigns
+    # a value to the terminal node from the perspective of the player that has to play next. So in C's case,
+    # {XO::Grid::X} (the max player) has to play next. But {XO::Grid::X} can't play because {XO::Grid::O} won. So {XO::Grid::X} would
+    # value C with a low value, -1 in this case.
+    #
+    # Each intermediate node can now get a value in the following way. Consider node A. It's {XO::Grid::X}'s turn to play and
+    # {XO::Grid::X} is the max player. The max player seeks to maximize their value over all the values of its children (conversely,
+    # the min player seeks to minimize their value over all its children). It has 2 children and they will eventually be determined
+    # to have the values 0 and -1. Since 0 is greater than -1, A will get the value of 0. What this means essentially is that the max
+    # player will play to favor a squashed game rather than a losing game in this particular instance.
+    #
+    # It is interesting to note that B is simply a reflection of A and so will end up having the same value. The algorithm below is
+    # smart enough to recognize that and so it will not have to perform a similar calculation in B's case.
+    #
+    # The Minimax class is a Singleton class. You use it as follows:
+    #
+    # @example
+    #  Minimax.instance.moves(XO::Grid.new('xox x o o'), XO::Grid::O) # => [[3, 2]]
+    #
+    # The first time the instance of Minimax is created, it runs the minimax algorithm to compute the value of all the nodes in the
+    # search space. This of course takes a bit of time (~ 4 seconds), but subsequent calls are instantaneous.
+    class Minimax
+      include Singleton
+
+      # Determines the best moves that can be made on the given grid, knowing that it's turn's time to play.
+      #
+      # @param grid [XO::Grid]
+      # @param turn [XO::Grid::X, XO::Grid::O]
+      # @raise [ArgumentError] if turn is not a token or the combination of the values of grid and turn doesn't make sense
+      # @return [Array<Array(Integer, Integer)>]
+      def moves(grid, turn)
+        raise ArgumentError, "illegal token #{turn}" unless GeometricGrid.is_token?(turn)
+
+        best_moves(*lift(grid, turn))
+      end
 
-module XO::AI
+      private
 
-  def self.minimax(grid, player)
-    state = MaxGameState.new(grid, player)
-    moves = state.next_states.select { |next_state| state.score == next_state.score }.map(&:move)
+        attr_reader :the_grid, :scores
 
-    OpenStruct.new(start_state: state, moves: moves)
-  end
+        def initialize
+          init_search
+          build_search_tree
+        end
 
-  class GameState
+        def init_search
+          @the_grid = GeometricGrid.new
+          @scores = {}
+        end
 
-    attr_reader :grid, :player, :move, :next_states
+        def build_search_tree(player = MaxPlayer)
+          return if has_score?
 
-    def initialize(grid, player, move = nil)
-      @grid   = grid.dup
-      @player = player
-      @move   = move
+          analyze_grid(player)
 
-      generate_next_states
-    end
+          if terminal?
+            set_score(player)
+          else
+            next_grids = []
 
-    def result
-      @result ||= XO::Evaluator.analyze(grid, player)
-    end
+            the_grid.each_open do |r, c|
+              the_grid[r, c] = player.token
+              next_grids << the_grid.dup
 
-    def is_terminal?
-      case result[:status]
-      when :ok
-        false
-      when :game_over
-        true
-      else
-        raise IllegalGridStatusError
-      end
-    end
+              build_search_tree(player.other)
 
-    def scores
-      next_states.map(&:score)
-    end
+              the_grid[r, c] = :e
+            end
 
-    def score
-      if is_terminal?
-        terminal_score
-      else
-        non_terminal_score
-      end
-    end
+            set_final_score(player, next_grids)
+          end
+        end
 
-    def terminal_score
-      raise NotImplementedError
-    end
+        def has_score?
+          scores.key?(the_grid)
+        end
 
-    def non_terminal_score
-      raise NotImplementedError
-    end
+        def analyze_grid(player)
+          @results = Evaluator.instance.analyze(the_grid, player.token)
+        end
 
-    def next_game_state(next_grid, other_player, move)
-      raise NotImplementedError
-    end
+        def terminal?
+          @results[:status] == :game_over
+        end
+
+        def set_score(player)
+          scores[the_grid.dup] = player.score(@results[:type])
+        end
+
+        def set_final_score(player, next_grids)
+          scores[the_grid.dup] = player.final_score(next_grids, scores)
+        end
 
-    private
+        # The search tree that gets built is for the situation when {XO::Grid::X} is assumed to
+        # have played first. However, if we are given a grid to evaluate such that
+        # it can only be reached by assuming that {XO::Grid::O} played first then we need to
+        # patch things up so that we can find a representative in our search space
+        # for the given configuration.
+        def lift(grid, turn)
+          xs, os = Evaluator.instance.xos(grid)
+
+          if turn == GeometricGrid::X
+            if xs == os
+              [GeometricGrid.new(grid.inspect), GeometricGrid::X]
+            elsif xs < os
+              [invert(grid), GeometricGrid::O]
+            else
+              raise ArgumentError, "#{grid} and #{turn} is not a valid combination, too many X's"
+            end
+          else
+            if xs == os
+              [invert(grid), GeometricGrid::X]
+            elsif xs > os
+              [GeometricGrid.new(grid.inspect), GeometricGrid::O]
+            else
+              raise ArgumentError, "#{grid} and #{turn} is not a valid combination, too many O's"
+            end
+          end
+        end
+
+        def invert(grid)
+          inverted_grid = GeometricGrid.new
+
+          grid.each do |r, c, val|
+            inverted_grid[r, c] = GeometricGrid.other_token(val)
+          end
+
+          inverted_grid
+        end
+
+        def best_moves(grid, turn)
+          final_score = @scores[grid]
+          moves = []
 
-      def generate_next_states
-        @next_states = []
+          grid.each_open do |r, c|
+            grid[r, c] = turn
 
-        unless is_terminal?
-          grid.each_free do |r, c|
-            next_grid = grid.dup
-            next_grid[r, c] = player
+            moves << [r, c] if @scores[grid] == final_score
 
-            @next_states << next_game_state(next_grid, XO.other_player(player), XO::Position.new(r, c))
+            grid[r, c] = :e
           end
+
+          moves
         end
+    end
+
+    module MaxPlayer
+
+      def self.token
+        GeometricGrid::X
       end
-  end
 
-  class MaxGameState < GameState
+      def self.other
+        MinPlayer
+      end
 
-    def next_game_state(next_grid, other_player, move)
-      MinGameState.new(next_grid, other_player, move)
-    end
+      def self.score(type)
+        { winner: 1, loser: -1, squashed: 0 }[type]
+      end
 
-    def terminal_score
-      case result[:type]
-      when :winner
-        1
-      when :loser
-        -1
-      when :squashed
-        0
+      def self.final_score(next_grids, scores)
+        next_grids.map { |grid| scores[grid] }.max
       end
     end
 
-    def non_terminal_score
-      scores.max
-    end
-  end
+    module MinPlayer
 
-  class MinGameState < GameState
+      def self.token
+        GeometricGrid::O
+      end
 
-    def next_game_state(next_grid, other_player, move)
-      MaxGameState.new(next_grid, other_player, move)
-    end
+      def self.other
+        MaxPlayer
+      end
 
-    def terminal_score
-      case result[:type]
-      when :winner
-        -1
-      when :loser
-        1
-      when :squashed
-        0
+      def self.score(type)
+        { winner: -1, loser: 1, squashed: 0 }[type]
       end
-    end
 
-    def non_terminal_score
-      scores.min
+      def self.final_score(next_grids, scores)
+        next_grids.map { |grid| scores[grid] }.min
+      end
     end
   end
-
-  class IllegalGridStatusError < StandardError; end
 end