-
| Percept: | \n", + "Feel Food | \n", + "Feel Water | \n", + "Feel Nothing | \n", + "
| Action: | \n", + "eat | \n", + "drink | \n", + "move down | \n", + "
| Percept: | \n", @@ -226,117 +461,254 @@ "Action: | \n", "eat | \n", "drink | \n", - "move up | \n", + "\n",
+ "
| \n",
"
class CSP(search.Problem):\n",
+ " """This class describes finite-domain Constraint Satisfaction Problems.\n",
+ " A CSP is specified by the following inputs:\n",
+ " variables A list of variables; each is atomic (e.g. int or string).\n",
+ " domains A dict of {var:[possible_value, ...]} entries.\n",
+ " neighbors A dict of {var:[var,...]} that for each variable lists\n",
+ " the other variables that participate in constraints.\n",
+ " constraints A function f(A, a, B, b) that returns true if neighbors\n",
+ " A, B satisfy the constraint when they have values A=a, B=b\n",
+ "\n",
+ " In the textbook and in most mathematical definitions, the\n",
+ " constraints are specified as explicit pairs of allowable values,\n",
+ " but the formulation here is easier to express and more compact for\n",
+ " most cases. (For example, the n-Queens problem can be represented\n",
+ " in O(n) space using this notation, instead of O(N^4) for the\n",
+ " explicit representation.) In terms of describing the CSP as a\n",
+ " problem, that's all there is.\n",
+ "\n",
+ " However, the class also supports data structures and methods that help you\n",
+ " solve CSPs by calling a search function on the CSP. Methods and slots are\n",
+ " as follows, where the argument 'a' represents an assignment, which is a\n",
+ " dict of {var:val} entries:\n",
+ " assign(var, val, a) Assign a[var] = val; do other bookkeeping\n",
+ " unassign(var, a) Do del a[var], plus other bookkeeping\n",
+ " nconflicts(var, val, a) Return the number of other variables that\n",
+ " conflict with var=val\n",
+ " curr_domains[var] Slot: remaining consistent values for var\n",
+ " Used by constraint propagation routines.\n",
+ " The following methods are used only by graph_search and tree_search:\n",
+ " actions(state) Return a list of actions\n",
+ " result(state, action) Return a successor of state\n",
+ " goal_test(state) Return true if all constraints satisfied\n",
+ " The following are just for debugging purposes:\n",
+ " nassigns Slot: tracks the number of assignments made\n",
+ " display(a) Print a human-readable representation\n",
+ " """\n",
+ "\n",
+ " def __init__(self, variables, domains, neighbors, constraints):\n",
+ " """Construct a CSP problem. If variables is empty, it becomes domains.keys()."""\n",
+ " variables = variables or list(domains.keys())\n",
+ " self.variables = variables\n",
+ " self.domains = domains\n",
+ " self.neighbors = neighbors\n",
+ " self.constraints = constraints\n",
+ " self.initial = ()\n",
+ " self.curr_domains = None\n",
+ " self.nassigns = 0\n",
+ "\n",
+ " def assign(self, var, val, assignment):\n",
+ " """Add {var: val} to assignment; Discard the old value if any."""\n",
+ " assignment[var] = val\n",
+ " self.nassigns += 1\n",
+ "\n",
+ " def unassign(self, var, assignment):\n",
+ " """Remove {var: val} from assignment.\n",
+ " DO NOT call this if you are changing a variable to a new value;\n",
+ " just call assign for that."""\n",
+ " if var in assignment:\n",
+ " del assignment[var]\n",
+ "\n",
+ " def nconflicts(self, var, val, assignment):\n",
+ " """Return the number of conflicts var=val has with other variables."""\n",
+ "\n",
+ " # Subclasses may implement this more efficiently\n",
+ " def conflict(var2):\n",
+ " return (var2 in assignment and\n",
+ " not self.constraints(var, val, var2, assignment[var2]))\n",
+ "\n",
+ " return count(conflict(v) for v in self.neighbors[var])\n",
+ "\n",
+ " def display(self, assignment):\n",
+ " """Show a human-readable representation of the CSP."""\n",
+ " # Subclasses can print in a prettier way, or display with a GUI\n",
+ " print('CSP:', self, 'with assignment:', assignment)\n",
+ "\n",
+ " # These methods are for the tree and graph-search interface:\n",
+ "\n",
+ " def actions(self, state):\n",
+ " """Return a list of applicable actions: nonconflicting\n",
+ " assignments to an unassigned variable."""\n",
+ " if len(state) == len(self.variables):\n",
+ " return []\n",
+ " else:\n",
+ " assignment = dict(state)\n",
+ " var = first([v for v in self.variables if v not in assignment])\n",
+ " return [(var, val) for val in self.domains[var]\n",
+ " if self.nconflicts(var, val, assignment) == 0]\n",
+ "\n",
+ " def result(self, state, action):\n",
+ " """Perform an action and return the new state."""\n",
+ " (var, val) = action\n",
+ " return state + ((var, val),)\n",
+ "\n",
+ " def goal_test(self, state):\n",
+ " """The goal is to assign all variables, with all constraints satisfied."""\n",
+ " assignment = dict(state)\n",
+ " return (len(assignment) == len(self.variables)\n",
+ " and all(self.nconflicts(variables, assignment[variables], assignment) == 0\n",
+ " for variables in self.variables))\n",
+ "\n",
+ " # These are for constraint propagation\n",
+ "\n",
+ " def support_pruning(self):\n",
+ " """Make sure we can prune values from domains. (We want to pay\n",
+ " for this only if we use it.)"""\n",
+ " if self.curr_domains is None:\n",
+ " self.curr_domains = {v: list(self.domains[v]) for v in self.variables}\n",
+ "\n",
+ " def suppose(self, var, value):\n",
+ " """Start accumulating inferences from assuming var=value."""\n",
+ " self.support_pruning()\n",
+ " removals = [(var, a) for a in self.curr_domains[var] if a != value]\n",
+ " self.curr_domains[var] = [value]\n",
+ " return removals\n",
+ "\n",
+ " def prune(self, var, value, removals):\n",
+ " """Rule out var=value."""\n",
+ " self.curr_domains[var].remove(value)\n",
+ " if removals is not None:\n",
+ " removals.append((var, value))\n",
+ "\n",
+ " def choices(self, var):\n",
+ " """Return all values for var that aren't currently ruled out."""\n",
+ " return (self.curr_domains or self.domains)[var]\n",
+ "\n",
+ " def infer_assignment(self):\n",
+ " """Return the partial assignment implied by the current inferences."""\n",
+ " self.support_pruning()\n",
+ " return {v: self.curr_domains[v][0]\n",
+ " for v in self.variables if 1 == len(self.curr_domains[v])}\n",
+ "\n",
+ " def restore(self, removals):\n",
+ " """Undo a supposition and all inferences from it."""\n",
+ " for B, b in removals:\n",
+ " self.curr_domains[B].append(b)\n",
+ "\n",
+ " # This is for min_conflicts search\n",
+ "\n",
+ " def conflicted_vars(self, current):\n",
+ " """Return a list of variables in current assignment that are in conflict"""\n",
+ " return [var for var in self.variables\n",
+ " if self.nconflicts(var, current[var], current) > 0]\n",
+ "def different_values_constraint(A, a, B, b):\n",
+ " """A constraint saying two neighboring variables must differ in value."""\n",
+ " return a != b\n",
+ "def MapColoringCSP(colors, neighbors):\n",
+ " """Make a CSP for the problem of coloring a map with different colors\n",
+ " for any two adjacent regions. Arguments are a list of colors, and a\n",
+ " dict of {region: [neighbor,...]} entries. This dict may also be\n",
+ " specified as a string of the form defined by parse_neighbors."""\n",
+ " if isinstance(neighbors, str):\n",
+ " neighbors = parse_neighbors(neighbors)\n",
+ " return CSP(list(neighbors.keys()), UniversalDict(colors), neighbors,\n",
+ " different_values_constraint)\n",
+ "def queen_constraint(A, a, B, b):\n",
+ " """Constraint is satisfied (true) if A, B are really the same variable,\n",
+ " or if they are not in the same row, down diagonal, or up diagonal."""\n",
+ " return A == B or (a != b and A + a != B + b and A - a != B - b)\n",
+ "class NQueensCSP(CSP):\n",
+ " """Make a CSP for the nQueens problem for search with min_conflicts.\n",
+ " Suitable for large n, it uses only data structures of size O(n).\n",
+ " Think of placing queens one per column, from left to right.\n",
+ " That means position (x, y) represents (var, val) in the CSP.\n",
+ " The main structures are three arrays to count queens that could conflict:\n",
+ " rows[i] Number of queens in the ith row (i.e val == i)\n",
+ " downs[i] Number of queens in the \\ diagonal\n",
+ " such that their (x, y) coordinates sum to i\n",
+ " ups[i] Number of queens in the / diagonal\n",
+ " such that their (x, y) coordinates have x-y+n-1 = i\n",
+ " We increment/decrement these counts each time a queen is placed/moved from\n",
+ " a row/diagonal. So moving is O(1), as is nconflicts. But choosing\n",
+ " a variable, and a best value for the variable, are each O(n).\n",
+ " If you want, you can keep track of conflicted variables, then variable\n",
+ " selection will also be O(1).\n",
+ " >>> len(backtracking_search(NQueensCSP(8)))\n",
+ " 8\n",
+ " """\n",
+ "\n",
+ " def __init__(self, n):\n",
+ " """Initialize data structures for n Queens."""\n",
+ " CSP.__init__(self, list(range(n)), UniversalDict(list(range(n))),\n",
+ " UniversalDict(list(range(n))), queen_constraint)\n",
+ "\n",
+ " self.rows = [0] * n\n",
+ " self.ups = [0] * (2 * n - 1)\n",
+ " self.downs = [0] * (2 * n - 1)\n",
+ "\n",
+ " def nconflicts(self, var, val, assignment):\n",
+ " """The number of conflicts, as recorded with each assignment.\n",
+ " Count conflicts in row and in up, down diagonals. If there\n",
+ " is a queen there, it can't conflict with itself, so subtract 3."""\n",
+ " n = len(self.variables)\n",
+ " c = self.rows[val] + self.downs[var + val] + self.ups[var - val + n - 1]\n",
+ " if assignment.get(var, None) == val:\n",
+ " c -= 3\n",
+ " return c\n",
+ "\n",
+ " def assign(self, var, val, assignment):\n",
+ " """Assign var, and keep track of conflicts."""\n",
+ " oldval = assignment.get(var, None)\n",
+ " if val != oldval:\n",
+ " if oldval is not None: # Remove old val if there was one\n",
+ " self.record_conflict(assignment, var, oldval, -1)\n",
+ " self.record_conflict(assignment, var, val, +1)\n",
+ " CSP.assign(self, var, val, assignment)\n",
+ "\n",
+ " def unassign(self, var, assignment):\n",
+ " """Remove var from assignment (if it is there) and track conflicts."""\n",
+ " if var in assignment:\n",
+ " self.record_conflict(assignment, var, assignment[var], -1)\n",
+ " CSP.unassign(self, var, assignment)\n",
+ "\n",
+ " def record_conflict(self, assignment, var, val, delta):\n",
+ " """Record conflicts caused by addition or deletion of a Queen."""\n",
+ " n = len(self.variables)\n",
+ " self.rows[val] += delta\n",
+ " self.downs[var + val] += delta\n",
+ " self.ups[var - val + n - 1] += delta\n",
+ "\n",
+ " def display(self, assignment):\n",
+ " """Print the queens and the nconflicts values (for debugging)."""\n",
+ " n = len(self.variables)\n",
+ " for val in range(n):\n",
+ " for var in range(n):\n",
+ " if assignment.get(var, '') == val:\n",
+ " ch = 'Q'\n",
+ " elif (var + val) % 2 == 0:\n",
+ " ch = '.'\n",
+ " else:\n",
+ " ch = '-'\n",
+ " print(ch, end=' ')\n",
+ " print(' ', end=' ')\n",
+ " for var in range(n):\n",
+ " if assignment.get(var, '') == val:\n",
+ " ch = '*'\n",
+ " else:\n",
+ " ch = ' '\n",
+ " print(str(self.nconflicts(var, val, assignment)) + ch, end=' ')\n",
+ " print()\n",
+ "def min_conflicts(csp, max_steps=100000):\n",
+ " """Solve a CSP by stochastic Hill Climbing on the number of conflicts."""\n",
+ " # Generate a complete assignment for all variables (probably with conflicts)\n",
+ " csp.current = current = {}\n",
+ " for var in csp.variables:\n",
+ " val = min_conflicts_value(csp, var, current)\n",
+ " csp.assign(var, val, current)\n",
+ " # Now repeatedly choose a random conflicted variable and change it\n",
+ " for i in range(max_steps):\n",
+ " conflicted = csp.conflicted_vars(current)\n",
+ " if not conflicted:\n",
+ " return current\n",
+ " var = random.choice(conflicted)\n",
+ " val = min_conflicts_value(csp, var, current)\n",
+ " csp.assign(var, val, current)\n",
+ " return None\n",
+ "def AC3(csp, queue=None, removals=None, arc_heuristic=dom_j_up):\n",
+ " """[Figure 6.3]"""\n",
+ " if queue is None:\n",
+ " queue = {(Xi, Xk) for Xi in csp.variables for Xk in csp.neighbors[Xi]}\n",
+ " csp.support_pruning()\n",
+ " queue = arc_heuristic(csp, queue)\n",
+ " while queue:\n",
+ " (Xi, Xj) = queue.pop()\n",
+ " if revise(csp, Xi, Xj, removals):\n",
+ " if not csp.curr_domains[Xi]:\n",
+ " return False\n",
+ " for Xk in csp.neighbors[Xi]:\n",
+ " if Xk != Xj:\n",
+ " queue.add((Xk, Xi))\n",
+ " return True\n",
+ "def revise(csp, Xi, Xj, removals):\n",
+ " """Return true if we remove a value."""\n",
+ " revised = False\n",
+ " for x in csp.curr_domains[Xi][:]:\n",
+ " # If Xi=x conflicts with Xj=y for every possible y, eliminate Xi=x\n",
+ " if all(not csp.constraints(Xi, x, Xj, y) for y in csp.curr_domains[Xj]):\n",
+ " csp.prune(Xi, x, removals)\n",
+ " revised = True\n",
+ " return revised\n",
+ "def mrv(assignment, csp):\n",
+ " """Minimum-remaining-values heuristic."""\n",
+ " return argmin_random_tie(\n",
+ " [v for v in csp.variables if v not in assignment],\n",
+ " key=lambda var: num_legal_values(csp, var, assignment))\n",
+ "def num_legal_values(csp, var, assignment):\n",
+ " if csp.curr_domains:\n",
+ " return len(csp.curr_domains[var])\n",
+ " else:\n",
+ " return count(csp.nconflicts(var, val, assignment) == 0\n",
+ " for val in csp.domains[var])\n",
+ " def nconflicts(self, var, val, assignment):\n",
+ " """Return the number of conflicts var=val has with other variables."""\n",
+ "\n",
+ " # Subclasses may implement this more efficiently\n",
+ " def conflict(var2):\n",
+ " return (var2 in assignment and\n",
+ " not self.constraints(var, val, var2, assignment[var2]))\n",
+ "\n",
+ " return count(conflict(v) for v in self.neighbors[var])\n",
+ "def lcv(var, assignment, csp):\n",
+ " """Least-constraining-values heuristic."""\n",
+ " return sorted(csp.choices(var),\n",
+ " key=lambda val: csp.nconflicts(var, val, assignment))\n",
+ "def tree_csp_solver(csp):\n",
+ " """[Figure 6.11]"""\n",
+ " assignment = {}\n",
+ " root = csp.variables[0]\n",
+ " X, parent = topological_sort(csp, root)\n",
+ "\n",
+ " csp.support_pruning()\n",
+ " for Xj in reversed(X[1:]):\n",
+ " if not make_arc_consistent(parent[Xj], Xj, csp):\n",
+ " return None\n",
+ "\n",
+ " assignment[root] = csp.curr_domains[root][0]\n",
+ " for Xi in X[1:]:\n",
+ " assignment[Xi] = assign_value(parent[Xi], Xi, csp, assignment)\n",
+ " if not assignment[Xi]:\n",
+ " return None\n",
+ " return assignment\n",
+ "![](\"images/fig_5_2.png\")
\n",
+ "\n",
+ "The states are represented with capital letters inside the triangles (eg. \"A\") while moves are the labels on the edges between states (eg. \"a1\"). Terminal nodes carry utility values. Note that the terminal nodes are named in this example 'B1', 'B2' and 'B2' for the nodes below 'B', and so forth.\n",
+ "\n",
+ "We will model the moves, utilities and initial state like this:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "moves = dict(A=dict(a1='B', a2='C', a3='D'),\n",
+ " B=dict(b1='B1', b2='B2', b3='B3'),\n",
+ " C=dict(c1='C1', c2='C2', c3='C3'),\n",
+ " D=dict(d1='D1', d2='D2', d3='D3'))\n",
+ "utils = dict(B1=3, B2=12, B3=8, C1=2, C2=4, C3=6, D1=14, D2=5, D3=2)\n",
+ "initial = 'A'"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "In `moves`, we have a nested dictionary system. The outer's dictionary has keys as the states and values the possible moves from that state (as a dictionary). The inner dictionary of moves has keys the move names and values the next state after the move is complete.\n",
+ "\n",
+ "Below is an example that showcases `moves`. We want the next state after move 'a1' from 'A', which is 'B'. A quick glance at the above image confirms that this is indeed the case."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "B\n"
+ ]
+ }
+ ],
+ "source": [
+ "print(moves['A']['a1'])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We will now take a look at the functions we need to implement. First we need to create an object of the `Fig52Game` class."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "fig52 = Fig52Game()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "`actions`: Returns the list of moves one can make from a given state."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "psource(Fig52Game.actions)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "['b1', 'b2', 'b3']\n"
+ ]
+ }
+ ],
+ "source": [
+ "print(fig52.actions('B'))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "`result`: Returns the next state after we make a specific move."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "psource(Fig52Game.result)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 10,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "B\n"
+ ]
+ }
+ ],
+ "source": [
+ "print(fig52.result('A', 'a1'))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "`utility`: Returns the value of the terminal state for a player ('MAX' and 'MIN'). Note that for 'MIN' the value returned is the negative of the utility."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "psource(Fig52Game.utility)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 12,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "3\n",
+ "-3\n"
+ ]
+ }
+ ],
+ "source": [
+ "print(fig52.utility('B1', 'MAX'))\n",
+ "print(fig52.utility('B1', 'MIN'))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "`terminal_test`: Returns `True` if the given state is a terminal state, `False` otherwise."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "psource(Fig52Game.terminal_test)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 14,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "True\n"
+ ]
+ }
+ ],
+ "source": [
+ "print(fig52.terminal_test('C3'))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "`to_move`: Return the player who will move in this state."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "psource(Fig52Game.to_move)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 16,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "MAX\n"
+ ]
+ }
+ ],
+ "source": [
+ "print(fig52.to_move('A'))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "As a whole the class `Fig52` that inherits from the class `Game` and overrides its functions:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "psource(Fig52Game)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# MIN-MAX\n",
+ "\n",
+ "## Overview\n",
+ "\n",
+ "This algorithm (often called *Minimax*) computes the next move for a player (MIN or MAX) at their current state. It recursively computes the minimax value of successor states, until it reaches terminals (the leaves of the tree). Using the `utility` value of the terminal states, it computes the values of parent states until it reaches the initial node (the root of the tree).\n",
+ "\n",
+ "It is worth noting that the algorithm works in a depth-first manner. The pseudocode can be found below:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/markdown": [
+ "### AIMA3e\n",
+ "__function__ MINIMAX-DECISION(_state_) __returns__ _an action_ \n",
+ " __return__ arg max _a_ ∈ ACTIONS(_s_) MIN\\-VALUE(RESULT(_state_, _a_)) \n",
+ "\n",
+ "---\n",
+ "__function__ MAX\\-VALUE(_state_) __returns__ _a utility value_ \n",
+ " __if__ TERMINAL\\-TEST(_state_) __then return__ UTILITY(_state_) \n",
+ " _v_ ← −∞ \n",
+ " __for each__ _a_ __in__ ACTIONS(_state_) __do__ \n",
+ " _v_ ← MAX(_v_, MIN\\-VALUE(RESULT(_state_, _a_))) \n",
+ " __return__ _v_ \n",
+ "\n",
+ "---\n",
+ "__function__ MIN\\-VALUE(_state_) __returns__ _a utility value_ \n",
+ " __if__ TERMINAL\\-TEST(_state_) __then return__ UTILITY(_state_) \n",
+ " _v_ ← ∞ \n",
+ " __for each__ _a_ __in__ ACTIONS(_state_) __do__ \n",
+ " _v_ ← MIN(_v_, MAX\\-VALUE(RESULT(_state_, _a_))) \n",
+ " __return__ _v_ \n",
+ "\n",
+ "---\n",
+ "__Figure__ ?? An algorithm for calculating minimax decisions. It returns the action corresponding to the best possible move, that is, the move that leads to the outcome with the best utility, under the assumption that the opponent plays to minimize utility. The functions MAX\\-VALUE and MIN\\-VALUE go through the whole game tree, all the way to the leaves, to determine the backed\\-up value of a state. The notation argmax _a_ ∈ _S_ _f_(_a_) computes the element _a_ of set _S_ that has maximum value of _f_(_a_)."
+ ],
+ "text/plain": [
+ "![](\"images/fig_5_2.svg\")
"
+ "# PLAYERS\n",
+ "\n",
+ "So, we have finished the implementation of the `TicTacToe` and `Fig52Game` classes. What these classes do is defining the rules of the games. We need more to create an AI that can actually play games. This is where `random_player` and `alphabeta_player` come in.\n",
+ "\n",
+ "## query_player\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",
+ "## random_player\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",
+ "## alphabeta_player\n",
+ "The `alphabeta_player`, on the other hand, calls the `alphabeta_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.\n",
+ "\n",
+ "## minimax_player\n",
+ "The `minimax_player`, on the other hand calls the `minimax_search` function which returns the best move in the current game state.\n",
+ "\n",
+ "## play_game\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": [
+ "# LET'S PLAY SOME GAMES!\n",
+ "\n",
+ "## Game52\n",
+ "\n",
"Let's start by experimenting with the `Fig52Game` first. For that we'll create an instance of the subclass Fig52Game inherited from the class Game:"
]
},
{
"cell_type": "code",
- "execution_count": 4,
+ "execution_count": 27,
"metadata": {
- "collapsed": false
+ "collapsed": true
},
"outputs": [],
"source": [
@@ -227,10 +894,8 @@
},
{
"cell_type": "code",
- "execution_count": 5,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 28,
+ "metadata": {},
"outputs": [
{
"name": "stdout",
@@ -250,15 +915,13 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "The `alphabeta_player(game, state)` will always give us the best move possible:"
+ "The `alphabeta_player(game, state)` will always give us the best move possible, for the relevant player (MAX or MIN):"
]
},
{
"cell_type": "code",
- "execution_count": 6,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 29,
+ "metadata": {},
"outputs": [
{
"name": "stdout",
@@ -280,15 +943,13 @@
"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."
+ "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 with regards to time because it prunes the search tree and hence, explores lesser number of states."
]
},
{
"cell_type": "code",
- "execution_count": 7,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 30,
+ "metadata": {},
"outputs": [
{
"data": {
@@ -296,7 +957,7 @@
"'a1'"
]
},
- "execution_count": 7,
+ "execution_count": 30,
"metadata": {},
"output_type": "execute_result"
}
@@ -307,10 +968,8 @@
},
{
"cell_type": "code",
- "execution_count": 8,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 31,
+ "metadata": {},
"outputs": [
{
"data": {
@@ -318,13 +977,13 @@
"'a1'"
]
},
- "execution_count": 8,
+ "execution_count": 31,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
- "alphabeta_full_search('A', game52)"
+ "alphabeta_search('A', game52)"
]
},
{
@@ -336,10 +995,8 @@
},
{
"cell_type": "code",
- "execution_count": 9,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 32,
+ "metadata": {},
"outputs": [
{
"name": "stdout",
@@ -354,21 +1011,19 @@
"3"
]
},
- "execution_count": 9,
+ "execution_count": 32,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
- "play_game(game52, alphabeta_player, alphabeta_player)"
+ "game52.play_game(alphabeta_player, alphabeta_player)"
]
},
{
"cell_type": "code",
- "execution_count": 10,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 33,
+ "metadata": {},
"outputs": [
{
"name": "stdout",
@@ -383,47 +1038,100 @@
"12"
]
},
- "execution_count": 10,
+ "execution_count": 33,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
- "play_game(game52, alphabeta_player, random_player)"
+ "game52.play_game(alphabeta_player, random_player)"
]
},
{
"cell_type": "code",
- "execution_count": 11,
- "metadata": {
- "collapsed": true
- },
- "outputs": [],
+ "execution_count": 34,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "current state:\n",
+ "A\n",
+ "available moves: ['a1', 'a2', 'a3']\n",
+ "\n",
+ "Your move? a1\n",
+ "B1\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "3"
+ ]
+ },
+ "execution_count": 34,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
"source": [
- "#play_game(game52, query_player, alphabeta_player)\n",
- "#play_game(game52, alphabeta_player, query_player)"
+ "game52.play_game(query_player, alphabeta_player)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 35,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "current state:\n",
+ "B\n",
+ "available moves: ['b1', 'b2', 'b3']\n",
+ "\n",
+ "Your move? b1\n",
+ "B1\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "3"
+ ]
+ },
+ "execution_count": 35,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "game52.play_game(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."
+ "Note that if you are the first player then alphabeta_player plays as MIN, and if you are the second player then 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."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "### TicTacToe game\n",
+ "## TicTacToe\n",
+ "\n",
"Now let's play `TicTacToe`. First we initialize the game by creating an instance of the subclass TicTacToe inherited from the class Game:"
]
},
{
"cell_type": "code",
- "execution_count": 12,
+ "execution_count": 36,
"metadata": {
- "collapsed": false
+ "collapsed": true
},
"outputs": [],
"source": [
@@ -439,10 +1147,8 @@
},
{
"cell_type": "code",
- "execution_count": 13,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 37,
+ "metadata": {},
"outputs": [
{
"name": "stdout",
@@ -462,16 +1168,16 @@
"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:"
+ "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": 14,
+ "execution_count": 38,
"metadata": {
- "collapsed": false
+ "collapsed": true
},
"outputs": [],
"source": [
@@ -490,15 +1196,13 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "So, how does this game state looks like?"
+ "So, how does this game state look like?"
]
},
{
"cell_type": "code",
- "execution_count": 15,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 39,
+ "metadata": {},
"outputs": [
{
"name": "stdout",
@@ -523,18 +1227,16 @@
},
{
"cell_type": "code",
- "execution_count": 16,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 40,
+ "metadata": {},
"outputs": [
{
"data": {
"text/plain": [
- "(3, 3)"
+ "(2, 2)"
]
},
- "execution_count": 16,
+ "execution_count": 40,
"metadata": {},
"output_type": "execute_result"
}
@@ -545,18 +1247,16 @@
},
{
"cell_type": "code",
- "execution_count": 17,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 41,
+ "metadata": {},
"outputs": [
{
"data": {
"text/plain": [
- "(3, 2)"
+ "(2, 2)"
]
},
- "execution_count": 17,
+ "execution_count": 41,
"metadata": {},
"output_type": "execute_result"
}
@@ -574,10 +1274,8 @@
},
{
"cell_type": "code",
- "execution_count": 18,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 42,
+ "metadata": {},
"outputs": [
{
"data": {
@@ -585,7 +1283,7 @@
"(2, 2)"
]
},
- "execution_count": 18,
+ "execution_count": 42,
"metadata": {},
"output_type": "execute_result"
}
@@ -598,46 +1296,51 @@
"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."
+ "Now let's make two 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": 19,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 43,
+ "metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
- "O X O \n",
- "O . X \n",
- "O X X \n",
- "-1\n"
+ "O O . \n",
+ "X O X \n",
+ "X X O \n"
]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "-1"
+ ]
+ },
+ "execution_count": 43,
+ "metadata": {},
+ "output_type": "execute_result"
}
],
"source": [
- "print(play_game(ttt, random_player, alphabeta_player))"
+ "ttt.play_game(random_player, alphabeta_player)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "The output is -1, hence `random_player` loses implies `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:"
+ "The output is (usually) -1, because `random_player` loses to `alphabeta_player`. Sometimes, however, `random_player` manages to draw with `alphabeta_player`.\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": 20,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 44,
+ "metadata": {},
"outputs": [
{
"name": "stdout",
@@ -688,7 +1391,7 @@
],
"source": [
"for _ in range(10):\n",
- " print(play_game(ttt, alphabeta_player, alphabeta_player))"
+ " print(ttt.play_game(alphabeta_player, alphabeta_player))"
]
},
{
@@ -700,61 +1403,59 @@
},
{
"cell_type": "code",
- "execution_count": 21,
- "metadata": {
- "collapsed": false
- },
+ "execution_count": 45,
+ "metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
- "X . . \n",
+ "X O O \n",
+ "X O . \n",
+ "O X X \n",
+ "-1\n",
+ "O X . \n",
+ "O X X \n",
+ "O . . \n",
+ "-1\n",
+ "X X O \n",
+ "O O X \n",
+ "O X . \n",
+ "-1\n",
"O O O \n",
". X X \n",
+ "X . . \n",
"-1\n",
"O O O \n",
- "X X O \n",
- "X X . \n",
+ ". . X \n",
+ "X . X \n",
"-1\n",
- "O X . \n",
- ". O X \n",
+ "O X O \n",
+ "X O X \n",
"X . O \n",
"-1\n",
- "O . . \n",
- ". O X \n",
- "X X O \n",
+ "O X X \n",
+ "O X X \n",
+ "O O . \n",
"-1\n",
+ "O O X \n",
"X O X \n",
- "X O O \n",
- ". O X \n",
- "-1\n",
- "O . X \n",
"X O . \n",
- ". X O \n",
"-1\n",
"O O X \n",
- "X O X \n",
"X O . \n",
+ "X O X \n",
"-1\n",
- "O O O \n",
- "O X X \n",
- "X . X \n",
- "-1\n",
- "X X O \n",
"O O X \n",
- "O X . \n",
- "-1\n",
- "X . X \n",
- "O O O \n",
- ". X . \n",
- "-1\n"
+ "X X O \n",
+ "O X X \n",
+ "0\n"
]
}
],
"source": [
"for _ in range(10):\n",
- " print(play_game(ttt, random_player, alphabeta_player))"
+ " print(ttt.play_game(random_player, alphabeta_player))"
]
},
{
@@ -765,15 +1466,24 @@
"\n",
"This subclass is used to play TicTacToe game interactively in Jupyter notebooks. TicTacToe class is called while initializing this subclass.\n",
"\n",
- "Let's have match between `random_player` and `alphabeta_player`. Click on the board to call players to make a move."
+ "Let's have a match between `random_player` and `alphabeta_player`. Click on the board to call players to make a move."
]
},
{
"cell_type": "code",
- "execution_count": 22,
+ "execution_count": 46,
"metadata": {
- "collapsed": false
+ "collapsed": true
},
+ "outputs": [],
+ "source": [
+ "from notebook import Canvas_TicTacToe"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 47,
+ "metadata": {},
"outputs": [
{
"data": {
@@ -781,7 +1491,7 @@
"\n",
"\n",
"class FOIL_container(FolKB):\n",
+ " """Hold the kb and other necessary elements required by FOIL."""\n",
+ "\n",
+ " def __init__(self, clauses=None):\n",
+ " self.const_syms = set()\n",
+ " self.pred_syms = set()\n",
+ " FolKB.__init__(self, clauses)\n",
+ "\n",
+ " def tell(self, sentence):\n",
+ " if is_definite_clause(sentence):\n",
+ " self.clauses.append(sentence)\n",
+ " self.const_syms.update(constant_symbols(sentence))\n",
+ " self.pred_syms.update(predicate_symbols(sentence))\n",
+ " else:\n",
+ " raise Exception("Not a definite clause: {}".format(sentence))\n",
+ "\n",
+ " def foil(self, examples, target):\n",
+ " """Learn a list of first-order horn clauses\n",
+ " 'examples' is a tuple: (positive_examples, negative_examples).\n",
+ " positive_examples and negative_examples are both lists which contain substitutions."""\n",
+ " clauses = []\n",
+ "\n",
+ " pos_examples = examples[0]\n",
+ " neg_examples = examples[1]\n",
+ "\n",
+ " while pos_examples:\n",
+ " clause, extended_pos_examples = self.new_clause((pos_examples, neg_examples), target)\n",
+ " # remove positive examples covered by clause\n",
+ " pos_examples = self.update_examples(target, pos_examples, extended_pos_examples)\n",
+ " clauses.append(clause)\n",
+ "\n",
+ " return clauses\n",
+ "\n",
+ " def new_clause(self, examples, target):\n",
+ " """Find a horn clause which satisfies part of the positive\n",
+ " examples but none of the negative examples.\n",
+ " The horn clause is specified as [consequent, list of antecedents]\n",
+ " Return value is the tuple (horn_clause, extended_positive_examples)."""\n",
+ " clause = [target, []]\n",
+ " # [positive_examples, negative_examples]\n",
+ " extended_examples = examples\n",
+ " while extended_examples[1]:\n",
+ " l = self.choose_literal(self.new_literals(clause), extended_examples)\n",
+ " clause[1].append(l)\n",
+ " extended_examples = [sum([list(self.extend_example(example, l)) for example in\n",
+ " extended_examples[i]], []) for i in range(2)]\n",
+ "\n",
+ " return (clause, extended_examples[0])\n",
+ "\n",
+ " def extend_example(self, example, literal):\n",
+ " """Generate extended examples which satisfy the literal."""\n",
+ " # find all substitutions that satisfy literal\n",
+ " for s in self.ask_generator(subst(example, literal)):\n",
+ " s.update(example)\n",
+ " yield s\n",
+ "\n",
+ " def new_literals(self, clause):\n",
+ " """Generate new literals based on known predicate symbols.\n",
+ " Generated literal must share atleast one variable with clause"""\n",
+ " share_vars = variables(clause[0])\n",
+ " for l in clause[1]:\n",
+ " share_vars.update(variables(l))\n",
+ " for pred, arity in self.pred_syms:\n",
+ " new_vars = {standardize_variables(expr('x')) for _ in range(arity - 1)}\n",
+ " for args in product(share_vars.union(new_vars), repeat=arity):\n",
+ " if any(var in share_vars for var in args):\n",
+ " # make sure we don't return an existing rule\n",
+ " if not Expr(pred, args) in clause[1]:\n",
+ " yield Expr(pred, *[var for var in args])\n",
+ "\n",
+ "\n",
+ " def choose_literal(self, literals, examples): \n",
+ " """Choose the best literal based on the information gain."""\n",
+ "\n",
+ " return max(literals, key = partial(self.gain , examples = examples))\n",
+ "\n",
+ "\n",
+ " def gain(self, l ,examples):\n",
+ " """\n",
+ " Find the utility of each literal when added to the body of the clause. \n",
+ " Utility function is: \n",
+ " gain(R, l) = T * (log_2 (post_pos / (post_pos + post_neg)) - log_2 (pre_pos / (pre_pos + pre_neg)))\n",
+ "\n",
+ " where: \n",
+ " \n",
+ " pre_pos = number of possitive bindings of rule R (=current set of rules)\n",
+ " pre_neg = number of negative bindings of rule R \n",
+ " post_pos = number of possitive bindings of rule R' (= R U {l} )\n",
+ " post_neg = number of negative bindings of rule R' \n",
+ " T = number of possitive bindings of rule R that are still covered \n",
+ " after adding literal l \n",
+ "\n",
+ " """\n",
+ " pre_pos = len(examples[0])\n",
+ " pre_neg = len(examples[1])\n",
+ " post_pos = sum([list(self.extend_example(example, l)) for example in examples[0]], []) \n",
+ " post_neg = sum([list(self.extend_example(example, l)) for example in examples[1]], []) \n",
+ " if pre_pos + pre_neg ==0 or len(post_pos) + len(post_neg)==0:\n",
+ " return -1\n",
+ " # number of positive example that are represented in extended_examples\n",
+ " T = 0\n",
+ " for example in examples[0]:\n",
+ " represents = lambda d: all(d[x] == example[x] for x in example)\n",
+ " if any(represents(l_) for l_ in post_pos):\n",
+ " T += 1\n",
+ " value = T * (log(len(post_pos) / (len(post_pos) + len(post_neg)) + 1e-12,2) - log(pre_pos / (pre_pos + pre_neg),2))\n",
+ " return value\n",
+ "\n",
+ "\n",
+ " def update_examples(self, target, examples, extended_examples):\n",
+ " """Add to the kb those examples what are represented in extended_examples\n",
+ " List of omitted examples is returned."""\n",
+ " uncovered = []\n",
+ " for example in examples:\n",
+ " represents = lambda d: all(d[x] == example[x] for x in example)\n",
+ " if any(represents(l) for l in extended_examples):\n",
+ " self.tell(subst(example, target))\n",
+ " else:\n",
+ " uncovered.append(example)\n",
+ "\n",
+ " return uncovered\n",
+ "def current_best_learning(examples, h, examples_so_far=None):\n",
+ " """ [Figure 19.2]\n",
+ " The hypothesis is a list of dictionaries, with each dictionary representing\n",
+ " a disjunction."""\n",
+ " if not examples:\n",
+ " return h\n",
+ "\n",
+ " examples_so_far = examples_so_far or []\n",
+ " e = examples[0]\n",
+ " if is_consistent(e, h):\n",
+ " return current_best_learning(examples[1:], h, examples_so_far + [e])\n",
+ " elif false_positive(e, h):\n",
+ " for h2 in specializations(examples_so_far + [e], h):\n",
+ " h3 = current_best_learning(examples[1:], h2, examples_so_far + [e])\n",
+ " if h3 != 'FAIL':\n",
+ " return h3\n",
+ " elif false_negative(e, h):\n",
+ " for h2 in generalizations(examples_so_far + [e], h):\n",
+ " h3 = current_best_learning(examples[1:], h2, examples_so_far + [e])\n",
+ " if h3 != 'FAIL':\n",
+ " return h3\n",
+ "\n",
+ " return 'FAIL'\n",
+ "\n",
+ "\n",
+ "def specializations(examples_so_far, h):\n",
+ " """Specialize the hypothesis by adding AND operations to the disjunctions"""\n",
+ " hypotheses = []\n",
+ "\n",
+ " for i, disj in enumerate(h):\n",
+ " for e in examples_so_far:\n",
+ " for k, v in e.items():\n",
+ " if k in disj or k == 'GOAL':\n",
+ " continue\n",
+ "\n",
+ " h2 = h[i].copy()\n",
+ " h2[k] = '!' + v\n",
+ " h3 = h.copy()\n",
+ " h3[i] = h2\n",
+ " if check_all_consistency(examples_so_far, h3):\n",
+ " hypotheses.append(h3)\n",
+ "\n",
+ " shuffle(hypotheses)\n",
+ " return hypotheses\n",
+ "\n",
+ "\n",
+ "def generalizations(examples_so_far, h):\n",
+ " """Generalize the hypothesis. First delete operations\n",
+ " (including disjunctions) from the hypothesis. Then, add OR operations."""\n",
+ " hypotheses = []\n",
+ "\n",
+ " # Delete disjunctions\n",
+ " disj_powerset = powerset(range(len(h)))\n",
+ " for disjs in disj_powerset:\n",
+ " h2 = h.copy()\n",
+ " for d in reversed(list(disjs)):\n",
+ " del h2[d]\n",
+ "\n",
+ " if check_all_consistency(examples_so_far, h2):\n",
+ " hypotheses += h2\n",
+ "\n",
+ " # Delete AND operations in disjunctions\n",
+ " for i, disj in enumerate(h):\n",
+ " a_powerset = powerset(disj.keys())\n",
+ " for attrs in a_powerset:\n",
+ " h2 = h[i].copy()\n",
+ " for a in attrs:\n",
+ " del h2[a]\n",
+ "\n",
+ " if check_all_consistency(examples_so_far, [h2]):\n",
+ " h3 = h.copy()\n",
+ " h3[i] = h2.copy()\n",
+ " hypotheses += h3\n",
+ "\n",
+ " # Add OR operations\n",
+ " if hypotheses == [] or hypotheses == [{}]:\n",
+ " hypotheses = add_or(examples_so_far, h)\n",
+ " else:\n",
+ " hypotheses.extend(add_or(examples_so_far, h))\n",
+ "\n",
+ " shuffle(hypotheses)\n",
+ " return hypotheses\n",
+ "def version_space_learning(examples):\n",
+ " """ [Figure 19.3]\n",
+ " The version space is a list of hypotheses, which in turn are a list\n",
+ " of dictionaries/disjunctions."""\n",
+ " V = all_hypotheses(examples)\n",
+ " for e in examples:\n",
+ " if V:\n",
+ " V = version_space_update(V, e)\n",
+ "\n",
+ " return V\n",
+ "\n",
+ "\n",
+ "def version_space_update(V, e):\n",
+ " return [h for h in V if is_consistent(e, h)]\n",
+ "def all_hypotheses(examples):\n",
+ " """Build a list of all the possible hypotheses"""\n",
+ " values = values_table(examples)\n",
+ " h_powerset = powerset(values.keys())\n",
+ " hypotheses = []\n",
+ " for s in h_powerset:\n",
+ " hypotheses.extend(build_attr_combinations(s, values))\n",
+ "\n",
+ " hypotheses.extend(build_h_combinations(hypotheses))\n",
+ "\n",
+ " return hypotheses\n",
+ "\n",
+ "\n",
+ "def values_table(examples):\n",
+ " """Build a table with all the possible values for each attribute.\n",
+ " Returns a dictionary with keys the attribute names and values a list\n",
+ " with the possible values for the corresponding attribute."""\n",
+ " values = defaultdict(lambda: [])\n",
+ " for e in examples:\n",
+ " for k, v in e.items():\n",
+ " if k == 'GOAL':\n",
+ " continue\n",
+ "\n",
+ " mod = '!'\n",
+ " if e['GOAL']:\n",
+ " mod = ''\n",
+ "\n",
+ " if mod + v not in values[k]:\n",
+ " values[k].append(mod + v)\n",
+ "\n",
+ " values = dict(values)\n",
+ " return values\n",
+ "def build_attr_combinations(s, values):\n",
+ " """Given a set of attributes, builds all the combinations of values.\n",
+ " If the set holds more than one attribute, recursively builds the\n",
+ " combinations."""\n",
+ " if len(s) == 1:\n",
+ " # s holds just one attribute, return its list of values\n",
+ " k = values[s[0]]\n",
+ " h = [[{s[0]: v}] for v in values[s[0]]]\n",
+ " return h\n",
+ "\n",
+ " h = []\n",
+ " for i, a in enumerate(s):\n",
+ " rest = build_attr_combinations(s[i+1:], values)\n",
+ " for v in values[a]:\n",
+ " o = {a: v}\n",
+ " for r in rest:\n",
+ " t = o.copy()\n",
+ " for d in r:\n",
+ " t.update(d)\n",
+ " h.append([t])\n",
+ "\n",
+ " return h\n",
+ "\n",
+ "\n",
+ "def build_h_combinations(hypotheses):\n",
+ " """Given a set of hypotheses, builds and returns all the combinations of the\n",
+ " hypotheses."""\n",
+ " h = []\n",
+ " h_powerset = powerset(range(len(hypotheses)))\n",
+ "\n",
+ " for s in h_powerset:\n",
+ " t = []\n",
+ " for i in s:\n",
+ " t.extend(hypotheses[i])\n",
+ " h.append(t)\n",
+ "\n",
+ " return h\n",
+ "def minimal_consistent_det(E, A):\n",
+ " """Return a minimal set of attributes which give consistent determination"""\n",
+ " n = len(A)\n",
+ "\n",
+ " for i in range(n + 1):\n",
+ " for A_i in combinations(A, i):\n",
+ " if consistent_det(A_i, E):\n",
+ " return set(A_i)\n",
+ "def consistent_det(A, E):\n",
+ " """Check if the attributes(A) is consistent with the examples(E)"""\n",
+ " H = {}\n",
+ "\n",
+ " for e in E:\n",
+ " attr_values = tuple(e[attr] for attr in A)\n",
+ " if attr_values in H and H[attr_values] != e['GOAL']:\n",
+ " return False\n",
+ " H[attr_values] = e['GOAL']\n",
+ "\n",
+ " return True\n",
+ "def AdaBoost(L, K):\n",
+ " """[Figure 18.34]"""\n",
+ " def train(dataset):\n",
+ " examples, target = dataset.examples, dataset.target\n",
+ " N = len(examples)\n",
+ " epsilon = 1. / (2 * N)\n",
+ " w = [1. / N] * N\n",
+ " h, z = [], []\n",
+ " for k in range(K):\n",
+ " h_k = L(dataset, w)\n",
+ " h.append(h_k)\n",
+ " error = sum(weight for example, weight in zip(examples, w)\n",
+ " if example[target] != h_k(example))\n",
+ " # Avoid divide-by-0 from either 0% or 100% error rates:\n",
+ " error = clip(error, epsilon, 1 - epsilon)\n",
+ " for j, example in enumerate(examples):\n",
+ " if example[target] == h_k(example):\n",
+ " w[j] *= error / (1. - error)\n",
+ " w = normalize(w)\n",
+ " z.append(math.log((1. - error) / error))\n",
+ " return WeightedMajority(h, z)\n",
+ " return train\n",
+ "def KB_AgentProgram(KB):\n",
+ " """A generic logical knowledge-based agent program. [Figure 7.1]"""\n",
+ " steps = itertools.count()\n",
+ "\n",
+ " def program(percept):\n",
+ " t = next(steps)\n",
+ " KB.tell(make_percept_sentence(percept, t))\n",
+ " action = KB.ask(make_action_query(t))\n",
+ " KB.tell(make_action_sentence(action, t))\n",
+ " return action\n",
+ "\n",
+ " def make_percept_sentence(percept, t):\n",
+ " return Expr("Percept")(percept, t)\n",
+ "\n",
+ " def make_action_query(t):\n",
+ " return expr("ShouldDo(action, {})".format(t))\n",
+ "\n",
+ " def make_action_sentence(action, t):\n",
+ " return Expr("Did")(action[expr('action')], t)\n",
+ "\n",
+ " return program\n",
+ "def tt_check_all(kb, alpha, symbols, model):\n",
+ " """Auxiliary routine to implement tt_entails."""\n",
+ " if not symbols:\n",
+ " if pl_true(kb, model):\n",
+ " result = pl_true(alpha, model)\n",
+ " assert result in (True, False)\n",
+ " return result\n",
+ " else:\n",
+ " return True\n",
+ " else:\n",
+ " P, rest = symbols[0], symbols[1:]\n",
+ " return (tt_check_all(kb, alpha, rest, extend(model, P, True)) and\n",
+ " tt_check_all(kb, alpha, rest, extend(model, P, False)))\n",
+ "def tt_entails(kb, alpha):\n",
+ " """Does kb entail the sentence alpha? Use truth tables. For propositional\n",
+ " kb's and sentences. [Figure 7.10]. Note that the 'kb' should be an\n",
+ " Expr which is a conjunction of clauses.\n",
+ " >>> tt_entails(expr('P & Q'), expr('Q'))\n",
+ " True\n",
+ " """\n",
+ " assert not variables(alpha)\n",
+ " symbols = list(prop_symbols(kb & alpha))\n",
+ " return tt_check_all(kb, alpha, symbols, {})\n",
+ "def to_cnf(s):\n",
+ " """Convert a propositional logical sentence to conjunctive normal form.\n",
+ " That is, to the form ((A | ~B | ...) & (B | C | ...) & ...) [p. 253]\n",
+ " >>> to_cnf('~(B | C)')\n",
+ " (~B & ~C)\n",
+ " """\n",
+ " s = expr(s)\n",
+ " if isinstance(s, str):\n",
+ " s = expr(s)\n",
+ " s = eliminate_implications(s) # Steps 1, 2 from p. 253\n",
+ " s = move_not_inwards(s) # Step 3\n",
+ " return distribute_and_over_or(s) # Step 4\n",
+ "def eliminate_implications(s):\n",
+ " """Change implications into equivalent form with only &, |, and ~ as logical operators."""\n",
+ " s = expr(s)\n",
+ " if not s.args or is_symbol(s.op):\n",
+ " return s # Atoms are unchanged.\n",
+ " args = list(map(eliminate_implications, s.args))\n",
+ " a, b = args[0], args[-1]\n",
+ " if s.op == '==>':\n",
+ " return b | ~a\n",
+ " elif s.op == '<==':\n",
+ " return a | ~b\n",
+ " elif s.op == '<=>':\n",
+ " return (a | ~b) & (b | ~a)\n",
+ " elif s.op == '^':\n",
+ " assert len(args) == 2 # TODO: relax this restriction\n",
+ " return (a & ~b) | (~a & b)\n",
+ " else:\n",
+ " assert s.op in ('&', '|', '~')\n",
+ " return Expr(s.op, *args)\n",
+ "def move_not_inwards(s):\n",
+ " """Rewrite sentence s by moving negation sign inward.\n",
+ " >>> move_not_inwards(~(A | B))\n",
+ " (~A & ~B)"""\n",
+ " s = expr(s)\n",
+ " if s.op == '~':\n",
+ " def NOT(b):\n",
+ " return move_not_inwards(~b)\n",
+ " a = s.args[0]\n",
+ " if a.op == '~':\n",
+ " return move_not_inwards(a.args[0]) # ~~A ==> A\n",
+ " if a.op == '&':\n",
+ " return associate('|', list(map(NOT, a.args)))\n",
+ " if a.op == '|':\n",
+ " return associate('&', list(map(NOT, a.args)))\n",
+ " return s\n",
+ " elif is_symbol(s.op) or not s.args:\n",
+ " return s\n",
+ " else:\n",
+ " return Expr(s.op, *list(map(move_not_inwards, s.args)))\n",
+ "def distribute_and_over_or(s):\n",
+ " """Given a sentence s consisting of conjunctions and disjunctions\n",
+ " of literals, return an equivalent sentence in CNF.\n",
+ " >>> distribute_and_over_or((A & B) | C)\n",
+ " ((A | C) & (B | C))\n",
+ " """\n",
+ " s = expr(s)\n",
+ " if s.op == '|':\n",
+ " s = associate('|', s.args)\n",
+ " if s.op != '|':\n",
+ " return distribute_and_over_or(s)\n",
+ " if len(s.args) == 0:\n",
+ " return False\n",
+ " if len(s.args) == 1:\n",
+ " return distribute_and_over_or(s.args[0])\n",
+ " conj = first(arg for arg in s.args if arg.op == '&')\n",
+ " if not conj:\n",
+ " return s\n",
+ " others = [a for a in s.args if a is not conj]\n",
+ " rest = associate('|', others)\n",
+ " return associate('&', [distribute_and_over_or(c | rest)\n",
+ " for c in conj.args])\n",
+ " elif s.op == '&':\n",
+ " return associate('&', list(map(distribute_and_over_or, s.args)))\n",
+ " else:\n",
+ " return s\n",
+ "def pl_resolution(KB, alpha):\n",
+ " """Propositional-logic resolution: say if alpha follows from KB. [Figure 7.12]"""\n",
+ " clauses = KB.clauses + conjuncts(to_cnf(~alpha))\n",
+ " new = set()\n",
+ " while True:\n",
+ " n = len(clauses)\n",
+ " pairs = [(clauses[i], clauses[j])\n",
+ " for i in range(n) for j in range(i+1, n)]\n",
+ " for (ci, cj) in pairs:\n",
+ " resolvents = pl_resolve(ci, cj)\n",
+ " if False in resolvents:\n",
+ " return True\n",
+ " new = new.union(set(resolvents))\n",
+ " if new.issubset(set(clauses)):\n",
+ " return False\n",
+ " for c in new:\n",
+ " if c not in clauses:\n",
+ " clauses.append(c)\n",
+ " def clauses_with_premise(self, p):\n",
+ " """Return a list of the clauses in KB that have p in their premise.\n",
+ " This could be cached away for O(1) speed, but we'll recompute it."""\n",
+ " return [c for c in self.clauses\n",
+ " if c.op == '==>' and p in conjuncts(c.args[0])]\n",
+ "def pl_fc_entails(KB, q):\n",
+ " """Use forward chaining to see if a PropDefiniteKB entails symbol q.\n",
+ " [Figure 7.15]\n",
+ " >>> pl_fc_entails(horn_clauses_KB, expr('Q'))\n",
+ " True\n",
+ " """\n",
+ " count = {c: len(conjuncts(c.args[0]))\n",
+ " for c in KB.clauses\n",
+ " if c.op == '==>'}\n",
+ " inferred = defaultdict(bool)\n",
+ " agenda = [s for s in KB.clauses if is_prop_symbol(s.op)]\n",
+ " while agenda:\n",
+ " p = agenda.pop()\n",
+ " if p == q:\n",
+ " return True\n",
+ " if not inferred[p]:\n",
+ " inferred[p] = True\n",
+ " for c in KB.clauses_with_premise(p):\n",
+ " count[c] -= 1\n",
+ " if count[c] == 0:\n",
+ " agenda.append(c.args[1])\n",
+ " return False\n",
+ "def dpll(clauses, symbols, model):\n",
+ " """See if the clauses are true in a partial model."""\n",
+ " unknown_clauses = [] # clauses with an unknown truth value\n",
+ " for c in clauses:\n",
+ " val = pl_true(c, model)\n",
+ " if val is False:\n",
+ " return False\n",
+ " if val is not True:\n",
+ " unknown_clauses.append(c)\n",
+ " if not unknown_clauses:\n",
+ " return model\n",
+ " P, value = find_pure_symbol(symbols, unknown_clauses)\n",
+ " if P:\n",
+ " return dpll(clauses, removeall(P, symbols), extend(model, P, value))\n",
+ " P, value = find_unit_clause(clauses, model)\n",
+ " if P:\n",
+ " return dpll(clauses, removeall(P, symbols), extend(model, P, value))\n",
+ " if not symbols:\n",
+ " raise TypeError("Argument should be of the type Expr.")\n",
+ " P, symbols = symbols[0], symbols[1:]\n",
+ " return (dpll(clauses, symbols, extend(model, P, True)) or\n",
+ " dpll(clauses, symbols, extend(model, P, False)))\n",
+ "def dpll_satisfiable(s):\n",
+ " """Check satisfiability of a propositional sentence.\n",
+ " This differs from the book code in two ways: (1) it returns a model\n",
+ " rather than True when it succeeds; this is more useful. (2) The\n",
+ " function find_pure_symbol is passed a list of unknown clauses, rather\n",
+ " than a list of all clauses and the model; this is more efficient."""\n",
+ " clauses = conjuncts(to_cnf(s))\n",
+ " symbols = list(prop_symbols(s))\n",
+ " return dpll(clauses, symbols, {})\n",
+ "def WalkSAT(clauses, p=0.5, max_flips=10000):\n",
+ " """Checks for satisfiability of all clauses by randomly flipping values of variables\n",
+ " """\n",
+ " # Set of all symbols in all clauses\n",
+ " symbols = {sym for clause in clauses for sym in prop_symbols(clause)}\n",
+ " # model is a random assignment of true/false to the symbols in clauses\n",
+ " model = {s: random.choice([True, False]) for s in symbols}\n",
+ " for i in range(max_flips):\n",
+ " satisfied, unsatisfied = [], []\n",
+ " for clause in clauses:\n",
+ " (satisfied if pl_true(clause, model) else unsatisfied).append(clause)\n",
+ " if not unsatisfied: # if model satisfies all the clauses\n",
+ " return model\n",
+ " clause = random.choice(unsatisfied)\n",
+ " if probability(p):\n",
+ " sym = random.choice(list(prop_symbols(clause)))\n",
+ " else:\n",
+ " # Flip the symbol in clause that maximizes number of sat. clauses\n",
+ " def sat_count(sym):\n",
+ " # Return the the number of clauses satisfied after flipping the symbol.\n",
+ " model[sym] = not model[sym]\n",
+ " count = len([clause for clause in clauses if pl_true(clause, model)])\n",
+ " model[sym] = not model[sym]\n",
+ " return count\n",
+ " sym = argmax(prop_symbols(clause), key=sat_count)\n",
+ " model[sym] = not model[sym]\n",
+ " # If no solution is found within the flip limit, we return failure\n",
+ " return None\n",
+ "def SAT_plan(init, transition, goal, t_max, SAT_solver=dpll_satisfiable):\n",
+ " """Converts a planning problem to Satisfaction problem by translating it to a cnf sentence.\n",
+ " [Figure 7.22]"""\n",
+ "\n",
+ " # Functions used by SAT_plan\n",
+ " def translate_to_SAT(init, transition, goal, time):\n",
+ " clauses = []\n",
+ " states = [state for state in transition]\n",
+ "\n",
+ " # Symbol claiming state s at time t\n",
+ " state_counter = itertools.count()\n",
+ " for s in states:\n",
+ " for t in range(time+1):\n",
+ " state_sym[s, t] = Expr("State_{}".format(next(state_counter)))\n",
+ "\n",
+ " # Add initial state axiom\n",
+ " clauses.append(state_sym[init, 0])\n",
+ "\n",
+ " # Add goal state axiom\n",
+ " clauses.append(state_sym[goal, time])\n",
+ "\n",
+ " # All possible transitions\n",
+ " transition_counter = itertools.count()\n",
+ " for s in states:\n",
+ " for action in transition[s]:\n",
+ " s_ = transition[s][action]\n",
+ " for t in range(time):\n",
+ " # Action 'action' taken from state 's' at time 't' to reach 's_'\n",
+ " action_sym[s, action, t] = Expr(\n",
+ " "Transition_{}".format(next(transition_counter)))\n",
+ "\n",
+ " # Change the state from s to s_\n",
+ " clauses.append(action_sym[s, action, t] |'==>'| state_sym[s, t])\n",
+ " clauses.append(action_sym[s, action, t] |'==>'| state_sym[s_, t + 1])\n",
+ "\n",
+ " # Allow only one state at any time\n",
+ " for t in range(time+1):\n",
+ " # must be a state at any time\n",
+ " clauses.append(associate('|', [state_sym[s, t] for s in states]))\n",
+ "\n",
+ " for s in states:\n",
+ " for s_ in states[states.index(s) + 1:]:\n",
+ " # for each pair of states s, s_ only one is possible at time t\n",
+ " clauses.append((~state_sym[s, t]) | (~state_sym[s_, t]))\n",
+ "\n",
+ " # Restrict to one transition per timestep\n",
+ " for t in range(time):\n",
+ " # list of possible transitions at time t\n",
+ " transitions_t = [tr for tr in action_sym if tr[2] == t]\n",
+ "\n",
+ " # make sure at least one of the transitions happens\n",
+ " clauses.append(associate('|', [action_sym[tr] for tr in transitions_t]))\n",
+ "\n",
+ " for tr in transitions_t:\n",
+ " for tr_ in transitions_t[transitions_t.index(tr) + 1:]:\n",
+ " # there cannot be two transitions tr and tr_ at time t\n",
+ " clauses.append(~action_sym[tr] | ~action_sym[tr_])\n",
+ "\n",
+ " # Combine the clauses to form the cnf\n",
+ " return associate('&', clauses)\n",
+ "\n",
+ " def extract_solution(model):\n",
+ " true_transitions = [t for t in action_sym if model[action_sym[t]]]\n",
+ " # Sort transitions based on time, which is the 3rd element of the tuple\n",
+ " true_transitions.sort(key=lambda x: x[2])\n",
+ " return [action for s, action, time in true_transitions]\n",
+ "\n",
+ " # Body of SAT_plan algorithm\n",
+ " for t in range(t_max):\n",
+ " # dictionaries to help extract the solution from model\n",
+ " state_sym = {}\n",
+ " action_sym = {}\n",
+ "\n",
+ " cnf = translate_to_SAT(init, transition, goal, t)\n",
+ " model = SAT_solver(cnf)\n",
+ " if model is not False:\n",
+ " return extract_solution(model)\n",
+ " return None\n",
+ "def subst(s, x):\n",
+ " """Substitute the substitution s into the expression x.\n",
+ " >>> subst({x: 42, y:0}, F(x) + y)\n",
+ " (F(42) + 0)\n",
+ " """\n",
+ " if isinstance(x, list):\n",
+ " return [subst(s, xi) for xi in x]\n",
+ " elif isinstance(x, tuple):\n",
+ " return tuple([subst(s, xi) for xi in x])\n",
+ " elif not isinstance(x, Expr):\n",
+ " return x\n",
+ " elif is_var_symbol(x.op):\n",
+ " return s.get(x, x)\n",
+ " else:\n",
+ " return Expr(x.op, *[subst(s, arg) for arg in x.args])\n",
+ "def fol_fc_ask(KB, alpha):\n",
+ " """A simple forward-chaining algorithm. [Figure 9.3]"""\n",
+ " # TODO: Improve efficiency\n",
+ " kb_consts = list({c for clause in KB.clauses for c in constant_symbols(clause)})\n",
+ " def enum_subst(p):\n",
+ " query_vars = list({v for clause in p for v in variables(clause)})\n",
+ " for assignment_list in itertools.product(kb_consts, repeat=len(query_vars)):\n",
+ " theta = {x: y for x, y in zip(query_vars, assignment_list)}\n",
+ " yield theta\n",
+ "\n",
+ " # check if we can answer without new inferences\n",
+ " for q in KB.clauses:\n",
+ " phi = unify(q, alpha, {})\n",
+ " if phi is not None:\n",
+ " yield phi\n",
+ "\n",
+ " while True:\n",
+ " new = []\n",
+ " for rule in KB.clauses:\n",
+ " p, q = parse_definite_clause(rule)\n",
+ " for theta in enum_subst(p):\n",
+ " if set(subst(theta, p)).issubset(set(KB.clauses)):\n",
+ " q_ = subst(theta, q)\n",
+ " if all([unify(x, q_, {}) is None for x in KB.clauses + new]):\n",
+ " new.append(q_)\n",
+ " phi = unify(q_, alpha, {})\n",
+ " if phi is not None:\n",
+ " yield phi\n",
+ " if not new:\n",
+ " break\n",
+ " for clause in new:\n",
+ " KB.tell(clause)\n",
+ " return None\n",
+ "def fol_bc_or(KB, goal, theta):\n",
+ " for rule in KB.fetch_rules_for_goal(goal):\n",
+ " lhs, rhs = parse_definite_clause(standardize_variables(rule))\n",
+ " for theta1 in fol_bc_and(KB, lhs, unify(rhs, goal, theta)):\n",
+ " yield theta1\n",
+ "def fol_bc_and(KB, goals, theta):\n",
+ " if theta is None:\n",
+ " pass\n",
+ " elif not goals:\n",
+ " yield theta\n",
+ " else:\n",
+ " first, rest = goals[0], goals[1:]\n",
+ " for theta1 in fol_bc_or(KB, subst(theta, first), theta):\n",
+ " for theta2 in fol_bc_and(KB, rest, theta1):\n",
+ " yield theta2\n",
+ "class MDP:\n",
+ "\n",
+ " """A Markov Decision Process, defined by an initial state, transition model,\n",
+ " and reward function. We also keep track of a gamma value, for use by\n",
+ " algorithms. The transition model is represented somewhat differently from\n",
+ " the text. Instead of P(s' | s, a) being a probability number for each\n",
+ " state/state/action triplet, we instead have T(s, a) return a\n",
+ " list of (p, s') pairs. We also keep track of the possible states,\n",
+ " terminal states, and actions for each state. [page 646]"""\n",
+ "\n",
+ " def __init__(self, init, actlist, terminals, transitions = {}, reward = None, states=None, gamma=.9):\n",
+ " if not (0 < gamma <= 1):\n",
+ " raise ValueError("An MDP must have 0 < gamma <= 1")\n",
+ "\n",
+ " if states:\n",
+ " self.states = states\n",
+ " else:\n",
+ " ## collect states from transitions table\n",
+ " self.states = self.get_states_from_transitions(transitions)\n",
+ " \n",
+ " \n",
+ " self.init = init\n",
+ " \n",
+ " if isinstance(actlist, list):\n",
+ " ## if actlist is a list, all states have the same actions\n",
+ " self.actlist = actlist\n",
+ " elif isinstance(actlist, dict):\n",
+ " ## if actlist is a dict, different actions for each state\n",
+ " self.actlist = actlist\n",
+ " \n",
+ " self.terminals = terminals\n",
+ " self.transitions = transitions\n",
+ " if self.transitions == {}:\n",
+ " print("Warning: Transition table is empty.")\n",
+ " self.gamma = gamma\n",
+ " if reward:\n",
+ " self.reward = reward\n",
+ " else:\n",
+ " self.reward = {s : 0 for s in self.states}\n",
+ " #self.check_consistency()\n",
+ "\n",
+ " def R(self, state):\n",
+ " """Return a numeric reward for this state."""\n",
+ " return self.reward[state]\n",
+ "\n",
+ " def T(self, state, action):\n",
+ " """Transition model. From a state and an action, return a list\n",
+ " of (probability, result-state) pairs."""\n",
+ " if(self.transitions == {}):\n",
+ " raise ValueError("Transition model is missing")\n",
+ " else:\n",
+ " return self.transitions[state][action]\n",
+ "\n",
+ " def actions(self, state):\n",
+ " """Set of actions that can be performed in this state. By default, a\n",
+ " fixed list of actions, except for terminal states. Override this\n",
+ " method if you need to specialize by state."""\n",
+ " if state in self.terminals:\n",
+ " return [None]\n",
+ " else:\n",
+ " return self.actlist\n",
+ "\n",
+ " def get_states_from_transitions(self, transitions):\n",
+ " if isinstance(transitions, dict):\n",
+ " s1 = set(transitions.keys())\n",
+ " s2 = set([tr[1] for actions in transitions.values() \n",
+ " for effects in actions.values() for tr in effects])\n",
+ " return s1.union(s2)\n",
+ " else:\n",
+ " print('Could not retrieve states from transitions')\n",
+ " return None\n",
+ "\n",
+ " def check_consistency(self):\n",
+ " # check that all states in transitions are valid\n",
+ " assert set(self.states) == self.get_states_from_transitions(self.transitions)\n",
+ " # check that init is a valid state\n",
+ " assert self.init in self.states\n",
+ " # check reward for each state\n",
+ " #assert set(self.reward.keys()) == set(self.states)\n",
+ " assert set(self.reward.keys()) == set(self.states)\n",
+ " # check that all terminals are valid states\n",
+ " assert all([t in self.states for t in self.terminals])\n",
+ " # check that probability distributions for all actions sum to 1\n",
+ " for s1, actions in self.transitions.items():\n",
+ " for a in actions.keys():\n",
+ " s = 0\n",
+ " for o in actions[a]:\n",
+ " s += o[0]\n",
+ " assert abs(s - 1) < 0.001\n",
+ "class GridMDP(MDP):\n",
+ "\n",
+ " """A two-dimensional grid MDP, as in [Figure 17.1]. All you have to do is\n",
+ " specify the grid as a list of lists of rewards; use None for an obstacle\n",
+ " (unreachable state). Also, you should specify the terminal states.\n",
+ " An action is an (x, y) unit vector; e.g. (1, 0) means move east."""\n",
+ "\n",
+ " def __init__(self, grid, terminals, init=(0, 0), gamma=.9):\n",
+ " grid.reverse() # because we want row 0 on bottom, not on top\n",
+ " reward = {}\n",
+ " states = set()\n",
+ " self.rows = len(grid)\n",
+ " self.cols = len(grid[0])\n",
+ " self.grid = grid\n",
+ " for x in range(self.cols):\n",
+ " for y in range(self.rows):\n",
+ " if grid[y][x] is not None:\n",
+ " states.add((x, y))\n",
+ " reward[(x, y)] = grid[y][x]\n",
+ " self.states = states\n",
+ " actlist = orientations\n",
+ " transitions = {}\n",
+ " for s in states:\n",
+ " transitions[s] = {}\n",
+ " for a in actlist:\n",
+ " transitions[s][a] = self.calculate_T(s, a)\n",
+ " MDP.__init__(self, init, actlist=actlist,\n",
+ " terminals=terminals, transitions = transitions, \n",
+ " reward = reward, states = states, gamma=gamma)\n",
+ "\n",
+ " def calculate_T(self, state, action):\n",
+ " if action is None:\n",
+ " return [(0.0, state)]\n",
+ " else:\n",
+ " return [(0.8, self.go(state, action)),\n",
+ " (0.1, self.go(state, turn_right(action))),\n",
+ " (0.1, self.go(state, turn_left(action)))]\n",
+ " \n",
+ " def T(self, state, action):\n",
+ " if action is None:\n",
+ " return [(0.0, state)]\n",
+ " else:\n",
+ " return self.transitions[state][action]\n",
+ " \n",
+ " def go(self, state, direction):\n",
+ " """Return the state that results from going in this direction."""\n",
+ " state1 = vector_add(state, direction)\n",
+ " return state1 if state1 in self.states else state\n",
+ "\n",
+ " def to_grid(self, mapping):\n",
+ " """Convert a mapping from (x, y) to v into a [[..., v, ...]] grid."""\n",
+ " return list(reversed([[mapping.get((x, y), None)\n",
+ " for x in range(self.cols)]\n",
+ " for y in range(self.rows)]))\n",
+ "\n",
+ " def to_arrows(self, policy):\n",
+ " chars = {\n",
+ " (1, 0): '>', (0, 1): '^', (-1, 0): '<', (0, -1): 'v', None: '.'}\n",
+ " return self.to_grid({s: chars[a] for (s, a) in policy.items()})\n",
+ "def value_iteration(mdp, epsilon=0.001):\n",
+ " """Solving an MDP by value iteration. [Figure 17.4]"""\n",
+ " U1 = {s: 0 for s in mdp.states}\n",
+ " R, T, gamma = mdp.R, mdp.T, mdp.gamma\n",
+ " while True:\n",
+ " U = U1.copy()\n",
+ " delta = 0\n",
+ " for s in mdp.states:\n",
+ " U1[s] = R(s) + gamma * max([sum([p * U[s1] for (p, s1) in T(s, a)])\n",
+ " for a in mdp.actions(s)])\n",
+ " delta = max(delta, abs(U1[s] - U[s]))\n",
+ " if delta < epsilon * (1 - gamma) / gamma:\n",
+ " return U\n",
+ "def expected_utility(a, s, U, mdp):\n",
+ " """The expected utility of doing a in state s, according to the MDP and U."""\n",
+ " return sum([p * U[s1] for (p, s1) in mdp.T(s, a)])\n",
+ "def policy_iteration(mdp):\n",
+ " """Solve an MDP by policy iteration [Figure 17.7]"""\n",
+ " U = {s: 0 for s in mdp.states}\n",
+ " pi = {s: random.choice(mdp.actions(s)) for s in mdp.states}\n",
+ " while True:\n",
+ " U = policy_evaluation(pi, U, mdp)\n",
+ " unchanged = True\n",
+ " for s in mdp.states:\n",
+ " a = argmax(mdp.actions(s), key=lambda a: expected_utility(a, s, U, mdp))\n",
+ " if a != pi[s]:\n",
+ " pi[s] = a\n",
+ " unchanged = False\n",
+ " if unchanged:\n",
+ " return pi\n",
+ "def policy_evaluation(pi, U, mdp, k=20):\n",
+ " """Return an updated utility mapping U from each state in the MDP to its\n",
+ " utility, using an approximation (modified policy iteration)."""\n",
+ " R, T, gamma = mdp.R, mdp.T, mdp.gamma\n",
+ " for i in range(k):\n",
+ " for s in mdp.states:\n",
+ " U[s] = R(s) + gamma * sum([p * U[s1] for (p, s1) in T(s, pi[s])])\n",
+ " return U\n",
+ " def T(self, state, action):\n",
+ " if action is None:\n",
+ " return [(0.0, state)]\n",
+ " else:\n",
+ " return self.transitions[state][action]\n",
+ " def to_arrows(self, policy):\n",
+ " chars = {\n",
+ " (1, 0): '>', (0, 1): '^', (-1, 0): '<', (0, -1): 'v', None: '.'}\n",
+ " return self.to_grid({s: chars[a] for (s, a) in policy.items()})\n",
+ " def to_grid(self, mapping):\n",
+ " """Convert a mapping from (x, y) to v into a [[..., v, ...]] grid."""\n",
+ " return list(reversed([[mapping.get((x, y), None)\n",
+ " for x in range(self.cols)]\n",
+ " for y in range(self.rows)]))\n",
+ "class POMDP(MDP):\n",
+ "\n",
+ " """A Partially Observable Markov Decision Process, defined by\n",
+ " a transition model P(s'|s,a), actions A(s), a reward function R(s),\n",
+ " and a sensor model P(e|s). We also keep track of a gamma value,\n",
+ " for use by algorithms. The transition and the sensor models\n",
+ " are defined as matrices. We also keep track of the possible states\n",
+ " and actions for each state. [page 659]."""\n",
+ "\n",
+ " def __init__(self, actions, transitions=None, evidences=None, rewards=None, states=None, gamma=0.95):\n",
+ " """Initialize variables of the pomdp"""\n",
+ "\n",
+ " if not (0 < gamma <= 1):\n",
+ " raise ValueError('A POMDP must have 0 < gamma <= 1')\n",
+ "\n",
+ " self.states = states\n",
+ " self.actions = actions\n",
+ "\n",
+ " # transition model cannot be undefined\n",
+ " self.t_prob = transitions or {}\n",
+ " if not self.t_prob:\n",
+ " print('Warning: Transition model is undefined')\n",
+ " \n",
+ " # sensor model cannot be undefined\n",
+ " self.e_prob = evidences or {}\n",
+ " if not self.e_prob:\n",
+ " print('Warning: Sensor model is undefined')\n",
+ " \n",
+ " self.gamma = gamma\n",
+ " self.rewards = rewards\n",
+ "\n",
+ " def remove_dominated_plans(self, input_values):\n",
+ " """\n",
+ " Remove dominated plans.\n",
+ " This method finds all the lines contributing to the\n",
+ " upper surface and removes those which don't.\n",
+ " """\n",
+ "\n",
+ " values = [val for action in input_values for val in input_values[action]]\n",
+ " values.sort(key=lambda x: x[0], reverse=True)\n",
+ "\n",
+ " best = [values[0]]\n",
+ " y1_max = max(val[1] for val in values)\n",
+ " tgt = values[0]\n",
+ " prev_b = 0\n",
+ " prev_ix = 0\n",
+ " while tgt[1] != y1_max:\n",
+ " min_b = 1\n",
+ " min_ix = 0\n",
+ " for i in range(prev_ix + 1, len(values)):\n",
+ " if values[i][0] - tgt[0] + tgt[1] - values[i][1] != 0:\n",
+ " trans_b = (values[i][0] - tgt[0]) / (values[i][0] - tgt[0] + tgt[1] - values[i][1])\n",
+ " if 0 <= trans_b <= 1 and trans_b > prev_b and trans_b < min_b:\n",
+ " min_b = trans_b\n",
+ " min_ix = i\n",
+ " prev_b = min_b\n",
+ " prev_ix = min_ix\n",
+ " tgt = values[min_ix]\n",
+ " best.append(tgt)\n",
+ "\n",
+ " return self.generate_mapping(best, input_values)\n",
+ "\n",
+ " def remove_dominated_plans_fast(self, input_values):\n",
+ " """\n",
+ " Remove dominated plans using approximations.\n",
+ " Resamples the upper boundary at intervals of 100 and\n",
+ " finds the maximum values at these points.\n",
+ " """\n",
+ "\n",
+ " values = [val for action in input_values for val in input_values[action]]\n",
+ " values.sort(key=lambda x: x[0], reverse=True)\n",
+ "\n",
+ " best = []\n",
+ " sr = 100\n",
+ " for i in range(sr + 1):\n",
+ " x = i / float(sr)\n",
+ " maximum = (values[0][1] - values[0][0]) * x + values[0][0]\n",
+ " tgt = values[0]\n",
+ " for value in values:\n",
+ " val = (value[1] - value[0]) * x + value[0]\n",
+ " if val > maximum:\n",
+ " maximum = val\n",
+ " tgt = value\n",
+ "\n",
+ " if all(any(tgt != v) for v in best):\n",
+ " best.append(tgt)\n",
+ "\n",
+ " return self.generate_mapping(best, input_values)\n",
+ "\n",
+ " def generate_mapping(self, best, input_values):\n",
+ " """Generate mappings after removing dominated plans"""\n",
+ "\n",
+ " mapping = defaultdict(list)\n",
+ " for value in best:\n",
+ " for action in input_values:\n",
+ " if any(all(value == v) for v in input_values[action]):\n",
+ " mapping[action].append(value)\n",
+ "\n",
+ " return mapping\n",
+ "\n",
+ " def max_difference(self, U1, U2):\n",
+ " """Find maximum difference between two utility mappings"""\n",
+ "\n",
+ " for k, v in U1.items():\n",
+ " sum1 = 0\n",
+ " for element in U1[k]:\n",
+ " sum1 += sum(element)\n",
+ " sum2 = 0\n",
+ " for element in U2[k]:\n",
+ " sum2 += sum(element)\n",
+ " return abs(sum1 - sum2)\n",
+ "def pomdp_value_iteration(pomdp, epsilon=0.1):\n",
+ " """Solving a POMDP by value iteration."""\n",
+ "\n",
+ " U = {'':[[0]* len(pomdp.states)]}\n",
+ " count = 0\n",
+ " while True:\n",
+ " count += 1\n",
+ " prev_U = U\n",
+ " values = [val for action in U for val in U[action]]\n",
+ " value_matxs = []\n",
+ " for i in values:\n",
+ " for j in values:\n",
+ " value_matxs.append([i, j])\n",
+ "\n",
+ " U1 = defaultdict(list)\n",
+ " for action in pomdp.actions:\n",
+ " for u in value_matxs:\n",
+ " u1 = Matrix.matmul(Matrix.matmul(pomdp.t_prob[int(action)], Matrix.multiply(pomdp.e_prob[int(action)], Matrix.transpose(u))), [[1], [1]])\n",
+ " u1 = Matrix.add(Matrix.scalar_multiply(pomdp.gamma, Matrix.transpose(u1)), [pomdp.rewards[int(action)]])\n",
+ " U1[action].append(u1[0])\n",
+ "\n",
+ " U = pomdp.remove_dominated_plans_fast(U1)\n",
+ " # replace with U = pomdp.remove_dominated_plans(U1) for accurate calculations\n",
+ " \n",
+ " if count > 10:\n",
+ " if pomdp.max_difference(U, prev_U) < epsilon * (1 - pomdp.gamma) / pomdp.gamma:\n",
+ " return U\n",
+ "def NeuralNetLearner(dataset, hidden_layer_sizes=None,\n",
+ " learning_rate=0.01, epochs=100, activation = sigmoid):\n",
+ " """Layered feed-forward network.\n",
+ " hidden_layer_sizes: List of number of hidden units per hidden layer\n",
+ " learning_rate: Learning rate of gradient descent\n",
+ " epochs: Number of passes over the dataset\n",
+ " """\n",
+ "\n",
+ " hidden_layer_sizes = hidden_layer_sizes or [3] # default value\n",
+ " i_units = len(dataset.inputs)\n",
+ " o_units = len(dataset.values[dataset.target])\n",
+ "\n",
+ " # construct a network\n",
+ " raw_net = network(i_units, hidden_layer_sizes, o_units, activation)\n",
+ " learned_net = BackPropagationLearner(dataset, raw_net,\n",
+ " learning_rate, epochs, activation)\n",
+ "\n",
+ " def predict(example):\n",
+ " # Input nodes\n",
+ " i_nodes = learned_net[0]\n",
+ "\n",
+ " # Activate input layer\n",
+ " for v, n in zip(example, i_nodes):\n",
+ " n.value = v\n",
+ "\n",
+ " # Forward pass\n",
+ " for layer in learned_net[1:]:\n",
+ " for node in layer:\n",
+ " inc = [n.value for n in node.inputs]\n",
+ " in_val = dotproduct(inc, node.weights)\n",
+ " node.value = node.activation(in_val)\n",
+ "\n",
+ " # Hypothesis\n",
+ " o_nodes = learned_net[-1]\n",
+ " prediction = find_max_node(o_nodes)\n",
+ " return prediction\n",
+ "\n",
+ " return predict\n",
+ "def BackPropagationLearner(dataset, net, learning_rate, epochs, activation=sigmoid):\n",
+ " """[Figure 18.23] The back-propagation algorithm for multilayer networks"""\n",
+ " # Initialise weights\n",
+ " for layer in net:\n",
+ " for node in layer:\n",
+ " node.weights = random_weights(min_value=-0.5, max_value=0.5,\n",
+ " num_weights=len(node.weights))\n",
+ "\n",
+ " examples = dataset.examples\n",
+ " '''\n",
+ " As of now dataset.target gives an int instead of list,\n",
+ " Changing dataset class will have effect on all the learners.\n",
+ " Will be taken care of later.\n",
+ " '''\n",
+ " o_nodes = net[-1]\n",
+ " i_nodes = net[0]\n",
+ " o_units = len(o_nodes)\n",
+ " idx_t = dataset.target\n",
+ " idx_i = dataset.inputs\n",
+ " n_layers = len(net)\n",
+ "\n",
+ " inputs, targets = init_examples(examples, idx_i, idx_t, o_units)\n",
+ "\n",
+ " for epoch in range(epochs):\n",
+ " # Iterate over each example\n",
+ " for e in range(len(examples)):\n",
+ " i_val = inputs[e]\n",
+ " t_val = targets[e]\n",
+ "\n",
+ " # Activate input layer\n",
+ " for v, n in zip(i_val, i_nodes):\n",
+ " n.value = v\n",
+ "\n",
+ " # Forward pass\n",
+ " for layer in net[1:]:\n",
+ " for node in layer:\n",
+ " inc = [n.value for n in node.inputs]\n",
+ " in_val = dotproduct(inc, node.weights)\n",
+ " node.value = node.activation(in_val)\n",
+ "\n",
+ " # Initialize delta\n",
+ " delta = [[] for _ in range(n_layers)]\n",
+ "\n",
+ " # Compute outer layer delta\n",
+ "\n",
+ " # Error for the MSE cost function\n",
+ " err = [t_val[i] - o_nodes[i].value for i in range(o_units)]\n",
+ "\n",
+ " # The activation function used is relu or sigmoid function\n",
+ " if node.activation == sigmoid:\n",
+ " delta[-1] = [sigmoid_derivative(o_nodes[i].value) * err[i] for i in range(o_units)]\n",
+ " else:\n",
+ " delta[-1] = [relu_derivative(o_nodes[i].value) * err[i] for i in range(o_units)]\n",
+ "\n",
+ " # Backward pass\n",
+ " h_layers = n_layers - 2\n",
+ " for i in range(h_layers, 0, -1):\n",
+ " layer = net[i]\n",
+ " h_units = len(layer)\n",
+ " nx_layer = net[i+1]\n",
+ "\n",
+ " # weights from each ith layer node to each i + 1th layer node\n",
+ " w = [[node.weights[k] for node in nx_layer] for k in range(h_units)]\n",
+ "\n",
+ " if activation == sigmoid:\n",
+ " delta[i] = [sigmoid_derivative(layer[j].value) * dotproduct(w[j], delta[i+1])\n",
+ " for j in range(h_units)]\n",
+ " else:\n",
+ " delta[i] = [relu_derivative(layer[j].value) * dotproduct(w[j], delta[i+1])\n",
+ " for j in range(h_units)]\n",
+ "\n",
+ " # Update weights\n",
+ " for i in range(1, n_layers):\n",
+ " layer = net[i]\n",
+ " inc = [node.value for node in net[i-1]]\n",
+ " units = len(layer)\n",
+ " for j in range(units):\n",
+ " layer[j].weights = vector_add(layer[j].weights,\n",
+ " scalar_vector_product(\n",
+ " learning_rate * delta[i][j], inc))\n",
+ "\n",
+ " return net\n",
+ "![](\"images/nn.png\")
\n",
+ "\n",
+ "In our code, we implemented it as:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# initialize the network\n",
+ "raw_net = [InputLayer(input_size)]\n",
+ "# add hidden layers\n",
+ "hidden_input_size = input_size\n",
+ "for h_size in hidden_layer_sizes:\n",
+ " raw_net.append(DenseLayer(hidden_input_size, h_size))\n",
+ " hidden_input_size = h_size\n",
+ "raw_net.append(DenseLayer(hidden_input_size, output_size))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Where hidden_layer_sizes are the sizes of each hidden layer in a list which can be specified by user. Neural network learner uses gradient descent as default optimizer but user can specify any optimizer when calling `neural_net_learner`. The other special attribute that can be changed in `neural_net_learner` is `batch_size` which controls the number of examples used in each round of update. `neural_net_learner` also returns a `predict` function which calculates prediction by multiplying weight to inputs and applying activation functions.\n",
+ "\n",
+ "### Example\n",
+ "\n",
+ "Let's also try `neural_net_learner` on the `iris` dataset:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "epoch:10, total_loss:15.931817841643683\n",
+ "epoch:20, total_loss:8.248422285412149\n",
+ "epoch:30, total_loss:6.102968668275\n",
+ "epoch:40, total_loss:5.463915043272969\n",
+ "epoch:50, total_loss:5.298986288420822\n",
+ "epoch:60, total_loss:4.032928400456889\n",
+ "epoch:70, total_loss:3.2628899927346855\n",
+ "epoch:80, total_loss:6.01336701367312\n",
+ "epoch:90, total_loss:5.412020420311795\n",
+ "epoch:100, total_loss:3.1044027319850773\n"
+ ]
+ }
+ ],
+ "source": [
+ "nn = neural_net_learner(iris, epochs=100, learning_rate=0.15, optimizer=gradient_descent, verbose=10)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Similarly we check the model's accuracy on both training and test dataset:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "error ration on training set: 0.033333333333333326\n"
+ ]
+ }
+ ],
+ "source": [
+ "print(\"error ration on training set:\",err_ratio(nn, iris))"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "accuracy on test set: 1\n"
+ ]
+ }
+ ],
+ "source": [
+ "tests = [([5.0, 3.1, 0.9, 0.1], 0),\n",
+ " ([5.1, 3.5, 1.0, 0.0], 0),\n",
+ " ([4.9, 3.3, 1.1, 0.1], 0),\n",
+ " ([6.0, 3.0, 4.0, 1.1], 1),\n",
+ " ([6.1, 2.2, 3.5, 1.0], 1),\n",
+ " ([5.9, 2.5, 3.3, 1.1], 1),\n",
+ " ([7.5, 4.1, 6.2, 2.3], 2),\n",
+ " ([7.3, 4.0, 6.1, 2.4], 2),\n",
+ " ([7.0, 3.3, 6.1, 2.5], 2)]\n",
+ "print(\"accuracy on test set:\",grade_learner(nn, tests))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We can see that the error ratio on the training set is smaller than the perceptron learner. As the error ratio is relatively small, let's try the model on the MNIST dataset to see whether there will be a larger difference. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 15,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "epoch:10, total_loss:89.0002153455983\n",
+ "epoch:20, total_loss:87.29675663038348\n",
+ "epoch:30, total_loss:86.29591779319225\n",
+ "epoch:40, total_loss:83.78091780128402\n",
+ "epoch:50, total_loss:82.17091581738829\n",
+ "epoch:60, total_loss:83.8434277386084\n",
+ "epoch:70, total_loss:83.55209905561495\n",
+ "epoch:80, total_loss:83.106898191118\n",
+ "epoch:90, total_loss:83.37041170165992\n",
+ "epoch:100, total_loss:82.57013813500876\n"
+ ]
+ }
+ ],
+ "source": [
+ "nn = neural_net_learner(mnist, epochs=100, verbose=10)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 16,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "0.784\n"
+ ]
+ }
+ ],
+ "source": [
+ "print(err_ratio(nn, mnist))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "After the model converging, the model's error ratio on the training set is still high. We will introduce the convolutional network in the following chapters to see how it helps improve accuracy on learning this dataset."
+ ]
+ }
+ ],
+ "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.6.9"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/notebooks/chapter19/Loss Functions and Layers.ipynb b/notebooks/chapter19/Loss Functions and Layers.ipynb
new file mode 100644
index 000000000..25676e899
--- /dev/null
+++ b/notebooks/chapter19/Loss Functions and Layers.ipynb
@@ -0,0 +1,398 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Loss Function\n",
+ "\n",
+ "Loss functions evaluate how well specific algorithm models the given data. Commonly loss functions are used to compare the target data and model's prediction. If predictions deviate too much from actual targets, loss function would output a large value. Usually, loss functions can help other optimization functions to improve the accuracy of the model.\n",
+ "\n",
+ "However, there’s no one-size-fits-all loss function to algorithms in machine learning. For each algorithm and machine learning projects, specifying certain loss functions could assist the user in getting better model performance. Here we will demonstrate two loss functions: `mse_loss` and `cross_entropy_loss`."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Min Square Error\n",
+ "\n",
+ "Min square error(MSE) is the most commonly used loss function in machine learning. The intuition of MSE is straight forward: the distance between two points represents the difference between them. "
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "$$MSE = -\\sum_i{(y_i-t_i)^2/n}$$"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Where $y_i$ is the prediction of the ith example and $t_i$ is the target of the ith example. And n is the total number of examples.\n",
+ "\n",
+ "Below is a plot of an MSE function where the true target value is 100, and the predicted values range between -10,000 to 10,000. The MSE loss (Y-axis) reaches its minimum value at prediction (X-axis) = 100."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "![](\"images/mse_plot.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Cross-Entropy\n",
+ "\n",
+ "For most deep learning applications, we can get away with just one loss function: cross-entropy loss function. We can think of most deep learning algorithms as learning probability distributions and what we are learning is a distribution of predictions $P(y|x)$ given a series of inputs. \n",
+ "\n",
+ "To associate input examples x with output examples y, the parameters that maximize the likelihood of the training set should be:"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "$$\\theta^* = argmax_\\theta \\prod_{i=0}^n p(y^{(i)}/x^{(i)})$$"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Maxmizing the above formula equals to minimizing the negative log form of it:"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "$$\\theta^* = argmin_\\theta -\\sum_{i=0}^n logp(y^{(i)}/x^{(i)})$$"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "It can be proven that the above formula equals to minimizing MSE loss.\n",
+ "\n",
+ "The majority of deep learning algorithms use cross-entropy in some way. Classifiers that use deep learning calculate the cross-entropy between categorical distributions over the output class. For a given class, its contribution to the loss is dependent on its probability in the following trend:"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "![](\"images/corss_entropy_plot.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Examples\n",
+ "\n",
+ "First let's import necessary packages."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "Using TensorFlow backend.\n"
+ ]
+ }
+ ],
+ "source": [
+ "import os, sys\n",
+ "sys.path = [os.path.abspath(\"../../\")] + sys.path\n",
+ "from deep_learning4e import *\n",
+ "from notebook4e import *"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Neural Network Layers\n",
+ "\n",
+ "Neural networks may be conveniently described using data structures of computational graphs. A computational graph is a directed graph describing how many variables should be computed, with each variable by computed by applying a specific operation to a set of other variables. \n",
+ "\n",
+ "In our code, we provide class `NNUnit` as the basic structure of a neural network. The structure of `NNUnit` is simple, it only stores the following information:\n",
+ "\n",
+ "- **val**: the value of the current node.\n",
+ "- **parent**: parents of the current node.\n",
+ "- **weights**: weights between parent nodes and current node. It should be in the same size as parents.\n",
+ "\n",
+ "There is another class `Layer` inheriting from `NNUnit`. A `Layer` object holds a list of nodes that represents all the nodes in a layer. It also has a method `forward` to pass a value through the current layer. Here we will demonstrate several pre-defined types of layers in a Neural Network."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Output Layers\n",
+ "\n",
+ "Neural networks need specialized output layers for each type of data we might ask them to produce. For many problems, we need to model discrete variables that have k distinct values instead of just binary variables. For example, models of natural language may predict a single word from among of vocabulary of tens of thousands or even more choices. To represent these distributions, we use a softmax layer:"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "$$P(y=i|x)=softmax(h(x)^TW+b)_i$$"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "where $W$ is matrix of learned weights of output layer $b$ is a vector of learned biases, and the softmax function is:\n",
+ "\n",
+ "$$softmax(z_i)=exp(z_i)/\\sum_i exp(z_i)$$"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "It is simple to create a output layer and feed an example into it:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "[0.03205860328008499, 0.08714431874203257, 0.23688281808991013, 0.6439142598879722]\n"
+ ]
+ }
+ ],
+ "source": [
+ "layer = OutputLayer(size=4)\n",
+ "example = [1,2,3,4]\n",
+ "print(layer.forward(example))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The output can be treated like normalized probability when the input of output layer is calculated by probability."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Input Layers\n",
+ "\n",
+ "Input layers can be treated like a mapping layer that maps each element of the input vector to each input layer node. The input layer acts as a storage of input vector information which can be used when doing forward propagation.\n",
+ "\n",
+ "In our realization of input layers, the size of the input vector and input layer should match."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "[1, 2, 3]\n"
+ ]
+ }
+ ],
+ "source": [
+ "layer = InputLayer(size=3)\n",
+ "example = [1,2,3]\n",
+ "print(layer.forward(example))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Hidden Layers\n",
+ "\n",
+ "While processing an input vector x of the neural network, it performs several intermediate computations before producing the output y. We can think of these intermediate computations as the state of memory during the execution of a multi-step program. We call the intermediate computations hidden because the data does not specify the values of these variables.\n",
+ "\n",
+ "Most neural network hidden layers are based on a linear transformation followed by the application of an elementwise nonlinear function called the activation function g:\n",
+ "\n",
+ "$$h=g(W+b)$$\n",
+ "\n",
+ "where W is a learned matrix of weights and b is a learned set of bias parameters.\n",
+ "\n",
+ "Here we pre-defined several activation functions in `utils.py`: `sigmoid`, `relu`, `elu`, `tanh` and `leaky_relu`. They are all inherited from the `Activation` class. You can get the value of the function or its derivative at a certain point of x:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Sigmoid at 0: 0.5\n",
+ "Deriavation of sigmoid at 0: 0\n"
+ ]
+ }
+ ],
+ "source": [
+ "s = sigmoid()\n",
+ "print(\"Sigmoid at 0:\", s.f(0))\n",
+ "print(\"Deriavation of sigmoid at 0:\", s.derivative(0))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "To create a hidden layer object, there are several attributes need to be specified:\n",
+ "\n",
+ "- **in_size**: the input vector size of each hidden layer node.\n",
+ "- **out_size**: the size of the output vector of the hidden layer. Thus each node will hide the weight of the size of (in_size). The weights will be initialized randomly.\n",
+ "- **activation**: the activation function used for this layer.\n",
+ "\n",
+ "Now let's demonstrate how a dense hidden layer works briefly:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "[0.21990266877137224, 0.2038864498984756, 0.5543443697256466]\n"
+ ]
+ }
+ ],
+ "source": [
+ "layer = DenseLayer(in_size=4, out_size=3, activation=sigmoid())\n",
+ "example = [1,2,3,4]\n",
+ "print(layer.forward(example))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "This layer mapped input of size 4 to output of size 3. "
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Convolutional Layers\n",
+ "\n",
+ "The convolutional layer is similar to the hidden layer except they use a different forward strategy. The convolutional layer takes an input of multiple channels and does convolution on each channel with a pre-defined kernel function. Thus the output of the convolutional layer will still be with the same number of channels. If we image each input as an image, then channels represent its color model such as RGB. The output will still have the same color model as the input.\n",
+ "\n",
+ "Now let's try the one-dimensional convolution layer:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "[array([3.9894228, 3.9894228, 3.9894228]), array([3.9894228, 3.9894228, 3.9894228]), array([3.9894228, 3.9894228, 3.9894228])]\n"
+ ]
+ }
+ ],
+ "source": [
+ "layer = ConvLayer1D(size=3, kernel_size=3)\n",
+ "example = [[1]*3 for _ in range(3)]\n",
+ "print(layer.forward(example))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Which can be deemed as a one-dimensional image with three channels."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Pooling Layers\n",
+ "\n",
+ "Pooling layers can be treated as a special kind of convolutional layer that uses a special kind of kernel to extract a certain value in the kernel region. Here we use max-pooling to report the maximum value in each group."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 9,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "[[3, 4], [4, 4], [4, 4]]\n"
+ ]
+ }
+ ],
+ "source": [
+ "layer = MaxPoolingLayer1D(size=3, kernel_size=3)\n",
+ "example = [[1,2,3,4], [2,3,4,1],[3,4,1,2]]\n",
+ "print(layer.forward(example))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We can see that each time kernel picks up the maximum value in its region."
+ ]
+ }
+ ],
+ "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.6.9"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/notebooks/chapter19/Optimizer and Backpropagation.ipynb b/notebooks/chapter19/Optimizer and Backpropagation.ipynb
new file mode 100644
index 000000000..5194adc7a
--- /dev/null
+++ b/notebooks/chapter19/Optimizer and Backpropagation.ipynb
@@ -0,0 +1,311 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Optimization Algorithms\n",
+ "\n",
+ "Training a neural network consists of modifying the network’s parameters to minimize the cost function on the training set. In principle, any kind of optimization algorithm could be used. In practice, modern neural networks are almost always trained with some variant of stochastic gradient descent(SGD). Here we will provide two optimization algorithms: SGD and Adam optimizer.\n",
+ "\n",
+ "## Stochastic Gradient Descent\n",
+ "\n",
+ "The goal of an optimization algorithm is to find the value of the parameter to make loss function very low. For some types of models, an optimization algorithm might find the global minimum value of loss function, but for neural network, the most efficient way to converge loss function to a local minimum is to minimize loss function according to each example.\n",
+ "\n",
+ "Gradient descent uses the following update rule to minimize loss function:"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "$$\\theta^{(t+1)} = \\theta^{(t)}-\\alpha\\nabla_\\theta L(\\theta^{(t)})$$"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "where t is the time step of the algorithm and $\\alpha$ is the learning rate. But this rule could be very costly when $L(\\theta)$ is defined as a sum across the entire training set. Using SGD can accelerate the learning process as we can use only a batch of examples to update the parameters. \n",
+ "\n",
+ "We implemented the gradient descent algorithm, which can be viewed with the following code:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "Using TensorFlow backend.\n"
+ ]
+ }
+ ],
+ "source": [
+ "import os, sys\n",
+ "sys.path = [os.path.abspath(\"../../\")] + sys.path\n",
+ "from deep_learning4e import *\n",
+ "from notebook4e import *"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ " def gradient_descent(dataset, net, loss, epochs=1000, l_rate=0.01, batch_size=1):\n",
+ " """\n",
+ " gradient descent algorithm to update the learnable parameters of a network.\n",
+ " :return: the updated network.\n",
+ " """\n",
+ " # init data\n",
+ " examples = dataset.examples\n",
+ "\n",
+ " for e in range(epochs):\n",
+ " total_loss = 0\n",
+ " random.shuffle(examples)\n",
+ " weights = [[node.weights for node in layer.nodes] for layer in net]\n",
+ "\n",
+ " for batch in get_batch(examples, batch_size):\n",
+ "\n",
+ " inputs, targets = init_examples(batch, dataset.inputs, dataset.target, len(net[-1].nodes))\n",
+ " # compute gradients of weights\n",
+ " gs, batch_loss = BackPropagation(inputs, targets, weights, net, loss)\n",
+ " # update weights with gradient descent\n",
+ " weights = vector_add(weights, scalar_vector_product(-l_rate, gs))\n",
+ " total_loss += batch_loss\n",
+ " # update the weights of network each batch\n",
+ " for i in range(len(net)):\n",
+ " if weights[i]:\n",
+ " for j in range(len(weights[i])):\n",
+ " net[i].nodes[j].weights = weights[i][j]\n",
+ "\n",
+ " if (e+1) % 10 == 0:\n",
+ " print("epoch:{}, total_loss:{}".format(e+1,total_loss))\n",
+ " return net\n",
+ "![](\"images/backprop.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Applying optimizers and back-propagation algorithm together, we can update the weights of a neural network to minimize the loss function with alternatively doing forward and back-propagation process. Here is a figure form [here](https://medium.com/datathings/neural-networks-and-backpropagation-explained-in-a-simple-way-f540a3611f5e) describing how a neural network updates its weights:\n",
+ "\n",
+ "![](\"images/nn_steps.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "In our implementation, all the steps are integrated into the optimizer objects. The forward-backward process of passing information through the whole neural network is put into the method `BackPropagation`. You can view the code with:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "psource(BackPropagation)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The demonstration of optimizers and back-propagation algorithm will be made together with neural network learners."
+ ]
+ }
+ ],
+ "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.6.9"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/notebooks/chapter19/RNN.ipynb b/notebooks/chapter19/RNN.ipynb
new file mode 100644
index 000000000..b6971b36a
--- /dev/null
+++ b/notebooks/chapter19/RNN.ipynb
@@ -0,0 +1,487 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# RNN\n",
+ "\n",
+ "## Overview\n",
+ "\n",
+ "When human is thinking, they are thinking based on the understanding of previous time steps but not from scratch. Traditional neural networks can’t do this, and it seems like a major shortcoming. For example, imagine you want to do sentimental analysis of some texts. It will be unclear if the traditional network cannot recognize the short phrase and sentences.\n",
+ "\n",
+ "Recurrent neural networks address this issue. They are networks with loops in them, allowing information to persist.\n",
+ "\n",
+ "![](\"images/rnn_unit.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "A recurrent neural network can be thought of as multiple copies of the same network, each passing a message to a successor. Consider what happens if we unroll the above loop:\n",
+ " \n",
+ "![](\"images/rnn_units.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "As demonstrated in the book, recurrent neural networks may be connected in many different ways: sequences in the input, the output, or in the most general case both.\n",
+ "\n",
+ "![](\"images/rnn_connections.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Implementation\n",
+ "\n",
+ "In our case, we implemented rnn with modules offered by the package of `keras`. To use `keras` and our module, you must have both `tensorflow` and `keras` installed as a prerequisite. `keras` offered very well defined high-level neural networks API which allows for easy and fast prototyping. `keras` supports many different types of networks such as convolutional and recurrent neural networks as well as user-defined networks. About how to get started with `keras`, please read the [tutorial](https://keras.io/).\n",
+ "\n",
+ "To view our implementation of a simple rnn, please use the following code:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "Using TensorFlow backend.\n"
+ ]
+ }
+ ],
+ "source": [
+ "import warnings\n",
+ "warnings.filterwarnings(\"ignore\", category=FutureWarning)\n",
+ "import os, sys\n",
+ "sys.path = [os.path.abspath(\"../../\")] + sys.path\n",
+ "from deep_learning4e import *\n",
+ "from notebook4e import *"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ " def SimpleRNNLearner(train_data, val_data, epochs=2):\n",
+ " """\n",
+ " RNN example for text sentimental analysis.\n",
+ " :param train_data: a tuple of (training data, targets)\n",
+ " Training data: ndarray taking training examples, while each example is coded by embedding\n",
+ " Targets: ndarray taking targets of each example. Each target is mapped to an integer.\n",
+ " :param val_data: a tuple of (validation data, targets)\n",
+ " :param epochs: number of epochs\n",
+ " :return: a keras model\n",
+ " """\n",
+ "\n",
+ " total_inputs = 5000\n",
+ " input_length = 500\n",
+ "\n",
+ " # init data\n",
+ " X_train, y_train = train_data\n",
+ " X_val, y_val = val_data\n",
+ "\n",
+ " # init a the sequential network (embedding layer, rnn layer, dense layer)\n",
+ " model = Sequential()\n",
+ " model.add(Embedding(total_inputs, 32, input_length=input_length))\n",
+ " model.add(SimpleRNN(units=128))\n",
+ " model.add(Dense(1, activation='sigmoid'))\n",
+ " model.compile(loss='binary_crossentropy', optimizer='adam', metrics=['accuracy'])\n",
+ "\n",
+ " # train the model\n",
+ " model.fit(X_train, y_train, validation_data=(X_val, y_val), epochs=epochs, batch_size=128, verbose=2)\n",
+ "\n",
+ " return model\n",
+ "![](\"images/autoencoder.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Autoencoders are learned automatically from data examples. It means that it is easy to train specialized instances of the algorithm that will perform well on a specific type of input and that it does not require any new engineering, only the appropriate training data.\n",
+ "\n",
+ "Autoencoders have different architectures for different kinds of data. Here we only provide a simple example of a vanilla encoder, which means they're only one hidden layer in the network:\n",
+ "\n",
+ "![](\"images/vanilla.png\")
\n",
+ "\n",
+ "You can view the source code by:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ " def AutoencoderLearner(inputs, encoding_size, epochs=200):\n",
+ " """\n",
+ " Simple example of linear auto encoder learning producing the input itself.\n",
+ " :param inputs: a batch of input data in np.ndarray type\n",
+ " :param encoding_size: int, the size of encoding layer\n",
+ " :param epochs: number of epochs\n",
+ " :return: a keras model\n",
+ " """\n",
+ "\n",
+ " # init data\n",
+ " input_size = len(inputs[0])\n",
+ "\n",
+ " # init model\n",
+ " model = Sequential()\n",
+ " model.add(Dense(encoding_size, input_dim=input_size, activation='relu', kernel_initializer='random_uniform',\n",
+ " bias_initializer='ones'))\n",
+ " model.add(Dense(input_size, activation='relu', kernel_initializer='random_uniform', bias_initializer='ones'))\n",
+ "\n",
+ " # update model with sgd\n",
+ " sgd = optimizers.SGD(lr=0.01)\n",
+ " model.compile(loss='mean_squared_error', optimizer=sgd, metrics=['accuracy'])\n",
+ "\n",
+ " # train the model\n",
+ " model.fit(inputs, inputs, epochs=epochs, batch_size=10, verbose=2)\n",
+ "\n",
+ " return model\n",
+ "![](\"images/mdp.png\")
Now we define actions and a policy similar to **Fig 21.1** in the book."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 7,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Action Directions\n",
+ "north = (0, 1)\n",
+ "south = (0,-1)\n",
+ "west = (-1, 0)\n",
+ "east = (1, 0)\n",
+ "\n",
+ "policy = {\n",
+ " (0, 2): east, (1, 2): east, (2, 2): east, (3, 2): None,\n",
+ " (0, 1): north, (2, 1): north, (3, 1): None,\n",
+ " (0, 0): north, (1, 0): west, (2, 0): west, (3, 0): west, \n",
+ "}"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "This enviroment will be extensively used in the following demonstrations."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Direct Utility Estimation (DUE)\n",
+ " \n",
+ " The first, most naive method of estimating utility comes from the simplest interpretation of the above definition. We construct an agent that follows the policy until it reaches the terminal state. At each step, it logs its current state, reward. Once it reaches the terminal state, it can estimate the utility for each state for *that* iteration, by simply summing the discounted rewards from that state to the terminal one.\n",
+ "\n",
+ " It can now run this 'simulation' $n$ times and calculate the average utility of each state. If a state occurs more than once in a simulation, both its utility values are counted separately.\n",
+ " \n",
+ " Note that this method may be prohibitively slow for very large state-spaces. Besides, **it pays no attention to the transition probability $P(s'\\ |\\ s, a)$.** It misses out on information that it is capable of collecting (say, by recording the number of times an action from one state led to another state). The next method addresses this issue.\n",
+ " \n",
+ "### Examples\n",
+ "\n",
+ "The `PassiveDEUAgent` class in the `rl` module implements the Agent Program described in **Fig 21.2** of the AIMA Book. `PassiveDEUAgent` sums over rewards to find the estimated utility for each state. It thus requires the running of several iterations."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "%psource PassiveDUEAgent"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Now let's try the `PassiveDEUAgent` on the newly defined `sequential_decision_environment`:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "DUEagent = PassiveDUEAgent(policy, sequential_decision_environment)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We can try passing information through the markove model for 200 times in order to get the converged utility value:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 12,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "for i in range(200):\n",
+ " run_single_trial(DUEagent, sequential_decision_environment)\n",
+ " DUEagent.estimate_U()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Now let's print our estimated utility for each position:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 15,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "(0, 1):0.7956939931414414\n",
+ "(1, 2):0.9162054322837863\n",
+ "(3, 2):1.0\n",
+ "(0, 0):0.734717308253083\n",
+ "(2, 2):0.9595117143816332\n",
+ "(0, 2):0.8481387156375687\n",
+ "(1, 0):0.4355860415209706\n",
+ "(2, 1):-0.550079982553143\n",
+ "(3, 1):-1.0\n"
+ ]
+ }
+ ],
+ "source": [
+ "print('\\n'.join([str(k)+':'+str(v) for k, v in DUEagent.U.items()]))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Adaptive Dynamic Programming (ADP)\n",
+ " \n",
+ " This method makes use of knowledge of the past state $s$, the action $a$, and the new perceived state $s'$ to estimate the transition probability $P(s'\\ |\\ s,a)$. It does this by the simple counting of new states resulting from previous states and actions.![](\"images/gradients.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Implementation\n",
+ "\n",
+ "We implemented an edge detector using a gradient method as `gradient_edge_detector` in `perceptron.py`. There are two filters defined as $[[1, -1]], [[1], [-1]]$ to extract edges in x and y directions respectively. The filters are applied to an image using `convolve2d` method in `scipy.single` package. The image passed into the function needs to be in the form of `numpy.ndarray` or an iterable object that can be transformed into a `ndarray`.\n",
+ "\n",
+ "To view the detailed implementation, please execute the following block"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "psource(gradient_edge_detector)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Example\n",
+ "\n",
+ "Now let's try the detector for real case pictures. First, we will show the original picture before edge detection:"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "![](\"images/stapler.png\")
\n",
+ "\n",
+ "We will use `matplotlib` to read the image as a numpy ndarray:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "image height: 590\n",
+ "image width: 787\n"
+ ]
+ }
+ ],
+ "source": [
+ "import matplotlib.pyplot as plt\n",
+ "import numpy as np\n",
+ "import matplotlib.image as mpimg\n",
+ "\n",
+ "im =mpimg.imread('images/stapler.png')\n",
+ "print(\"image height:\", len(im))\n",
+ "print(\"image width:\", len(im[0]))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The code shows we get an image with a size of $787*590$. `gaussian_derivative_edge_detector` can extract images in both x and y direction and then put them together in a ndarray:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "image height: 590\n",
+ "image width: 787\n"
+ ]
+ }
+ ],
+ "source": [
+ "edges = gradient_edge_detector(im)\n",
+ "print(\"image height:\", len(edges))\n",
+ "print(\"image width:\", len(edges[0]))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The edges are in the same shape of the original image. Now we will try print out the image, we implemented a `show_edges` function to do this:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "image/png": "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\n",
+ "text/plain": [
+ "![](\"images/derivative_of_gaussian.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Implementation\n",
+ "\n",
+ "In our implementation, we initialize Gaussian filters by applying the 2D Gaussian function on a given size of the grid which is the same as the kernel size. Then the x and y direction image filters are calculated as the convolution of the Gaussian filter and the gradient filter:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "x_filter = scipy.signal.convolve2d(gaussian_filter, np.asarray([[1, -1]]), 'same')\n",
+ "y_filter = scipy.signal.convolve2d(gaussian_filter, np.asarray([[1], [-1]]), 'same')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Then both of the filters are applied to the input image to extract the x and y direction edges. For detailed implementation, please view by:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "psource(gaussian_derivative_edge_detector)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Example\n",
+ "\n",
+ "Now let's try again on the stapler image and plot the extracted edges:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "image/png": "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\n",
+ "text/plain": [
+ "![](\"images/laplacian.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Implementation\n",
+ "\n",
+ "There are two commonly used small Laplacian kernels:"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "![](\"images/laplacian_kernels.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "In our implementation, we used the first one as the default kernel and convolve it with the original image using packages provided by `scipy`."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Example\n",
+ "\n",
+ "Now let's use the Laplacian edge detector to extract edges of the staple example:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "image/png": "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\n",
+ "text/plain": [
+ "![](\"images/stapler_bbox.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Some of the bounding boxes do have the stapler or at least most of it in the box, which can assist the classification process."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### R-CNN and Faster R-CNN\n",
+ "\n",
+ "[Ross Girshick et al.](https://arxiv.org/pdf/1311.2524.pdf) proposed a method where they use selective search to extract just 2000 regions from the image. Then the regions in bounding boxes are feed into a convolutional neural network to perform classification. The brief architecture can be shown as:\n",
+ "\n",
+ "![](\"images/RCNN.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The problem with R-CNN is that one must pass each box independently through an image classifier thus it takes a huge amount of time to train the network. And meanwhile, the selective search is not that stable and sometimes may generate bad examples.\n",
+ "\n",
+ "Faster R-CNN solved the drawbacks of R-CNN by applying a faster object detection algorithm. Instead of feeding the region proposals to the CNN, we feed the input image to the CNN to generate a convolutional feature map. Then we identify the region of interests on the feature map and then reshape them into a fixed size with an ROI pooling layer so it can be put into another classifier. \n",
+ "\n",
+ "This algorithm is faster than R-CNN as the image is not frequently fed into the CNN to extract feature maps."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "#### Implementation\n",
+ "\n",
+ "For an ROI pooling layer, we implemented a simple demo of it as `pool_rois`. We can fake a simple feature map with `numpy`:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 12,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import numpy as np\n",
+ "\n",
+ "feature_maps_shape = (200, 100, 1)\n",
+ "feature_map = np.ones(feature_maps_shape, dtype='float32')\n",
+ "feature_map[200 - 1, 100 - 3, 0] = 50"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Note that the fake feature map is all 1 except for one spot with a value of 50. Now let's generate some regio of interests:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 13,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "roiss = np.asarray([[0.5, 0.2, 0.7, 0.4], [0.0, 0.0, 1.0, 1.0]])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Here we only made up two regions of interest. The first only crops some part of the image where all pixels are '1' which ranges from 0.5-0.7 of the length of the horizontal edge and 0.2-0.4 of verticle edge. The range of the second region is the whole image. Now let's pool a 3x7 area out of each region of interest."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 14,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "[array([[1., 1., 1., 1., 1., 1., 1.],\n",
+ " [1., 1., 1., 1., 1., 1., 1.],\n",
+ " [1., 1., 1., 1., 1., 1., 1.]], dtype=float32),\n",
+ " array([[ 1., 1., 1., 1., 1., 1., 1.],\n",
+ " [ 1., 1., 1., 1., 1., 1., 1.],\n",
+ " [ 1., 1., 1., 1., 1., 1., 50.]], dtype=float32)]"
+ ]
+ },
+ "execution_count": 14,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "pool_rois(feature_map, roiss, 3, 7)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "What we are expecting is that the second pooled region is different from the first one as there is an artificial feature-the '50' in its input. The printed result is exactly the same as we expected."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "In order to try the whole algorithm of the Faster R-CNN, you can refer to [this GitHub repository](https://github.com/endernewton/tf-faster-rcnn) for more detailed guidance."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": []
+ }
+ ],
+ "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.6.9"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/notebooks/chapter24/images/RCNN.png b/notebooks/chapter24/images/RCNN.png
new file mode 100644
index 000000000..273021fbe
Binary files /dev/null and b/notebooks/chapter24/images/RCNN.png differ
diff --git a/notebooks/chapter24/images/derivative_of_gaussian.png b/notebooks/chapter24/images/derivative_of_gaussian.png
new file mode 100644
index 000000000..0be575529
Binary files /dev/null and b/notebooks/chapter24/images/derivative_of_gaussian.png differ
diff --git a/notebooks/chapter24/images/gradients.png b/notebooks/chapter24/images/gradients.png
new file mode 100644
index 000000000..ae57bdf3b
Binary files /dev/null and b/notebooks/chapter24/images/gradients.png differ
diff --git a/notebooks/chapter24/images/laplacian.png b/notebooks/chapter24/images/laplacian.png
new file mode 100644
index 000000000..6d7e6916a
Binary files /dev/null and b/notebooks/chapter24/images/laplacian.png differ
diff --git a/notebooks/chapter24/images/laplacian_kernels.png b/notebooks/chapter24/images/laplacian_kernels.png
new file mode 100644
index 000000000..faca3321c
Binary files /dev/null and b/notebooks/chapter24/images/laplacian_kernels.png differ
diff --git a/notebooks/chapter24/images/stapler.png b/notebooks/chapter24/images/stapler.png
new file mode 100644
index 000000000..e550d83f9
Binary files /dev/null and b/notebooks/chapter24/images/stapler.png differ
diff --git a/notebooks/chapter24/images/stapler_bbox.png b/notebooks/chapter24/images/stapler_bbox.png
new file mode 100644
index 000000000..c5a7c7af0
Binary files /dev/null and b/notebooks/chapter24/images/stapler_bbox.png differ
diff --git a/obsolete_search4e.ipynb b/obsolete_search4e.ipynb
new file mode 100644
index 000000000..72981d49b
--- /dev/null
+++ b/obsolete_search4e.ipynb
@@ -0,0 +1,3835 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "source": [
+ "*Note: This is not yet ready, but shows the direction I'm leaning in for Fourth Edition Search.*\n",
+ "\n",
+ "# State-Space Search\n",
+ "\n",
+ "This notebook describes several state-space search algorithms, and how they can be used to solve a variety of problems. We start with a simple algorithm and a simple domain: finding a route from city to city. Later we will explore other algorithms and domains.\n",
+ "\n",
+ "## The Route-Finding Domain\n",
+ "\n",
+ "Like all state-space search problems, in a route-finding problem you will be given:\n",
+ "- A start state (for example, `'A'` for the city Arad).\n",
+ "- A goal state (for example, `'B'` for the city Bucharest).\n",
+ "- Actions that can change state (for example, driving from `'A'` to `'S'`).\n",
+ "\n",
+ "You will be asked to find:\n",
+ "- A path from the start state, through intermediate states, to the goal state.\n",
+ "\n",
+ "We'll use this map:\n",
+ "\n",
+ "![](\"http://robotics.cs.tamu.edu/dshell/cs625/images/map.jpg\")
\n",
+ "\n",
+ "A state-space search problem can be represented by a *graph*, where the vertices of the graph are the states of the problem (in this case, cities) and the edges of the graph are the actions (in this case, driving along a road).\n",
+ "\n",
+ "We'll represent a city by its single initial letter. \n",
+ "We'll represent the graph of connections as a `dict` that maps each city to a list of the neighboring cities (connected by a road). For now we don't explicitly represent the actions, nor the distances\n",
+ "between cities."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {
+ "button": false,
+ "collapsed": true,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "romania = {\n",
+ " 'A': ['Z', 'T', 'S'],\n",
+ " 'B': ['F', 'P', 'G', 'U'],\n",
+ " 'C': ['D', 'R', 'P'],\n",
+ " 'D': ['M', 'C'],\n",
+ " 'E': ['H'],\n",
+ " 'F': ['S', 'B'],\n",
+ " 'G': ['B'],\n",
+ " 'H': ['U', 'E'],\n",
+ " 'I': ['N', 'V'],\n",
+ " 'L': ['T', 'M'],\n",
+ " 'M': ['L', 'D'],\n",
+ " 'N': ['I'],\n",
+ " 'O': ['Z', 'S'],\n",
+ " 'P': ['R', 'C', 'B'],\n",
+ " 'R': ['S', 'C', 'P'],\n",
+ " 'S': ['A', 'O', 'F', 'R'],\n",
+ " 'T': ['A', 'L'],\n",
+ " 'U': ['B', 'V', 'H'],\n",
+ " 'V': ['U', 'I'],\n",
+ " 'Z': ['O', 'A']}"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "source": [
+ "Suppose we want to get from `A` to `B`. Where can we go from the start state, `A`?"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "['Z', 'T', 'S']"
+ ]
+ },
+ "execution_count": 2,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "romania['A']"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "source": [
+ "We see that from `A` we can get to any of the three cities `['Z', 'T', 'S']`. Which should we choose? *We don't know.* That's the whole point of *search*: we don't know which immediate action is best, so we'll have to explore, until we find a *path* that leads to the goal. \n",
+ "\n",
+ "How do we explore? We'll start with a simple algorithm that will get us from `A` to `B`. We'll keep a *frontier*—a collection of not-yet-explored states—and expand the frontier outward until it reaches the goal. To be more precise:\n",
+ "\n",
+ "- Initially, the only state in the frontier is the start state, `'A'`.\n",
+ "- Until we reach the goal, or run out of states in the frontier to explore, do the following:\n",
+ " - Remove the first state from the frontier. Call it `s`.\n",
+ " - If `s` is the goal, we're done. Return the path to `s`.\n",
+ " - Otherwise, consider all the neighboring states of `s`. For each one:\n",
+ " - If we have not previously explored the state, add it to the end of the frontier.\n",
+ " - Also keep track of the previous state that led to this new neighboring state; we'll need this to reconstruct the path to the goal, and to keep us from re-visiting previously explored states.\n",
+ " \n",
+ "# A Simple Search Algorithm: `breadth_first`\n",
+ " \n",
+ "The function `breadth_first` implements this strategy:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {
+ "button": false,
+ "collapsed": true,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "from collections import deque # Doubly-ended queue: pop from left, append to right.\n",
+ "\n",
+ "def breadth_first(start, goal, neighbors):\n",
+ " \"Find a shortest sequence of states from start to the goal.\"\n",
+ " frontier = deque([start]) # A queue of states\n",
+ " previous = {start: None} # start has no previous state; other states will\n",
+ " while frontier:\n",
+ " s = frontier.popleft()\n",
+ " if s == goal:\n",
+ " return path(previous, s)\n",
+ " for s2 in neighbors[s]:\n",
+ " if s2 not in previous:\n",
+ " frontier.append(s2)\n",
+ " previous[s2] = s\n",
+ " \n",
+ "def path(previous, s): \n",
+ " \"Return a list of states that lead to state s, according to the previous dict.\"\n",
+ " return [] if (s is None) else path(previous, previous[s]) + [s]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "source": [
+ "A couple of things to note: \n",
+ "\n",
+ "1. We always add new states to the end of the frontier queue. That means that all the states that are adjacent to the start state will come first in the queue, then all the states that are two steps away, then three steps, etc.\n",
+ "That's what we mean by *breadth-first* search.\n",
+ "2. We recover the path to an `end` state by following the trail of `previous[end]` pointers, all the way back to `start`.\n",
+ "The dict `previous` is a map of `{state: previous_state}`. \n",
+ "3. When we finally get an `s` that is the goal state, we know we have found a shortest path, because any other state in the queue must correspond to a path that is as long or longer.\n",
+ "3. Note that `previous` contains all the states that are currently in `frontier` as well as all the states that were in `frontier` in the past.\n",
+ "4. If no path to the goal is found, then `breadth_first` returns `None`. If a path is found, it returns the sequence of states on the path.\n",
+ "\n",
+ "Some examples:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "['A', 'S', 'F', 'B']"
+ ]
+ },
+ "execution_count": 4,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "breadth_first('A', 'B', romania)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "['L', 'T', 'A', 'S', 'F', 'B', 'U', 'V', 'I', 'N']"
+ ]
+ },
+ "execution_count": 5,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "breadth_first('L', 'N', romania)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "['N', 'I', 'V', 'U', 'B', 'F', 'S', 'A', 'T', 'L']"
+ ]
+ },
+ "execution_count": 6,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "breadth_first('N', 'L', romania)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 7,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "['E']"
+ ]
+ },
+ "execution_count": 7,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "breadth_first('E', 'E', romania)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "source": [
+ "Now let's try a different kind of problem that can be solved with the same search function.\n",
+ "\n",
+ "## Word Ladders Problem\n",
+ "\n",
+ "A *word ladder* problem is this: given a start word and a goal word, find the shortest way to transform the start word into the goal word by changing one letter at a time, such that each change results in a word. For example starting with `green` we can reach `grass` in 7 steps:\n",
+ "\n",
+ "`green` → `greed` → `treed` → `trees` → `tress` → `cress` → `crass` → `grass`\n",
+ "\n",
+ "We will need a dictionary of words. We'll use 5-letter words from the [Stanford GraphBase](http://www-cs-faculty.stanford.edu/~uno/sgb.html) project for this purpose. Let's get that file from aimadata."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "metadata": {
+ "button": false,
+ "collapsed": true,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "from search import *\n",
+ "sgb_words = open_data(\"EN-text/sgb-words.txt\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "source": [
+ "We can assign `WORDS` to be the set of all the words in this file:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 9,
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "5757"
+ ]
+ },
+ "execution_count": 9,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "WORDS = set(sgb_words.read().split())\n",
+ "len(WORDS)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "source": [
+ "And define `neighboring_words` to return the set of all words that are a one-letter change away from a given `word`:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 10,
+ "metadata": {
+ "button": false,
+ "collapsed": true,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "def neighboring_words(word):\n",
+ " \"All words that are one letter away from this word.\"\n",
+ " neighbors = {word[:i] + c + word[i+1:]\n",
+ " for i in range(len(word))\n",
+ " for c in 'abcdefghijklmnopqrstuvwxyz'\n",
+ " if c != word[i]}\n",
+ " return neighbors & WORDS"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "For example:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 11,
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "{'cello', 'hallo', 'hells', 'hullo', 'jello'}"
+ ]
+ },
+ "execution_count": 11,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "neighboring_words('hello')"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 12,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "{'would'}"
+ ]
+ },
+ "execution_count": 12,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "neighboring_words('world')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "source": [
+ "Now we can create `word_neighbors` as a dict of `{word: {neighboring_word, ...}}`: "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 13,
+ "metadata": {
+ "button": false,
+ "collapsed": true,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "word_neighbors = {word: neighboring_words(word)\n",
+ " for word in WORDS}"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "source": [
+ "Now the `breadth_first` function can be used to solve a word ladder problem:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 14,
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "['green', 'greed', 'treed', 'trees', 'treys', 'trays', 'grays', 'grass']"
+ ]
+ },
+ "execution_count": 14,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "breadth_first('green', 'grass', word_neighbors)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 15,
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "['smart',\n",
+ " 'start',\n",
+ " 'stars',\n",
+ " 'sears',\n",
+ " 'bears',\n",
+ " 'beans',\n",
+ " 'brans',\n",
+ " 'brand',\n",
+ " 'braid',\n",
+ " 'brain']"
+ ]
+ },
+ "execution_count": 15,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "breadth_first('smart', 'brain', word_neighbors)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 16,
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "['frown',\n",
+ " 'flown',\n",
+ " 'flows',\n",
+ " 'slows',\n",
+ " 'slots',\n",
+ " 'slits',\n",
+ " 'spits',\n",
+ " 'spite',\n",
+ " 'smite',\n",
+ " 'smile']"
+ ]
+ },
+ "execution_count": 16,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "breadth_first('frown', 'smile', word_neighbors)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "source": [
+ "# More General Search Algorithms\n",
+ "\n",
+ "Now we'll embelish the `breadth_first` algorithm to make a family of search algorithms with more capabilities:\n",
+ "\n",
+ "1. We distinguish between an *action* and the *result* of an action.\n",
+ "3. We allow different measures of the cost of a solution (not just the number of steps in the sequence).\n",
+ "4. We search through the state space in an order that is more likely to lead to an optimal solution quickly.\n",
+ "\n",
+ "Here's how we do these things:\n",
+ "\n",
+ "1. Instead of having a graph of neighboring states, we instead have an object of type *Problem*. A Problem\n",
+ "has one method, `Problem.actions(state)` to return a collection of the actions that are allowed in a state,\n",
+ "and another method, `Problem.result(state, action)` that says what happens when you take an action.\n",
+ "2. We keep a set, `explored` of states that have already been explored. We also have a class, `Frontier`, that makes it efficient to ask if a state is on the frontier.\n",
+ "3. Each action has a cost associated with it (in fact, the cost can vary with both the state and the action).\n",
+ "4. The `Frontier` class acts as a priority queue, allowing the \"best\" state to be explored next.\n",
+ "We represent a sequence of actions and resulting states as a linked list of `Node` objects.\n",
+ "\n",
+ "The algorithm `breadth_first_search` is basically the same as `breadth_first`, but using our new conventions:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 17,
+ "metadata": {
+ "button": false,
+ "collapsed": true,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "def breadth_first_search(problem):\n",
+ " \"Search for goal; paths with least number of steps first.\"\n",
+ " if problem.is_goal(problem.initial): \n",
+ " return Node(problem.initial)\n",
+ " frontier = FrontierQ(Node(problem.initial), LIFO=False)\n",
+ " explored = set()\n",
+ " while frontier:\n",
+ " node = frontier.pop()\n",
+ " explored.add(node.state)\n",
+ " for action in problem.actions(node.state):\n",
+ " child = node.child(problem, action)\n",
+ " if child.state not in explored and child.state not in frontier:\n",
+ " if problem.is_goal(child.state):\n",
+ " return child\n",
+ " frontier.add(child)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Next is `uniform_cost_search`, in which each step can have a different cost, and we still consider first one os the states with minimum cost so far."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 18,
+ "metadata": {
+ "button": false,
+ "collapsed": true,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "def uniform_cost_search(problem, costfn=lambda node: node.path_cost):\n",
+ " frontier = FrontierPQ(Node(problem.initial), costfn)\n",
+ " explored = set()\n",
+ " while frontier:\n",
+ " node = frontier.pop()\n",
+ " if problem.is_goal(node.state):\n",
+ " return node\n",
+ " explored.add(node.state)\n",
+ " for action in problem.actions(node.state):\n",
+ " child = node.child(problem, action)\n",
+ " if child.state not in explored and child not in frontier:\n",
+ " frontier.add(child)\n",
+ " elif child in frontier and frontier.cost[child] < child.path_cost:\n",
+ " frontier.replace(child)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Finally, `astar_search` in which the cost includes an estimate of the distance to the goal as well as the distance travelled so far."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 19,
+ "metadata": {
+ "button": false,
+ "collapsed": true,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "def astar_search(problem, heuristic):\n",
+ " costfn = lambda node: node.path_cost + heuristic(node.state)\n",
+ " return uniform_cost_search(problem, costfn)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "button": false,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "source": [
+ "# Search Tree Nodes\n",
+ "\n",
+ "The solution to a search problem is now a linked list of `Node`s, where each `Node`\n",
+ "includes a `state` and the `path_cost` of getting to the state. In addition, for every `Node` except for the first (root) `Node`, there is a previous `Node` (indicating the state that lead to this `Node`) and an `action` (indicating the action taken to get here)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 20,
+ "metadata": {
+ "button": false,
+ "collapsed": true,
+ "new_sheet": false,
+ "run_control": {
+ "read_only": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "class Node(object):\n",
+ " \"\"\"A node in a search tree. A search tree is spanning tree over states.\n",
+ " A Node contains a state, the previous node in the tree, the action that\n",
+ " takes us from the previous state to this state, and the path cost to get to \n",
+ " this state. If a state is arrived at by two paths, then there are two nodes \n",
+ " with the same state.\"\"\"\n",
+ "\n",
+ " def __init__(self, state, previous=None, action=None, step_cost=1):\n",
+ " \"Create a search tree Node, derived from a previous Node by an action.\"\n",
+ " self.state = state\n",
+ " self.previous = previous\n",
+ " self.action = action\n",
+ " self.path_cost = 0 if previous is None else (previous.path_cost + step_cost)\n",
+ "\n",
+ " def __repr__(self): return \"class PlanningProblem:\n",
+ " """\n",
+ " Planning Domain Definition Language (PlanningProblem) used to define a search problem.\n",
+ " It stores states in a knowledge base consisting of first order logic statements.\n",
+ " The conjunction of these logical statements completely defines a state.\n",
+ " """\n",
+ "\n",
+ " def __init__(self, init, goals, actions):\n",
+ " self.init = self.convert(init)\n",
+ " self.goals = self.convert(goals)\n",
+ " self.actions = actions\n",
+ "\n",
+ " def convert(self, clauses):\n",
+ " """Converts strings into exprs"""\n",
+ " if not isinstance(clauses, Expr):\n",
+ " if len(clauses) > 0:\n",
+ " clauses = expr(clauses)\n",
+ " else:\n",
+ " clauses = []\n",
+ " try:\n",
+ " clauses = conjuncts(clauses)\n",
+ " except AttributeError:\n",
+ " clauses = clauses\n",
+ "\n",
+ " new_clauses = []\n",
+ " for clause in clauses:\n",
+ " if clause.op == '~':\n",
+ " new_clauses.append(expr('Not' + str(clause.args[0])))\n",
+ " else:\n",
+ " new_clauses.append(clause)\n",
+ " return new_clauses\n",
+ "\n",
+ " def goal_test(self):\n",
+ " """Checks if the goals have been reached"""\n",
+ " return all(goal in self.init for goal in self.goals)\n",
+ "\n",
+ " def act(self, action):\n",
+ " """\n",
+ " Performs the action given as argument.\n",
+ " Note that action is an Expr like expr('Remove(Glass, Table)') or expr('Eat(Sandwich)')\n",
+ " """ \n",
+ " action_name = action.op\n",
+ " args = action.args\n",
+ " list_action = first(a for a in self.actions if a.name == action_name)\n",
+ " if list_action is None:\n",
+ " raise Exception("Action '{}' not found".format(action_name))\n",
+ " if not list_action.check_precond(self.init, args):\n",
+ " raise Exception("Action '{}' pre-conditions not satisfied".format(action))\n",
+ " self.init = list_action(self.init, args).clauses\n",
+ "class Action:\n",
+ " """\n",
+ " Defines an action schema using preconditions and effects.\n",
+ " Use this to describe actions in PlanningProblem.\n",
+ " action is an Expr where variables are given as arguments(args).\n",
+ " Precondition and effect are both lists with positive and negative literals.\n",
+ " Negative preconditions and effects are defined by adding a 'Not' before the name of the clause\n",
+ " Example:\n",
+ " precond = [expr("Human(person)"), expr("Hungry(Person)"), expr("NotEaten(food)")]\n",
+ " effect = [expr("Eaten(food)"), expr("Hungry(person)")]\n",
+ " eat = Action(expr("Eat(person, food)"), precond, effect)\n",
+ " """\n",
+ "\n",
+ " def __init__(self, action, precond, effect):\n",
+ " if isinstance(action, str):\n",
+ " action = expr(action)\n",
+ " self.name = action.op\n",
+ " self.args = action.args\n",
+ " self.precond = self.convert(precond)\n",
+ " self.effect = self.convert(effect)\n",
+ "\n",
+ " def __call__(self, kb, args):\n",
+ " return self.act(kb, args)\n",
+ "\n",
+ " def __repr__(self):\n",
+ " return '{}({})'.format(self.__class__.__name__, Expr(self.name, *self.args))\n",
+ "\n",
+ " def convert(self, clauses):\n",
+ " """Converts strings into Exprs"""\n",
+ " if isinstance(clauses, Expr):\n",
+ " clauses = conjuncts(clauses)\n",
+ " for i in range(len(clauses)):\n",
+ " if clauses[i].op == '~':\n",
+ " clauses[i] = expr('Not' + str(clauses[i].args[0]))\n",
+ "\n",
+ " elif isinstance(clauses, str):\n",
+ " clauses = clauses.replace('~', 'Not')\n",
+ " if len(clauses) > 0:\n",
+ " clauses = expr(clauses)\n",
+ "\n",
+ " try:\n",
+ " clauses = conjuncts(clauses)\n",
+ " except AttributeError:\n",
+ " pass\n",
+ "\n",
+ " return clauses\n",
+ "\n",
+ " def substitute(self, e, args):\n",
+ " """Replaces variables in expression with their respective Propositional symbol"""\n",
+ "\n",
+ " new_args = list(e.args)\n",
+ " for num, x in enumerate(e.args):\n",
+ " for i, _ in enumerate(self.args):\n",
+ " if self.args[i] == x:\n",
+ " new_args[num] = args[i]\n",
+ " return Expr(e.op, *new_args)\n",
+ "\n",
+ " def check_precond(self, kb, args):\n",
+ " """Checks if the precondition is satisfied in the current state"""\n",
+ "\n",
+ " if isinstance(kb, list):\n",
+ " kb = FolKB(kb)\n",
+ " for clause in self.precond:\n",
+ " if self.substitute(clause, args) not in kb.clauses:\n",
+ " return False\n",
+ " return True\n",
+ "\n",
+ " def act(self, kb, args):\n",
+ " """Executes the action on the state's knowledge base"""\n",
+ "\n",
+ " if isinstance(kb, list):\n",
+ " kb = FolKB(kb)\n",
+ "\n",
+ " if not self.check_precond(kb, args):\n",
+ " raise Exception('Action pre-conditions not satisfied')\n",
+ " for clause in self.effect:\n",
+ " kb.tell(self.substitute(clause, args))\n",
+ " if clause.op[:3] == 'Not':\n",
+ " new_clause = Expr(clause.op[3:], *clause.args)\n",
+ "\n",
+ " if kb.ask(self.substitute(new_clause, args)) is not False:\n",
+ " kb.retract(self.substitute(new_clause, args))\n",
+ " else:\n",
+ " new_clause = Expr('Not' + clause.op, *clause.args)\n",
+ "\n",
+ " if kb.ask(self.substitute(new_clause, args)) is not False: \n",
+ " kb.retract(self.substitute(new_clause, args))\n",
+ "\n",
+ " return kb\n",
+ "def air_cargo():\n",
+ " """\n",
+ " [Figure 10.1] AIR-CARGO-PROBLEM\n",
+ "\n",
+ " An air-cargo shipment problem for delivering cargo to different locations,\n",
+ " given the starting location and airplanes.\n",
+ "\n",
+ " Example:\n",
+ " >>> from planning import *\n",
+ " >>> ac = air_cargo()\n",
+ " >>> ac.goal_test()\n",
+ " False\n",
+ " >>> ac.act(expr('Load(C2, P2, JFK)'))\n",
+ " >>> ac.act(expr('Load(C1, P1, SFO)'))\n",
+ " >>> ac.act(expr('Fly(P1, SFO, JFK)'))\n",
+ " >>> ac.act(expr('Fly(P2, JFK, SFO)'))\n",
+ " >>> ac.act(expr('Unload(C2, P2, SFO)'))\n",
+ " >>> ac.goal_test()\n",
+ " False\n",
+ " >>> ac.act(expr('Unload(C1, P1, JFK)'))\n",
+ " >>> ac.goal_test()\n",
+ " True\n",
+ " >>>\n",
+ " """\n",
+ "\n",
+ " return PlanningProblem(init='At(C1, SFO) & At(C2, JFK) & At(P1, SFO) & At(P2, JFK) & Cargo(C1) & Cargo(C2) & Plane(P1) & Plane(P2) & Airport(SFO) & Airport(JFK)', \n",
+ " goals='At(C1, JFK) & At(C2, SFO)',\n",
+ " actions=[Action('Load(c, p, a)', \n",
+ " precond='At(c, a) & At(p, a) & Cargo(c) & Plane(p) & Airport(a)',\n",
+ " effect='In(c, p) & ~At(c, a)'),\n",
+ " Action('Unload(c, p, a)',\n",
+ " precond='In(c, p) & At(p, a) & Cargo(c) & Plane(p) & Airport(a)',\n",
+ " effect='At(c, a) & ~In(c, p)'),\n",
+ " Action('Fly(p, f, to)',\n",
+ " precond='At(p, f) & Plane(p) & Airport(f) & Airport(to)',\n",
+ " effect='At(p, to) & ~At(p, f)')])\n",
+ "def spare_tire():\n",
+ " """[Figure 10.2] SPARE-TIRE-PROBLEM\n",
+ "\n",
+ " A problem involving changing the flat tire of a car\n",
+ " with a spare tire from the trunk.\n",
+ "\n",
+ " Example:\n",
+ " >>> from planning import *\n",
+ " >>> st = spare_tire()\n",
+ " >>> st.goal_test()\n",
+ " False\n",
+ " >>> st.act(expr('Remove(Spare, Trunk)'))\n",
+ " >>> st.act(expr('Remove(Flat, Axle)'))\n",
+ " >>> st.goal_test()\n",
+ " False\n",
+ " >>> st.act(expr('PutOn(Spare, Axle)'))\n",
+ " >>> st.goal_test()\n",
+ " True\n",
+ " >>>\n",
+ " """\n",
+ "\n",
+ " return PlanningProblem(init='Tire(Flat) & Tire(Spare) & At(Flat, Axle) & At(Spare, Trunk)',\n",
+ " goals='At(Spare, Axle) & At(Flat, Ground)',\n",
+ " actions=[Action('Remove(obj, loc)',\n",
+ " precond='At(obj, loc)',\n",
+ " effect='At(obj, Ground) & ~At(obj, loc)'),\n",
+ " Action('PutOn(t, Axle)',\n",
+ " precond='Tire(t) & At(t, Ground) & ~At(Flat, Axle)',\n",
+ " effect='At(t, Axle) & ~At(t, Ground)'),\n",
+ " Action('LeaveOvernight',\n",
+ " precond='',\n",
+ " effect='~At(Spare, Ground) & ~At(Spare, Axle) & ~At(Spare, Trunk) & \\\n",
+ " ~At(Flat, Ground) & ~At(Flat, Axle) & ~At(Flat, Trunk)')])\n",
+ "def three_block_tower():\n",
+ " """\n",
+ " [Figure 10.3] THREE-BLOCK-TOWER\n",
+ "\n",
+ " A blocks-world problem of stacking three blocks in a certain configuration,\n",
+ " also known as the Sussman Anomaly.\n",
+ "\n",
+ " Example:\n",
+ " >>> from planning import *\n",
+ " >>> tbt = three_block_tower()\n",
+ " >>> tbt.goal_test()\n",
+ " False\n",
+ " >>> tbt.act(expr('MoveToTable(C, A)'))\n",
+ " >>> tbt.act(expr('Move(B, Table, C)'))\n",
+ " >>> tbt.goal_test()\n",
+ " False\n",
+ " >>> tbt.act(expr('Move(A, Table, B)'))\n",
+ " >>> tbt.goal_test()\n",
+ " True\n",
+ " >>>\n",
+ " """\n",
+ "\n",
+ " return PlanningProblem(init='On(A, Table) & On(B, Table) & On(C, A) & Block(A) & Block(B) & Block(C) & Clear(B) & Clear(C)',\n",
+ " goals='On(A, B) & On(B, C)',\n",
+ " actions=[Action('Move(b, x, y)',\n",
+ " precond='On(b, x) & Clear(b) & Clear(y) & Block(b) & Block(y)',\n",
+ " effect='On(b, y) & Clear(x) & ~On(b, x) & ~Clear(y)'),\n",
+ " Action('MoveToTable(b, x)',\n",
+ " precond='On(b, x) & Clear(b) & Block(b)',\n",
+ " effect='On(b, Table) & Clear(x) & ~On(b, x)')])\n",
+ "def simple_blocks_world():\n",
+ " """\n",
+ " SIMPLE-BLOCKS-WORLD\n",
+ "\n",
+ " A simplified definition of the Sussman Anomaly problem.\n",
+ "\n",
+ " Example:\n",
+ " >>> from planning import *\n",
+ " >>> sbw = simple_blocks_world()\n",
+ " >>> sbw.goal_test()\n",
+ " False\n",
+ " >>> sbw.act(expr('ToTable(A, B)'))\n",
+ " >>> sbw.act(expr('FromTable(B, A)'))\n",
+ " >>> sbw.goal_test()\n",
+ " False\n",
+ " >>> sbw.act(expr('FromTable(C, B)'))\n",
+ " >>> sbw.goal_test()\n",
+ " True\n",
+ " >>>\n",
+ " """\n",
+ "\n",
+ " return PlanningProblem(init='On(A, B) & Clear(A) & OnTable(B) & OnTable(C) & Clear(C)',\n",
+ " goals='On(B, A) & On(C, B)',\n",
+ " actions=[Action('ToTable(x, y)',\n",
+ " precond='On(x, y) & Clear(x)',\n",
+ " effect='~On(x, y) & Clear(y) & OnTable(x)'),\n",
+ " Action('FromTable(y, x)',\n",
+ " precond='OnTable(y) & Clear(y) & Clear(x)',\n",
+ " effect='~OnTable(y) & ~Clear(x) & On(y, x)')])\n",
+ "def shopping_problem():\n",
+ " """\n",
+ " SHOPPING-PROBLEM\n",
+ "\n",
+ " A problem of acquiring some items given their availability at certain stores.\n",
+ "\n",
+ " Example:\n",
+ " >>> from planning import *\n",
+ " >>> sp = shopping_problem()\n",
+ " >>> sp.goal_test()\n",
+ " False\n",
+ " >>> sp.act(expr('Go(Home, HW)'))\n",
+ " >>> sp.act(expr('Buy(Drill, HW)'))\n",
+ " >>> sp.act(expr('Go(HW, SM)'))\n",
+ " >>> sp.act(expr('Buy(Banana, SM)'))\n",
+ " >>> sp.goal_test()\n",
+ " False\n",
+ " >>> sp.act(expr('Buy(Milk, SM)'))\n",
+ " >>> sp.goal_test()\n",
+ " True\n",
+ " >>>\n",
+ " """\n",
+ "\n",
+ " return PlanningProblem(init='At(Home) & Sells(SM, Milk) & Sells(SM, Banana) & Sells(HW, Drill)',\n",
+ " goals='Have(Milk) & Have(Banana) & Have(Drill)', \n",
+ " actions=[Action('Buy(x, store)',\n",
+ " precond='At(store) & Sells(store, x)',\n",
+ " effect='Have(x)'),\n",
+ " Action('Go(x, y)',\n",
+ " precond='At(x)',\n",
+ " effect='At(y) & ~At(x)')])\n",
+ "def socks_and_shoes():\n",
+ " """\n",
+ " SOCKS-AND-SHOES-PROBLEM\n",
+ "\n",
+ " A task of wearing socks and shoes on both feet\n",
+ "\n",
+ " Example:\n",
+ " >>> from planning import *\n",
+ " >>> ss = socks_and_shoes()\n",
+ " >>> ss.goal_test()\n",
+ " False\n",
+ " >>> ss.act(expr('RightSock'))\n",
+ " >>> ss.act(expr('RightShoe'))\n",
+ " >>> ss.act(expr('LeftSock'))\n",
+ " >>> ss.goal_test()\n",
+ " False\n",
+ " >>> ss.act(expr('LeftShoe'))\n",
+ " >>> ss.goal_test()\n",
+ " True\n",
+ " >>>\n",
+ " """\n",
+ "\n",
+ " return PlanningProblem(init='',\n",
+ " goals='RightShoeOn & LeftShoeOn',\n",
+ " actions=[Action('RightShoe',\n",
+ " precond='RightSockOn',\n",
+ " effect='RightShoeOn'),\n",
+ " Action('RightSock',\n",
+ " precond='',\n",
+ " effect='RightSockOn'),\n",
+ " Action('LeftShoe',\n",
+ " precond='LeftSockOn',\n",
+ " effect='LeftShoeOn'),\n",
+ " Action('LeftSock',\n",
+ " precond='',\n",
+ " effect='LeftSockOn')])\n",
+ "def have_cake_and_eat_cake_too():\n",
+ " """\n",
+ " [Figure 10.7] CAKE-PROBLEM\n",
+ "\n",
+ " A problem where we begin with a cake and want to \n",
+ " reach the state of having a cake and having eaten a cake.\n",
+ " The possible actions include baking a cake and eating a cake.\n",
+ "\n",
+ " Example:\n",
+ " >>> from planning import *\n",
+ " >>> cp = have_cake_and_eat_cake_too()\n",
+ " >>> cp.goal_test()\n",
+ " False\n",
+ " >>> cp.act(expr('Eat(Cake)'))\n",
+ " >>> cp.goal_test()\n",
+ " False\n",
+ " >>> cp.act(expr('Bake(Cake)'))\n",
+ " >>> cp.goal_test()\n",
+ " True\n",
+ " >>>\n",
+ " """\n",
+ "\n",
+ " return PlanningProblem(init='Have(Cake)',\n",
+ " goals='Have(Cake) & Eaten(Cake)',\n",
+ " actions=[Action('Eat(Cake)',\n",
+ " precond='Have(Cake)',\n",
+ " effect='Eaten(Cake) & ~Have(Cake)'),\n",
+ " Action('Bake(Cake)',\n",
+ " precond='~Have(Cake)',\n",
+ " effect='Have(Cake)')])\n",
+ "class Problem(PlanningProblem):\n",
+ " """\n",
+ " Define real-world problems by aggregating resources as numerical quantities instead of\n",
+ " named entities.\n",
+ "\n",
+ " This class is identical to PDLL, except that it overloads the act function to handle\n",
+ " resource and ordering conditions imposed by HLA as opposed to Action.\n",
+ " """\n",
+ " def __init__(self, init, goals, actions, jobs=None, resources=None):\n",
+ " super().__init__(init, goals, actions)\n",
+ " self.jobs = jobs\n",
+ " self.resources = resources or {}\n",
+ "\n",
+ " def act(self, action):\n",
+ " """\n",
+ " Performs the HLA given as argument.\n",
+ "\n",
+ " Note that this is different from the superclass action - where the parameter was an\n",
+ " Expression. For real world problems, an Expr object isn't enough to capture all the\n",
+ " detail required for executing the action - resources, preconditions, etc need to be\n",
+ " checked for too.\n",
+ " """\n",
+ " args = action.args\n",
+ " list_action = first(a for a in self.actions if a.name == action.name)\n",
+ " if list_action is None:\n",
+ " raise Exception("Action '{}' not found".format(action.name))\n",
+ " self.init = list_action.do_action(self.jobs, self.resources, self.init, args).clauses\n",
+ "\n",
+ " def refinements(hla, state, library): # refinements may be (multiple) HLA themselves ...\n",
+ " """\n",
+ " state is a Problem, containing the current state kb\n",
+ " library is a dictionary containing details for every possible refinement. eg:\n",
+ " {\n",
+ " 'HLA': [\n",
+ " 'Go(Home, SFO)',\n",
+ " 'Go(Home, SFO)',\n",
+ " 'Drive(Home, SFOLongTermParking)',\n",
+ " 'Shuttle(SFOLongTermParking, SFO)',\n",
+ " 'Taxi(Home, SFO)'\n",
+ " ],\n",
+ " 'steps': [\n",
+ " ['Drive(Home, SFOLongTermParking)', 'Shuttle(SFOLongTermParking, SFO)'],\n",
+ " ['Taxi(Home, SFO)'],\n",
+ " [],\n",
+ " [],\n",
+ " []\n",
+ " ],\n",
+ " # empty refinements indicate a primitive action\n",
+ " 'precond': [\n",
+ " ['At(Home) & Have(Car)'],\n",
+ " ['At(Home)'],\n",
+ " ['At(Home) & Have(Car)'],\n",
+ " ['At(SFOLongTermParking)'],\n",
+ " ['At(Home)']\n",
+ " ],\n",
+ " 'effect': [\n",
+ " ['At(SFO) & ~At(Home)'],\n",
+ " ['At(SFO) & ~At(Home)'],\n",
+ " ['At(SFOLongTermParking) & ~At(Home)'],\n",
+ " ['At(SFO) & ~At(SFOLongTermParking)'],\n",
+ " ['At(SFO) & ~At(Home)']\n",
+ " ]\n",
+ " }\n",
+ " """\n",
+ " e = Expr(hla.name, hla.args)\n",
+ " indices = [i for i, x in enumerate(library['HLA']) if expr(x).op == hla.name]\n",
+ " for i in indices:\n",
+ " actions = []\n",
+ " for j in range(len(library['steps'][i])):\n",
+ " # find the index of the step [j] of the HLA \n",
+ " index_step = [k for k,x in enumerate(library['HLA']) if x == library['steps'][i][j]][0]\n",
+ " precond = library['precond'][index_step][0] # preconditions of step [j]\n",
+ " effect = library['effect'][index_step][0] # effect of step [j]\n",
+ " actions.append(HLA(library['steps'][i][j], precond, effect))\n",
+ " yield actions\n",
+ "\n",
+ " def hierarchical_search(problem, hierarchy):\n",
+ " """\n",
+ " [Figure 11.5] 'Hierarchical Search, a Breadth First Search implementation of Hierarchical\n",
+ " Forward Planning Search'\n",
+ " The problem is a real-world problem defined by the problem class, and the hierarchy is\n",
+ " a dictionary of HLA - refinements (see refinements generator for details)\n",
+ " """\n",
+ " act = Node(problem.actions[0])\n",
+ " frontier = deque()\n",
+ " frontier.append(act)\n",
+ " while True:\n",
+ " if not frontier:\n",
+ " return None\n",
+ " plan = frontier.popleft()\n",
+ " print(plan.state.name)\n",
+ " hla = plan.state # first_or_null(plan)\n",
+ " prefix = None\n",
+ " if plan.parent:\n",
+ " prefix = plan.parent.state.action # prefix, suffix = subseq(plan.state, hla)\n",
+ " outcome = Problem.result(problem, prefix)\n",
+ " if hla is None:\n",
+ " if outcome.goal_test():\n",
+ " return plan.path()\n",
+ " else:\n",
+ " print("else")\n",
+ " for sequence in Problem.refinements(hla, outcome, hierarchy):\n",
+ " print("...")\n",
+ " frontier.append(Node(plan.state, plan.parent, sequence))\n",
+ "\n",
+ " def result(state, actions):\n",
+ " """The outcome of applying an action to the current problem"""\n",
+ " for a in actions: \n",
+ " if a.check_precond(state, a.args):\n",
+ " state = a(state, a.args).clauses\n",
+ " return state\n",
+ " \n",
+ "\n",
+ " def angelic_search(problem, hierarchy, initialPlan):\n",
+ " """\n",
+ "\t[Figure 11.8] A hierarchical planning algorithm that uses angelic semantics to identify and\n",
+ "\tcommit to high-level plans that work while avoiding high-level plans that don’t. \n",
+ "\tThe predicate MAKING-PROGRESS checks to make sure that we aren’t stuck in an infinite regression\n",
+ "\tof refinements. \n",
+ "\tAt top level, call ANGELIC -SEARCH with [Act ] as the initialPlan .\n",
+ "\n",
+ " initialPlan contains a sequence of HLA's with angelic semantics \n",
+ "\n",
+ " The possible effects of an angelic HLA in initialPlan are : \n",
+ " ~ : effect remove\n",
+ " $+: effect possibly add\n",
+ " $-: effect possibly remove\n",
+ " $$: possibly add or remove\n",
+ "\t"""\n",
+ " frontier = deque(initialPlan)\n",
+ " while True: \n",
+ " if not frontier:\n",
+ " return None\n",
+ " plan = frontier.popleft() # sequence of HLA/Angelic HLA's \n",
+ " opt_reachable_set = Problem.reach_opt(problem.init, plan)\n",
+ " pes_reachable_set = Problem.reach_pes(problem.init, plan)\n",
+ " if problem.intersects_goal(opt_reachable_set): \n",
+ " if Problem.is_primitive( plan, hierarchy ): \n",
+ " return ([x for x in plan.action])\n",
+ " guaranteed = problem.intersects_goal(pes_reachable_set) \n",
+ " if guaranteed and Problem.making_progress(plan, plan):\n",
+ " final_state = guaranteed[0] # any element of guaranteed \n",
+ " #print('decompose')\n",
+ " return Problem.decompose(hierarchy, problem, plan, final_state, pes_reachable_set)\n",
+ " (hla, index) = Problem.find_hla(plan, hierarchy) # there should be at least one HLA/Angelic_HLA, otherwise plan would be primitive.\n",
+ " prefix = plan.action[:index-1]\n",
+ " suffix = plan.action[index+1:]\n",
+ " outcome = Problem(Problem.result(problem.init, prefix), problem.goals , problem.actions )\n",
+ " for sequence in Problem.refinements(hla, outcome, hierarchy): # find refinements\n",
+ " frontier.append(Angelic_Node(outcome.init, plan, prefix + sequence+ suffix, prefix+sequence+suffix))\n",
+ "\n",
+ "\n",
+ " def intersects_goal(problem, reachable_set):\n",
+ " """\n",
+ " Find the intersection of the reachable states and the goal\n",
+ " """\n",
+ " return [y for x in list(reachable_set.keys()) for y in reachable_set[x] if all(goal in y for goal in problem.goals)] \n",
+ "\n",
+ "\n",
+ " def is_primitive(plan, library):\n",
+ " """\n",
+ " checks if the hla is primitive action \n",
+ " """\n",
+ " for hla in plan.action: \n",
+ " indices = [i for i, x in enumerate(library['HLA']) if expr(x).op == hla.name]\n",
+ " for i in indices:\n",
+ " if library["steps"][i]: \n",
+ " return False\n",
+ " return True\n",
+ " \n",
+ "\n",
+ "\n",
+ " def reach_opt(init, plan): \n",
+ " """\n",
+ " Finds the optimistic reachable set of the sequence of actions in plan \n",
+ " """\n",
+ " reachable_set = {0: [init]}\n",
+ " optimistic_description = plan.action #list of angelic actions with optimistic description\n",
+ " return Problem.find_reachable_set(reachable_set, optimistic_description)\n",
+ " \n",
+ "\n",
+ " def reach_pes(init, plan): \n",
+ " """ \n",
+ " Finds the pessimistic reachable set of the sequence of actions in plan\n",
+ " """\n",
+ " reachable_set = {0: [init]}\n",
+ " pessimistic_description = plan.action_pes # list of angelic actions with pessimistic description\n",
+ " return Problem.find_reachable_set(reachable_set, pessimistic_description)\n",
+ "\n",
+ " def find_reachable_set(reachable_set, action_description):\n",
+ " """\n",
+ "\tFinds the reachable states of the action_description when applied in each state of reachable set.\n",
+ "\t"""\n",
+ " for i in range(len(action_description)):\n",
+ " reachable_set[i+1]=[]\n",
+ " if type(action_description[i]) is Angelic_HLA:\n",
+ " possible_actions = action_description[i].angelic_action()\n",
+ " else: \n",
+ " possible_actions = action_description\n",
+ " for action in possible_actions:\n",
+ " for state in reachable_set[i]:\n",
+ " if action.check_precond(state , action.args) :\n",
+ " if action.effect[0] :\n",
+ " new_state = action(state, action.args).clauses\n",
+ " reachable_set[i+1].append(new_state)\n",
+ " else: \n",
+ " reachable_set[i+1].append(state)\n",
+ " return reachable_set\n",
+ "\n",
+ " def find_hla(plan, hierarchy):\n",
+ " """\n",
+ " Finds the the first HLA action in plan.action, which is not primitive\n",
+ " and its corresponding index in plan.action\n",
+ " """\n",
+ " hla = None\n",
+ " index = len(plan.action)\n",
+ " for i in range(len(plan.action)): # find the first HLA in plan, that is not primitive\n",
+ " if not Problem.is_primitive(Node(plan.state, plan.parent, [plan.action[i]]), hierarchy):\n",
+ " hla = plan.action[i] \n",
+ " index = i\n",
+ " break\n",
+ " return (hla, index)\n",
+ "\t\n",
+ " def making_progress(plan, initialPlan):\n",
+ " """ \n",
+ " Not correct\n",
+ "\n",
+ " Normally should from infinite regression of refinements \n",
+ " \n",
+ " Only case covered: when plan contains one action (then there is no regression to be done) \n",
+ " """\n",
+ " if (len(plan.action)==1):\n",
+ " return False\n",
+ " return True \n",
+ "\n",
+ " def decompose(hierarchy, s_0, plan, s_f, reachable_set):\n",
+ " solution = [] \n",
+ " while plan.action_pes: \n",
+ " action = plan.action_pes.pop()\n",
+ " i = max(reachable_set.keys())\n",
+ " if (i==0): \n",
+ " return solution\n",
+ " s_i = Problem.find_previous_state(s_f, reachable_set,i, action) \n",
+ " problem = Problem(s_i, s_f , plan.action)\n",
+ " j=0\n",
+ " for x in Problem.angelic_search(problem, hierarchy, [Angelic_Node(s_i, Node(None), [action],[action])]):\n",
+ " solution.insert(j,x)\n",
+ " j+=1\n",
+ " s_f = s_i\n",
+ " return solution\n",
+ "\n",
+ "\n",
+ " def find_previous_state(s_f, reachable_set, i, action):\n",
+ " """\n",
+ " Given a final state s_f and an action finds a state s_i in reachable_set \n",
+ " such that when action is applied to state s_i returns s_f. \n",
+ " """\n",
+ " s_i = reachable_set[i-1][0]\n",
+ " for state in reachable_set[i-1]:\n",
+ " if s_f in [x for x in Problem.reach_pes(state, Angelic_Node(state, None, [action],[action]))[1]]:\n",
+ " s_i =state\n",
+ " break\n",
+ " return s_i\n",
+ "class HLA(Action):\n",
+ " """\n",
+ " Define Actions for the real-world (that may be refined further), and satisfy resource\n",
+ " constraints.\n",
+ " """\n",
+ " unique_group = 1\n",
+ "\n",
+ " def __init__(self, action, precond=None, effect=None, duration=0,\n",
+ " consume=None, use=None):\n",
+ " """\n",
+ " As opposed to actions, to define HLA, we have added constraints.\n",
+ " duration holds the amount of time required to execute the task\n",
+ " consumes holds a dictionary representing the resources the task consumes\n",
+ " uses holds a dictionary representing the resources the task uses\n",
+ " """\n",
+ " precond = precond or [None]\n",
+ " effect = effect or [None]\n",
+ " super().__init__(action, precond, effect)\n",
+ " self.duration = duration\n",
+ " self.consumes = consume or {}\n",
+ " self.uses = use or {}\n",
+ " self.completed = False\n",
+ " # self.priority = -1 # must be assigned in relation to other HLAs\n",
+ " # self.job_group = -1 # must be assigned in relation to other HLAs\n",
+ "\n",
+ " def do_action(self, job_order, available_resources, kb, args):\n",
+ " """\n",
+ " An HLA based version of act - along with knowledge base updation, it handles\n",
+ " resource checks, and ensures the actions are executed in the correct order.\n",
+ " """\n",
+ " # print(self.name)\n",
+ " if not self.has_usable_resource(available_resources):\n",
+ " raise Exception('Not enough usable resources to execute {}'.format(self.name))\n",
+ " if not self.has_consumable_resource(available_resources):\n",
+ " raise Exception('Not enough consumable resources to execute {}'.format(self.name))\n",
+ " if not self.inorder(job_order):\n",
+ " raise Exception("Can't execute {} - execute prerequisite actions first".\n",
+ " format(self.name))\n",
+ " kb = super().act(kb, args) # update knowledge base\n",
+ " for resource in self.consumes: # remove consumed resources\n",
+ " available_resources[resource] -= self.consumes[resource]\n",
+ " self.completed = True # set the task status to complete\n",
+ " return kb\n",
+ "\n",
+ " def has_consumable_resource(self, available_resources):\n",
+ " """\n",
+ " Ensure there are enough consumable resources for this action to execute.\n",
+ " """\n",
+ " for resource in self.consumes:\n",
+ " if available_resources.get(resource) is None:\n",
+ " return False\n",
+ " if available_resources[resource] < self.consumes[resource]:\n",
+ " return False\n",
+ " return True\n",
+ "\n",
+ " def has_usable_resource(self, available_resources):\n",
+ " """\n",
+ " Ensure there are enough usable resources for this action to execute.\n",
+ " """\n",
+ " for resource in self.uses:\n",
+ " if available_resources.get(resource) is None:\n",
+ " return False\n",
+ " if available_resources[resource] < self.uses[resource]:\n",
+ " return False\n",
+ " return True\n",
+ "\n",
+ " def inorder(self, job_order):\n",
+ " """\n",
+ " Ensure that all the jobs that had to be executed before the current one have been\n",
+ " successfully executed.\n",
+ " """\n",
+ " for jobs in job_order:\n",
+ " if self in jobs:\n",
+ " for job in jobs:\n",
+ " if job is self:\n",
+ " return True\n",
+ " if not job.completed:\n",
+ " return False\n",
+ " return True\n",
+ "def job_shop_problem():\n",
+ " """\n",
+ " [Figure 11.1] JOB-SHOP-PROBLEM\n",
+ "\n",
+ " A job-shop scheduling problem for assembling two cars,\n",
+ " with resource and ordering constraints.\n",
+ "\n",
+ " Example:\n",
+ " >>> from planning import *\n",
+ " >>> p = job_shop_problem()\n",
+ " >>> p.goal_test()\n",
+ " False\n",
+ " >>> p.act(p.jobs[1][0])\n",
+ " >>> p.act(p.jobs[1][1])\n",
+ " >>> p.act(p.jobs[1][2])\n",
+ " >>> p.act(p.jobs[0][0])\n",
+ " >>> p.act(p.jobs[0][1])\n",
+ " >>> p.goal_test()\n",
+ " False\n",
+ " >>> p.act(p.jobs[0][2])\n",
+ " >>> p.goal_test()\n",
+ " True\n",
+ " >>>\n",
+ " """\n",
+ " resources = {'EngineHoists': 1, 'WheelStations': 2, 'Inspectors': 2, 'LugNuts': 500}\n",
+ "\n",
+ " add_engine1 = HLA('AddEngine1', precond='~Has(C1, E1)', effect='Has(C1, E1)', duration=30, use={'EngineHoists': 1})\n",
+ " add_engine2 = HLA('AddEngine2', precond='~Has(C2, E2)', effect='Has(C2, E2)', duration=60, use={'EngineHoists': 1})\n",
+ " add_wheels1 = HLA('AddWheels1', precond='~Has(C1, W1)', effect='Has(C1, W1)', duration=30, use={'WheelStations': 1}, consume={'LugNuts': 20})\n",
+ " add_wheels2 = HLA('AddWheels2', precond='~Has(C2, W2)', effect='Has(C2, W2)', duration=15, use={'WheelStations': 1}, consume={'LugNuts': 20})\n",
+ " inspect1 = HLA('Inspect1', precond='~Inspected(C1)', effect='Inspected(C1)', duration=10, use={'Inspectors': 1})\n",
+ " inspect2 = HLA('Inspect2', precond='~Inspected(C2)', effect='Inspected(C2)', duration=10, use={'Inspectors': 1})\n",
+ "\n",
+ " actions = [add_engine1, add_engine2, add_wheels1, add_wheels2, inspect1, inspect2]\n",
+ "\n",
+ " job_group1 = [add_engine1, add_wheels1, inspect1]\n",
+ " job_group2 = [add_engine2, add_wheels2, inspect2]\n",
+ "\n",
+ " return Problem(init='Car(C1) & Car(C2) & Wheels(W1) & Wheels(W2) & Engine(E2) & Engine(E2) & ~Has(C1, E1) & ~Has(C2, E2) & ~Has(C1, W1) & ~Has(C2, W2) & ~Inspected(C1) & ~Inspected(C2)',\n",
+ " goals='Has(C1, W1) & Has(C1, E1) & Inspected(C1) & Has(C2, W2) & Has(C2, E2) & Inspected(C2)',\n",
+ " actions=actions,\n",
+ " jobs=[job_group1, job_group2],\n",
+ " resources=resources)\n",
+ "def double_tennis_problem():\n",
+ " """\n",
+ " [Figure 11.10] DOUBLE-TENNIS-PROBLEM\n",
+ "\n",
+ " A multiagent planning problem involving two partner tennis players\n",
+ " trying to return an approaching ball and repositioning around in the court.\n",
+ "\n",
+ " Example:\n",
+ " >>> from planning import *\n",
+ " >>> dtp = double_tennis_problem()\n",
+ " >>> goal_test(dtp.goals, dtp.init)\n",
+ " False\n",
+ " >>> dtp.act(expr('Go(A, RightBaseLine, LeftBaseLine)'))\n",
+ " >>> dtp.act(expr('Hit(A, Ball, RightBaseLine)'))\n",
+ " >>> goal_test(dtp.goals, dtp.init)\n",
+ " False\n",
+ " >>> dtp.act(expr('Go(A, LeftNet, RightBaseLine)'))\n",
+ " >>> goal_test(dtp.goals, dtp.init)\n",
+ " True\n",
+ " >>>\n",
+ " """\n",
+ "\n",
+ " return PlanningProblem(init='At(A, LeftBaseLine) & At(B, RightNet) & Approaching(Ball, RightBaseLine) & Partner(A, B) & Partner(B, A)',\n",
+ " goals='Returned(Ball) & At(a, LeftNet) & At(a, RightNet)',\n",
+ " actions=[Action('Hit(actor, Ball, loc)',\n",
+ " precond='Approaching(Ball, loc) & At(actor, loc)',\n",
+ " effect='Returned(Ball)'),\n",
+ " Action('Go(actor, to, loc)', \n",
+ " precond='At(actor, loc)',\n",
+ " effect='At(actor, to) & ~At(actor, loc)')])\n",
+ " def angelic_search(problem, hierarchy, initialPlan):\n",
+ " """\n",
+ "\t[Figure 11.8] A hierarchical planning algorithm that uses angelic semantics to identify and\n",
+ "\tcommit to high-level plans that work while avoiding high-level plans that don’t. \n",
+ "\tThe predicate MAKING-PROGRESS checks to make sure that we aren’t stuck in an infinite regression\n",
+ "\tof refinements. \n",
+ "\tAt top level, call ANGELIC -SEARCH with [Act ] as the initialPlan .\n",
+ "\n",
+ " initialPlan contains a sequence of HLA's with angelic semantics \n",
+ "\n",
+ " The possible effects of an angelic HLA in initialPlan are : \n",
+ " ~ : effect remove\n",
+ " $+: effect possibly add\n",
+ " $-: effect possibly remove\n",
+ " $$: possibly add or remove\n",
+ "\t"""\n",
+ " frontier = deque(initialPlan)\n",
+ " while True: \n",
+ " if not frontier:\n",
+ " return None\n",
+ " plan = frontier.popleft() # sequence of HLA/Angelic HLA's \n",
+ " opt_reachable_set = Problem.reach_opt(problem.init, plan)\n",
+ " pes_reachable_set = Problem.reach_pes(problem.init, plan)\n",
+ " if problem.intersects_goal(opt_reachable_set): \n",
+ " if Problem.is_primitive( plan, hierarchy ): \n",
+ " return ([x for x in plan.action])\n",
+ " guaranteed = problem.intersects_goal(pes_reachable_set) \n",
+ " if guaranteed and Problem.making_progress(plan, initialPlan):\n",
+ " final_state = guaranteed[0] # any element of guaranteed \n",
+ " #print('decompose')\n",
+ " return Problem.decompose(hierarchy, problem, plan, final_state, pes_reachable_set)\n",
+ " (hla, index) = Problem.find_hla(plan, hierarchy) # there should be at least one HLA/Angelic_HLA, otherwise plan would be primitive.\n",
+ " prefix = plan.action[:index]\n",
+ " suffix = plan.action[index+1:]\n",
+ " outcome = Problem(Problem.result(problem.init, prefix), problem.goals , problem.actions )\n",
+ " for sequence in Problem.refinements(hla, outcome, hierarchy): # find refinements\n",
+ " frontier.append(Angelic_Node(outcome.init, plan, prefix + sequence+ suffix, prefix+sequence+suffix))\n",
+ " def decompose(hierarchy, s_0, plan, s_f, reachable_set):\n",
+ " solution = [] \n",
+ " i = max(reachable_set.keys())\n",
+ " while plan.action_pes: \n",
+ " action = plan.action_pes.pop()\n",
+ " if (i==0): \n",
+ " return solution\n",
+ " s_i = Problem.find_previous_state(s_f, reachable_set,i, action) \n",
+ " problem = Problem(s_i, s_f , plan.action)\n",
+ " angelic_call = Problem.angelic_search(problem, hierarchy, [Angelic_Node(s_i, Node(None), [action],[action])])\n",
+ " if angelic_call:\n",
+ " for x in angelic_call: \n",
+ " solution.insert(0,x)\n",
+ " else: \n",
+ " return None\n",
+ " s_f = s_i\n",
+ " i-=1\n",
+ " return solution\n",
+ "class Level:\n",
+ " """\n",
+ " Contains the state of the planning problem\n",
+ " and exhaustive list of actions which use the\n",
+ " states as pre-condition.\n",
+ " """\n",
+ "\n",
+ " def __init__(self, kb):\n",
+ " """Initializes variables to hold state and action details of a level"""\n",
+ "\n",
+ " self.kb = kb\n",
+ " # current state\n",
+ " self.current_state = kb.clauses\n",
+ " # current action to state link\n",
+ " self.current_action_links = {}\n",
+ " # current state to action link\n",
+ " self.current_state_links = {}\n",
+ " # current action to next state link\n",
+ " self.next_action_links = {}\n",
+ " # next state to current action link\n",
+ " self.next_state_links = {}\n",
+ " # mutually exclusive actions\n",
+ " self.mutex = []\n",
+ "\n",
+ " def __call__(self, actions, objects):\n",
+ " self.build(actions, objects)\n",
+ " self.find_mutex()\n",
+ "\n",
+ " def separate(self, e):\n",
+ " """Separates an iterable of elements into positive and negative parts"""\n",
+ "\n",
+ " positive = []\n",
+ " negative = []\n",
+ " for clause in e:\n",
+ " if clause.op[:3] == 'Not':\n",
+ " negative.append(clause)\n",
+ " else:\n",
+ " positive.append(clause)\n",
+ " return positive, negative\n",
+ "\n",
+ " def find_mutex(self):\n",
+ " """Finds mutually exclusive actions"""\n",
+ "\n",
+ " # Inconsistent effects\n",
+ " pos_nsl, neg_nsl = self.separate(self.next_state_links)\n",
+ "\n",
+ " for negeff in neg_nsl:\n",
+ " new_negeff = Expr(negeff.op[3:], *negeff.args)\n",
+ " for poseff in pos_nsl:\n",
+ " if new_negeff == poseff:\n",
+ " for a in self.next_state_links[poseff]:\n",
+ " for b in self.next_state_links[negeff]:\n",
+ " if {a, b} not in self.mutex:\n",
+ " self.mutex.append({a, b})\n",
+ "\n",
+ " # Interference will be calculated with the last step\n",
+ " pos_csl, neg_csl = self.separate(self.current_state_links)\n",
+ "\n",
+ " # Competing needs\n",
+ " for posprecond in pos_csl:\n",
+ " for negprecond in neg_csl:\n",
+ " new_negprecond = Expr(negprecond.op[3:], *negprecond.args)\n",
+ " if new_negprecond == posprecond:\n",
+ " for a in self.current_state_links[posprecond]:\n",
+ " for b in self.current_state_links[negprecond]:\n",
+ " if {a, b} not in self.mutex:\n",
+ " self.mutex.append({a, b})\n",
+ "\n",
+ " # Inconsistent support\n",
+ " state_mutex = []\n",
+ " for pair in self.mutex:\n",
+ " next_state_0 = self.next_action_links[list(pair)[0]]\n",
+ " if len(pair) == 2:\n",
+ " next_state_1 = self.next_action_links[list(pair)[1]]\n",
+ " else:\n",
+ " next_state_1 = self.next_action_links[list(pair)[0]]\n",
+ " if (len(next_state_0) == 1) and (len(next_state_1) == 1):\n",
+ " state_mutex.append({next_state_0[0], next_state_1[0]})\n",
+ " \n",
+ " self.mutex = self.mutex + state_mutex\n",
+ "\n",
+ " def build(self, actions, objects):\n",
+ " """Populates the lists and dictionaries containing the state action dependencies"""\n",
+ "\n",
+ " for clause in self.current_state:\n",
+ " p_expr = Expr('P' + clause.op, *clause.args)\n",
+ " self.current_action_links[p_expr] = [clause]\n",
+ " self.next_action_links[p_expr] = [clause]\n",
+ " self.current_state_links[clause] = [p_expr]\n",
+ " self.next_state_links[clause] = [p_expr]\n",
+ "\n",
+ " for a in actions:\n",
+ " num_args = len(a.args)\n",
+ " possible_args = tuple(itertools.permutations(objects, num_args))\n",
+ "\n",
+ " for arg in possible_args:\n",
+ " if a.check_precond(self.kb, arg):\n",
+ " for num, symbol in enumerate(a.args):\n",
+ " if not symbol.op.islower():\n",
+ " arg = list(arg)\n",
+ " arg[num] = symbol\n",
+ " arg = tuple(arg)\n",
+ "\n",
+ " new_action = a.substitute(Expr(a.name, *a.args), arg)\n",
+ " self.current_action_links[new_action] = []\n",
+ "\n",
+ " for clause in a.precond:\n",
+ " new_clause = a.substitute(clause, arg)\n",
+ " self.current_action_links[new_action].append(new_clause)\n",
+ " if new_clause in self.current_state_links:\n",
+ " self.current_state_links[new_clause].append(new_action)\n",
+ " else:\n",
+ " self.current_state_links[new_clause] = [new_action]\n",
+ " \n",
+ " self.next_action_links[new_action] = []\n",
+ " for clause in a.effect:\n",
+ " new_clause = a.substitute(clause, arg)\n",
+ "\n",
+ " self.next_action_links[new_action].append(new_clause)\n",
+ " if new_clause in self.next_state_links:\n",
+ " self.next_state_links[new_clause].append(new_action)\n",
+ " else:\n",
+ " self.next_state_links[new_clause] = [new_action]\n",
+ "\n",
+ " def perform_actions(self):\n",
+ " """Performs the necessary actions and returns a new Level"""\n",
+ "\n",
+ " new_kb = FolKB(list(set(self.next_state_links.keys())))\n",
+ " return Level(new_kb)\n",
+ "class Graph:\n",
+ " """\n",
+ " Contains levels of state and actions\n",
+ " Used in graph planning algorithm to extract a solution\n",
+ " """\n",
+ "\n",
+ " def __init__(self, planningproblem):\n",
+ " self.planningproblem = planningproblem\n",
+ " self.kb = FolKB(planningproblem.init)\n",
+ " self.levels = [Level(self.kb)]\n",
+ " self.objects = set(arg for clause in self.kb.clauses for arg in clause.args)\n",
+ "\n",
+ " def __call__(self):\n",
+ " self.expand_graph()\n",
+ "\n",
+ " def expand_graph(self):\n",
+ " """Expands the graph by a level"""\n",
+ "\n",
+ " last_level = self.levels[-1]\n",
+ " last_level(self.planningproblem.actions, self.objects)\n",
+ " self.levels.append(last_level.perform_actions())\n",
+ "\n",
+ " def non_mutex_goals(self, goals, index):\n",
+ " """Checks whether the goals are mutually exclusive"""\n",
+ "\n",
+ " goal_perm = itertools.combinations(goals, 2)\n",
+ " for g in goal_perm:\n",
+ " if set(g) in self.levels[index].mutex:\n",
+ " return False\n",
+ " return True\n",
+ "class GraphPlan:\n",
+ " """\n",
+ " Class for formulation GraphPlan algorithm\n",
+ " Constructs a graph of state and action space\n",
+ " Returns solution for the planning problem\n",
+ " """\n",
+ "\n",
+ " def __init__(self, planningproblem):\n",
+ " self.graph = Graph(planningproblem)\n",
+ " self.nogoods = []\n",
+ " self.solution = []\n",
+ "\n",
+ " def check_leveloff(self):\n",
+ " """Checks if the graph has levelled off"""\n",
+ "\n",
+ " check = (set(self.graph.levels[-1].current_state) == set(self.graph.levels[-2].current_state))\n",
+ "\n",
+ " if check:\n",
+ " return True\n",
+ "\n",
+ " def extract_solution(self, goals, index):\n",
+ " """Extracts the solution"""\n",
+ "\n",
+ " level = self.graph.levels[index] \n",
+ " if not self.graph.non_mutex_goals(goals, index):\n",
+ " self.nogoods.append((level, goals))\n",
+ " return\n",
+ "\n",
+ " level = self.graph.levels[index - 1] \n",
+ "\n",
+ " # Create all combinations of actions that satisfy the goal \n",
+ " actions = []\n",
+ " for goal in goals:\n",
+ " actions.append(level.next_state_links[goal]) \n",
+ "\n",
+ " all_actions = list(itertools.product(*actions)) \n",
+ "\n",
+ " # Filter out non-mutex actions\n",
+ " non_mutex_actions = [] \n",
+ " for action_tuple in all_actions:\n",
+ " action_pairs = itertools.combinations(list(set(action_tuple)), 2) \n",
+ " non_mutex_actions.append(list(set(action_tuple))) \n",
+ " for pair in action_pairs: \n",
+ " if set(pair) in level.mutex:\n",
+ " non_mutex_actions.pop(-1)\n",
+ " break\n",
+ " \n",
+ "\n",
+ " # Recursion\n",
+ " for action_list in non_mutex_actions: \n",
+ " if [action_list, index] not in self.solution:\n",
+ " self.solution.append([action_list, index])\n",
+ "\n",
+ " new_goals = []\n",
+ " for act in set(action_list): \n",
+ " if act in level.current_action_links:\n",
+ " new_goals = new_goals + level.current_action_links[act]\n",
+ "\n",
+ " if abs(index) + 1 == len(self.graph.levels):\n",
+ " return\n",
+ " elif (level, new_goals) in self.nogoods:\n",
+ " return\n",
+ " else:\n",
+ " self.extract_solution(new_goals, index - 1)\n",
+ "\n",
+ " # Level-Order multiple solutions\n",
+ " solution = []\n",
+ " for item in self.solution:\n",
+ " if item[1] == -1:\n",
+ " solution.append([])\n",
+ " solution[-1].append(item[0])\n",
+ " else:\n",
+ " solution[-1].append(item[0])\n",
+ "\n",
+ " for num, item in enumerate(solution):\n",
+ " item.reverse()\n",
+ " solution[num] = item\n",
+ "\n",
+ " return solution\n",
+ "\n",
+ " def goal_test(self, kb):\n",
+ " return all(kb.ask(q) is not False for q in self.graph.planningproblem.goals)\n",
+ "\n",
+ " def execute(self):\n",
+ " """Executes the GraphPlan algorithm for the given problem"""\n",
+ "\n",
+ " while True:\n",
+ " self.graph.expand_graph()\n",
+ " if (self.goal_test(self.graph.levels[-1].kb) and self.graph.non_mutex_goals(self.graph.planningproblem.goals, -1)):\n",
+ " solution = self.extract_solution(self.graph.planningproblem.goals, -1)\n",
+ " if solution:\n",
+ " return solution\n",
+ " \n",
+ " if len(self.graph.levels) >= 2 and self.check_leveloff():\n",
+ " return None\n",
+ "def air_cargo_graphplan():\n",
+ " """Solves the air cargo problem using GraphPlan"""\n",
+ " return GraphPlan(air_cargo()).execute()\n",
+ " def refinements(hla, state, library): # refinements may be (multiple) HLA themselves ...\n",
+ " """\n",
+ " state is a Problem, containing the current state kb\n",
+ " library is a dictionary containing details for every possible refinement. eg:\n",
+ " {\n",
+ " 'HLA': [\n",
+ " 'Go(Home, SFO)',\n",
+ " 'Go(Home, SFO)',\n",
+ " 'Drive(Home, SFOLongTermParking)',\n",
+ " 'Shuttle(SFOLongTermParking, SFO)',\n",
+ " 'Taxi(Home, SFO)'\n",
+ " ],\n",
+ " 'steps': [\n",
+ " ['Drive(Home, SFOLongTermParking)', 'Shuttle(SFOLongTermParking, SFO)'],\n",
+ " ['Taxi(Home, SFO)'],\n",
+ " [],\n",
+ " [],\n",
+ " []\n",
+ " ],\n",
+ " # empty refinements indicate a primitive action\n",
+ " 'precond': [\n",
+ " ['At(Home) & Have(Car)'],\n",
+ " ['At(Home)'],\n",
+ " ['At(Home) & Have(Car)'],\n",
+ " ['At(SFOLongTermParking)'],\n",
+ " ['At(Home)']\n",
+ " ],\n",
+ " 'effect': [\n",
+ " ['At(SFO) & ~At(Home)'],\n",
+ " ['At(SFO) & ~At(Home)'],\n",
+ " ['At(SFOLongTermParking) & ~At(Home)'],\n",
+ " ['At(SFO) & ~At(SFOLongTermParking)'],\n",
+ " ['At(SFO) & ~At(Home)']\n",
+ " ]\n",
+ " }\n",
+ " """\n",
+ " e = Expr(hla.name, hla.args)\n",
+ " indices = [i for i, x in enumerate(library['HLA']) if expr(x).op == hla.name]\n",
+ " for i in indices:\n",
+ " actions = []\n",
+ " for j in range(len(library['steps'][i])):\n",
+ " # find the index of the step [j] of the HLA \n",
+ " index_step = [k for k,x in enumerate(library['HLA']) if x == library['steps'][i][j]][0]\n",
+ " precond = library['precond'][index_step][0] # preconditions of step [j]\n",
+ " effect = library['effect'][index_step][0] # effect of step [j]\n",
+ " actions.append(HLA(library['steps'][i][j], precond, effect))\n",
+ " yield actions\n",
+ " def hierarchical_search(problem, hierarchy):\n",
+ " """\n",
+ " [Figure 11.5] 'Hierarchical Search, a Breadth First Search implementation of Hierarchical\n",
+ " Forward Planning Search'\n",
+ " The problem is a real-world problem defined by the problem class, and the hierarchy is\n",
+ " a dictionary of HLA - refinements (see refinements generator for details)\n",
+ " """\n",
+ " act = Node(problem.init, None, [problem.actions[0]])\n",
+ " frontier = deque()\n",
+ " frontier.append(act)\n",
+ " while True:\n",
+ " if not frontier:\n",
+ " return None\n",
+ " plan = frontier.popleft()\n",
+ " (hla, index) = Problem.find_hla(plan, hierarchy) # finds the first non primitive hla in plan actions\n",
+ " prefix = plan.action[:index]\n",
+ " outcome = Problem(Problem.result(problem.init, prefix), problem.goals , problem.actions )\n",
+ " suffix = plan.action[index+1:]\n",
+ " if not hla: # hla is None and plan is primitive\n",
+ " if outcome.goal_test():\n",
+ " return plan.action\n",
+ " else:\n",
+ " for sequence in Problem.refinements(hla, outcome, hierarchy): # find refinements\n",
+ " frontier.append(Node(outcome.init, plan, prefix + sequence+ suffix))\n",
+ "class PartialOrderPlanner:\n",
+ "\n",
+ " def __init__(self, planningproblem):\n",
+ " self.planningproblem = planningproblem\n",
+ " self.initialize()\n",
+ "\n",
+ " def initialize(self):\n",
+ " """Initialize all variables"""\n",
+ " self.causal_links = []\n",
+ " self.start = Action('Start', [], self.planningproblem.init)\n",
+ " self.finish = Action('Finish', self.planningproblem.goals, [])\n",
+ " self.actions = set()\n",
+ " self.actions.add(self.start)\n",
+ " self.actions.add(self.finish)\n",
+ " self.constraints = set()\n",
+ " self.constraints.add((self.start, self.finish))\n",
+ " self.agenda = set()\n",
+ " for precond in self.finish.precond:\n",
+ " self.agenda.add((precond, self.finish))\n",
+ " self.expanded_actions = self.expand_actions()\n",
+ "\n",
+ " def expand_actions(self, name=None):\n",
+ " """Generate all possible actions with variable bindings for precondition selection heuristic"""\n",
+ "\n",
+ " objects = set(arg for clause in self.planningproblem.init for arg in clause.args)\n",
+ " expansions = []\n",
+ " action_list = []\n",
+ " if name is not None:\n",
+ " for action in self.planningproblem.actions:\n",
+ " if str(action.name) == name:\n",
+ " action_list.append(action)\n",
+ " else:\n",
+ " action_list = self.planningproblem.actions\n",
+ "\n",
+ " for action in action_list:\n",
+ " for permutation in itertools.permutations(objects, len(action.args)):\n",
+ " bindings = unify(Expr(action.name, *action.args), Expr(action.name, *permutation))\n",
+ " if bindings is not None:\n",
+ " new_args = []\n",
+ " for arg in action.args:\n",
+ " if arg in bindings:\n",
+ " new_args.append(bindings[arg])\n",
+ " else:\n",
+ " new_args.append(arg)\n",
+ " new_expr = Expr(str(action.name), *new_args)\n",
+ " new_preconds = []\n",
+ " for precond in action.precond:\n",
+ " new_precond_args = []\n",
+ " for arg in precond.args:\n",
+ " if arg in bindings:\n",
+ " new_precond_args.append(bindings[arg])\n",
+ " else:\n",
+ " new_precond_args.append(arg)\n",
+ " new_precond = Expr(str(precond.op), *new_precond_args)\n",
+ " new_preconds.append(new_precond)\n",
+ " new_effects = []\n",
+ " for effect in action.effect:\n",
+ " new_effect_args = []\n",
+ " for arg in effect.args:\n",
+ " if arg in bindings:\n",
+ " new_effect_args.append(bindings[arg])\n",
+ " else:\n",
+ " new_effect_args.append(arg)\n",
+ " new_effect = Expr(str(effect.op), *new_effect_args)\n",
+ " new_effects.append(new_effect)\n",
+ " expansions.append(Action(new_expr, new_preconds, new_effects))\n",
+ "\n",
+ " return expansions\n",
+ "\n",
+ " def find_open_precondition(self):\n",
+ " """Find open precondition with the least number of possible actions"""\n",
+ "\n",
+ " number_of_ways = dict()\n",
+ " actions_for_precondition = dict()\n",
+ " for element in self.agenda:\n",
+ " open_precondition = element[0]\n",
+ " possible_actions = list(self.actions) + self.expanded_actions\n",
+ " for action in possible_actions:\n",
+ " for effect in action.effect:\n",
+ " if effect == open_precondition:\n",
+ " if open_precondition in number_of_ways:\n",
+ " number_of_ways[open_precondition] += 1\n",
+ " actions_for_precondition[open_precondition].append(action)\n",
+ " else:\n",
+ " number_of_ways[open_precondition] = 1\n",
+ " actions_for_precondition[open_precondition] = [action]\n",
+ "\n",
+ " number = sorted(number_of_ways, key=number_of_ways.__getitem__)\n",
+ " \n",
+ " for k, v in number_of_ways.items():\n",
+ " if v == 0:\n",
+ " return None, None, None\n",
+ "\n",
+ " act1 = None\n",
+ " for element in self.agenda:\n",
+ " if element[0] == number[0]:\n",
+ " act1 = element[1]\n",
+ " break\n",
+ "\n",
+ " if number[0] in self.expanded_actions:\n",
+ " self.expanded_actions.remove(number[0])\n",
+ "\n",
+ " return number[0], act1, actions_for_precondition[number[0]]\n",
+ "\n",
+ " def find_action_for_precondition(self, oprec):\n",
+ " """Find action for a given precondition"""\n",
+ "\n",
+ " # either\n",
+ " # choose act0 E Actions such that act0 achieves G\n",
+ " for action in self.actions:\n",
+ " for effect in action.effect:\n",
+ " if effect == oprec:\n",
+ " return action, 0\n",
+ "\n",
+ " # or\n",
+ " # choose act0 E Actions such that act0 achieves G\n",
+ " for action in self.planningproblem.actions:\n",
+ " for effect in action.effect:\n",
+ " if effect.op == oprec.op:\n",
+ " bindings = unify(effect, oprec)\n",
+ " if bindings is None:\n",
+ " break\n",
+ " return action, bindings\n",
+ "\n",
+ " def generate_expr(self, clause, bindings):\n",
+ " """Generate atomic expression from generic expression given variable bindings"""\n",
+ "\n",
+ " new_args = []\n",
+ " for arg in clause.args:\n",
+ " if arg in bindings:\n",
+ " new_args.append(bindings[arg])\n",
+ " else:\n",
+ " new_args.append(arg)\n",
+ "\n",
+ " try:\n",
+ " return Expr(str(clause.name), *new_args)\n",
+ " except:\n",
+ " return Expr(str(clause.op), *new_args)\n",
+ " \n",
+ " def generate_action_object(self, action, bindings):\n",
+ " """Generate action object given a generic action andvariable bindings"""\n",
+ "\n",
+ " # if bindings is 0, it means the action already exists in self.actions\n",
+ " if bindings == 0:\n",
+ " return action\n",
+ "\n",
+ " # bindings cannot be None\n",
+ " else:\n",
+ " new_expr = self.generate_expr(action, bindings)\n",
+ " new_preconds = []\n",
+ " for precond in action.precond:\n",
+ " new_precond = self.generate_expr(precond, bindings)\n",
+ " new_preconds.append(new_precond)\n",
+ " new_effects = []\n",
+ " for effect in action.effect:\n",
+ " new_effect = self.generate_expr(effect, bindings)\n",
+ " new_effects.append(new_effect)\n",
+ " return Action(new_expr, new_preconds, new_effects)\n",
+ "\n",
+ " def cyclic(self, graph):\n",
+ " """Check cyclicity of a directed graph"""\n",
+ "\n",
+ " new_graph = dict()\n",
+ " for element in graph:\n",
+ " if element[0] in new_graph:\n",
+ " new_graph[element[0]].append(element[1])\n",
+ " else:\n",
+ " new_graph[element[0]] = [element[1]]\n",
+ "\n",
+ " path = set()\n",
+ "\n",
+ " def visit(vertex):\n",
+ " path.add(vertex)\n",
+ " for neighbor in new_graph.get(vertex, ()):\n",
+ " if neighbor in path or visit(neighbor):\n",
+ " return True\n",
+ " path.remove(vertex)\n",
+ " return False\n",
+ "\n",
+ " value = any(visit(v) for v in new_graph)\n",
+ " return value\n",
+ "\n",
+ " def add_const(self, constraint, constraints):\n",
+ " """Add the constraint to constraints if the resulting graph is acyclic"""\n",
+ "\n",
+ " if constraint[0] == self.finish or constraint[1] == self.start:\n",
+ " return constraints\n",
+ "\n",
+ " new_constraints = set(constraints)\n",
+ " new_constraints.add(constraint)\n",
+ "\n",
+ " if self.cyclic(new_constraints):\n",
+ " return constraints\n",
+ " return new_constraints\n",
+ "\n",
+ " def is_a_threat(self, precondition, effect):\n",
+ " """Check if effect is a threat to precondition"""\n",
+ "\n",
+ " if (str(effect.op) == 'Not' + str(precondition.op)) or ('Not' + str(effect.op) == str(precondition.op)):\n",
+ " if effect.args == precondition.args:\n",
+ " return True\n",
+ " return False\n",
+ "\n",
+ " def protect(self, causal_link, action, constraints):\n",
+ " """Check and resolve threats by promotion or demotion"""\n",
+ "\n",
+ " threat = False\n",
+ " for effect in action.effect:\n",
+ " if self.is_a_threat(causal_link[1], effect):\n",
+ " threat = True\n",
+ " break\n",
+ "\n",
+ " if action != causal_link[0] and action != causal_link[2] and threat:\n",
+ " # try promotion\n",
+ " new_constraints = set(constraints)\n",
+ " new_constraints.add((action, causal_link[0]))\n",
+ " if not self.cyclic(new_constraints):\n",
+ " constraints = self.add_const((action, causal_link[0]), constraints)\n",
+ " else:\n",
+ " # try demotion\n",
+ " new_constraints = set(constraints)\n",
+ " new_constraints.add((causal_link[2], action))\n",
+ " if not self.cyclic(new_constraints):\n",
+ " constraints = self.add_const((causal_link[2], action), constraints)\n",
+ " else:\n",
+ " # both promotion and demotion fail\n",
+ " print('Unable to resolve a threat caused by', action, 'onto', causal_link)\n",
+ " return\n",
+ " return constraints\n",
+ "\n",
+ " def convert(self, constraints):\n",
+ " """Convert constraints into a dict of Action to set orderings"""\n",
+ "\n",
+ " graph = dict()\n",
+ " for constraint in constraints:\n",
+ " if constraint[0] in graph:\n",
+ " graph[constraint[0]].add(constraint[1])\n",
+ " else:\n",
+ " graph[constraint[0]] = set()\n",
+ " graph[constraint[0]].add(constraint[1])\n",
+ " return graph\n",
+ "\n",
+ " def toposort(self, graph):\n",
+ " """Generate topological ordering of constraints"""\n",
+ "\n",
+ " if len(graph) == 0:\n",
+ " return\n",
+ "\n",
+ " graph = graph.copy()\n",
+ "\n",
+ " for k, v in graph.items():\n",
+ " v.discard(k)\n",
+ "\n",
+ " extra_elements_in_dependencies = _reduce(set.union, graph.values()) - set(graph.keys())\n",
+ "\n",
+ " graph.update({element:set() for element in extra_elements_in_dependencies})\n",
+ " while True:\n",
+ " ordered = set(element for element, dependency in graph.items() if len(dependency) == 0)\n",
+ " if not ordered:\n",
+ " break\n",
+ " yield ordered\n",
+ " graph = {element: (dependency - ordered) for element, dependency in graph.items() if element not in ordered}\n",
+ " if len(graph) != 0:\n",
+ " raise ValueError('The graph is not acyclic and cannot be linearly ordered')\n",
+ "\n",
+ " def display_plan(self):\n",
+ " """Display causal links, constraints and the plan"""\n",
+ "\n",
+ " print('Causal Links')\n",
+ " for causal_link in self.causal_links:\n",
+ " print(causal_link)\n",
+ "\n",
+ " print('\\nConstraints')\n",
+ " for constraint in self.constraints:\n",
+ " print(constraint[0], '<', constraint[1])\n",
+ "\n",
+ " print('\\nPartial Order Plan')\n",
+ " print(list(reversed(list(self.toposort(self.convert(self.constraints))))))\n",
+ "\n",
+ " def execute(self, display=True):\n",
+ " """Execute the algorithm"""\n",
+ "\n",
+ " step = 1\n",
+ " self.tries = 1\n",
+ " while len(self.agenda) > 0:\n",
+ " step += 1\n",
+ " # select <G, act1> from Agenda\n",
+ " try:\n",
+ " G, act1, possible_actions = self.find_open_precondition()\n",
+ " except IndexError:\n",
+ " print('Probably Wrong')\n",
+ " break\n",
+ "\n",
+ " act0 = possible_actions[0]\n",
+ " # remove <G, act1> from Agenda\n",
+ " self.agenda.remove((G, act1))\n",
+ "\n",
+ " # For actions with variable number of arguments, use least commitment principle\n",
+ " # act0_temp, bindings = self.find_action_for_precondition(G)\n",
+ " # act0 = self.generate_action_object(act0_temp, bindings)\n",
+ "\n",
+ " # Actions = Actions U {act0}\n",
+ " self.actions.add(act0)\n",
+ "\n",
+ " # Constraints = add_const(start < act0, Constraints)\n",
+ " self.constraints = self.add_const((self.start, act0), self.constraints)\n",
+ "\n",
+ " # for each CL E CausalLinks do\n",
+ " # Constraints = protect(CL, act0, Constraints)\n",
+ " for causal_link in self.causal_links:\n",
+ " self.constraints = self.protect(causal_link, act0, self.constraints)\n",
+ "\n",
+ " # Agenda = Agenda U {<P, act0>: P is a precondition of act0}\n",
+ " for precondition in act0.precond:\n",
+ " self.agenda.add((precondition, act0))\n",
+ "\n",
+ " # Constraints = add_const(act0 < act1, Constraints)\n",
+ " self.constraints = self.add_const((act0, act1), self.constraints)\n",
+ "\n",
+ " # CausalLinks U {<act0, G, act1>}\n",
+ " if (act0, G, act1) not in self.causal_links:\n",
+ " self.causal_links.append((act0, G, act1))\n",
+ "\n",
+ " # for each A E Actions do\n",
+ " # Constraints = protect(<act0, G, act1>, A, Constraints)\n",
+ " for action in self.actions:\n",
+ " self.constraints = self.protect((act0, G, act1), action, self.constraints)\n",
+ "\n",
+ " if step > 200:\n",
+ " print('Couldn\\'t find a solution')\n",
+ " return None, None\n",
+ "\n",
+ " if display:\n",
+ " self.display_plan()\n",
+ " else:\n",
+ " return self.constraints, self.causal_links \n",
+ "class Linearize:\n",
+ "\n",
+ " def __init__(self, planningproblem):\n",
+ " self.planningproblem = planningproblem\n",
+ "\n",
+ " def filter(self, solution):\n",
+ " """Filter out persistence actions from a solution"""\n",
+ "\n",
+ " new_solution = []\n",
+ " for section in solution[0]:\n",
+ " new_section = []\n",
+ " for operation in section:\n",
+ " if not (operation.op[0] == 'P' and operation.op[1].isupper()):\n",
+ " new_section.append(operation)\n",
+ " new_solution.append(new_section)\n",
+ " return new_solution\n",
+ "\n",
+ " def orderlevel(self, level, planningproblem):\n",
+ " """Return valid linear order of actions for a given level"""\n",
+ "\n",
+ " for permutation in itertools.permutations(level):\n",
+ " temp = copy.deepcopy(planningproblem)\n",
+ " count = 0\n",
+ " for action in permutation:\n",
+ " try:\n",
+ " temp.act(action)\n",
+ " count += 1\n",
+ " except:\n",
+ " count = 0\n",
+ " temp = copy.deepcopy(planningproblem)\n",
+ " break\n",
+ " if count == len(permutation):\n",
+ " return list(permutation), temp\n",
+ " return None\n",
+ "\n",
+ " def execute(self):\n",
+ " """Finds total-order solution for a planning graph"""\n",
+ "\n",
+ " graphplan_solution = GraphPlan(self.planningproblem).execute()\n",
+ " filtered_solution = self.filter(graphplan_solution)\n",
+ " ordered_solution = []\n",
+ " planningproblem = self.planningproblem\n",
+ " for level in filtered_solution:\n",
+ " level_solution, planningproblem = self.orderlevel(level, planningproblem)\n",
+ " for element in level_solution:\n",
+ " ordered_solution.append(element)\n",
+ "\n",
+ " return ordered_solution\n",
+ "class ProbDist:\n",
+ " """A discrete probability distribution. You name the random variable\n",
+ " in the constructor, then assign and query probability of values.\n",
+ " >>> P = ProbDist('Flip'); P['H'], P['T'] = 0.25, 0.75; P['H']\n",
+ " 0.25\n",
+ " >>> P = ProbDist('X', {'lo': 125, 'med': 375, 'hi': 500})\n",
+ " >>> P['lo'], P['med'], P['hi']\n",
+ " (0.125, 0.375, 0.5)\n",
+ " """\n",
+ "\n",
+ " def __init__(self, varname='?', freqs=None):\n",
+ " """If freqs is given, it is a dictionary of values - frequency pairs,\n",
+ " then ProbDist is normalized."""\n",
+ " self.prob = {}\n",
+ " self.varname = varname\n",
+ " self.values = []\n",
+ " if freqs:\n",
+ " for (v, p) in freqs.items():\n",
+ " self[v] = p\n",
+ " self.normalize()\n",
+ "\n",
+ " def __getitem__(self, val):\n",
+ " """Given a value, return P(value)."""\n",
+ " try:\n",
+ " return self.prob[val]\n",
+ " except KeyError:\n",
+ " return 0\n",
+ "\n",
+ " def __setitem__(self, val, p):\n",
+ " """Set P(val) = p."""\n",
+ " if val not in self.values:\n",
+ " self.values.append(val)\n",
+ " self.prob[val] = p\n",
+ "\n",
+ " def normalize(self):\n",
+ " """Make sure the probabilities of all values sum to 1.\n",
+ " Returns the normalized distribution.\n",
+ " Raises a ZeroDivisionError if the sum of the values is 0."""\n",
+ " total = sum(self.prob.values())\n",
+ " if not isclose(total, 1.0):\n",
+ " for val in self.prob:\n",
+ " self.prob[val] /= total\n",
+ " return self\n",
+ "\n",
+ " def show_approx(self, numfmt='{:.3g}'):\n",
+ " """Show the probabilities rounded and sorted by key, for the\n",
+ " sake of portable doctests."""\n",
+ " return ', '.join([('{}: ' + numfmt).format(v, p)\n",
+ " for (v, p) in sorted(self.prob.items())])\n",
+ "\n",
+ " def __repr__(self):\n",
+ " return "P({})".format(self.varname)\n",
+ "class JointProbDist(ProbDist):\n",
+ " """A discrete probability distribute over a set of variables.\n",
+ " >>> P = JointProbDist(['X', 'Y']); P[1, 1] = 0.25\n",
+ " >>> P[1, 1]\n",
+ " 0.25\n",
+ " >>> P[dict(X=0, Y=1)] = 0.5\n",
+ " >>> P[dict(X=0, Y=1)]\n",
+ " 0.5"""\n",
+ "\n",
+ " def __init__(self, variables):\n",
+ " self.prob = {}\n",
+ " self.variables = variables\n",
+ " self.vals = defaultdict(list)\n",
+ "\n",
+ " def __getitem__(self, values):\n",
+ " """Given a tuple or dict of values, return P(values)."""\n",
+ " values = event_values(values, self.variables)\n",
+ " return ProbDist.__getitem__(self, values)\n",
+ "\n",
+ " def __setitem__(self, values, p):\n",
+ " """Set P(values) = p. Values can be a tuple or a dict; it must\n",
+ " have a value for each of the variables in the joint. Also keep track\n",
+ " of the values we have seen so far for each variable."""\n",
+ " values = event_values(values, self.variables)\n",
+ " self.prob[values] = p\n",
+ " for var, val in zip(self.variables, values):\n",
+ " if val not in self.vals[var]:\n",
+ " self.vals[var].append(val)\n",
+ "\n",
+ " def values(self, var):\n",
+ " """Return the set of possible values for a variable."""\n",
+ " return self.vals[var]\n",
+ "\n",
+ " def __repr__(self):\n",
+ " return "P({})".format(self.variables)\n",
+ "def enumerate_joint(variables, e, P):\n",
+ " """Return the sum of those entries in P consistent with e,\n",
+ " provided variables is P's remaining variables (the ones not in e)."""\n",
+ " if not variables:\n",
+ " return P[e]\n",
+ " Y, rest = variables[0], variables[1:]\n",
+ " return sum([enumerate_joint(rest, extend(e, Y, y), P)\n",
+ " for y in P.values(Y)])\n",
+ "def enumerate_joint_ask(X, e, P):\n",
+ " """Return a probability distribution over the values of the variable X,\n",
+ " given the {var:val} observations e, in the JointProbDist P. [Section 13.3]\n",
+ " >>> P = JointProbDist(['X', 'Y'])\n",
+ " >>> P[0,0] = 0.25; P[0,1] = 0.5; P[1,1] = P[2,1] = 0.125\n",
+ " >>> enumerate_joint_ask('X', dict(Y=1), P).show_approx()\n",
+ " '0: 0.667, 1: 0.167, 2: 0.167'\n",
+ " """\n",
+ " assert X not in e, "Query variable must be distinct from evidence"\n",
+ " Q = ProbDist(X) # probability distribution for X, initially empty\n",
+ " Y = [v for v in P.variables if v != X and v not in e] # hidden variables.\n",
+ " for xi in P.values(X):\n",
+ " Q[xi] = enumerate_joint(Y, extend(e, X, xi), P)\n",
+ " return Q.normalize()\n",
+ "class BayesNode:\n",
+ " """A conditional probability distribution for a boolean variable,\n",
+ " P(X | parents). Part of a BayesNet."""\n",
+ "\n",
+ " def __init__(self, X, parents, cpt):\n",
+ " """X is a variable name, and parents a sequence of variable\n",
+ " names or a space-separated string. cpt, the conditional\n",
+ " probability table, takes one of these forms:\n",
+ "\n",
+ " * A number, the unconditional probability P(X=true). You can\n",
+ " use this form when there are no parents.\n",
+ "\n",
+ " * A dict {v: p, ...}, the conditional probability distribution\n",
+ " P(X=true | parent=v) = p. When there's just one parent.\n",
+ "\n",
+ " * A dict {(v1, v2, ...): p, ...}, the distribution P(X=true |\n",
+ " parent1=v1, parent2=v2, ...) = p. Each key must have as many\n",
+ " values as there are parents. You can use this form always;\n",
+ " the first two are just conveniences.\n",
+ "\n",
+ " In all cases the probability of X being false is left implicit,\n",
+ " since it follows from P(X=true).\n",
+ "\n",
+ " >>> X = BayesNode('X', '', 0.2)\n",
+ " >>> Y = BayesNode('Y', 'P', {T: 0.2, F: 0.7})\n",
+ " >>> Z = BayesNode('Z', 'P Q',\n",
+ " ... {(T, T): 0.2, (T, F): 0.3, (F, T): 0.5, (F, F): 0.7})\n",
+ " """\n",
+ " if isinstance(parents, str):\n",
+ " parents = parents.split()\n",
+ "\n",
+ " # We store the table always in the third form above.\n",
+ " if isinstance(cpt, (float, int)): # no parents, 0-tuple\n",
+ " cpt = {(): cpt}\n",
+ " elif isinstance(cpt, dict):\n",
+ " # one parent, 1-tuple\n",
+ " if cpt and isinstance(list(cpt.keys())[0], bool):\n",
+ " cpt = {(v,): p for v, p in cpt.items()}\n",
+ "\n",
+ " assert isinstance(cpt, dict)\n",
+ " for vs, p in cpt.items():\n",
+ " assert isinstance(vs, tuple) and len(vs) == len(parents)\n",
+ " assert all(isinstance(v, bool) for v in vs)\n",
+ " assert 0 <= p <= 1\n",
+ "\n",
+ " self.variable = X\n",
+ " self.parents = parents\n",
+ " self.cpt = cpt\n",
+ " self.children = []\n",
+ "\n",
+ " def p(self, value, event):\n",
+ " """Return the conditional probability\n",
+ " P(X=value | parents=parent_values), where parent_values\n",
+ " are the values of parents in event. (event must assign each\n",
+ " parent a value.)\n",
+ " >>> bn = BayesNode('X', 'Burglary', {T: 0.2, F: 0.625})\n",
+ " >>> bn.p(False, {'Burglary': False, 'Earthquake': True})\n",
+ " 0.375"""\n",
+ " assert isinstance(value, bool)\n",
+ " ptrue = self.cpt[event_values(event, self.parents)]\n",
+ " return ptrue if value else 1 - ptrue\n",
+ "\n",
+ " def sample(self, event):\n",
+ " """Sample from the distribution for this variable conditioned\n",
+ " on event's values for parent_variables. That is, return True/False\n",
+ " at random according with the conditional probability given the\n",
+ " parents."""\n",
+ " return probability(self.p(True, event))\n",
+ "\n",
+ " def __repr__(self):\n",
+ " return repr((self.variable, ' '.join(self.parents)))\n",
+ "class BayesNet:\n",
+ " """Bayesian network containing only boolean-variable nodes."""\n",
+ "\n",
+ " def __init__(self, node_specs=None):\n",
+ " """Nodes must be ordered with parents before children."""\n",
+ " self.nodes = []\n",
+ " self.variables = []\n",
+ " node_specs = node_specs or []\n",
+ " for node_spec in node_specs:\n",
+ " self.add(node_spec)\n",
+ "\n",
+ " def add(self, node_spec):\n",
+ " """Add a node to the net. Its parents must already be in the\n",
+ " net, and its variable must not."""\n",
+ " node = BayesNode(*node_spec)\n",
+ " assert node.variable not in self.variables\n",
+ " assert all((parent in self.variables) for parent in node.parents)\n",
+ " self.nodes.append(node)\n",
+ " self.variables.append(node.variable)\n",
+ " for parent in node.parents:\n",
+ " self.variable_node(parent).children.append(node)\n",
+ "\n",
+ " def variable_node(self, var):\n",
+ " """Return the node for the variable named var.\n",
+ " >>> burglary.variable_node('Burglary').variable\n",
+ " 'Burglary'"""\n",
+ " for n in self.nodes:\n",
+ " if n.variable == var:\n",
+ " return n\n",
+ " raise Exception("No such variable: {}".format(var))\n",
+ "\n",
+ " def variable_values(self, var):\n",
+ " """Return the domain of var."""\n",
+ " return [True, False]\n",
+ "\n",
+ " def __repr__(self):\n",
+ " return 'BayesNet({0!r})'.format(self.nodes)\n",
+ "def enumerate_all(variables, e, bn):\n",
+ " """Return the sum of those entries in P(variables | e{others})\n",
+ " consistent with e, where P is the joint distribution represented\n",
+ " by bn, and e{others} means e restricted to bn's other variables\n",
+ " (the ones other than variables). Parents must precede children in variables."""\n",
+ " if not variables:\n",
+ " return 1.0\n",
+ " Y, rest = variables[0], variables[1:]\n",
+ " Ynode = bn.variable_node(Y)\n",
+ " if Y in e:\n",
+ " return Ynode.p(e[Y], e) * enumerate_all(rest, e, bn)\n",
+ " else:\n",
+ " return sum(Ynode.p(y, e) * enumerate_all(rest, extend(e, Y, y), bn)\n",
+ " for y in bn.variable_values(Y))\n",
+ "def enumeration_ask(X, e, bn):\n",
+ " """Return the conditional probability distribution of variable X\n",
+ " given evidence e, from BayesNet bn. [Figure 14.9]\n",
+ " >>> enumeration_ask('Burglary', dict(JohnCalls=T, MaryCalls=T), burglary\n",
+ " ... ).show_approx()\n",
+ " 'False: 0.716, True: 0.284'"""\n",
+ " assert X not in e, "Query variable must be distinct from evidence"\n",
+ " Q = ProbDist(X)\n",
+ " for xi in bn.variable_values(X):\n",
+ " Q[xi] = enumerate_all(bn.variables, extend(e, X, xi), bn)\n",
+ " return Q.normalize()\n",
+ "def make_factor(var, e, bn):\n",
+ " """Return the factor for var in bn's joint distribution given e.\n",
+ " That is, bn's full joint distribution, projected to accord with e,\n",
+ " is the pointwise product of these factors for bn's variables."""\n",
+ " node = bn.variable_node(var)\n",
+ " variables = [X for X in [var] + node.parents if X not in e]\n",
+ " cpt = {event_values(e1, variables): node.p(e1[var], e1)\n",
+ " for e1 in all_events(variables, bn, e)}\n",
+ " return Factor(variables, cpt)\n",
+ "def all_events(variables, bn, e):\n",
+ " """Yield every way of extending e with values for all variables."""\n",
+ " if not variables:\n",
+ " yield e\n",
+ " else:\n",
+ " X, rest = variables[0], variables[1:]\n",
+ " for e1 in all_events(rest, bn, e):\n",
+ " for x in bn.variable_values(X):\n",
+ " yield extend(e1, X, x)\n",
+ " def pointwise_product(self, other, bn):\n",
+ " """Multiply two factors, combining their variables."""\n",
+ " variables = list(set(self.variables) | set(other.variables))\n",
+ " cpt = {event_values(e, variables): self.p(e) * other.p(e)\n",
+ " for e in all_events(variables, bn, {})}\n",
+ " return Factor(variables, cpt)\n",
+ "def pointwise_product(factors, bn):\n",
+ " return reduce(lambda f, g: f.pointwise_product(g, bn), factors)\n",
+ " def sum_out(self, var, bn):\n",
+ " """Make a factor eliminating var by summing over its values."""\n",
+ " variables = [X for X in self.variables if X != var]\n",
+ " cpt = {event_values(e, variables): sum(self.p(extend(e, var, val))\n",
+ " for val in bn.variable_values(var))\n",
+ " for e in all_events(variables, bn, {})}\n",
+ " return Factor(variables, cpt)\n",
+ "def sum_out(var, factors, bn):\n",
+ " """Eliminate var from all factors by summing over its values."""\n",
+ " result, var_factors = [], []\n",
+ " for f in factors:\n",
+ " (var_factors if var in f.variables else result).append(f)\n",
+ " result.append(pointwise_product(var_factors, bn).sum_out(var, bn))\n",
+ " return result\n",
+ "def elimination_ask(X, e, bn):\n",
+ " """Compute bn's P(X|e) by variable elimination. [Figure 14.11]\n",
+ " >>> elimination_ask('Burglary', dict(JohnCalls=T, MaryCalls=T), burglary\n",
+ " ... ).show_approx()\n",
+ " 'False: 0.716, True: 0.284'"""\n",
+ " assert X not in e, "Query variable must be distinct from evidence"\n",
+ " factors = []\n",
+ " for var in reversed(bn.variables):\n",
+ " factors.append(make_factor(var, e, bn))\n",
+ " if is_hidden(var, X, e):\n",
+ " factors = sum_out(var, factors, bn)\n",
+ " return pointwise_product(factors, bn).normalize()\n",
+ " def sample(self, event):\n",
+ " """Sample from the distribution for this variable conditioned\n",
+ " on event's values for parent_variables. That is, return True/False\n",
+ " at random according with the conditional probability given the\n",
+ " parents."""\n",
+ " return probability(self.p(True, event))\n",
+ "def prior_sample(bn):\n",
+ " """Randomly sample from bn's full joint distribution. The result\n",
+ " is a {variable: value} dict. [Figure 14.13]"""\n",
+ " event = {}\n",
+ " for node in bn.nodes:\n",
+ " event[node.variable] = node.sample(event)\n",
+ " return event\n",
+ "![](\"files/images/sprinklernet.jpg\")
\n",
"\n",
- "We store the samples on the observations. Let us find **P(Rain=True)**"
+ "Traversing the graph in topological order is important.\n",
+ "There are two possible topological orderings for this particular directed acyclic graph.\n",
+ "def rejection_sampling(X, e, bn, N=10000):\n",
+ " """Estimate the probability distribution of variable X given\n",
+ " evidence e in BayesNet bn, using N samples. [Figure 14.14]\n",
+ " Raises a ZeroDivisionError if all the N samples are rejected,\n",
+ " i.e., inconsistent with e.\n",
+ " >>> random.seed(47)\n",
+ " >>> rejection_sampling('Burglary', dict(JohnCalls=T, MaryCalls=T),\n",
+ " ... burglary, 10000).show_approx()\n",
+ " 'False: 0.7, True: 0.3'\n",
+ " """\n",
+ " counts = {x: 0 for x in bn.variable_values(X)} # bold N in [Figure 14.14]\n",
+ " for j in range(N):\n",
+ " sample = prior_sample(bn) # boldface x in [Figure 14.14]\n",
+ " if consistent_with(sample, e):\n",
+ " counts[sample[X]] += 1\n",
+ " return ProbDist(X, counts)\n",
+ "def consistent_with(event, evidence):\n",
+ " """Is event consistent with the given evidence?"""\n",
+ " return all(evidence.get(k, v) == v\n",
+ " for k, v in event.items())\n",
+ "def weighted_sample(bn, e):\n",
+ " """Sample an event from bn that's consistent with the evidence e;\n",
+ " return the event and its weight, the likelihood that the event\n",
+ " accords to the evidence."""\n",
+ " w = 1\n",
+ " event = dict(e) # boldface x in [Figure 14.15]\n",
+ " for node in bn.nodes:\n",
+ " Xi = node.variable\n",
+ " if Xi in e:\n",
+ " w *= node.p(e[Xi], event)\n",
+ " else:\n",
+ " event[Xi] = node.sample(event)\n",
+ " return event, w\n",
+ "def likelihood_weighting(X, e, bn, N=10000):\n",
+ " """Estimate the probability distribution of variable X given\n",
+ " evidence e in BayesNet bn. [Figure 14.15]\n",
+ " >>> random.seed(1017)\n",
+ " >>> likelihood_weighting('Burglary', dict(JohnCalls=T, MaryCalls=T),\n",
+ " ... burglary, 10000).show_approx()\n",
+ " 'False: 0.702, True: 0.298'\n",
+ " """\n",
+ " W = {x: 0 for x in bn.variable_values(X)}\n",
+ " for j in range(N):\n",
+ " sample, weight = weighted_sample(bn, e) # boldface x, w in [Figure 14.15]\n",
+ " W[sample[X]] += weight\n",
+ " return ProbDist(X, W)\n",
+ "def gibbs_ask(X, e, bn, N=1000):\n",
+ " """[Figure 14.16]"""\n",
+ " assert X not in e, "Query variable must be distinct from evidence"\n",
+ " counts = {x: 0 for x in bn.variable_values(X)} # bold N in [Figure 14.16]\n",
+ " Z = [var for var in bn.variables if var not in e]\n",
+ " state = dict(e) # boldface x in [Figure 14.16]\n",
+ " for Zi in Z:\n",
+ " state[Zi] = random.choice(bn.variable_values(Zi))\n",
+ " for j in range(N):\n",
+ " for Zi in Z:\n",
+ " state[Zi] = markov_blanket_sample(Zi, state, bn)\n",
+ " counts[state[X]] += 1\n",
+ " return ProbDist(X, counts)\n",
+ "class HiddenMarkovModel:\n",
+ " """A Hidden markov model which takes Transition model and Sensor model as inputs"""\n",
+ "\n",
+ " def __init__(self, transition_model, sensor_model, prior=None):\n",
+ " self.transition_model = transition_model\n",
+ " self.sensor_model = sensor_model\n",
+ " self.prior = prior or [0.5, 0.5]\n",
+ "\n",
+ " def sensor_dist(self, ev):\n",
+ " if ev is True:\n",
+ " return self.sensor_model[0]\n",
+ " else:\n",
+ " return self.sensor_model[1]\n",
+ "def forward(HMM, fv, ev):\n",
+ " prediction = vector_add(scalar_vector_product(fv[0], HMM.transition_model[0]),\n",
+ " scalar_vector_product(fv[1], HMM.transition_model[1]))\n",
+ " sensor_dist = HMM.sensor_dist(ev)\n",
+ "\n",
+ " return normalize(element_wise_product(sensor_dist, prediction))\n",
+ "def backward(HMM, b, ev):\n",
+ " sensor_dist = HMM.sensor_dist(ev)\n",
+ " prediction = element_wise_product(sensor_dist, b)\n",
+ "\n",
+ " return normalize(vector_add(scalar_vector_product(prediction[0], HMM.transition_model[0]),\n",
+ " scalar_vector_product(prediction[1], HMM.transition_model[1])))\n",
+ "def fixed_lag_smoothing(e_t, HMM, d, ev, t):\n",
+ " """[Figure 15.6]\n",
+ " Smoothing algorithm with a fixed time lag of 'd' steps.\n",
+ " Online algorithm that outputs the new smoothed estimate if observation\n",
+ " for new time step is given."""\n",
+ " ev.insert(0, None)\n",
+ "\n",
+ " T_model = HMM.transition_model\n",
+ " f = HMM.prior\n",
+ " B = [[1, 0], [0, 1]]\n",
+ " evidence = []\n",
+ "\n",
+ " evidence.append(e_t)\n",
+ " O_t = vector_to_diagonal(HMM.sensor_dist(e_t))\n",
+ " if t > d:\n",
+ " f = forward(HMM, f, e_t)\n",
+ " O_tmd = vector_to_diagonal(HMM.sensor_dist(ev[t - d]))\n",
+ " B = matrix_multiplication(inverse_matrix(O_tmd), inverse_matrix(T_model), B, T_model, O_t)\n",
+ " else:\n",
+ " B = matrix_multiplication(B, T_model, O_t)\n",
+ " t += 1\n",
+ "\n",
+ " if t > d:\n",
+ " # always returns a 1x2 matrix\n",
+ " return [normalize(i) for i in matrix_multiplication([f], B)][0]\n",
+ " else:\n",
+ " return None\n",
+ "def particle_filtering(e, N, HMM):\n",
+ " """Particle filtering considering two states variables."""\n",
+ " dist = [0.5, 0.5]\n",
+ " # Weight Initialization\n",
+ " w = [0 for _ in range(N)]\n",
+ " # STEP 1\n",
+ " # Propagate one step using transition model given prior state\n",
+ " dist = vector_add(scalar_vector_product(dist[0], HMM.transition_model[0]),\n",
+ " scalar_vector_product(dist[1], HMM.transition_model[1]))\n",
+ " # Assign state according to probability\n",
+ " s = ['A' if probability(dist[0]) else 'B' for _ in range(N)]\n",
+ " w_tot = 0\n",
+ " # Calculate importance weight given evidence e\n",
+ " for i in range(N):\n",
+ " if s[i] == 'A':\n",
+ " # P(U|A)*P(A)\n",
+ " w_i = HMM.sensor_dist(e)[0] * dist[0]\n",
+ " if s[i] == 'B':\n",
+ " # P(U|B)*P(B)\n",
+ " w_i = HMM.sensor_dist(e)[1] * dist[1]\n",
+ " w[i] = w_i\n",
+ " w_tot += w_i\n",
+ "\n",
+ " # Normalize all the weights\n",
+ " for i in range(N):\n",
+ " w[i] = w[i] / w_tot\n",
+ "\n",
+ " # Limit weights to 4 digits\n",
+ " for i in range(N):\n",
+ " w[i] = float("{0:.4f}".format(w[i]))\n",
+ "\n",
+ " # STEP 2\n",
+ "\n",
+ " s = weighted_sample_with_replacement(N, s, w)\n",
+ "\n",
+ " return s\n",
+ "def monte_carlo_localization(a, z, N, P_motion_sample, P_sensor, m, S=None):\n",
+ " """Monte Carlo localization algorithm from Fig 25.9"""\n",
+ "\n",
+ " def ray_cast(sensor_num, kin_state, m):\n",
+ " return m.ray_cast(sensor_num, kin_state)\n",
+ "\n",
+ " M = len(z)\n",
+ " W = [0]*N\n",
+ " S_ = [0]*N\n",
+ " W_ = [0]*N\n",
+ " v = a['v']\n",
+ " w = a['w']\n",
+ "\n",
+ " if S is None:\n",
+ " S = [m.sample() for _ in range(N)]\n",
+ "\n",
+ " for i in range(N):\n",
+ " S_[i] = P_motion_sample(S[i], v, w)\n",
+ " W_[i] = 1\n",
+ " for j in range(M):\n",
+ " z_ = ray_cast(j, S_[i], m)\n",
+ " W_[i] = W_[i] * P_sensor(z[j], z_)\n",
+ "\n",
+ " S = weighted_sample_with_replacement(N, S_, W_)\n",
+ " return S\n",
+ "def DTAgentProgram(belief_state):\n",
+ " """A decision-theoretic agent. [Figure 13.1]"""\n",
+ " def program(percept):\n",
+ " belief_state.observe(program.action, percept)\n",
+ " program.action = argmax(belief_state.actions(),\n",
+ " key=belief_state.expected_outcome_utility)\n",
+ " return program.action\n",
+ " program.action = None\n",
+ " return program\n",
+ "class DecisionNetwork(BayesNet):\n",
+ " """An abstract class for a decision network as a wrapper for a BayesNet.\n",
+ " Represents an agent's current state, its possible actions, reachable states\n",
+ " and utilities of those states."""\n",
+ "\n",
+ " def __init__(self, action, infer):\n",
+ " """action: a single action node\n",
+ " infer: the preferred method to carry out inference on the given BayesNet"""\n",
+ " super(DecisionNetwork, self).__init__()\n",
+ " self.action = action\n",
+ " self.infer = infer\n",
+ "\n",
+ " def best_action(self):\n",
+ " """Return the best action in the network"""\n",
+ " return self.action\n",
+ "\n",
+ " def get_utility(self, action, state):\n",
+ " """Return the utility for a particular action and state in the network"""\n",
+ " raise NotImplementedError\n",
+ "\n",
+ " def get_expected_utility(self, action, evidence):\n",
+ " """Compute the expected utility given an action and evidence"""\n",
+ " u = 0.0\n",
+ " prob_dist = self.infer(action, evidence, self).prob\n",
+ " for item, _ in prob_dist.items():\n",
+ " u += prob_dist[item] * self.get_utility(action, item)\n",
+ "\n",
+ " return u\n",
+ "class InformationGatheringAgent(Agent):\n",
+ " """A simple information gathering agent. The agent works by repeatedly selecting\n",
+ " the observation with the highest information value, until the cost of the next\n",
+ " observation is greater than its expected benefit. [Figure 16.9]"""\n",
+ "\n",
+ " def __init__(self, decnet, infer, initial_evidence=None):\n",
+ " """decnet: a decision network\n",
+ " infer: the preferred method to carry out inference on the given decision network\n",
+ " initial_evidence: initial evidence"""\n",
+ " self.decnet = decnet\n",
+ " self.infer = infer\n",
+ " self.observation = initial_evidence or []\n",
+ " self.variables = self.decnet.nodes\n",
+ "\n",
+ " def integrate_percept(self, percept):\n",
+ " """Integrate the given percept into the decision network"""\n",
+ " raise NotImplementedError\n",
+ "\n",
+ " def execute(self, percept):\n",
+ " """Execute the information gathering algorithm"""\n",
+ " self.observation = self.integrate_percept(percept)\n",
+ " vpis = self.vpi_cost_ratio(self.variables)\n",
+ " j = argmax(vpis)\n",
+ " variable = self.variables[j]\n",
+ "\n",
+ " if self.vpi(variable) > self.cost(variable):\n",
+ " return self.request(variable)\n",
+ "\n",
+ " return self.decnet.best_action()\n",
+ "\n",
+ " def request(self, variable):\n",
+ " """Return the value of the given random variable as the next percept"""\n",
+ " raise NotImplementedError\n",
+ "\n",
+ " def cost(self, var):\n",
+ " """Return the cost of obtaining evidence through tests, consultants or questions"""\n",
+ " raise NotImplementedError\n",
+ "\n",
+ " def vpi_cost_ratio(self, variables):\n",
+ " """Return the VPI to cost ratio for the given variables"""\n",
+ " v_by_c = []\n",
+ " for var in variables:\n",
+ " v_by_c.append(self.vpi(var) / self.cost(var))\n",
+ " return v_by_c\n",
+ "\n",
+ " def vpi(self, variable):\n",
+ " """Return VPI for a given variable"""\n",
+ " vpi = 0.0\n",
+ " prob_dist = self.infer(variable, self.observation, self.decnet).prob\n",
+ " for item, _ in prob_dist.items():\n",
+ " post_prob = prob_dist[item]\n",
+ " new_observation = list(self.observation)\n",
+ " new_observation.append(item)\n",
+ " expected_utility = self.decnet.get_expected_utility(variable, new_observation)\n",
+ " vpi += post_prob * expected_utility\n",
+ "\n",
+ " vpi -= self.decnet.get_expected_utility(variable, self.observation)\n",
+ " return vpi\n",
+ "![](\"files/images/mdp.png\")
Now we define actions and a policy similar to **Fig 21.1** in the book."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "# Action Directions\n",
+ "north = (0, 1)\n",
+ "south = (0,-1)\n",
+ "west = (-1, 0)\n",
+ "east = (1, 0)\n",
+ "\n",
+ "policy = {\n",
+ " (0, 2): east, (1, 2): east, (2, 2): east, (3, 2): None,\n",
+ " (0, 1): north, (2, 1): north, (3, 1): None,\n",
+ " (0, 0): north, (1, 0): west, (2, 0): west, (3, 0): west, \n",
+ "}\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Direction Utility Estimation Agent\n",
+ "\n",
+ "The `PassiveDEUAgent` class in the `rl` module implements the Agent Program described in **Fig 21.2** of the AIMA Book. `PassiveDEUAgent` sums over rewards to find the estimated utility for each state. It thus requires the running of a number of iterations."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "%psource PassiveDUEAgent"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "DUEagent = PassiveDUEAgent(policy, sequential_decision_environment)\n",
+ "for i in range(200):\n",
+ " run_single_trial(DUEagent, sequential_decision_environment)\n",
+ " DUEagent.estimate_U()\n",
+ "\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The calculated utilities are:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "print('\\n'.join([str(k)+':'+str(v) for k, v in DUEagent.U.items()]))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Adaptive Dynamic Programming Agent\n",
+ "\n",
+ "The `PassiveADPAgent` class in the `rl` module implements the Agent Program described in **Fig 21.2** of the AIMA Book. `PassiveADPAgent` uses state transition and occurrence counts to estimate $P$, and then $U$. Go through the source below to understand the agent."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "%psource PassiveADPAgent"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We instantiate a `PassiveADPAgent` below with the `GridMDP` shown and train it over 200 iterations. The `rl` module has a simple implementation to simulate iterations. The function is called **run_single_trial**."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "scrolled": true
+ },
+ "outputs": [],
+ "source": [
+ "ADPagent = PassiveADPAgent(policy, sequential_decision_environment)\n",
+ "for i in range(200):\n",
+ " run_single_trial(ADPagent, sequential_decision_environment)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The calculated utilities are:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "scrolled": true
+ },
+ "outputs": [],
+ "source": [
+ "print('\\n'.join([str(k)+':'+str(v) for k, v in ADPagent.U.items()]))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Passive Temporal Difference Agent\n",
+ "\n",
+ "`PassiveTDAgent` uses temporal differences to learn utility estimates. We learn the difference between the states and backup the values to previous states. Let us look into the source before we see some usage examples."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "%psource PassiveTDAgent"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "In creating the `TDAgent`, we use the **same learning rate** $\\alpha$ as given in the footnote of the book on **page 837**."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "TDagent = PassiveTDAgent(policy, sequential_decision_environment, alpha = lambda n: 60./(59+n))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Now we run **200 trials** for the agent to estimate Utilities."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "for i in range(200):\n",
+ " run_single_trial(TDagent,sequential_decision_environment)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The calculated utilities are:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "print('\\n'.join([str(k)+':'+str(v) for k, v in TDagent.U.items()]))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Comparison with value iteration method\n",
+ "\n",
+ "We can also compare the utility estimates learned by our agent to those obtained via **value iteration**.\n",
+ "\n",
+ "**Note that value iteration has a priori knowledge of the transition table $P$, the rewards $R$, and all the states $s$.**"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "from mdp import value_iteration"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The values calculated by value iteration:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "U_values = value_iteration(sequential_decision_environment)\n",
+ "print('\\n'.join([str(k)+':'+str(v) for k, v in U_values.items()]))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Evolution of utility estimates over iterations\n",
+ "\n",
+ "We can explore how these estimates vary with time by using plots similar to **Fig 21.5a**. We will first enable matplotlib using the inline backend. We also define a function to collect the values of utilities at each iteration."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "%matplotlib inline\n",
+ "import matplotlib.pyplot as plt\n",
+ "\n",
+ "def graph_utility_estimates(agent_program, mdp, no_of_iterations, states_to_graph):\n",
+ " graphs = {state:[] for state in states_to_graph}\n",
+ " for iteration in range(1,no_of_iterations+1):\n",
+ " run_single_trial(agent_program, mdp)\n",
+ " for state in states_to_graph:\n",
+ " graphs[state].append((iteration, agent_program.U[state]))\n",
+ " for state, value in graphs.items():\n",
+ " state_x, state_y = zip(*value)\n",
+ " plt.plot(state_x, state_y, label=str(state))\n",
+ " plt.ylim([0,1.2])\n",
+ " plt.legend(loc='lower right')\n",
+ " plt.xlabel('Iterations')\n",
+ " plt.ylabel('U')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Here is a plot of state $(2,2)$."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "agent = PassiveTDAgent(policy, sequential_decision_environment, alpha=lambda n: 60./(59+n))\n",
+ "graph_utility_estimates(agent, sequential_decision_environment, 500, [(2,2)])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "It is also possible to plot multiple states on the same plot. As expected, the utility of the finite state $(3,2)$ stays constant and is equal to $R((3,2)) = 1$."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "graph_utility_estimates(agent, sequential_decision_environment, 500, [(2,2), (3,2)])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "collapsed": true
+ },
+ "source": [
+ "## ACTIVE REINFORCEMENT LEARNING\n",
+ "\n",
+ "Unlike Passive Reinforcement Learning in Active Reinforcement Learning we are not bound by a policy pi and we need to select our actions. In other words the agent needs to learn an optimal policy. The fundamental tradeoff the agent needs to face is that of exploration vs. exploitation. "
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### QLearning Agent\n",
+ "\n",
+ "The QLearningAgent class in the rl module implements the Agent Program described in **Fig 21.8** of the AIMA Book. In Q-Learning the agent learns an action-value function Q which gives the utility of taking a given action in a particular state. Q-Learning does not required a transition model and hence is a model free method. Let us look into the source before we see some usage examples."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "%psource QLearningAgent"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The Agent Program can be obtained by creating the instance of the class by passing the appropriate parameters. Because of the __ call __ method the object that is created behaves like a callable and returns an appropriate action as most Agent Programs do. To instantiate the object we need a mdp similar to the PassiveTDAgent.\n",
+ "\n",
+ " Let us use the same GridMDP object we used above. **Figure 17.1 (sequential_decision_environment)** is similar to **Figure 21.1** but has some discounting as **gamma = 0.9**. The class also implements an exploration function **f** which returns fixed **Rplus** until agent has visited state, action **Ne** number of times. This is the same as the one defined on page **842** of the book. The method **actions_in_state** returns actions possible in given state. It is useful when applying max and argmax operations."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Let us create our object now. We also use the **same alpha** as given in the footnote of the book on **page 837**. We use **Rplus = 2** and **Ne = 5** as defined on page 843. **Fig 21.7** "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "q_agent = QLearningAgent(sequential_decision_environment, Ne=5, Rplus=2, \n",
+ " alpha=lambda n: 60./(59+n))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Now to try out the q_agent we make use of the **run_single_trial** function in rl.py (which was also used above). Let us use **200** iterations."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "for i in range(200):\n",
+ " run_single_trial(q_agent,sequential_decision_environment)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Now let us see the Q Values. The keys are state-action pairs. Where different actions correspond according to:\n",
+ "\n",
+ "north = (0, 1)\n",
+ "south = (0,-1)\n",
+ "west = (-1, 0)\n",
+ "east = (1, 0)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "q_agent.Q"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The Utility **U** of each state is related to **Q** by the following equation.\n",
+ "\n",
+ "**U (s) = max a Q(s, a)**\n",
+ "\n",
+ "Let us convert the Q Values above into U estimates.\n",
+ "\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "U = defaultdict(lambda: -1000.) # Very Large Negative Value for Comparison see below.\n",
+ "for state_action, value in q_agent.Q.items():\n",
+ " state, action = state_action\n",
+ " if U[state] < value:\n",
+ " U[state] = value"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "U"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Let us finally compare these estimates to value_iteration results."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "print(value_iteration(sequential_decision_environment))"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": []
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": []
+ }
+ ],
+ "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.6.3"
+ },
+ "pycharm": {
+ "stem_cell": {
+ "cell_type": "raw",
+ "source": [],
+ "metadata": {
+ "collapsed": false
+ }
+ }
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}
\ No newline at end of file
diff --git a/reinforcement_learning.py b/reinforcement_learning.py
new file mode 100644
index 000000000..4cb91af0f
--- /dev/null
+++ b/reinforcement_learning.py
@@ -0,0 +1,337 @@
+"""Reinforcement Learning (Chapter 21)"""
+
+import random
+from collections import defaultdict
+
+from mdp import MDP, policy_evaluation
+
+
+class PassiveDUEAgent:
+ """
+ Passive (non-learning) agent that uses direct utility estimation
+ on a given MDP and policy.
+
+ import sys
+ from mdp import sequential_decision_environment
+ north = (0, 1)
+ south = (0,-1)
+ west = (-1, 0)
+ east = (1, 0)
+ policy = {(0, 2): east, (1, 2): east, (2, 2): east, (3, 2): None, (0, 1): north, (2, 1): north,
+ (3, 1): None, (0, 0): north, (1, 0): west, (2, 0): west, (3, 0): west,}
+ agent = PassiveDUEAgent(policy, sequential_decision_environment)
+ for i in range(200):
+ run_single_trial(agent,sequential_decision_environment)
+ agent.estimate_U()
+ agent.U[(0, 0)] > 0.2
+ True
+ """
+
+ def __init__(self, pi, mdp):
+ self.pi = pi
+ self.mdp = mdp
+ self.U = {}
+ self.s = None
+ self.a = None
+ self.s_history = []
+ self.r_history = []
+ self.init = mdp.init
+
+ def __call__(self, percept):
+ s1, r1 = percept
+ self.s_history.append(s1)
+ self.r_history.append(r1)
+ ##
+ ##
+ if s1 in self.mdp.terminals:
+ self.s = self.a = None
+ else:
+ self.s, self.a = s1, self.pi[s1]
+ return self.a
+
+ def estimate_U(self):
+ # this function can be called only if the MDP has reached a terminal state
+ # it will also reset the mdp history
+ assert self.a is None, 'MDP is not in terminal state'
+ assert len(self.s_history) == len(self.r_history)
+ # calculating the utilities based on the current iteration
+ U2 = {s: [] for s in set(self.s_history)}
+ for i in range(len(self.s_history)):
+ s = self.s_history[i]
+ U2[s] += [sum(self.r_history[i:])]
+ U2 = {k: sum(v) / max(len(v), 1) for k, v in U2.items()}
+ # resetting history
+ self.s_history, self.r_history = [], []
+ # setting the new utilities to the average of the previous
+ # iteration and this one
+ for k in U2.keys():
+ if k in self.U.keys():
+ self.U[k] = (self.U[k] + U2[k]) / 2
+ else:
+ self.U[k] = U2[k]
+ return self.U
+
+ def update_state(self, percept):
+ """To be overridden in most cases. The default case
+ assumes the percept to be of type (state, reward)"""
+ return percept
+
+
+class PassiveADPAgent:
+ """
+ [Figure 21.2]
+ Passive (non-learning) agent that uses adaptive dynamic programming
+ on a given MDP and policy.
+
+ import sys
+ from mdp import sequential_decision_environment
+ north = (0, 1)
+ south = (0,-1)
+ west = (-1, 0)
+ east = (1, 0)
+ policy = {(0, 2): east, (1, 2): east, (2, 2): east, (3, 2): None, (0, 1): north, (2, 1): north,
+ (3, 1): None, (0, 0): north, (1, 0): west, (2, 0): west, (3, 0): west,}
+ agent = PassiveADPAgent(policy, sequential_decision_environment)
+ for i in range(100):
+ run_single_trial(agent,sequential_decision_environment)
+
+ agent.U[(0, 0)] > 0.2
+ True
+ agent.U[(0, 1)] > 0.2
+ True
+ """
+
+ class ModelMDP(MDP):
+ """Class for implementing modified Version of input MDP with
+ an editable transition model P and a custom function T."""
+
+ def __init__(self, init, actlist, terminals, gamma, states):
+ super().__init__(init, actlist, terminals, states=states, gamma=gamma)
+ nested_dict = lambda: defaultdict(nested_dict)
+ # StackOverflow:whats-the-best-way-to-initialize-a-dict-of-dicts-in-python
+ self.P = nested_dict()
+
+ def T(self, s, a):
+ """Return a list of tuples with probabilities for states
+ based on the learnt model P."""
+ return [(prob, res) for (res, prob) in self.P[(s, a)].items()]
+
+ def __init__(self, pi, mdp):
+ self.pi = pi
+ self.mdp = PassiveADPAgent.ModelMDP(mdp.init, mdp.actlist,
+ mdp.terminals, mdp.gamma, mdp.states)
+ self.U = {}
+ self.Nsa = defaultdict(int)
+ self.Ns1_sa = defaultdict(int)
+ self.s = None
+ self.a = None
+ self.visited = set() # keeping track of visited states
+
+ def __call__(self, percept):
+ s1, r1 = percept
+ mdp = self.mdp
+ R, P, terminals, pi = mdp.reward, mdp.P, mdp.terminals, self.pi
+ s, a, Nsa, Ns1_sa, U = self.s, self.a, self.Nsa, self.Ns1_sa, self.U
+
+ if s1 not in self.visited: # Reward is only known for visited state.
+ U[s1] = R[s1] = r1
+ self.visited.add(s1)
+ if s is not None:
+ Nsa[(s, a)] += 1
+ Ns1_sa[(s1, s, a)] += 1
+ # for each t such that Ns′|sa [t, s, a] is nonzero
+ for t in [res for (res, state, act), freq in Ns1_sa.items()
+ if (state, act) == (s, a) and freq != 0]:
+ P[(s, a)][t] = Ns1_sa[(t, s, a)] / Nsa[(s, a)]
+
+ self.U = policy_evaluation(pi, U, mdp)
+ ##
+ ##
+ self.Nsa, self.Ns1_sa = Nsa, Ns1_sa
+ if s1 in terminals:
+ self.s = self.a = None
+ else:
+ self.s, self.a = s1, self.pi[s1]
+ return self.a
+
+ def update_state(self, percept):
+ """To be overridden in most cases. The default case
+ assumes the percept to be of type (state, reward)."""
+ return percept
+
+
+class PassiveTDAgent:
+ """
+ [Figure 21.4]
+ The abstract class for a Passive (non-learning) agent that uses
+ temporal differences to learn utility estimates. Override update_state
+ method to convert percept to state and reward. The mdp being provided
+ should be an instance of a subclass of the MDP Class.
+
+ import sys
+ from mdp import sequential_decision_environment
+ north = (0, 1)
+ south = (0,-1)
+ west = (-1, 0)
+ east = (1, 0)
+ policy = {(0, 2): east, (1, 2): east, (2, 2): east, (3, 2): None, (0, 1): north, (2, 1): north,
+ (3, 1): None, (0, 0): north, (1, 0): west, (2, 0): west, (3, 0): west,}
+ agent = PassiveTDAgent(policy, sequential_decision_environment, alpha=lambda n: 60./(59+n))
+ for i in range(200):
+ run_single_trial(agent,sequential_decision_environment)
+
+ agent.U[(0, 0)] > 0.2
+ True
+ agent.U[(0, 1)] > 0.2
+ True
+ """
+
+ def __init__(self, pi, mdp, alpha=None):
+
+ self.pi = pi
+ self.U = {s: 0. for s in mdp.states}
+ self.Ns = {s: 0 for s in mdp.states}
+ self.s = None
+ self.a = None
+ self.r = None
+ self.gamma = mdp.gamma
+ self.terminals = mdp.terminals
+
+ if alpha:
+ self.alpha = alpha
+ else:
+ self.alpha = lambda n: 1 / (1 + n) # udacity video
+
+ def __call__(self, percept):
+ s1, r1 = self.update_state(percept)
+ pi, U, Ns, s, r = self.pi, self.U, self.Ns, self.s, self.r
+ alpha, gamma, terminals = self.alpha, self.gamma, self.terminals
+ if not Ns[s1]:
+ U[s1] = r1
+ if s is not None:
+ Ns[s] += 1
+ U[s] += alpha(Ns[s]) * (r + gamma * U[s1] - U[s])
+ if s1 in terminals:
+ self.s = self.a = self.r = None
+ else:
+ self.s, self.a, self.r = s1, pi[s1], r1
+ return self.a
+
+ def update_state(self, percept):
+ """To be overridden in most cases. The default case
+ assumes the percept to be of type (state, reward)."""
+ return percept
+
+
+class QLearningAgent:
+ """
+ [Figure 21.8]
+ An exploratory Q-learning agent. It avoids having to learn the transition
+ model because the Q-value of a state can be related directly to those of
+ its neighbors.
+
+ import sys
+ from mdp import sequential_decision_environment
+ north = (0, 1)
+ south = (0,-1)
+ west = (-1, 0)
+ east = (1, 0)
+ policy = {(0, 2): east, (1, 2): east, (2, 2): east, (3, 2): None, (0, 1): north, (2, 1): north,
+ (3, 1): None, (0, 0): north, (1, 0): west, (2, 0): west, (3, 0): west,}
+ q_agent = QLearningAgent(sequential_decision_environment, Ne=5, Rplus=2, alpha=lambda n: 60./(59+n))
+ for i in range(200):
+ run_single_trial(q_agent,sequential_decision_environment)
+
+ q_agent.Q[((0, 1), (0, 1))] >= -0.5
+ True
+ q_agent.Q[((1, 0), (0, -1))] <= 0.5
+ True
+ """
+
+ def __init__(self, mdp, Ne, Rplus, alpha=None):
+
+ self.gamma = mdp.gamma
+ self.terminals = mdp.terminals
+ self.all_act = mdp.actlist
+ self.Ne = Ne # iteration limit in exploration function
+ self.Rplus = Rplus # large value to assign before iteration limit
+ self.Q = defaultdict(float)
+ self.Nsa = defaultdict(float)
+ self.s = None
+ self.a = None
+ self.r = None
+
+ if alpha:
+ self.alpha = alpha
+ else:
+ self.alpha = lambda n: 1. / (1 + n) # udacity video
+
+ def f(self, u, n):
+ """Exploration function. Returns fixed Rplus until
+ agent has visited state, action a Ne number of times.
+ Same as ADP agent in book."""
+ if n < self.Ne:
+ return self.Rplus
+ else:
+ return u
+
+ def actions_in_state(self, state):
+ """Return actions possible in given state.
+ Useful for max and argmax."""
+ if state in self.terminals:
+ return [None]
+ else:
+ return self.all_act
+
+ def __call__(self, percept):
+ s1, r1 = self.update_state(percept)
+ Q, Nsa, s, a, r = self.Q, self.Nsa, self.s, self.a, self.r
+ alpha, gamma, terminals = self.alpha, self.gamma, self.terminals,
+ actions_in_state = self.actions_in_state
+
+ if s in terminals:
+ Q[s, None] = r1
+ if s is not None:
+ Nsa[s, a] += 1
+ Q[s, a] += alpha(Nsa[s, a]) * (r + gamma * max(Q[s1, a1]
+ for a1 in actions_in_state(s1)) - Q[s, a])
+ if s in terminals:
+ self.s = self.a = self.r = None
+ else:
+ self.s, self.r = s1, r1
+ self.a = max(actions_in_state(s1), key=lambda a1: self.f(Q[s1, a1], Nsa[s1, a1]))
+ return self.a
+
+ def update_state(self, percept):
+ """To be overridden in most cases. The default case
+ assumes the percept to be of type (state, reward)."""
+ return percept
+
+
+def run_single_trial(agent_program, mdp):
+ """Execute trial for given agent_program
+ and mdp. mdp should be an instance of subclass
+ of mdp.MDP """
+
+ def take_single_action(mdp, s, a):
+ """
+ Select outcome of taking action a
+ in state s. Weighted Sampling.
+ """
+ x = random.uniform(0, 1)
+ cumulative_probability = 0.0
+ for probability_state in mdp.T(s, a):
+ probability, state = probability_state
+ cumulative_probability += probability
+ if x < cumulative_probability:
+ break
+ return state
+
+ current_state = mdp.init
+ while True:
+ current_reward = mdp.R(current_state)
+ percept = (current_state, current_reward)
+ next_action = agent_program(percept)
+ if next_action is None:
+ break
+ current_state = take_single_action(mdp, current_state, next_action)
diff --git a/reinforcement_learning4e.py b/reinforcement_learning4e.py
new file mode 100644
index 000000000..eaaba3e5a
--- /dev/null
+++ b/reinforcement_learning4e.py
@@ -0,0 +1,353 @@
+"""Reinforcement Learning (Chapter 21)"""
+
+import random
+from collections import defaultdict
+
+from mdp4e import MDP, policy_evaluation
+
+
+# _________________________________________
+# 21.2 Passive Reinforcement Learning
+# 21.2.1 Direct utility estimation
+
+
+class PassiveDUEAgent:
+ """
+ Passive (non-learning) agent that uses direct utility estimation
+ on a given MDP and policy.
+
+ import sys
+ from mdp import sequential_decision_environment
+ north = (0, 1)
+ south = (0,-1)
+ west = (-1, 0)
+ east = (1, 0)
+ policy = {(0, 2): east, (1, 2): east, (2, 2): east, (3, 2): None, (0, 1): north, (2, 1): north,
+ (3, 1): None, (0, 0): north, (1, 0): west, (2, 0): west, (3, 0): west,}
+ agent = PassiveDUEAgent(policy, sequential_decision_environment)
+ for i in range(200):
+ run_single_trial(agent,sequential_decision_environment)
+ agent.estimate_U()
+ agent.U[(0, 0)] > 0.2
+ True
+ """
+
+ def __init__(self, pi, mdp):
+ self.pi = pi
+ self.mdp = mdp
+ self.U = {}
+ self.s = None
+ self.a = None
+ self.s_history = []
+ self.r_history = []
+ self.init = mdp.init
+
+ def __call__(self, percept):
+ s1, r1 = percept
+ self.s_history.append(s1)
+ self.r_history.append(r1)
+ ##
+ ##
+ if s1 in self.mdp.terminals:
+ self.s = self.a = None
+ else:
+ self.s, self.a = s1, self.pi[s1]
+ return self.a
+
+ def estimate_U(self):
+ # this function can be called only if the MDP has reached a terminal state
+ # it will also reset the mdp history
+ assert self.a is None, 'MDP is not in terminal state'
+ assert len(self.s_history) == len(self.r_history)
+ # calculating the utilities based on the current iteration
+ U2 = {s: [] for s in set(self.s_history)}
+ for i in range(len(self.s_history)):
+ s = self.s_history[i]
+ U2[s] += [sum(self.r_history[i:])]
+ U2 = {k: sum(v) / max(len(v), 1) for k, v in U2.items()}
+ # resetting history
+ self.s_history, self.r_history = [], []
+ # setting the new utilities to the average of the previous
+ # iteration and this one
+ for k in U2.keys():
+ if k in self.U.keys():
+ self.U[k] = (self.U[k] + U2[k]) / 2
+ else:
+ self.U[k] = U2[k]
+ return self.U
+
+ def update_state(self, percept):
+ """To be overridden in most cases. The default case
+ assumes the percept to be of type (state, reward)"""
+ return percept
+
+
+# 21.2.2 Adaptive dynamic programming
+
+
+class PassiveADPAgent:
+ """
+ [Figure 21.2]
+ Passive (non-learning) agent that uses adaptive dynamic programming
+ on a given MDP and policy.
+
+ import sys
+ from mdp import sequential_decision_environment
+ north = (0, 1)
+ south = (0,-1)
+ west = (-1, 0)
+ east = (1, 0)
+ policy = {(0, 2): east, (1, 2): east, (2, 2): east, (3, 2): None, (0, 1): north, (2, 1): north,
+ (3, 1): None, (0, 0): north, (1, 0): west, (2, 0): west, (3, 0): west,}
+ agent = PassiveADPAgent(policy, sequential_decision_environment)
+ for i in range(100):
+ run_single_trial(agent,sequential_decision_environment)
+
+ agent.U[(0, 0)] > 0.2
+ True
+ agent.U[(0, 1)] > 0.2
+ True
+ """
+
+ class ModelMDP(MDP):
+ """Class for implementing modified Version of input MDP with
+ an editable transition model P and a custom function T."""
+
+ def __init__(self, init, actlist, terminals, gamma, states):
+ super().__init__(init, actlist, terminals, states=states, gamma=gamma)
+ nested_dict = lambda: defaultdict(nested_dict)
+ # StackOverflow:whats-the-best-way-to-initialize-a-dict-of-dicts-in-python
+ self.P = nested_dict()
+
+ def T(self, s, a):
+ """Return a list of tuples with probabilities for states
+ based on the learnt model P."""
+ return [(prob, res) for (res, prob) in self.P[(s, a)].items()]
+
+ def __init__(self, pi, mdp):
+ self.pi = pi
+ self.mdp = PassiveADPAgent.ModelMDP(mdp.init, mdp.actlist,
+ mdp.terminals, mdp.gamma, mdp.states)
+ self.U = {}
+ self.Nsa = defaultdict(int)
+ self.Ns1_sa = defaultdict(int)
+ self.s = None
+ self.a = None
+ self.visited = set() # keeping track of visited states
+
+ def __call__(self, percept):
+ s1, r1 = percept
+ mdp = self.mdp
+ R, P, terminals, pi = mdp.reward, mdp.P, mdp.terminals, self.pi
+ s, a, Nsa, Ns1_sa, U = self.s, self.a, self.Nsa, self.Ns1_sa, self.U
+
+ if s1 not in self.visited: # Reward is only known for visited state.
+ U[s1] = R[s1] = r1
+ self.visited.add(s1)
+ if s is not None:
+ Nsa[(s, a)] += 1
+ Ns1_sa[(s1, s, a)] += 1
+ # for each t such that Ns′|sa [t, s, a] is nonzero
+ for t in [res for (res, state, act), freq in Ns1_sa.items()
+ if (state, act) == (s, a) and freq != 0]:
+ P[(s, a)][t] = Ns1_sa[(t, s, a)] / Nsa[(s, a)]
+
+ self.U = policy_evaluation(pi, U, mdp)
+ ##
+ ##
+ self.Nsa, self.Ns1_sa = Nsa, Ns1_sa
+ if s1 in terminals:
+ self.s = self.a = None
+ else:
+ self.s, self.a = s1, self.pi[s1]
+ return self.a
+
+ def update_state(self, percept):
+ """To be overridden in most cases. The default case
+ assumes the percept to be of type (state, reward)."""
+ return percept
+
+
+# 21.2.3 Temporal-difference learning
+
+
+class PassiveTDAgent:
+ """
+ [Figure 21.4]
+ The abstract class for a Passive (non-learning) agent that uses
+ temporal differences to learn utility estimates. Override update_state
+ method to convert percept to state and reward. The mdp being provided
+ should be an instance of a subclass of the MDP Class.
+
+ import sys
+ from mdp import sequential_decision_environment
+ north = (0, 1)
+ south = (0,-1)
+ west = (-1, 0)
+ east = (1, 0)
+ policy = {(0, 2): east, (1, 2): east, (2, 2): east, (3, 2): None, (0, 1): north, (2, 1): north,
+ (3, 1): None, (0, 0): north, (1, 0): west, (2, 0): west, (3, 0): west,}
+ agent = PassiveTDAgent(policy, sequential_decision_environment, alpha=lambda n: 60./(59+n))
+ for i in range(200):
+ run_single_trial(agent,sequential_decision_environment)
+
+ agent.U[(0, 0)] > 0.2
+ True
+ agent.U[(0, 1)] > 0.2
+ True
+ """
+
+ def __init__(self, pi, mdp, alpha=None):
+
+ self.pi = pi
+ self.U = {s: 0. for s in mdp.states}
+ self.Ns = {s: 0 for s in mdp.states}
+ self.s = None
+ self.a = None
+ self.r = None
+ self.gamma = mdp.gamma
+ self.terminals = mdp.terminals
+
+ if alpha:
+ self.alpha = alpha
+ else:
+ self.alpha = lambda n: 1 / (1 + n) # udacity video
+
+ def __call__(self, percept):
+ s1, r1 = self.update_state(percept)
+ pi, U, Ns, s, r = self.pi, self.U, self.Ns, self.s, self.r
+ alpha, gamma, terminals = self.alpha, self.gamma, self.terminals
+ if not Ns[s1]:
+ U[s1] = r1
+ if s is not None:
+ Ns[s] += 1
+ U[s] += alpha(Ns[s]) * (r + gamma * U[s1] - U[s])
+ if s1 in terminals:
+ self.s = self.a = self.r = None
+ else:
+ self.s, self.a, self.r = s1, pi[s1], r1
+ return self.a
+
+ def update_state(self, percept):
+ """To be overridden in most cases. The default case
+ assumes the percept to be of type (state, reward)."""
+ return percept
+
+
+# __________________________________________
+# 21.3. Active Reinforcement Learning
+# 21.3.2 Learning an action-utility function
+
+
+class QLearningAgent:
+ """
+ [Figure 21.8]
+ An exploratory Q-learning agent. It avoids having to learn the transition
+ model because the Q-value of a state can be related directly to those of
+ its neighbors.
+
+ import sys
+ from mdp import sequential_decision_environment
+ north = (0, 1)
+ south = (0,-1)
+ west = (-1, 0)
+ east = (1, 0)
+ policy = {(0, 2): east, (1, 2): east, (2, 2): east, (3, 2): None, (0, 1): north, (2, 1): north,
+ (3, 1): None, (0, 0): north, (1, 0): west, (2, 0): west, (3, 0): west,}
+ q_agent = QLearningAgent(sequential_decision_environment, Ne=5, Rplus=2, alpha=lambda n: 60./(59+n))
+ for i in range(200):
+ run_single_trial(q_agent,sequential_decision_environment)
+
+ q_agent.Q[((0, 1), (0, 1))] >= -0.5
+ True
+ q_agent.Q[((1, 0), (0, -1))] <= 0.5
+ True
+ """
+
+ def __init__(self, mdp, Ne, Rplus, alpha=None):
+
+ self.gamma = mdp.gamma
+ self.terminals = mdp.terminals
+ self.all_act = mdp.actlist
+ self.Ne = Ne # iteration limit in exploration function
+ self.Rplus = Rplus # large value to assign before iteration limit
+ self.Q = defaultdict(float)
+ self.Nsa = defaultdict(float)
+ self.s = None
+ self.a = None
+ self.r = None
+
+ if alpha:
+ self.alpha = alpha
+ else:
+ self.alpha = lambda n: 1. / (1 + n) # udacity video
+
+ def f(self, u, n):
+ """Exploration function. Returns fixed Rplus until
+ agent has visited state, action a Ne number of times.
+ Same as ADP agent in book."""
+ if n < self.Ne:
+ return self.Rplus
+ else:
+ return u
+
+ def actions_in_state(self, state):
+ """Return actions possible in given state.
+ Useful for max and argmax."""
+ if state in self.terminals:
+ return [None]
+ else:
+ return self.all_act
+
+ def __call__(self, percept):
+ s1, r1 = self.update_state(percept)
+ Q, Nsa, s, a, r = self.Q, self.Nsa, self.s, self.a, self.r
+ alpha, gamma, terminals = self.alpha, self.gamma, self.terminals,
+ actions_in_state = self.actions_in_state
+
+ if s in terminals:
+ Q[s, None] = r1
+ if s is not None:
+ Nsa[s, a] += 1
+ Q[s, a] += alpha(Nsa[s, a]) * (r + gamma * max(Q[s1, a1]
+ for a1 in actions_in_state(s1)) - Q[s, a])
+ if s in terminals:
+ self.s = self.a = self.r = None
+ else:
+ self.s, self.r = s1, r1
+ self.a = max(actions_in_state(s1), key=lambda a1: self.f(Q[s1, a1], Nsa[s1, a1]))
+ return self.a
+
+ def update_state(self, percept):
+ """To be overridden in most cases. The default case
+ assumes the percept to be of type (state, reward)."""
+ return percept
+
+
+def run_single_trial(agent_program, mdp):
+ """Execute trial for given agent_program
+ and mdp. mdp should be an instance of subclass
+ of mdp.MDP """
+
+ def take_single_action(mdp, s, a):
+ """
+ Select outcome of taking action a
+ in state s. Weighted Sampling.
+ """
+ x = random.uniform(0, 1)
+ cumulative_probability = 0.0
+ for probability_state in mdp.T(s, a):
+ probability, state = probability_state
+ cumulative_probability += probability
+ if x < cumulative_probability:
+ break
+ return state
+
+ current_state = mdp.init
+ while True:
+ current_reward = mdp.R(current_state)
+ percept = (current_state, current_reward)
+ next_action = agent_program(percept)
+ if next_action is None:
+ break
+ current_state = take_single_action(mdp, current_state, next_action)
diff --git a/requirements.txt b/requirements.txt
index c4a6dd78f..dd6b1be8a 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1 +1,18 @@
-networkx==1.11
\ No newline at end of file
+cvxopt
+image
+ipython
+ipythonblocks
+ipywidgets
+jupyter
+keras
+matplotlib
+networkx
+numpy
+opencv-python
+pandas
+pillow
+pytest-cov
+qpsolvers
+scipy
+sortedcontainers
+tensorflow
\ No newline at end of file
diff --git a/rl.ipynb b/rl.ipynb
deleted file mode 100644
index 103c32e9e..000000000
--- a/rl.ipynb
+++ /dev/null
@@ -1,590 +0,0 @@
-{
- "cells": [
- {
- "cell_type": "markdown",
- "metadata": {
- "collapsed": false
- },
- "source": [
- "# Reinforcement Learning\n",
- "\n",
- "This IPy notebook acts as supporting material for **Chapter 21 Reinforcement Learning** of the book* Artificial Intelligence: A Modern Approach*. This notebook makes use of the implementations in rl.py module. We also make use of implementation of MDPs in the mdp.py module to test our agents. It might be helpful if you have already gone through the IPy notebook dealing with Markov decision process. Let us import everything from the rl module. It might be helpful to view the source of some of our implementations. Please refer to the Introductory IPy file for more details."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 1,
- "metadata": {
- "collapsed": true
- },
- "outputs": [],
- "source": [
- "from rl import *"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "collapsed": true
- },
- "source": [
- "## Review\n",
- "Before we start playing with the actual implementations let us review a couple of things about RL.\n",
- "\n",
- "1. Reinforcement Learning is concerned with how software agents ought to take actions in an environment so as to maximize some notion of cumulative reward. \n",
- "\n",
- "2. Reinforcement learning differs from standard supervised learning in that correct input/output pairs are never presented, nor sub-optimal actions explicitly corrected. Further, there is a focus on on-line performance, which involves finding a balance between exploration (of uncharted territory) and exploitation (of current knowledge).\n",
- "\n",
- "-- Source: [Wikipedia](https://en.wikipedia.org/wiki/Reinforcement_learning)\n",
- "\n",
- "In summary we have a sequence of state action transitions with rewards associated with some states. Our goal is to find the optimal policy (pi) which tells us what action to take in each state."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Passive Reinforcement Learning\n",
- "\n",
- "In passive Reinforcement Learning the agent follows a fixed policy and tries to learn the Reward function and the Transition model (if it is not aware of that).\n",
- "\n"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "### Passive Temporal Difference Agent\n",
- "\n",
- "The PassiveTDAgent class in the rl module implements the Agent Program (notice the usage of word Program) described in **Fig 21.4** of the AIMA Book. PassiveTDAgent uses temporal differences to learn utility estimates. In simple terms we learn the difference between the states and backup the values to previous states while following a fixed policy. Let us look into the source before we see some usage examples."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 2,
- "metadata": {
- "collapsed": true
- },
- "outputs": [],
- "source": [
- "%psource PassiveTDAgent"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The Agent Program can be obtained by creating the instance of the class by passing the appropriate parameters. Because of the __ call __ method the object that is created behaves like a callable and returns an appropriate action as most Agent Programs do. To instantiate the object we need a policy(pi) and a mdp whose utility of states will be estimated. Let us import a GridMDP object from the mdp module. **Figure 17.1 (sequential_decision_environment)** is similar to **Figure 21.1** but has some discounting as **gamma = 0.9**."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 3,
- "metadata": {
- "collapsed": false
- },
- "outputs": [],
- "source": [
- "from mdp import sequential_decision_environment"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 4,
- "metadata": {
- "collapsed": false
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- " Now we define a policy similar to **Fig 21.1** in the book."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 5,
- "metadata": {
- "collapsed": true
- },
- "outputs": [],
- "source": [
- "# Action Directions\n",
- "north = (0, 1)\n",
- "south = (0,-1)\n",
- "west = (-1, 0)\n",
- "east = (1, 0)\n",
- "\n",
- "policy = {\n",
- " (0, 2): east, (1, 2): east, (2, 2): east, (3, 2): None,\n",
- " (0, 1): north, (2, 1): north, (3, 1): None,\n",
- " (0, 0): north, (1, 0): west, (2, 0): west, (3, 0): west, \n",
- "}\n"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Let us create our object now. We also use the **same alpha** as given in the footnote of the book on **page 837**."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 6,
- "metadata": {
- "collapsed": true
- },
- "outputs": [],
- "source": [
- "our_agent = PassiveTDAgent(policy, sequential_decision_environment, alpha=lambda n: 60./(59+n))"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The rl module also has a simple implementation to simulate iterations. The function is called **run_single_trial**. Now we can try our implementation. We can also compare the utility estimates learned by our agent to those obtained via **value iteration**.\n"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 7,
- "metadata": {
- "collapsed": true
- },
- "outputs": [],
- "source": [
- "from mdp import value_iteration"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The values calculated by value iteration:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 8,
- "metadata": {
- "collapsed": false
- },
- "outputs": [
- {
- "name": "stdout",
- "output_type": "stream",
- "text": [
- "{(0, 1): 0.3984432178350045, (1, 2): 0.649585681261095, (3, 2): 1.0, (0, 0): 0.2962883154554812, (3, 0): 0.12987274656746342, (3, 1): -1.0, (2, 1): 0.48644001739269643, (2, 0): 0.3447542300124158, (2, 2): 0.7953620878466678, (1, 0): 0.25386699846479516, (0, 2): 0.5093943765842497}\n"
- ]
- }
- ],
- "source": [
- "print(value_iteration(sequential_decision_environment))"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Now the values estimated by our agent after **200 trials**."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 9,
- "metadata": {
- "collapsed": false
- },
- "outputs": [
- {
- "name": "stdout",
- "output_type": "stream",
- "text": [
- "{(0, 1): 0.4496668011879283, (1, 2): 0.619085803445832, (3, 2): 1, (0, 0): 0.32062531035042224, (2, 0): 0.0, (3, 0): 0.0, (1, 0): 0.235638474671875, (3, 1): -1, (2, 2): 0.7597530664991547, (2, 1): 0.4275522091676434, (0, 2): 0.5333144285450669}\n"
- ]
- }
- ],
- "source": [
- "for i in range(200):\n",
- " run_single_trial(our_agent,sequential_decision_environment)\n",
- "print(our_agent.U)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "We can also explore how these estimates vary with time by using plots similar to **Fig 21.5a**. To do so we define a function to help us with the same. We will first enable matplotlib using the inline backend."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 10,
- "metadata": {
- "collapsed": false
- },
- "outputs": [],
- "source": [
- "%matplotlib inline\n",
- "import matplotlib.pyplot as plt\n",
- "\n",
- "def graph_utility_estimates(agent_program, mdp, no_of_iterations, states_to_graph):\n",
- " graphs = {state:[] for state in states_to_graph}\n",
- " for iteration in range(1,no_of_iterations+1):\n",
- " run_single_trial(agent_program, mdp)\n",
- " for state in states_to_graph:\n",
- " graphs[state].append((iteration, agent_program.U[state]))\n",
- " for state, value in graphs.items():\n",
- " state_x, state_y = zip(*value)\n",
- " plt.plot(state_x, state_y, label=str(state))\n",
- " plt.ylim([0,1.2])\n",
- " plt.legend(loc='lower right')\n",
- " plt.xlabel('Iterations')\n",
- " plt.ylabel('U')"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Here is a plot of state (2,2)."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 11,
- "metadata": {
- "collapsed": false
- },
- "outputs": [
- {
- "data": {
- "image/png": "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\nQhWsAAAAAElFTkSuQmCC\n",
- "text/plain": [
- "\n",
- "\n",
- "A state-space search problem can be represented by a *graph*, where the vertexes of the graph are the states of the problem (in this case, cities) and the edges of the graph are the actions (in this case, driving along a road).\n",
- "\n",
- "We'll represent a city by its single initial letter. \n",
- "We'll represent the graph of connections as a `dict` that maps each city to a list of the neighboring cities (connected by a road). For now we don't explicitly represent the actions, nor the distances\n",
- "between cities."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 1,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [],
- "source": [
- "romania = {\n",
- " 'A': ['Z', 'T', 'S'],\n",
- " 'B': ['F', 'P', 'G', 'U'],\n",
- " 'C': ['D', 'R', 'P'],\n",
- " 'D': ['M', 'C'],\n",
- " 'E': ['H'],\n",
- " 'F': ['S', 'B'],\n",
- " 'G': ['B'],\n",
- " 'H': ['U', 'E'],\n",
- " 'I': ['N', 'V'],\n",
- " 'L': ['T', 'M'],\n",
- " 'M': ['L', 'D'],\n",
- " 'N': ['I'],\n",
- " 'O': ['Z', 'S'],\n",
- " 'P': ['R', 'C', 'B'],\n",
- " 'R': ['S', 'C', 'P'],\n",
- " 'S': ['A', 'O', 'F', 'R'],\n",
- " 'T': ['A', 'L'],\n",
- " 'U': ['B', 'V', 'H'],\n",
- " 'V': ['U', 'I'],\n",
- " 'Z': ['O', 'A']}"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "button": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "source": [
- "Suppose we want to get from `A` to `B`. Where can we go from the start state, `A`?"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 2,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- "['Z', 'T', 'S']"
- ]
- },
- "execution_count": 2,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "romania['A']"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "button": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "source": [
- "We see that from `A` we can get to any of the three cities `['Z', 'T', 'S']`. Which should we choose? *We don't know.* That's the whole point of *search*: we don't know which immediate action is best, so we'll have to explore, until we find a *path* that leads to the goal. \n",
- "\n",
- "How do we explore? We'll start with a simple algorithm that will get us from `A` to `B`. We'll keep a *frontier*—a collection of not-yet-explored states—and expand the frontier outward until it reaches the goal. To be more precise:\n",
- "\n",
- "- Initially, the only state in the frontier is the start state, `'A'`.\n",
- "- Until we reach the goal, or run out of states in the frontier to explore, do the following:\n",
- " - Remove the first state from the frontier. Call it `s`.\n",
- " - If `s` is the goal, we're done. Return the path to `s`.\n",
- " - Otherwise, consider all the neighboring states of `s`. For each one:\n",
- " - If we have not previously explored the state, add it to the end of the frontier.\n",
- " - Also keep track of the previous state that led to this new neighboring state; we'll need this to reconstruct the path to the goal, and to keep us from re-visiting previously explored states.\n",
- " \n",
- "# A Simple Search Algorithm: `breadth_first`\n",
- " \n",
- "The function `breadth_first` implements this strategy:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 3,
- "metadata": {
- "button": false,
- "collapsed": true,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [],
- "source": [
- "from collections import deque # Doubly-ended queue: pop from left, append to right.\n",
- "\n",
- "def breadth_first(start, goal, neighbors):\n",
- " \"Find a shortest sequence of states from start to the goal.\"\n",
- " frontier = deque([start]) # A queue of states\n",
- " previous = {start: None} # start has no previous state; other states will\n",
- " while frontier:\n",
- " s = frontier.popleft()\n",
- " if s == goal:\n",
- " return path(previous, s)\n",
- " for s2 in neighbors[s]:\n",
- " if s2 not in previous:\n",
- " frontier.append(s2)\n",
- " previous[s2] = s\n",
- " \n",
- "def path(previous, s): \n",
- " \"Return a list of states that lead to state s, according to the previous dict.\"\n",
- " return [] if (s is None) else path(previous, previous[s]) + [s]"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "button": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "source": [
- "A couple of things to note: \n",
- "\n",
- "1. We always add new states to the end of the frontier queue. That means that all the states that are adjacent to the start state will come first in the queue, then all the states that are two steps away, then three steps, etc.\n",
- "That's what we mean by *breadth-first* search.\n",
- "2. We recover the path to an `end` state by following the trail of `previous[end]` pointers, all the way back to `start`.\n",
- "The dict `previous` is a map of `{state: previous_state}`. \n",
- "3. When we finally get an `s` that is the goal state, we know we have found a shortest path, because any other state in the queue must correspond to a path that is as long or longer.\n",
- "3. Note that `previous` contains all the states that are currently in `frontier` as well as all the states that were in `frontier` in the past.\n",
- "4. If no path to the goal is found, then `breadth_first` returns `None`. If a path is found, it returns the sequence of states on the path.\n",
- "\n",
- "Some examples:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 4,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- "['A', 'S', 'F', 'B']"
- ]
- },
- "execution_count": 4,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "breadth_first('A', 'B', romania)"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 5,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- "['L', 'T', 'A', 'S', 'F', 'B', 'U', 'V', 'I', 'N']"
- ]
- },
- "execution_count": 5,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "breadth_first('L', 'N', romania)"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 6,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- "['N', 'I', 'V', 'U', 'B', 'F', 'S', 'A', 'T', 'L']"
- ]
- },
- "execution_count": 6,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "breadth_first('N', 'L', romania)"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 7,
- "metadata": {
- "collapsed": false
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- "['E']"
- ]
- },
- "execution_count": 7,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "breadth_first('E', 'E', romania)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "button": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "source": [
- "Now let's try a different kind of problem that can be solved with the same search function.\n",
- "\n",
- "## Word Ladders Problem\n",
- "\n",
- "A *word ladder* problem is this: given a start word and a goal word, find the shortest way to transform the start word into the goal word by changing one letter at a time, such that each change results in a word. For example starting with `green` we can reach `grass` in 7 steps:\n",
- "\n",
- "`green` → `greed` → `treed` → `trees` → `tress` → `cress` → `crass` → `grass`\n",
- "\n",
- "We will need a dictionary of words. We'll use 5-letter words from the [Stanford GraphBase](http://www-cs-faculty.stanford.edu/~uno/sgb.html) project for this purpose. Let's get that file from aimadata."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 8,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [],
- "source": [
- "from search import *\n",
- "sgb_words = DataFile(\"EN-text/sgb-words.txt\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "button": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "source": [
- "We can assign `WORDS` to be the set of all the words in this file:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 9,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- "5757"
- ]
- },
- "execution_count": 9,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "WORDS = set(sgb_words.read().split())\n",
- "len(WORDS)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "button": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "source": [
- "And define `neighboring_words` to return the set of all words that are a one-letter change away from a given `word`:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 10,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [],
- "source": [
- "def neighboring_words(word):\n",
- " \"All words that are one letter away from this word.\"\n",
- " neighbors = {word[:i] + c + word[i+1:]\n",
- " for i in range(len(word))\n",
- " for c in 'abcdefghijklmnopqrstuvwxyz'\n",
- " if c != word[i]}\n",
- " return neighbors & WORDS"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "For example:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 11,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- "{'cello', 'hallo', 'hells', 'hullo', 'jello'}"
- ]
- },
- "execution_count": 11,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "neighboring_words('hello')"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 12,
- "metadata": {
- "collapsed": false
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- "{'would'}"
- ]
- },
- "execution_count": 12,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "neighboring_words('world')"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "button": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "source": [
- "Now we can create `word_neighbors` as a dict of `{word: {neighboring_word, ...}}`: "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 13,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [],
- "source": [
- "word_neighbors = {word: neighboring_words(word)\n",
- " for word in WORDS}"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "button": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "source": [
- "Now the `breadth_first` function can be used to solve a word ladder problem:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 14,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- "['green', 'greed', 'treed', 'trees', 'treys', 'greys', 'grays', 'grass']"
- ]
- },
- "execution_count": 14,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "breadth_first('green', 'grass', word_neighbors)"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 15,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- "['smart',\n",
- " 'start',\n",
- " 'stars',\n",
- " 'sears',\n",
- " 'bears',\n",
- " 'beans',\n",
- " 'brans',\n",
- " 'brand',\n",
- " 'braid',\n",
- " 'brain']"
- ]
- },
- "execution_count": 15,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "breadth_first('smart', 'brain', word_neighbors)"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 16,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- "['frown',\n",
- " 'flown',\n",
- " 'flows',\n",
- " 'slows',\n",
- " 'stows',\n",
- " 'stoas',\n",
- " 'stoae',\n",
- " 'stole',\n",
- " 'stile',\n",
- " 'smile']"
- ]
- },
- "execution_count": 16,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "breadth_first('frown', 'smile', word_neighbors)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "button": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "source": [
- "# More General Search Algorithms\n",
- "\n",
- "Now we'll embelish the `breadth_first` algorithm to make a family of search algorithms with more capabilities:\n",
- "\n",
- "1. We distinguish between an *action* and the *result* of an action.\n",
- "3. We allow different measures of the cost of a solution (not just the number of steps in the sequence).\n",
- "4. We search through the state space in an order that is more likely to lead to an optimal solution quickly.\n",
- "\n",
- "Here's how we do these things:\n",
- "\n",
- "1. Instead of having a graph of neighboring states, we instead have an object of type *Problem*. A Problem\n",
- "has one method, `Problem.actions(state)` to return a collection of the actions that are allowed in a state,\n",
- "and another method, `Problem.result(state, action)` that says what happens when you take an action.\n",
- "2. We keep a set, `explored` of states that have already been explored. We also have a class, `Frontier`, that makes it efficient to ask if a state is on the frontier.\n",
- "3. Each action has a cost associated with it (in fact, the cost can vary with both the state and the action).\n",
- "4. The `Frontier` class acts as a priority queue, allowing the \"best\" state to be explored next.\n",
- "We represent a sequence of actions and resulting states as a linked list of `Node` objects.\n",
- "\n",
- "The algorithm `breadth_first_search` is basically the same as `breadth_first`, but using our new conventions:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 17,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [],
- "source": [
- "def breadth_first_search(problem):\n",
- " \"Search for goal; paths with least number of steps first.\"\n",
- " if problem.is_goal(problem.initial): \n",
- " return Node(problem.initial)\n",
- " frontier = FrontierQ(Node(problem.initial), LIFO=False)\n",
- " explored = set()\n",
- " while frontier:\n",
- " node = frontier.pop()\n",
- " explored.add(node.state)\n",
- " for action in problem.actions(node.state):\n",
- " child = node.child(problem, action)\n",
- " if child.state not in explored and child.state not in frontier:\n",
- " if problem.is_goal(child.state):\n",
- " return child\n",
- " frontier.add(child)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Next is `uniform_cost_search`, in which each step can have a different cost, and we still consider first one os the states with minimum cost so far."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 18,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [],
- "source": [
- "def uniform_cost_search(problem, costfn=lambda node: node.path_cost):\n",
- " frontier = FrontierPQ(Node(problem.initial), costfn)\n",
- " explored = set()\n",
- " while frontier:\n",
- " node = frontier.pop()\n",
- " if problem.is_goal(node.state):\n",
- " return node\n",
- " explored.add(node.state)\n",
- " for action in problem.actions(node.state):\n",
- " child = node.child(problem, action)\n",
- " if child.state not in explored and child not in frontier:\n",
- " frontier.add(child)\n",
- " elif child in frontier and frontier.cost[child] < child.path_cost:\n",
- " frontier.replace(child)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Finally, `astar_search` in which the cost includes an estimate of the distance to the goal as well as the distance travelled so far."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 19,
- "metadata": {
- "button": false,
- "collapsed": true,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [],
- "source": [
- "def astar_search(problem, heuristic):\n",
- " costfn = lambda node: node.path_cost + heuristic(node.state)\n",
- " return uniform_cost_search(problem, costfn)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "button": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "source": [
- "# Search Tree Nodes\n",
- "\n",
- "The solution to a search problem is now a linked list of `Node`s, where each `Node`\n",
- "includes a `state` and the `path_cost` of getting to the state. In addition, for every `Node` except for the first (root) `Node`, there is a previous `Node` (indicating the state that lead to this `Node`) and an `action` (indicating the action taken to get here)."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 20,
- "metadata": {
- "button": false,
- "collapsed": false,
- "deletable": true,
- "new_sheet": false,
- "run_control": {
- "read_only": false
- }
- },
- "outputs": [],
- "source": [
- "class Node(object):\n",
- " \"\"\"A node in a search tree. A search tree is spanning tree over states.\n",
- " A Node contains a state, the previous node in the tree, the action that\n",
- " takes us from the previous state to this state, and the path cost to get to \n",
- " this state. If a state is arrived at by two paths, then there are two nodes \n",
- " with the same state.\"\"\"\n",
- "\n",
- " def __init__(self, state, previous=None, action=None, step_cost=1):\n",
- " \"Create a search tree Node, derived from a previous Node by an action.\"\n",
- " self.state = state\n",
- " self.previous = previous\n",
- " self.action = action\n",
- " self.path_cost = 0 if previous is None else (previous.path_cost + step_cost)\n",
- "\n",
- " def __repr__(self): return \"class Problem(object):\n",
+ "\n",
+ " """The abstract class for a formal problem. You should subclass\n",
+ " this and implement the methods actions and result, and possibly\n",
+ " __init__, goal_test, and path_cost. Then you will create instances\n",
+ " of your subclass and solve them with the various search functions."""\n",
+ "\n",
+ " def __init__(self, initial, goal=None):\n",
+ " """The constructor specifies the initial state, and possibly a goal\n",
+ " state, if there is a unique goal. Your subclass's constructor can add\n",
+ " other arguments."""\n",
+ " self.initial = initial\n",
+ " self.goal = goal\n",
+ "\n",
+ " def actions(self, state):\n",
+ " """Return the actions that can be executed in the given\n",
+ " state. The result would typically be a list, but if there are\n",
+ " many actions, consider yielding them one at a time in an\n",
+ " iterator, rather than building them all at once."""\n",
+ " raise NotImplementedError\n",
+ "\n",
+ " def result(self, state, action):\n",
+ " """Return the state that results from executing the given\n",
+ " action in the given state. The action must be one of\n",
+ " self.actions(state)."""\n",
+ " raise NotImplementedError\n",
+ "\n",
+ " def goal_test(self, state):\n",
+ " """Return True if the state is a goal. The default method compares the\n",
+ " state to self.goal or checks for state in self.goal if it is a\n",
+ " list, as specified in the constructor. Override this method if\n",
+ " checking against a single self.goal is not enough."""\n",
+ " if isinstance(self.goal, list):\n",
+ " return is_in(state, self.goal)\n",
+ " else:\n",
+ " return state == self.goal\n",
+ "\n",
+ " def path_cost(self, c, state1, action, state2):\n",
+ " """Return the cost of a solution path that arrives at state2 from\n",
+ " state1 via action, assuming cost c to get up to state1. If the problem\n",
+ " is such that the path doesn't matter, this function will only look at\n",
+ " state2. If the path does matter, it will consider c and maybe state1\n",
+ " and action. The default method costs 1 for every step in the path."""\n",
+ " return c + 1\n",
+ "\n",
+ " def value(self, state):\n",
+ " """For optimization problems, each state has a value. Hill-climbing\n",
+ " and related algorithms try to maximize this value."""\n",
+ " raise NotImplementedError\n",
+ "class Node:\n",
+ "\n",
+ " """A node in a search tree. Contains a pointer to the parent (the node\n",
+ " that this is a successor of) and to the actual state for this node. Note\n",
+ " that if a state is arrived at by two paths, then there are two nodes with\n",
+ " the same state. Also includes the action that got us to this state, and\n",
+ " the total path_cost (also known as g) to reach the node. Other functions\n",
+ " may add an f and h value; see best_first_graph_search and astar_search for\n",
+ " an explanation of how the f and h values are handled. You will not need to\n",
+ " subclass this class."""\n",
+ "\n",
+ " def __init__(self, state, parent=None, action=None, path_cost=0):\n",
+ " """Create a search tree Node, derived from a parent by an action."""\n",
+ " self.state = state\n",
+ " self.parent = parent\n",
+ " self.action = action\n",
+ " self.path_cost = path_cost\n",
+ " self.depth = 0\n",
+ " if parent:\n",
+ " self.depth = parent.depth + 1\n",
+ "\n",
+ " def __repr__(self):\n",
+ " return "<Node {}>".format(self.state)\n",
+ "\n",
+ " def __lt__(self, node):\n",
+ " return self.state < node.state\n",
+ "\n",
+ " def expand(self, problem):\n",
+ " """List the nodes reachable in one step from this node."""\n",
+ " return [self.child_node(problem, action)\n",
+ " for action in problem.actions(self.state)]\n",
+ "\n",
+ " def child_node(self, problem, action):\n",
+ " """[Figure 3.10]"""\n",
+ " next_state = problem.result(self.state, action)\n",
+ " next_node = Node(next_state, self, action,\n",
+ " problem.path_cost(self.path_cost, self.state,\n",
+ " action, next_state))\n",
+ " return next_node\n",
+ " \n",
+ " def solution(self):\n",
+ " """Return the sequence of actions to go from the root to this node."""\n",
+ " return [node.action for node in self.path()[1:]]\n",
+ "\n",
+ " def path(self):\n",
+ " """Return a list of nodes forming the path from the root to this node."""\n",
+ " node, path_back = self, []\n",
+ " while node:\n",
+ " path_back.append(node)\n",
+ " node = node.parent\n",
+ " return list(reversed(path_back))\n",
+ "\n",
+ " # We want for a queue of nodes in breadth_first_graph_search or\n",
+ " # astar_search to have no duplicated states, so we treat nodes\n",
+ " # with the same state as equal. [Problem: this may not be what you\n",
+ " # want in other contexts.]\n",
+ "\n",
+ " def __eq__(self, other):\n",
+ " return isinstance(other, Node) and self.state == other.state\n",
+ "\n",
+ " def __hash__(self):\n",
+ " return hash(self.state)\n",
+ "class GraphProblem(Problem):\n",
+ "\n",
+ " """The problem of searching a graph from one node to another."""\n",
+ "\n",
+ " def __init__(self, initial, goal, graph):\n",
+ " Problem.__init__(self, initial, goal)\n",
+ " self.graph = graph\n",
+ "\n",
+ " def actions(self, A):\n",
+ " """The actions at a graph node are just its neighbors."""\n",
+ " return list(self.graph.get(A).keys())\n",
+ "\n",
+ " def result(self, state, action):\n",
+ " """The result of going to a neighbor is just that neighbor."""\n",
+ " return action\n",
+ "\n",
+ " def path_cost(self, cost_so_far, A, action, B):\n",
+ " return cost_so_far + (self.graph.get(A, B) or infinity)\n",
+ "\n",
+ " def find_min_edge(self):\n",
+ " """Find minimum value of edges."""\n",
+ " m = infinity\n",
+ " for d in self.graph.graph_dict.values():\n",
+ " local_min = min(d.values())\n",
+ " m = min(m, local_min)\n",
+ "\n",
+ " return m\n",
+ "\n",
+ " def h(self, node):\n",
+ " """h function is straight-line distance from a node's state to goal."""\n",
+ " locs = getattr(self.graph, 'locations', None)\n",
+ " if locs:\n",
+ " if type(node) is str:\n",
+ " return int(distance(locs[node], locs[self.goal]))\n",
+ "\n",
+ " return int(distance(locs[node.state], locs[self.goal]))\n",
+ " else:\n",
+ " return infinity\n",
+ "class SimpleProblemSolvingAgentProgram:\n",
+ "\n",
+ " """Abstract framework for a problem-solving agent. [Figure 3.1]"""\n",
+ "\n",
+ " def __init__(self, initial_state=None):\n",
+ " """State is an abstract representation of the state\n",
+ " of the world, and seq is the list of actions required\n",
+ " to get to a particular state from the initial state(root)."""\n",
+ " self.state = initial_state\n",
+ " self.seq = []\n",
+ "\n",
+ " def __call__(self, percept):\n",
+ " """[Figure 3.1] Formulate a goal and problem, then\n",
+ " search for a sequence of actions to solve it."""\n",
+ " self.state = self.update_state(self.state, percept)\n",
+ " if not self.seq:\n",
+ " goal = self.formulate_goal(self.state)\n",
+ " problem = self.formulate_problem(self.state, goal)\n",
+ " self.seq = self.search(problem)\n",
+ " if not self.seq:\n",
+ " return None\n",
+ " return self.seq.pop(0)\n",
+ "\n",
+ " def update_state(self, state, percept):\n",
+ " raise NotImplementedError\n",
+ "\n",
+ " def formulate_goal(self, state):\n",
+ " raise NotImplementedError\n",
+ "\n",
+ " def formulate_problem(self, state, goal):\n",
+ " raise NotImplementedError\n",
+ "\n",
+ " def search(self, problem):\n",
+ " raise NotImplementedError\n",
+ "def recursive_best_first_search(problem, h=None):\n",
+ " """[Figure 3.26] Recursive best-first search (RBFS) is an\n",
+ " informative search algorithm. Like A*, it uses the heuristic\n",
+ " f(n) = g(n) + h(n) to determine the next node to expand, making\n",
+ " it both optimal and complete (iff the heuristic is consistent).\n",
+ " To reduce memory consumption, RBFS uses a depth first search\n",
+ " and only retains the best f values of its ancestors."""\n",
+ " h = memoize(h or problem.h, 'h')\n",
+ "\n",
+ " def RBFS(problem, node, flimit):\n",
+ " if problem.goal_test(node.state):\n",
+ " return node, 0 # (The second value is immaterial)\n",
+ " successors = node.expand(problem)\n",
+ " if len(successors) == 0:\n",
+ " return None, infinity\n",
+ " for s in successors:\n",
+ " s.f = max(s.path_cost + h(s), node.f)\n",
+ " while True:\n",
+ " # Order by lowest f value\n",
+ " successors.sort(key=lambda x: x.f)\n",
+ " best = successors[0]\n",
+ " if best.f > flimit:\n",
+ " return None, best.f\n",
+ " if len(successors) > 1:\n",
+ " alternative = successors[1].f\n",
+ " else:\n",
+ " alternative = infinity\n",
+ " result, best.f = RBFS(problem, best, min(flimit, alternative))\n",
+ " if result is not None:\n",
+ " return result, best.f\n",
+ "\n",
+ " node = Node(problem.initial)\n",
+ " node.f = h(node)\n",
+ " result, bestf = RBFS(problem, node, infinity)\n",
+ " return result\n",
+ "def hill_climbing(problem):\n",
+ " """From the initial node, keep choosing the neighbor with highest value,\n",
+ " stopping when no neighbor is better. [Figure 4.2]"""\n",
+ " current = Node(problem.initial)\n",
+ " while True:\n",
+ " neighbors = current.expand(problem)\n",
+ " if not neighbors:\n",
+ " break\n",
+ " neighbor = argmax_random_tie(neighbors,\n",
+ " key=lambda node: problem.value(node.state))\n",
+ " if problem.value(neighbor.state) <= problem.value(current.state):\n",
+ " break\n",
+ " current = neighbor\n",
+ " return current.state\n",
+ "def simulated_annealing(problem, schedule=exp_schedule()):\n",
+ " """[Figure 4.5] CAUTION: This differs from the pseudocode as it\n",
+ " returns a state instead of a Node."""\n",
+ " current = Node(problem.initial)\n",
+ " for t in range(sys.maxsize):\n",
+ " T = schedule(t)\n",
+ " if T == 0:\n",
+ " return current.state\n",
+ " neighbors = current.expand(problem)\n",
+ " if not neighbors:\n",
+ " return current.state\n",
+ " next_choice = random.choice(neighbors)\n",
+ " delta_e = problem.value(next_choice.state) - problem.value(current.state)\n",
+ " if delta_e > 0 or probability(math.exp(delta_e / T)):\n",
+ " current = next_choice\n",
+ "def exp_schedule(k=20, lam=0.005, limit=100):\n",
+ " """One possible schedule function for simulated annealing"""\n",
+ " return lambda t: (k * math.exp(-lam * t) if t < limit else 0)\n",
+ "