games.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Explaining the games.py module\n",
    "*Author: Chirag Vartak*<br>\n",
    "*Date: 12th March 2016*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## An Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "  Hello all!  \n",
    "  In this IPython notebook, I plan to help you a little so that you will be able to use the [games.py](https://github.com/aimacode/aima-python/blob/master/games.py) module. You might already know that the `games.py` module implements the algorithms in Chapter 5 (Adversarial Search) of the book *Artificial Intelligence: A Modern Approach*.  \n",
    "  \n",
    "  Before we begin, if you are unsure of how to use the [aima-python](https://github.com/aimacode/aima-python) repository or are not familiar with IPython notebooks you should read the [intro notebook](https://github.com/aimacode/aima-python/blob/master/intro.ipynb) first. Also, if you are more comfortable with Java than you are with Python we also have the [aima-java](https://github.com/aimacode/aima-java) repository.\n",
    "  \n",
    "  What we will do to learn to use the code in this module is simply dive in! I feel this is the correct approach as I assume you must have already read Chapter 5 of AIMA. If you haven't, you might want to go back and do that first. If you are tired (or just lazy), at least read the chapter upto Sec. 5.3 because this module covers the algorithms only till that section anyway. So, I will start by explaining what the class `Game` is and then we will immediately start implementing the `TicTacToe` game. After we define the rules of the `TicTacToe` game, we will create AI players who use different search strategies, namely Minimax Search and Alpha-Beta Search. We will make these players play among themselves, and later on we ourselves will play against these AI players (Yay!).  \n",
    "  \n",
    "The reason I chose the `TicTacToe` game for demonstration of this module should be obvious to you. Everyone knows it and has played it, it is analyzed in quite some detail in AIMA, and most importantly, it has comparatively few states (fewer than 362,880) so that we can explore the search tree completely.  \n",
    "  \n",
    "  So let's begin."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Implementing TicTacToe"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To use the code in `games.py` let's import everything from it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from games import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that, here, as the module `games.py` does a `from utils import *`, all the names (global variables, functions etc.) available in `utils.py` are directly available to us now."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### The class `Game`  \n",
    "  \n",
    "Let's have a look at the class `Game` in our module. We see that it has six functions, namely `actions`, `result`, `utility`, `terminal_test`, `to_move` and `display`. We see that these functions have not actually been implemented. This class is actually just a template class; we are supposed to create the class for our game, `TicTacToe` by inheriting this `Game` class and implement all the methods mentioned in `Game`. If you forget to implement any one of those, a `NotImplementedError` will be raised. So, in this sense, the `Game` class is what you might call an abstract class in Java: it implements nothing, just tells you all that you are supposed to implement and screams at you if forget to implement what it asks.  \n",
    "  \n",
    "  Now let's get into some details of all these methods in our `Game` class. You have to implement these methods when you create the new class that would represent your game.\n",
    "  \n",
    "* `__init__(self, <other variables>)` :  When you create a class inherited from the `Game` class (class `TicTacToe` in our case), you'll have to create an object of this inherited class to initialize the game. This initialization might require some additional information which would be passed to `__init__` as variables. For the case of our `TicTacToe` game, this additional information would be the number of rows `h`, number of columns `v` and how many consecutive X's or O's are needed in a row, column or diagonal for a win `k`. Also, the initial game state has to be defined here in `__init__`.\n",
    "* `actions(self, state)` : Given a game state, this method should generates all the legal actions possible from this state, as a list or a generator. Returning a generator rather than a list has the advantage that it saves space and you can still operate on it as a list.\n",
    "* `result(self, state, move)` : Given a game state and a move, this method returns the game state that you get by making that move on this game state.\n",
    "* `utility(self, state, player)` : Given a terminal game state and a player, this method returns the utility for that player in the given terminal game state. While implementing this method assume that the game state is a terminal game state. The logic in this module is such that this method will be called only on terminal game states.\n",
    "* `terminal_test(self, state)` : Given a game state, this method should return `True` if this game state is a terminal state, and `False` otherwise.\n",
    "* `to_move(self, state)` : Given a game state, this method returns the player who is to play next. This information is typically stored in the game state, so all this method does is extract this information and return it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Deciding the game state representation\n",
    "  \n",
    "  Now, before we start implementing our `TicTacToe` game, we need to decide how we will be representing our game state. Typically, a game state will give you all the current information about the game at any point in time. Yes, all of it. When you are given a game state, you should be able to tell whose turn it is next, how the game will look like on a real-life board (if it has one) etc. A game state need not include the history of the game. If you can play the game further given a game state, you game state representation is acceptable. While we might like to include all kinds of information in our game state, we wouldn't want to put too much information into it. Modifying this game state to generate a new one would be a real pain then.\n",
    "  \n",
    "  Now, as for our `TicTacToe` game state, would storing only the positions of all the X's and O's be sufficient to represent all the game information at that point in time? Well, does it tell us whose turn it is next? Looking at the 'X's and O's on the board and counting them should tell us that. But that would mean extra computing. To avoid this, we will also store whose move it is next in the game state.  \n",
    "  \n",
    "  Think about what we've done here. We have reduced extra computation by storing additional information in a game state. Now, this information might not be absolutely essential to tell us about the state of the game, but it does save us additional computation time. We'll do more of this later on.  \n",
    "  \n",
    "  The `TicTacToe` game defines its game state as:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "GameState = collections.namedtuple('GameState', 'to_move, utility, board, moves')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The game state is called, quite appropriately, `GameState`, and it has 4 variables, namely, `to_move`, `utility`, `board` and `moves`.  \n",
    "  \n",
    "  I'll describe these variables in some more detail:\n",
    "  \n",
    "* `to_move` : It represents whose turn it is to move next. This will be a string of a single character, either 'X' or 'O'.\n",
    "* `utility` : It stores the utility of the game state. Storing this utility is a good idea, because, when you do a Minimax Search or an Alphabeta Search, you generate many recursive calls, which travel all the way down to the terminal states. When these recursive calls go back up to the original callee, we have calculated utilities for many game states. We store these utilities in their respective `GameState`s to avoid calculating them all over again.\n",
    "* `board` : A dict that stores all the positions of X's and O's on the board\n",
    "* `moves` : It stores the list of legal moves possible from the current position. Note here, that storing the moves as a list, as it is done here, increases the space complexity of Minimax Search from `O(m)` to `O(bm)`. Refer to Sec. 5.2.1 of the book."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Representing a move  \n",
    "  \n",
    "  Now that we have decided how our game state will be represented, it's time to decide how our move will be represented. My advice on this: keep it simple. Becomes easy to use this move to modify a current game state to generate a new one.  \n",
    "  \n",
    "  For our `TicTacToe` game, we'll just represent a move by a tuple, where the first and the second elements of the tuple will represent the row and column, respectively, where the next X or O is to be made. Whether to make an X or an O will be decided by the `to_move` variable in the `GameState`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### The class `TicTacToe`  \n",
    "  \n",
    "  Take a look at the class `TicTacToe`. All the methods mentioned in the class `Game` have been implemented here. Some points to note in this class might be:  \n",
    "    \n",
    "* The class `TicTacToe` has been inherited from the class `Game`. As I mentioned earlier, you really want to do this. Catching bugs and errors becomes a whole lot easier.\n",
    "* A `display` function has been implemented. This function prints the given game state on the console. This might come in handy for debugging and is great when we play ourselves against AIs that we will be creating.\n",
    "* Additional functions `compute_utility` and `k_in_a_row` are created, which are used by other functions. Well, no one said that you can't do this."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating players to play the games  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `random_player` and `alphabeta_player`  \n",
    "  \n",
    "  So, we have finished implementation of the `TicTacToe` class. What this class does is that, it just defines the rules of the game. We need more to create an AI that can actually play the game. This is where `random_player` and `alphabeta_player` come in.  \n",
    "  \n",
    "  The `random_player` is a function that plays random moves in the game. That's it. There isn't much more to this guy.  \n",
    "  \n",
    "  The `alphabeta_player`, on the other hand, calls the `alphabeta_full_search` function, which returns the best move in the current game state. Thus, the `alphabeta_player` always plays the best move given a game state, assuming that the game tree is small enough to search entirely."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `query_player` and `play_game`  \n",
    "  \n",
    "  The `query_player` function allows you, a human opponent, to play the game. This function requires a `display` method to be implemented in your game class, so that successive game states can be displayed on the terminal, making it easier for you to visualize the game and play accordingly.  \n",
    "  \n",
    "  The `play_game` function will be the one that will actually be used to play the game. You pass as arguments to it, an instance of the game you want to play and the players you want in this game. Use it to play AI vs AI, AI vs human, or even human vs human matches!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Examples  \n",
    "  \n",
    "  I will show some code examples below that you can run. The games' classes which I will use are `TicTacToe` and the `Fig52Game`. The `Fig52Game` is already implemented (actually both are) in the module. This is that small game in Fig 5.2 of the book.  \n",
    "  \n",
    "  Have fun executing and modifying these examples!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"images/fig_5_2.svg\" width=\"75%\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's start by experimenting with the `Fig52Game` first. For that we'll first create an instance of this game:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from games import *\n",
    "game52 = Fig52Game()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First we try out our `random_player`. Given a game state it will give us a random move every time:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "random_player(game52, 'A')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "random_player(game52, 'A')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `alphabeta_player` will always give us the best move:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "print( alphabeta_player(game52, 'A') )\n",
    "print( alphabeta_player(game52, 'B') )\n",
    "print( alphabeta_player(game52, 'C') )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What the `alphabeta_player` does is, it simply calls the method `alphabeta_full_search`. They both are essentially the same. In the module, both `alphabeta_full_search` and `minimax_decision` have been implemented. They both do the same job and return the same thing, which is, the best move in the current state. It's just that `alphabeta_full_search` is more efficient w.r.t time because it prunes the search tree and hence, explores lesser number of states."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "minimax_decision('A', game52)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "alphabeta_full_search('A', game52)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's play `TicTacToe`. First we initialize the game:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "ttt = TicTacToe()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can print a state using the display method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "ttt.display(ttt.initial)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Hmm, so that's the initial state of the game; no X's and no O's.  \n",
    "  \n",
    "  Let us create a new game state by ourselves to experiment:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "my_state = GameState(\n",
    "    to_move = 'X',\n",
    "    utility = '0',\n",
    "    board = {(1,1): 'X', (1,2): 'O', (1,3): 'X',\n",
    "             (2,1): 'O',             (2,3): 'O',\n",
    "             (3,1): 'X',\n",
    "            },\n",
    "    moves = [(2,2), (3,2), (3,3)]\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, how does this game state look like?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "ttt.display(my_state)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `random_player` will behave how he is supposed to:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "random_player(ttt, my_state)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "random_player(ttt, my_state)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But the `alphabeta_player` will always give the best move, as expected:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "alphabeta_player(ttt, my_state)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's make 2 players play against each other. We use the `play_game` function for this. The `play_game` function makes players play the match against each other and returns the utility for the first player, of the terminal state reached when the game ends. Hence, for our `TicTacToe` game, if we get the output +1, the first player wins, -1 if the second player wins, and 0 if the match ends in a draw."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "bot_play = Canvas_TicTacToe('bot_play', 'random', 'alphabeta')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The output is +1, hence `alphabeta_player` wins.  \n",
    "  \n",
    "  Since, an `alphabeta_player` plays perfectly, a match between two `alphabeta_player`s should always end in a draw. Let's see if this happens:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "for _ in range(10):\n",
    "    print(play_game(ttt, alphabeta_player, alphabeta_player))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `random_player` should never win against an `alphabeta_player`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "for _ in range(10):\n",
    "    print(play_game(ttt, random_player, alphabeta_player))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, let's play a game ourselves against a `random_player`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "rand_play = Canvas_TicTacToe('rand_play', 'human', 'random')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Yay! We win. But we cannot win against an `alphabeta_player`, however hard we try."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "ab_play = Canvas_TicTacToe('ab_play', 'human', 'alphabeta')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Demonstrating the `play_game` function on the `game52`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "play_game(game52, alphabeta_player, alphabeta_player)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "play_game(game52, alphabeta_player, random_player)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "#play_game(game52, query_player, alphabeta_player)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "#play_game(game52, alphabeta_player, query_player)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that, here, if you are the first player, the `alphabeta_player` plays as MIN, and if you are the second player, the `alphabeta_player` plays as MAX. This happens because that's the way the game is defined in the class `Fig52Game`. Having a look at the code of this class should make it clear."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.5.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}