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",
+ "
![](\"images/fig_5_2.png\")
\n",
"\n",
- "The states are represented wih 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",
+ "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:"
]
@@ -849,6 +856,9 @@
"## 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!"
]
@@ -1651,9 +1661,9 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
- "version": "3.5.3"
+ "version": "3.8.2-final"
}
},
"nbformat": 4,
"nbformat_minor": 1
-}
+}
\ No newline at end of file
diff --git a/games.py b/games.py
index 00a2c33d3..d22b2e640 100644
--- a/games.py
+++ b/games.py
@@ -1,18 +1,23 @@
-"""Games, or Adversarial Search (Chapter 5)"""
+"""Games or Adversarial Search (Chapter 5)"""
-from collections import namedtuple
+import copy
+import itertools
import random
+from collections import namedtuple
-from utils import argmax
+import numpy as np
+
+from utils import vector_add
-infinity = float('inf')
GameState = namedtuple('GameState', 'to_move, utility, board, moves')
+StochasticGameState = namedtuple('StochasticGameState', 'to_move, utility, board, moves, chance')
+
# ______________________________________________________________________________
-# Minimax Search
+# MinMax Search
-def minimax_decision(state, game):
+def minmax_decision(state, game):
"""Given a state in a game, calculate the best move by searching
forward all the way to the terminal states. [Figure 5.3]"""
@@ -21,7 +26,7 @@ def minimax_decision(state, game):
def max_value(state):
if game.terminal_test(state):
return game.utility(state, player)
- v = -infinity
+ v = -np.inf
for a in game.actions(state):
v = max(v, min_value(game.result(state, a)))
return v
@@ -29,29 +34,69 @@ def max_value(state):
def min_value(state):
if game.terminal_test(state):
return game.utility(state, player)
- v = infinity
+ v = np.inf
for a in game.actions(state):
v = min(v, max_value(game.result(state, a)))
return v
- # Body of minimax_decision:
- return argmax(game.actions(state),
- key=lambda a: min_value(game.result(state, a)))
+ # Body of minmax_decision:
+ return max(game.actions(state), key=lambda a: min_value(game.result(state, a)))
+
# ______________________________________________________________________________
-def alphabeta_search(state, game):
+def expect_minmax(state, game):
+ """
+ [Figure 5.11]
+ Return the best move for a player after dice are thrown. The game tree
+ includes chance nodes along with min and max nodes.
+ """
+ player = game.to_move(state)
+
+ def max_value(state):
+ v = -np.inf
+ for a in game.actions(state):
+ v = max(v, chance_node(state, a))
+ return v
+
+ def min_value(state):
+ v = np.inf
+ for a in game.actions(state):
+ v = min(v, chance_node(state, a))
+ return v
+
+ def chance_node(state, action):
+ res_state = game.result(state, action)
+ if game.terminal_test(res_state):
+ return game.utility(res_state, player)
+ sum_chances = 0
+ num_chances = len(game.chances(res_state))
+ for chance in game.chances(res_state):
+ res_state = game.outcome(res_state, chance)
+ util = 0
+ if res_state.to_move == player:
+ util = max_value(res_state)
+ else:
+ util = min_value(res_state)
+ sum_chances += util * game.probability(chance)
+ return sum_chances / num_chances
+
+ # Body of expect_minmax:
+ return max(game.actions(state), key=lambda a: chance_node(state, a), default=None)
+
+
+def alpha_beta_search(state, game):
"""Search game to determine best action; use alpha-beta pruning.
As in [Figure 5.7], this version searches all the way to the leaves."""
player = game.to_move(state)
- # Functions used by alphabeta
+ # Functions used by alpha_beta
def max_value(state, alpha, beta):
if game.terminal_test(state):
return game.utility(state, player)
- v = -infinity
+ v = -np.inf
for a in game.actions(state):
v = max(v, min_value(game.result(state, a), alpha, beta))
if v >= beta:
@@ -62,7 +107,7 @@ def max_value(state, alpha, beta):
def min_value(state, alpha, beta):
if game.terminal_test(state):
return game.utility(state, player)
- v = infinity
+ v = np.inf
for a in game.actions(state):
v = min(v, max_value(game.result(state, a), alpha, beta))
if v <= alpha:
@@ -70,9 +115,9 @@ def min_value(state, alpha, beta):
beta = min(beta, v)
return v
- # Body of alphabeta_cutoff_search:
- best_score = -infinity
- beta = infinity
+ # Body of alpha_beta_search:
+ best_score = -np.inf
+ beta = np.inf
best_action = None
for a in game.actions(state):
v = min_value(game.result(state, a), best_score, beta)
@@ -82,20 +127,19 @@ def min_value(state, alpha, beta):
return best_action
-def alphabeta_cutoff_search(state, game, d=4, cutoff_test=None, eval_fn=None):
+def alpha_beta_cutoff_search(state, game, d=4, cutoff_test=None, eval_fn=None):
"""Search game to determine best action; use alpha-beta pruning.
This version cuts off search and uses an evaluation function."""
player = game.to_move(state)
- # Functions used by alphabeta
+ # Functions used by alpha_beta
def max_value(state, alpha, beta, depth):
if cutoff_test(state, depth):
return eval_fn(state)
- v = -infinity
+ v = -np.inf
for a in game.actions(state):
- v = max(v, min_value(game.result(state, a),
- alpha, beta, depth + 1))
+ v = max(v, min_value(game.result(state, a), alpha, beta, depth + 1))
if v >= beta:
return v
alpha = max(alpha, v)
@@ -104,23 +148,20 @@ def max_value(state, alpha, beta, depth):
def min_value(state, alpha, beta, depth):
if cutoff_test(state, depth):
return eval_fn(state)
- v = infinity
+ v = np.inf
for a in game.actions(state):
- v = min(v, max_value(game.result(state, a),
- alpha, beta, depth + 1))
+ v = min(v, max_value(game.result(state, a), alpha, beta, depth + 1))
if v <= alpha:
return v
beta = min(beta, v)
return v
- # Body of alphabeta_cutoff_search starts here:
+ # Body of alpha_beta_cutoff_search starts here:
# The default test cuts off at depth d or at a terminal state
- cutoff_test = (cutoff_test or
- (lambda state, depth: depth > d or
- game.terminal_test(state)))
+ cutoff_test = (cutoff_test or (lambda state, depth: depth > d or game.terminal_test(state)))
eval_fn = eval_fn or (lambda state: game.utility(state, player))
- best_score = -infinity
- beta = infinity
+ best_score = -np.inf
+ beta = np.inf
best_action = None
for a in game.actions(state):
v = min_value(game.result(state, a), best_score, beta, 1)
@@ -129,6 +170,7 @@ def min_value(state, alpha, beta, depth):
best_action = a
return best_action
+
# ______________________________________________________________________________
# Players for Games
@@ -139,21 +181,33 @@ def query_player(game, state):
game.display(state)
print("available moves: {}".format(game.actions(state)))
print("")
- move_string = input('Your move? ')
- try:
- move = eval(move_string)
- except NameError:
- move = move_string
+ move = None
+ if game.actions(state):
+ move_string = input('Your move? ')
+ try:
+ move = eval(move_string)
+ except NameError:
+ move = move_string
+ else:
+ print('no legal moves: passing turn to next player')
return move
def random_player(game, state):
"""A player that chooses a legal move at random."""
- return random.choice(game.actions(state))
+ return random.choice(game.actions(state)) if game.actions(state) else None
+
+
+def alpha_beta_player(game, state):
+ return alpha_beta_search(state, game)
+
+def minmax_player(game,state):
+ return minmax_decision(state,game)
-def alphabeta_player(game, state):
- return alphabeta_search(state, game)
+
+def expect_minmax_player(game, state):
+ return expect_minmax(state, game)
# ______________________________________________________________________________
@@ -208,6 +262,38 @@ def play_game(self, *players):
return self.utility(state, self.to_move(self.initial))
+class StochasticGame(Game):
+ """A stochastic game includes uncertain events which influence
+ the moves of players at each state. To create a stochastic game, subclass
+ this class and implement chances and outcome along with the other
+ unimplemented game class methods."""
+
+ def chances(self, state):
+ """Return a list of all possible uncertain events at a state."""
+ raise NotImplementedError
+
+ def outcome(self, state, chance):
+ """Return the state which is the outcome of a chance trial."""
+ raise NotImplementedError
+
+ def probability(self, chance):
+ """Return the probability of occurrence of a chance."""
+ raise NotImplementedError
+
+ def play_game(self, *players):
+ """Play an n-person, move-alternating stochastic game."""
+ state = self.initial
+ while True:
+ for player in players:
+ chance = random.choice(self.chances(state))
+ state = self.outcome(state, chance)
+ move = player(self, state)
+ state = self.result(state, move)
+ if self.terminal_test(state):
+ self.display(state)
+ return self.utility(state, self.to_move(self.initial))
+
+
class Fig52Game(Game):
"""The game represented in [Figure 5.2]. Serves as a simple test case."""
@@ -240,7 +326,7 @@ def to_move(self, state):
class Fig52Extended(Game):
"""Similar to Fig52Game but bigger. Useful for visualisation"""
- succs = {i:dict(l=i*3+1, m=i*3+2, r=i*3+3) for i in range(13)}
+ succs = {i: dict(l=i * 3 + 1, m=i * 3 + 2, r=i * 3 + 3) for i in range(13)}
utils = dict()
def actions(self, state):
@@ -261,6 +347,7 @@ def terminal_test(self, state):
def to_move(self, state):
return 'MIN' if state in {1, 2, 3} else 'MAX'
+
class TicTacToe(Game):
"""Play TicTacToe on an h x v board, with Max (first player) playing 'X'.
A state has the player to move, a cached utility, a list of moves in
@@ -341,4 +428,163 @@ def __init__(self, h=7, v=6, k=4):
def actions(self, state):
return [(x, y) for (x, y) in state.moves
- if y == 1 or (x, y - 1) in state.board]
+ if x == self.h or (x + 1 , y ) in state.board]
+
+class Gomoku(TicTacToe):
+ """Also known as Five in a row."""
+
+ def __init__(self, h=15, v=16, k=5):
+ TicTacToe.__init__(self, h, v, k)
+
+
+class Backgammon(StochasticGame):
+ """A two player game where the goal of each player is to move all the
+ checkers off the board. The moves for each state are determined by
+ rolling a pair of dice."""
+
+ def __init__(self):
+ """Initial state of the game"""
+ point = {'W': 0, 'B': 0}
+ board = [point.copy() for index in range(24)]
+ board[0]['B'] = board[23]['W'] = 2
+ board[5]['W'] = board[18]['B'] = 5
+ board[7]['W'] = board[16]['B'] = 3
+ board[11]['B'] = board[12]['W'] = 5
+ self.allow_bear_off = {'W': False, 'B': False}
+ self.direction = {'W': -1, 'B': 1}
+ self.initial = StochasticGameState(to_move='W',
+ utility=0,
+ board=board,
+ moves=self.get_all_moves(board, 'W'), chance=None)
+
+ def actions(self, state):
+ """Return a list of legal moves for a state."""
+ player = state.to_move
+ moves = state.moves
+ if len(moves) == 1 and len(moves[0]) == 1:
+ return moves
+ legal_moves = []
+ for move in moves:
+ board = copy.deepcopy(state.board)
+ if self.is_legal_move(board, move, state.chance, player):
+ legal_moves.append(move)
+ return legal_moves
+
+ def result(self, state, move):
+ board = copy.deepcopy(state.board)
+ player = state.to_move
+ self.move_checker(board, move[0], state.chance[0], player)
+ if len(move) == 2:
+ self.move_checker(board, move[1], state.chance[1], player)
+ to_move = ('W' if player == 'B' else 'B')
+ return StochasticGameState(to_move=to_move,
+ utility=self.compute_utility(board, move, player),
+ board=board,
+ moves=self.get_all_moves(board, to_move), chance=None)
+
+ def utility(self, state, player):
+ """Return the value to player; 1 for win, -1 for loss, 0 otherwise."""
+ return state.utility if player == 'W' else -state.utility
+
+ def terminal_test(self, state):
+ """A state is terminal if one player wins."""
+ return state.utility != 0
+
+ def get_all_moves(self, board, player):
+ """All possible moves for a player i.e. all possible ways of
+ choosing two checkers of a player from the board for a move
+ at a given state."""
+ all_points = board
+ taken_points = [index for index, point in enumerate(all_points)
+ if point[player] > 0]
+ if self.checkers_at_home(board, player) == 1:
+ return [(taken_points[0],)]
+ moves = list(itertools.permutations(taken_points, 2))
+ moves = moves + [(index, index) for index, point in enumerate(all_points)
+ if point[player] >= 2]
+ return moves
+
+ def display(self, state):
+ """Display state of the game."""
+ board = state.board
+ player = state.to_move
+ print("current state : ")
+ for index, point in enumerate(board):
+ print("point : ", index, " W : ", point['W'], " B : ", point['B'])
+ print("to play : ", player)
+
+ def compute_utility(self, board, move, player):
+ """If 'W' wins with this move, return 1; if 'B' wins return -1; else return 0."""
+ util = {'W': 1, 'B': -1}
+ for idx in range(0, 24):
+ if board[idx][player] > 0:
+ return 0
+ return util[player]
+
+ def checkers_at_home(self, board, player):
+ """Return the no. of checkers at home for a player."""
+ sum_range = range(0, 7) if player == 'W' else range(17, 24)
+ count = 0
+ for idx in sum_range:
+ count = count + board[idx][player]
+ return count
+
+ def is_legal_move(self, board, start, steps, player):
+ """Move is a tuple which contains starting points of checkers to be
+ moved during a player's turn. An on-board move is legal if both the destinations
+ are open. A bear-off move is the one where a checker is moved off-board.
+ It is legal only after a player has moved all his checkers to his home."""
+ dest1, dest2 = vector_add(start, steps)
+ dest_range = range(0, 24)
+ move1_legal = move2_legal = False
+ if dest1 in dest_range:
+ if self.is_point_open(player, board[dest1]):
+ self.move_checker(board, start[0], steps[0], player)
+ move1_legal = True
+ else:
+ if self.allow_bear_off[player]:
+ self.move_checker(board, start[0], steps[0], player)
+ move1_legal = True
+ if not move1_legal:
+ return False
+ if dest2 in dest_range:
+ if self.is_point_open(player, board[dest2]):
+ move2_legal = True
+ else:
+ if self.allow_bear_off[player]:
+ move2_legal = True
+ return move1_legal and move2_legal
+
+ def move_checker(self, board, start, steps, player):
+ """Move a checker from starting point by a given number of steps"""
+ dest = start + steps
+ dest_range = range(0, 24)
+ board[start][player] -= 1
+ if dest in dest_range:
+ board[dest][player] += 1
+ if self.checkers_at_home(board, player) == 15:
+ self.allow_bear_off[player] = True
+
+ def is_point_open(self, player, point):
+ """A point is open for a player if the no. of opponent's
+ checkers already present on it is 0 or 1. A player can
+ move a checker to a point only if it is open."""
+ opponent = 'B' if player == 'W' else 'W'
+ return point[opponent] <= 1
+
+ def chances(self, state):
+ """Return a list of all possible dice rolls at a state."""
+ dice_rolls = list(itertools.combinations_with_replacement([1, 2, 3, 4, 5, 6], 2))
+ return dice_rolls
+
+ def outcome(self, state, chance):
+ """Return the state which is the outcome of a dice roll."""
+ dice = tuple(map((self.direction[state.to_move]).__mul__, chance))
+ return StochasticGameState(to_move=state.to_move,
+ utility=state.utility,
+ board=state.board,
+ moves=state.moves, chance=dice)
+
+ def probability(self, chance):
+ """Return the probability of occurrence of a dice roll."""
+ return 1 / 36 if chance[0] == chance[1] else 1 / 18
diff --git a/games4e.ipynb b/games4e.ipynb
new file mode 100644
index 000000000..5b619f7ed
--- /dev/null
+++ b/games4e.ipynb
@@ -0,0 +1,1667 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Game Tree Search\n",
+ "\n",
+ "We start with defining the abstract class `Game`, for turn-taking *n*-player games. We rely on, but do not define yet, the concept of a `state` of the game; we'll see later how individual games define states. For now, all we require is that a state has a `state.to_move` attribute, which gives the name of the player whose turn it is. (\"Name\" will be something like `'X'` or `'O'` for tic-tac-toe.) \n",
+ "\n",
+ "We also define `play_game`, which takes a game and a dictionary of `{player_name: strategy_function}` pairs, and plays out the game, on each turn checking `state.to_move` to see whose turn it is, and then getting the strategy function for that player and applying it to the game and the state to get a move."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from collections import namedtuple, Counter, defaultdict\n",
+ "import random\n",
+ "import math\n",
+ "import functools \n",
+ "cache = functools.lru_cache(10**6)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 73,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class Game:\n",
+ " \"\"\"A game is similar to a problem, but it has a terminal test instead of \n",
+ " a goal test, and a utility for each terminal state. To create a game, \n",
+ " subclass this class and implement `actions`, `result`, `is_terminal`, \n",
+ " and `utility`. You will also need to set the .initial attribute to the \n",
+ " initial state; this can be done in the constructor.\"\"\"\n",
+ "\n",
+ " def actions(self, state):\n",
+ " \"\"\"Return a collection of the allowable moves from this state.\"\"\"\n",
+ " raise NotImplementedError\n",
+ "\n",
+ " def result(self, state, move):\n",
+ " \"\"\"Return the state that results from making a move from a state.\"\"\"\n",
+ " raise NotImplementedError\n",
+ "\n",
+ " def is_terminal(self, state):\n",
+ " \"\"\"Return True if this is a final state for the game.\"\"\"\n",
+ " return not self.actions(state)\n",
+ " \n",
+ " def utility(self, state, player):\n",
+ " \"\"\"Return the value of this final state to player.\"\"\"\n",
+ " raise NotImplementedError\n",
+ " \n",
+ "\n",
+ "def play_game(game, strategies: dict, verbose=False):\n",
+ " \"\"\"Play a turn-taking game. `strategies` is a {player_name: function} dict,\n",
+ " where function(state, game) is used to get the player's move.\"\"\"\n",
+ " state = game.initial\n",
+ " while not game.is_terminal(state):\n",
+ " player = state.to_move\n",
+ " move = strategies[player](game, state)\n",
+ " state = game.result(state, move)\n",
+ " if verbose: \n",
+ " print('Player', player, 'move:', move)\n",
+ " print(state)\n",
+ " return state"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Minimax-Based Game Search Algorithms\n",
+ "\n",
+ "We will define several game search algorithms. Each takes two inputs, the game we are playing and the current state of the game, and returns a a `(value, move)` pair, where `value` is the utility that the algorithm computes for the player whose turn it is to move, and `move` is the move itself.\n",
+ "\n",
+ "First we define `minimax_search`, which exhaustively searches the game tree to find an optimal move (assuming both players play optimally), and `alphabeta_search`, which does the same computation, but prunes parts of the tree that could not possibly have an affect on the optimnal move. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 66,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def minimax_search(game, state):\n",
+ " \"\"\"Search game tree to determine best move; return (value, move) pair.\"\"\"\n",
+ "\n",
+ " player = state.to_move\n",
+ "\n",
+ " def max_value(state):\n",
+ " if game.is_terminal(state):\n",
+ " return game.utility(state, player), None\n",
+ " v, move = -infinity, None\n",
+ " for a in game.actions(state):\n",
+ " v2, _ = min_value(game.result(state, a))\n",
+ " if v2 > v:\n",
+ " v, move = v2, a\n",
+ " return v, move\n",
+ "\n",
+ " def min_value(state):\n",
+ " if game.is_terminal(state):\n",
+ " return game.utility(state, player), None\n",
+ " v, move = +infinity, None\n",
+ " for a in game.actions(state):\n",
+ " v2, _ = max_value(game.result(state, a))\n",
+ " if v2 < v:\n",
+ " v, move = v2, a\n",
+ " return v, move\n",
+ "\n",
+ " return max_value(state)\n",
+ "\n",
+ "infinity = math.inf\n",
+ "\n",
+ "def alphabeta_search(game, state):\n",
+ " \"\"\"Search game to determine best action; use alpha-beta pruning.\n",
+ " As in [Figure 5.7], this version searches all the way to the leaves.\"\"\"\n",
+ "\n",
+ " player = state.to_move\n",
+ "\n",
+ " def max_value(state, alpha, beta):\n",
+ " if game.is_terminal(state):\n",
+ " return game.utility(state, player), None\n",
+ " v, move = -infinity, None\n",
+ " for a in game.actions(state):\n",
+ " v2, _ = min_value(game.result(state, a), alpha, beta)\n",
+ " if v2 > v:\n",
+ " v, move = v2, a\n",
+ " alpha = max(alpha, v)\n",
+ " if v >= beta:\n",
+ " return v, move\n",
+ " return v, move\n",
+ "\n",
+ " def min_value(state, alpha, beta):\n",
+ " if game.is_terminal(state):\n",
+ " return game.utility(state, player), None\n",
+ " v, move = +infinity, None\n",
+ " for a in game.actions(state):\n",
+ " v2, _ = max_value(game.result(state, a), alpha, beta)\n",
+ " if v2 < v:\n",
+ " v, move = v2, a\n",
+ " beta = min(beta, v)\n",
+ " if v <= alpha:\n",
+ " return v, move\n",
+ " return v, move\n",
+ "\n",
+ " return max_value(state, -infinity, +infinity)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# A Simple Game: Tic-Tac-Toe\n",
+ "\n",
+ "We have the notion of an abstract game, we have some search functions; now it is time to define a real game; a simple one, tic-tac-toe. Moves are `(x, y)` pairs denoting squares, where `(0, 0)` is the top left, and `(2, 2)` is the bottom right (on a board of size `height=width=3`)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 67,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class TicTacToe(Game):\n",
+ " \"\"\"Play TicTacToe on an `height` by `width` board, needing `k` in a row to win.\n",
+ " 'X' plays first against 'O'.\"\"\"\n",
+ "\n",
+ " def __init__(self, height=3, width=3, k=3):\n",
+ " self.k = k # k in a row\n",
+ " self.squares = {(x, y) for x in range(width) for y in range(height)}\n",
+ " self.initial = Board(height=height, width=width, to_move='X', utility=0)\n",
+ "\n",
+ " def actions(self, board):\n",
+ " \"\"\"Legal moves are any square not yet taken.\"\"\"\n",
+ " return self.squares - set(board)\n",
+ "\n",
+ " def result(self, board, square):\n",
+ " \"\"\"Place a marker for current player on square.\"\"\"\n",
+ " player = board.to_move\n",
+ " board = board.new({square: player}, to_move=('O' if player == 'X' else 'X'))\n",
+ " win = k_in_row(board, player, square, self.k)\n",
+ " board.utility = (0 if not win else +1 if player == 'X' else -1)\n",
+ " return board\n",
+ "\n",
+ " def utility(self, board, player):\n",
+ " \"\"\"Return the value to player; 1 for win, -1 for loss, 0 otherwise.\"\"\"\n",
+ " return board.utility if player == 'X' else -board.utility\n",
+ "\n",
+ " def is_terminal(self, board):\n",
+ " \"\"\"A board is a terminal state if it is won or there are no empty squares.\"\"\"\n",
+ " return board.utility != 0 or len(self.squares) == len(board)\n",
+ "\n",
+ " def display(self, board): print(board) \n",
+ "\n",
+ "\n",
+ "def k_in_row(board, player, square, k):\n",
+ " \"\"\"True if player has k pieces in a line through square.\"\"\"\n",
+ " def in_row(x, y, dx, dy): return 0 if board[x, y] != player else 1 + in_row(x + dx, y + dy, dx, dy)\n",
+ " return any(in_row(*square, dx, dy) + in_row(*square, -dx, -dy) - 1 >= k\n",
+ " for (dx, dy) in ((0, 1), (1, 0), (1, 1), (1, -1)))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "States in tic-tac-toe (and other games) will be represented as a `Board`, which is a subclass of `defaultdict` that in general will consist of `{(x, y): contents}` pairs, for example `{(0, 0): 'X', (1, 1): 'O'}` might be the state of the board after two moves. Besides the contents of squares, a board also has some attributes: \n",
+ "- `.to_move` to name the player whose move it is; \n",
+ "- `.width` and `.height` to give the size of the board (both 3 in tic-tac-toe, but other numbers in related games);\n",
+ "- possibly other attributes, as specified by keywords. \n",
+ "\n",
+ "As a `defaultdict`, the `Board` class has a `__missing__` method, which returns `empty` for squares that have no been assigned but are within the `width` × `height` boundaries, or `off` otherwise. The class has a `__hash__` method, so instances can be stored in hash tables."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 68,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class Board(defaultdict):\n",
+ " \"\"\"A board has the player to move, a cached utility value, \n",
+ " and a dict of {(x, y): player} entries, where player is 'X' or 'O'.\"\"\"\n",
+ " empty = '.'\n",
+ " off = '#'\n",
+ " \n",
+ " def __init__(self, width=8, height=8, to_move=None, **kwds):\n",
+ " self.__dict__.update(width=width, height=height, to_move=to_move, **kwds)\n",
+ " \n",
+ " def new(self, changes: dict, **kwds) -> 'Board':\n",
+ " \"Given a dict of {(x, y): contents} changes, return a new Board with the changes.\"\n",
+ " board = Board(width=self.width, height=self.height, **kwds)\n",
+ " board.update(self)\n",
+ " board.update(changes)\n",
+ " return board\n",
+ "\n",
+ " def __missing__(self, loc):\n",
+ " x, y = loc\n",
+ " if 0 <= x < self.width and 0 <= y < self.height:\n",
+ " return self.empty\n",
+ " else:\n",
+ " return self.off\n",
+ " \n",
+ " def __hash__(self): \n",
+ " return hash(tuple(sorted(self.items()))) + hash(self.to_move)\n",
+ " \n",
+ " def __repr__(self):\n",
+ " def row(y): return ' '.join(self[x, y] for x in range(self.width))\n",
+ " return '\\n'.join(map(row, range(self.height))) + '\\n'"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Players\n",
+ "\n",
+ "We need an interface for players. I'll represent a player as a `callable` that will be passed two arguments: `(game, state)` and will return a `move`.\n",
+ "The function `player` creates a player out of a search algorithm, but you can create your own players as functions, as is done with `random_player` below:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 69,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def random_player(game, state): return random.choice(list(game.actions(state)))\n",
+ "\n",
+ "def player(search_algorithm):\n",
+ " \"\"\"A game player who uses the specified search algorithm\"\"\"\n",
+ " return lambda game, state: search_algorithm(game, state)[1]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Playing a Game\n",
+ "\n",
+ "We're ready to play a game. I'll set up a match between a `random_player` (who chooses randomly from the legal moves) and a `player(alphabeta_search)` (who makes the optimal alpha-beta move; practical for tic-tac-toe, but not for large games). The `player(alphabeta_search)` will never lose, but if `random_player` is lucky, it will be a tie."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 74,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Player X move: (0, 0)\n",
+ "X . .\n",
+ ". . .\n",
+ ". . .\n",
+ "\n",
+ "Player O move: (1, 1)\n",
+ "X . .\n",
+ ". O .\n",
+ ". . .\n",
+ "\n",
+ "Player X move: (1, 2)\n",
+ "X . .\n",
+ ". O .\n",
+ ". X .\n",
+ "\n",
+ "Player O move: (0, 1)\n",
+ "X . .\n",
+ "O O .\n",
+ ". X .\n",
+ "\n",
+ "Player X move: (2, 1)\n",
+ "X . .\n",
+ "O O X\n",
+ ". X .\n",
+ "\n",
+ "Player O move: (2, 0)\n",
+ "X . O\n",
+ "O O X\n",
+ ". X .\n",
+ "\n",
+ "Player X move: (2, 2)\n",
+ "X . O\n",
+ "O O X\n",
+ ". X X\n",
+ "\n",
+ "Player O move: (0, 2)\n",
+ "X . O\n",
+ "O O X\n",
+ "O X X\n",
+ "\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "-1"
+ ]
+ },
+ "execution_count": 74,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "play_game(TicTacToe(), dict(X=random_player, O=player(alphabeta_search)), verbose=True).utility"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The alpha-beta player will never lose, but sometimes the random player can stumble into a draw. When two optimal (alpha-beta or minimax) players compete, it will always be a draw:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 75,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Player X move: (0, 1)\n",
+ ". . .\n",
+ "X . .\n",
+ ". . .\n",
+ "\n",
+ "Player O move: (0, 0)\n",
+ "O . .\n",
+ "X . .\n",
+ ". . .\n",
+ "\n",
+ "Player X move: (2, 0)\n",
+ "O . X\n",
+ "X . .\n",
+ ". . .\n",
+ "\n",
+ "Player O move: (2, 1)\n",
+ "O . X\n",
+ "X . O\n",
+ ". . .\n",
+ "\n",
+ "Player X move: (1, 2)\n",
+ "O . X\n",
+ "X . O\n",
+ ". X .\n",
+ "\n",
+ "Player O move: (0, 2)\n",
+ "O . X\n",
+ "X . O\n",
+ "O X .\n",
+ "\n",
+ "Player X move: (1, 0)\n",
+ "O X X\n",
+ "X . O\n",
+ "O X .\n",
+ "\n",
+ "Player O move: (1, 1)\n",
+ "O X X\n",
+ "X O O\n",
+ "O X .\n",
+ "\n",
+ "Player X move: (2, 2)\n",
+ "O X X\n",
+ "X O O\n",
+ "O X X\n",
+ "\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "0"
+ ]
+ },
+ "execution_count": 75,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "play_game(TicTacToe(), dict(X=player(alphabeta_search), O=player(minimax_search)), verbose=True).utility"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Connect Four\n",
+ "\n",
+ "Connect Four is a variant of tic-tac-toe, played on a larger (7 x 6) board, and with the restriction that in any column you can only play in the lowest empty square in the column."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 76,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class ConnectFour(TicTacToe):\n",
+ " \n",
+ " def __init__(self): super().__init__(width=7, height=6, k=4)\n",
+ "\n",
+ " def actions(self, board):\n",
+ " \"\"\"In each column you can play only the lowest empty square in the column.\"\"\"\n",
+ " return {(x, y) for (x, y) in self.squares - set(board)\n",
+ " if y == board.height - 1 or (x, y + 1) in board}"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 77,
+ "metadata": {
+ "scrolled": false
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Player X move: (2, 5)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . X . . . .\n",
+ "\n",
+ "Player O move: (1, 5)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". O X . . . .\n",
+ "\n",
+ "Player X move: (5, 5)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". O X . . X .\n",
+ "\n",
+ "Player O move: (4, 5)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". O X . O X .\n",
+ "\n",
+ "Player X move: (4, 4)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . X . .\n",
+ ". O X . O X .\n",
+ "\n",
+ "Player O move: (2, 4)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . O . X . .\n",
+ ". O X . O X .\n",
+ "\n",
+ "Player X move: (2, 3)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . X . . . .\n",
+ ". . O . X . .\n",
+ ". O X . O X .\n",
+ "\n",
+ "Player O move: (1, 4)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . X . . . .\n",
+ ". O O . X . .\n",
+ ". O X . O X .\n",
+ "\n",
+ "Player X move: (0, 5)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . X . . . .\n",
+ ". O O . X . .\n",
+ "X O X . O X .\n",
+ "\n",
+ "Player O move: (5, 4)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . X . . . .\n",
+ ". O O . X O .\n",
+ "X O X . O X .\n",
+ "\n",
+ "Player X move: (5, 3)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . X . . X .\n",
+ ". O O . X O .\n",
+ "X O X . O X .\n",
+ "\n",
+ "Player O move: (6, 5)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . X . . X .\n",
+ ". O O . X O .\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player X move: (1, 3)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". X X . . X .\n",
+ ". O O . X O .\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player O move: (6, 4)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". X X . . X .\n",
+ ". O O . X O O\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player X move: (5, 2)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . X .\n",
+ ". X X . . X .\n",
+ ". O O . X O O\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player O move: (0, 4)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . X .\n",
+ ". X X . . X .\n",
+ "O O O . X O O\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player X move: (0, 3)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . X .\n",
+ "X X X . . X .\n",
+ "O O O . X O O\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player O move: (0, 2)\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ "O . . . . X .\n",
+ "X X X . . X .\n",
+ "O O O . X O O\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player X move: (0, 1)\n",
+ ". . . . . . .\n",
+ "X . . . . . .\n",
+ "O . . . . X .\n",
+ "X X X . . X .\n",
+ "O O O . X O O\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player O move: (0, 0)\n",
+ "O . . . . . .\n",
+ "X . . . . . .\n",
+ "O . . . . X .\n",
+ "X X X . . X .\n",
+ "O O O . X O O\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player X move: (5, 1)\n",
+ "O . . . . . .\n",
+ "X . . . . X .\n",
+ "O . . . . X .\n",
+ "X X X . . X .\n",
+ "O O O . X O O\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player O move: (4, 3)\n",
+ "O . . . . . .\n",
+ "X . . . . X .\n",
+ "O . . . . X .\n",
+ "X X X . O X .\n",
+ "O O O . X O O\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player X move: (6, 3)\n",
+ "O . . . . . .\n",
+ "X . . . . X .\n",
+ "O . . . . X .\n",
+ "X X X . O X X\n",
+ "O O O . X O O\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player O move: (5, 0)\n",
+ "O . . . . O .\n",
+ "X . . . . X .\n",
+ "O . . . . X .\n",
+ "X X X . O X X\n",
+ "O O O . X O O\n",
+ "X O X . O X O\n",
+ "\n",
+ "Player X move: (3, 5)\n",
+ "O . . . . O .\n",
+ "X . . . . X .\n",
+ "O . . . . X .\n",
+ "X X X . O X X\n",
+ "O O O . X O O\n",
+ "X O X X O X O\n",
+ "\n",
+ "Player O move: (1, 2)\n",
+ "O . . . . O .\n",
+ "X . . . . X .\n",
+ "O O . . . X .\n",
+ "X X X . O X X\n",
+ "O O O . X O O\n",
+ "X O X X O X O\n",
+ "\n",
+ "Player X move: (1, 1)\n",
+ "O . . . . O .\n",
+ "X X . . . X .\n",
+ "O O . . . X .\n",
+ "X X X . O X X\n",
+ "O O O . X O O\n",
+ "X O X X O X O\n",
+ "\n",
+ "Player O move: (3, 4)\n",
+ "O . . . . O .\n",
+ "X X . . . X .\n",
+ "O O . . . X .\n",
+ "X X X . O X X\n",
+ "O O O O X O O\n",
+ "X O X X O X O\n",
+ "\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "-1"
+ ]
+ },
+ "execution_count": 77,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "play_game(ConnectFour(), dict(X=random_player, O=random_player), verbose=True).utility"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Transposition Tables\n",
+ "\n",
+ "By treating the game tree as a tree, we can arrive at the same state through different paths, and end up duplicating effort. In state-space search, we kept a table of `reached` states to prevent this. For game-tree search, we can achieve the same effect by applying the `@cache` decorator to the `min_value` and `max_value` functions. We'll use the suffix `_tt` to indicate a function that uses these transisiton tables."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 11,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def minimax_search_tt(game, state):\n",
+ " \"\"\"Search game to determine best move; return (value, move) pair.\"\"\"\n",
+ "\n",
+ " player = state.to_move\n",
+ "\n",
+ " @cache\n",
+ " def max_value(state):\n",
+ " if game.is_terminal(state):\n",
+ " return game.utility(state, player), None\n",
+ " v, move = -infinity, None\n",
+ " for a in game.actions(state):\n",
+ " v2, _ = min_value(game.result(state, a))\n",
+ " if v2 > v:\n",
+ " v, move = v2, a\n",
+ " return v, move\n",
+ "\n",
+ " @cache\n",
+ " def min_value(state):\n",
+ " if game.is_terminal(state):\n",
+ " return game.utility(state, player), None\n",
+ " v, move = +infinity, None\n",
+ " for a in game.actions(state):\n",
+ " v2, _ = max_value(game.result(state, a))\n",
+ " if v2 < v:\n",
+ " v, move = v2, a\n",
+ " return v, move\n",
+ "\n",
+ " return max_value(state)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "For alpha-beta search, we can still use a cache, but it should be based just on the state, not on whatever values alpha and beta have."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 79,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def cache1(function):\n",
+ " \"Like lru_cache(None), but only considers the first argument of function.\"\n",
+ " cache = {}\n",
+ " def wrapped(x, *args):\n",
+ " if x not in cache:\n",
+ " cache[x] = function(x, *args)\n",
+ " return cache[x]\n",
+ " return wrapped\n",
+ "\n",
+ "def alphabeta_search_tt(game, state):\n",
+ " \"\"\"Search game to determine best action; use alpha-beta pruning.\n",
+ " As in [Figure 5.7], this version searches all the way to the leaves.\"\"\"\n",
+ "\n",
+ " player = state.to_move\n",
+ "\n",
+ " @cache1\n",
+ " def max_value(state, alpha, beta):\n",
+ " if game.is_terminal(state):\n",
+ " return game.utility(state, player), None\n",
+ " v, move = -infinity, None\n",
+ " for a in game.actions(state):\n",
+ " v2, _ = min_value(game.result(state, a), alpha, beta)\n",
+ " if v2 > v:\n",
+ " v, move = v2, a\n",
+ " alpha = max(alpha, v)\n",
+ " if v >= beta:\n",
+ " return v, move\n",
+ " return v, move\n",
+ "\n",
+ " @cache1\n",
+ " def min_value(state, alpha, beta):\n",
+ " if game.is_terminal(state):\n",
+ " return game.utility(state, player), None\n",
+ " v, move = +infinity, None\n",
+ " for a in game.actions(state):\n",
+ " v2, _ = max_value(game.result(state, a), alpha, beta)\n",
+ " if v2 < v:\n",
+ " v, move = v2, a\n",
+ " beta = min(beta, v)\n",
+ " if v <= alpha:\n",
+ " return v, move\n",
+ " return v, move\n",
+ "\n",
+ " return max_value(state, -infinity, +infinity)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 81,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "CPU times: user 593 ms, sys: 52 ms, total: 645 ms\n",
+ "Wall time: 655 ms\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "O X X\n",
+ "X O O\n",
+ "O X X"
+ ]
+ },
+ "execution_count": 81,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "%time play_game(TicTacToe(), {'X':player(alphabeta_search_tt), 'O':player(minimax_search_tt)})"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 82,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "CPU times: user 3.07 s, sys: 30.7 ms, total: 3.1 s\n",
+ "Wall time: 3.15 s\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "O X X\n",
+ "X O O\n",
+ "O X X"
+ ]
+ },
+ "execution_count": 82,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "%time play_game(TicTacToe(), {'X':player(alphabeta_search), 'O':player(minimax_search)})"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Heuristic Cutoffs"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 63,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def cutoff_depth(d):\n",
+ " \"\"\"A cutoff function that searches to depth d.\"\"\"\n",
+ " return lambda game, state, depth: depth > d\n",
+ "\n",
+ "def h_alphabeta_search(game, state, cutoff=cutoff_depth(6), h=lambda s, p: 0):\n",
+ " \"\"\"Search game to determine best action; use alpha-beta pruning.\n",
+ " As in [Figure 5.7], this version searches all the way to the leaves.\"\"\"\n",
+ "\n",
+ " player = state.to_move\n",
+ "\n",
+ " @cache1\n",
+ " def max_value(state, alpha, beta, depth):\n",
+ " if game.is_terminal(state):\n",
+ " return game.utility(state, player), None\n",
+ " if cutoff(game, state, depth):\n",
+ " return h(state, player), None\n",
+ " v, move = -infinity, None\n",
+ " for a in game.actions(state):\n",
+ " v2, _ = min_value(game.result(state, a), alpha, beta, depth+1)\n",
+ " if v2 > v:\n",
+ " v, move = v2, a\n",
+ " alpha = max(alpha, v)\n",
+ " if v >= beta:\n",
+ " return v, move\n",
+ " return v, move\n",
+ "\n",
+ " @cache1\n",
+ " def min_value(state, alpha, beta, depth):\n",
+ " if game.is_terminal(state):\n",
+ " return game.utility(state, player), None\n",
+ " if cutoff(game, state, depth):\n",
+ " return h(state, player), None\n",
+ " v, move = +infinity, None\n",
+ " for a in game.actions(state):\n",
+ " v2, _ = max_value(game.result(state, a), alpha, beta, depth + 1)\n",
+ " if v2 < v:\n",
+ " v, move = v2, a\n",
+ " beta = min(beta, v)\n",
+ " if v <= alpha:\n",
+ " return v, move\n",
+ " return v, move\n",
+ "\n",
+ " return max_value(state, -infinity, +infinity, 0)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 54,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "CPU times: user 367 ms, sys: 7.9 ms, total: 375 ms\n",
+ "Wall time: 375 ms\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "O X X\n",
+ "X O O\n",
+ "O X X"
+ ]
+ },
+ "execution_count": 54,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "%time play_game(TicTacToe(), {'X':player(h_alphabeta_search), 'O':player(h_alphabeta_search)})"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 60,
+ "metadata": {
+ "scrolled": false
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . X\n",
+ ". . . . . X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . O X\n",
+ ". . . . . X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . O X\n",
+ ". . . . X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". . . . . O X\n",
+ ". . . . X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". . . . X O X\n",
+ ". . . . X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". . . . X O X\n",
+ ". O . . X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". X . . X O X\n",
+ ". O . . X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . O O\n",
+ ". X . . X O X\n",
+ ". O . . X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . X O O\n",
+ ". X . . X O X\n",
+ ". O . . X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . X O O\n",
+ ". X . . X O X\n",
+ ". O . O X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . X .\n",
+ ". . . . X O O\n",
+ ". X . . X O X\n",
+ ". O . O X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". . . . . X .\n",
+ ". . . . X O O\n",
+ ". X . . X O X\n",
+ ". O . O X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". . . . . X .\n",
+ ". X . . X O O\n",
+ ". X . . X O X\n",
+ ". O . O X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". . . . . X O\n",
+ ". X . . X O O\n",
+ ". X . . X O X\n",
+ ". O . O X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". X . . . X O\n",
+ ". X . . X O O\n",
+ ". X . . X O X\n",
+ ". O . O X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". X . . . X O\n",
+ ". X . . X O O\n",
+ ". X . . X O X\n",
+ ". O O O X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". X . . . X O\n",
+ ". X . . X O O\n",
+ ". X . . X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . O O\n",
+ ". X . . . X O\n",
+ ". X . . X O O\n",
+ ". X . . X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ ". . . . . . X\n",
+ ". . . . . O O\n",
+ ". X . . . X O\n",
+ ". X . . X O O\n",
+ ". X . . X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ ". . . . . . X\n",
+ ". . . . . O O\n",
+ ". X . . . X O\n",
+ ". X . . X O O\n",
+ "O X . . X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ ". . . . . X X\n",
+ ". . . . . O O\n",
+ ". X . . . X O\n",
+ ". X . . X O O\n",
+ "O X . . X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ ". . . . . X X\n",
+ ". . . . . O O\n",
+ ". X . . . X O\n",
+ ". X . . X O O\n",
+ "O X . O X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ ". . . . . X X\n",
+ ". . . . . O O\n",
+ ". X . . . X O\n",
+ ". X . X X O O\n",
+ "O X . O X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ ". . . . . X X\n",
+ ". . . . . O O\n",
+ ". X . . O X O\n",
+ ". X . X X O O\n",
+ "O X . O X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ ". . . . . X X\n",
+ ". . . . . O O\n",
+ ". X . X O X O\n",
+ ". X . X X O O\n",
+ "O X . O X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ ". . . . . X X\n",
+ ". . . . O O O\n",
+ ". X . X O X O\n",
+ ". X . X X O O\n",
+ "O X . O X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ ". . . . . X X\n",
+ ". . . X O O O\n",
+ ". X . X O X O\n",
+ ". X . X X O O\n",
+ "O X . O X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ ". . . . O X X\n",
+ ". . . X O O O\n",
+ ". X . X O X O\n",
+ ". X . X X O O\n",
+ "O X . O X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ ". . . X O X X\n",
+ ". . . X O O O\n",
+ ". X . X O X O\n",
+ ". X . X X O O\n",
+ "O X . O X O X\n",
+ "X O O O X X O\n",
+ "\n",
+ "CPU times: user 8.82 s, sys: 146 ms, total: 8.96 s\n",
+ "Wall time: 9.19 s\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "1"
+ ]
+ },
+ "execution_count": 60,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "%time play_game(ConnectFour(), {'X':player(h_alphabeta_search), 'O':random_player}, verbose=True).utility"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 61,
+ "metadata": {
+ "scrolled": false
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". . . . . X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". . . . X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . O .\n",
+ ". . O . X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . X O .\n",
+ ". . O . X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . X O .\n",
+ ". . O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . X O .\n",
+ ". X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". O . . X O .\n",
+ ". X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". X . . . . .\n",
+ ". O . . X O .\n",
+ ". X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". O . . . . .\n",
+ ". X . . . . .\n",
+ ". O . . X O .\n",
+ ". X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". O . . . . .\n",
+ ". X . . . . .\n",
+ ". O . . X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". O . . . . .\n",
+ ". X . . . . .\n",
+ "O O . . X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". O . . . . .\n",
+ ". X . . X . .\n",
+ "O O . . X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . . . .\n",
+ ". O . . O . .\n",
+ ". X . . X . .\n",
+ "O O . . X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . X . .\n",
+ ". O . . O . .\n",
+ ". X . . X . .\n",
+ "O O . . X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . X . .\n",
+ ". O . . O . .\n",
+ ". X . . X O .\n",
+ "O O . . X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . X . .\n",
+ ". O . . O X .\n",
+ ". X . . X O .\n",
+ "O O . . X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . X . .\n",
+ ". O . . O X .\n",
+ ". X . . X O .\n",
+ "O O O . X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . X . .\n",
+ ". O . . O X .\n",
+ ". X . . X O .\n",
+ "O O O X X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . X O .\n",
+ ". O . . O X .\n",
+ ". X . . X O .\n",
+ "O O O X X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . X O .\n",
+ ". O . . O X .\n",
+ ". X . X X O .\n",
+ "O O O X X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . . X O .\n",
+ ". O . O O X .\n",
+ ". X . X X O .\n",
+ "O O O X X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . . . . .\n",
+ ". . . X X O .\n",
+ ". O . O O X .\n",
+ ". X . X X O .\n",
+ "O O O X X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . O . . .\n",
+ ". . . X X O .\n",
+ ". O . O O X .\n",
+ ". X . X X O .\n",
+ "O O O X X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ ". . . O . . .\n",
+ ". . . X X O .\n",
+ ". O . O O X .\n",
+ ". X X X X O .\n",
+ "O O O X X O .\n",
+ "X X O O X X .\n",
+ "\n",
+ "CPU times: user 12.1 s, sys: 237 ms, total: 12.4 s\n",
+ "Wall time: 12.9 s\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "1"
+ ]
+ },
+ "execution_count": 61,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "%time play_game(ConnectFour(), {'X':player(h_alphabeta_search), 'O':player(h_alphabeta_search)}, verbose=True).utility"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 83,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Result states: 6,589; Terminal tests: 3,653; for alphabeta_search_tt\n",
+ "Result states: 25,703; Terminal tests: 25,704; for alphabeta_search\n",
+ "Result states: 4,687; Terminal tests: 2,805; for h_alphabeta_search\n",
+ "Result states: 16,167; Terminal tests: 5,478; for minimax_search_tt\n"
+ ]
+ }
+ ],
+ "source": [
+ "class CountCalls:\n",
+ " \"\"\"Delegate all attribute gets to the object, and count them in ._counts\"\"\"\n",
+ " def __init__(self, obj):\n",
+ " self._object = obj\n",
+ " self._counts = Counter()\n",
+ " \n",
+ " def __getattr__(self, attr):\n",
+ " \"Delegate to the original object, after incrementing a counter.\"\n",
+ " self._counts[attr] += 1\n",
+ " return getattr(self._object, attr)\n",
+ " \n",
+ "def report(game, searchers):\n",
+ " for searcher in searchers:\n",
+ " game = CountCalls(game)\n",
+ " searcher(game, game.initial)\n",
+ " print('Result states: {:7,d}; Terminal tests: {:7,d}; for {}'.format(\n",
+ " game._counts['result'], game._counts['is_terminal'], searcher.__name__))\n",
+ " \n",
+ "report(TicTacToe(), (alphabeta_search_tt, alphabeta_search, h_alphabeta_search, minimax_search_tt))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Monte Carlo Tree Search"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class Node:\n",
+ " def __init__(self, parent, )\n",
+ "def mcts(state, game, N=1000):"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Heuristic Search Algorithms"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": []
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": []
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": []
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "t = CountCalls(TicTacToe())\n",
+ " \n",
+ "play_game(t, dict(X=minimax_player, O=minimax_player), verbose=True)\n",
+ "t._counts"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "for tactic in (three, fork, center, opposite_corner, corner, any):\n",
+ " for s in squares:\n",
+ " if tactic(board, s,player): return s\n",
+ " for s ins quares:\n",
+ " if tactic(board, s, opponent): return s"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "\n",
+ "\n",
+ "def ucb(U, N, C=2**0.5, parentN=100):\n",
+ " return round(U/N + C * math.sqrt(math.log(parentN)/N), 2)\n",
+ "\n",
+ "{C: (ucb(60, 79, C), ucb(1, 10, C), ucb(2, 11, C)) \n",
+ " for C in (1.4, 1.5)}\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def ucb(U, N, parentN=100, C=2):\n",
+ " return U/N + C * math.sqrt(math.log(parentN)/N)\n",
+ "\n",
+ "\n",
+ "C = 1.4 \n",
+ "\n",
+ "class Node:\n",
+ " def __init__(self, name, children=(), U=0, N=0, parent=None, p=0.5):\n",
+ " self.__dict__.update(name=name, U=U, N=N, parent=parent, children=children, p=p)\n",
+ " for c in children:\n",
+ " c.parent = self\n",
+ " \n",
+ " def __repr__(self):\n",
+ " return '{}:{}/{}={:.0%}{}'.format(self.name, self.U, self.N, self.U/self.N, self.children)\n",
+ " \n",
+ "def select(n):\n",
+ " if n.children:\n",
+ " return select(max(n.children, key=ucb))\n",
+ " else:\n",
+ " return n\n",
+ " \n",
+ "def back(n, amount):\n",
+ " if n:\n",
+ " n.N += 1\n",
+ " n.U += amount\n",
+ " back(n.parent, 1 - amount)\n",
+ " \n",
+ " \n",
+ "def one(root): \n",
+ " n = select(root)\n",
+ " amount = int(random.uniform(0, 1) < n.p)\n",
+ " back(n, amount)\n",
+ " \n",
+ "def ucb(n): \n",
+ " return (float('inf') if n.N == 0 else\n",
+ " n.U / n.N + C * math.sqrt(math.log(n.parent.N)/n.N))\n",
+ "\n",
+ "\n",
+ "tree = Node('root', [Node('a', p=.8, children=[Node('a1', p=.05), \n",
+ " Node('a2', p=.25,\n",
+ " children=[Node('a2a', p=.7), Node('a2b')])]),\n",
+ " Node('b', p=.5, children=[Node('b1', p=.6,\n",
+ " children=[Node('b1a', p=.3), Node('b1b')]), \n",
+ " Node('b2', p=.4)]),\n",
+ " Node('c', p=.1)])\n",
+ "\n",
+ "for i in range(100):\n",
+ " one(tree); \n",
+ "for c in tree.children: print(c)\n",
+ "'select', select(tree), 'tree', tree\n",
+ "\n",
+ "\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "us = (100, 50, 25, 10, 5, 1)\n",
+ "infinity = float('inf')\n",
+ "\n",
+ "@lru_cache(None)\n",
+ "def f1(n, denom):\n",
+ " return (0 if n == 0 else\n",
+ " infinity if n < 0 or not denom else\n",
+ " min(1 + f1(n - denom[0], denom),\n",
+ " f1(n, denom[1:])))\n",
+ " \n",
+ "@lru_cache(None)\n",
+ "def f2(n, denom):\n",
+ " @lru_cache(None)\n",
+ " def f(n):\n",
+ " return (0 if n == 0 else\n",
+ " infinity if n < 0 else\n",
+ " 1 + min(f(n - d) for d in denom))\n",
+ " return f(n)\n",
+ "\n",
+ "@lru_cache(None)\n",
+ "def f3(n, denom):\n",
+ " return (0 if n == 0 else\n",
+ " infinity if n < 0 or not denom else\n",
+ " min(k + f2(n - k * denom[0], denom[1:]) \n",
+ " for k in range(1 + n // denom[0])))\n",
+ " \n",
+ "\n",
+ "def g(n, d=us): return f1(n, d), f2(n, d), f3(n, d)\n",
+ " \n",
+ "n = 12345\n",
+ "%time f1(n, us)\n",
+ "%time f2(n, us)\n",
+ "%time f3(n, us)\n",
+ " "
+ ]
+ },
+ {
+ "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.7.2"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/games4e.py b/games4e.py
new file mode 100644
index 000000000..aba5b0eb3
--- /dev/null
+++ b/games4e.py
@@ -0,0 +1,635 @@
+"""Games or Adversarial Search (Chapter 5)"""
+
+import copy
+import itertools
+import random
+from collections import namedtuple
+
+import numpy as np
+
+from utils4e import vector_add, MCT_Node, ucb
+
+GameState = namedtuple('GameState', 'to_move, utility, board, moves')
+StochasticGameState = namedtuple('StochasticGameState', 'to_move, utility, board, moves, chance')
+
+
+# ______________________________________________________________________________
+# MinMax Search
+
+
+def minmax_decision(state, game):
+ """Given a state in a game, calculate the best move by searching
+ forward all the way to the terminal states. [Figure 5.3]"""
+
+ player = game.to_move(state)
+
+ def max_value(state):
+ if game.terminal_test(state):
+ return game.utility(state, player)
+ v = -np.inf
+ for a in game.actions(state):
+ v = max(v, min_value(game.result(state, a)))
+ return v
+
+ def min_value(state):
+ if game.terminal_test(state):
+ return game.utility(state, player)
+ v = np.inf
+ for a in game.actions(state):
+ v = min(v, max_value(game.result(state, a)))
+ return v
+
+ # Body of minmax_decision:
+ return max(game.actions(state), key=lambda a: min_value(game.result(state, a)))
+
+
+# ______________________________________________________________________________
+
+
+def expect_minmax(state, game):
+ """
+ [Figure 5.11]
+ Return the best move for a player after dice are thrown. The game tree
+ includes chance nodes along with min and max nodes.
+ """
+ player = game.to_move(state)
+
+ def max_value(state):
+ v = -np.inf
+ for a in game.actions(state):
+ v = max(v, chance_node(state, a))
+ return v
+
+ def min_value(state):
+ v = np.inf
+ for a in game.actions(state):
+ v = min(v, chance_node(state, a))
+ return v
+
+ def chance_node(state, action):
+ res_state = game.result(state, action)
+ if game.terminal_test(res_state):
+ return game.utility(res_state, player)
+ sum_chances = 0
+ num_chances = len(game.chances(res_state))
+ for chance in game.chances(res_state):
+ res_state = game.outcome(res_state, chance)
+ util = 0
+ if res_state.to_move == player:
+ util = max_value(res_state)
+ else:
+ util = min_value(res_state)
+ sum_chances += util * game.probability(chance)
+ return sum_chances / num_chances
+
+ # Body of expect_min_max:
+ return max(game.actions(state), key=lambda a: chance_node(state, a), default=None)
+
+
+def alpha_beta_search(state, game):
+ """Search game to determine best action; use alpha-beta pruning.
+ As in [Figure 5.7], this version searches all the way to the leaves."""
+
+ player = game.to_move(state)
+
+ # Functions used by alpha_beta
+ def max_value(state, alpha, beta):
+ if game.terminal_test(state):
+ return game.utility(state, player)
+ v = -np.inf
+ for a in game.actions(state):
+ v = max(v, min_value(game.result(state, a), alpha, beta))
+ if v >= beta:
+ return v
+ alpha = max(alpha, v)
+ return v
+
+ def min_value(state, alpha, beta):
+ if game.terminal_test(state):
+ return game.utility(state, player)
+ v = np.inf
+ for a in game.actions(state):
+ v = min(v, max_value(game.result(state, a), alpha, beta))
+ if v <= alpha:
+ return v
+ beta = min(beta, v)
+ return v
+
+ # Body of alpha_beta_search:
+ best_score = -np.inf
+ beta = np.inf
+ best_action = None
+ for a in game.actions(state):
+ v = min_value(game.result(state, a), best_score, beta)
+ if v > best_score:
+ best_score = v
+ best_action = a
+ return best_action
+
+
+def alpha_beta_cutoff_search(state, game, d=4, cutoff_test=None, eval_fn=None):
+ """Search game to determine best action; use alpha-beta pruning.
+ This version cuts off search and uses an evaluation function."""
+
+ player = game.to_move(state)
+
+ # Functions used by alpha_beta
+ def max_value(state, alpha, beta, depth):
+ if cutoff_test(state, depth):
+ return eval_fn(state)
+ v = -np.inf
+ for a in game.actions(state):
+ v = max(v, min_value(game.result(state, a), alpha, beta, depth + 1))
+ if v >= beta:
+ return v
+ alpha = max(alpha, v)
+ return v
+
+ def min_value(state, alpha, beta, depth):
+ if cutoff_test(state, depth):
+ return eval_fn(state)
+ v = np.inf
+ for a in game.actions(state):
+ v = min(v, max_value(game.result(state, a), alpha, beta, depth + 1))
+ if v <= alpha:
+ return v
+ beta = min(beta, v)
+ return v
+
+ # Body of alpha_beta_cutoff_search starts here:
+ # The default test cuts off at depth d or at a terminal state
+ cutoff_test = (cutoff_test or (lambda state, depth: depth > d or game.terminal_test(state)))
+ eval_fn = eval_fn or (lambda state: game.utility(state, player))
+ best_score = -np.inf
+ beta = np.inf
+ best_action = None
+ for a in game.actions(state):
+ v = min_value(game.result(state, a), best_score, beta, 1)
+ if v > best_score:
+ best_score = v
+ best_action = a
+ return best_action
+
+
+# ______________________________________________________________________________
+# Monte Carlo Tree Search
+
+
+def monte_carlo_tree_search(state, game, N=1000):
+ def select(n):
+ """select a leaf node in the tree"""
+ if n.children:
+ return select(max(n.children.keys(), key=ucb))
+ else:
+ return n
+
+ def expand(n):
+ """expand the leaf node by adding all its children states"""
+ if not n.children and not game.terminal_test(n.state):
+ n.children = {MCT_Node(state=game.result(n.state, action), parent=n): action
+ for action in game.actions(n.state)}
+ return select(n)
+
+ def simulate(game, state):
+ """simulate the utility of current state by random picking a step"""
+ player = game.to_move(state)
+ while not game.terminal_test(state):
+ action = random.choice(list(game.actions(state)))
+ state = game.result(state, action)
+ v = game.utility(state, player)
+ return -v
+
+ def backprop(n, utility):
+ """passing the utility back to all parent nodes"""
+ if utility > 0:
+ n.U += utility
+ # if utility == 0:
+ # n.U += 0.5
+ n.N += 1
+ if n.parent:
+ backprop(n.parent, -utility)
+
+ root = MCT_Node(state=state)
+
+ for _ in range(N):
+ leaf = select(root)
+ child = expand(leaf)
+ result = simulate(game, child.state)
+ backprop(child, result)
+
+ max_state = max(root.children, key=lambda p: p.N)
+
+ return root.children.get(max_state)
+
+
+# ______________________________________________________________________________
+# Players for Games
+
+
+def query_player(game, state):
+ """Make a move by querying standard input."""
+ print("current state:")
+ game.display(state)
+ print("available moves: {}".format(game.actions(state)))
+ print("")
+ move = None
+ if game.actions(state):
+ move_string = input('Your move? ')
+ try:
+ move = eval(move_string)
+ except NameError:
+ move = move_string
+ else:
+ print('no legal moves: passing turn to next player')
+ return move
+
+
+def random_player(game, state):
+ """A player that chooses a legal move at random."""
+ return random.choice(game.actions(state)) if game.actions(state) else None
+
+
+def alpha_beta_player(game, state):
+ return alpha_beta_search(state, game)
+
+
+def expect_min_max_player(game, state):
+ return expect_minmax(state, game)
+
+
+def mcts_player(game, state):
+ return monte_carlo_tree_search(state, game)
+
+
+# ______________________________________________________________________________
+# Some Sample Games
+
+
+class Game:
+ """A game is similar to a problem, but it has a utility for each
+ state and a terminal test instead of a path cost and a goal
+ test. To create a game, subclass this class and implement actions,
+ result, utility, and terminal_test. You may override display and
+ successors or you can inherit their default methods. You will also
+ need to set the .initial attribute to the initial state; this can
+ be done in the constructor."""
+
+ def actions(self, state):
+ """Return a list of the allowable moves at this point."""
+ raise NotImplementedError
+
+ def result(self, state, move):
+ """Return the state that results from making a move from a state."""
+ raise NotImplementedError
+
+ def utility(self, state, player):
+ """Return the value of this final state to player."""
+ raise NotImplementedError
+
+ def terminal_test(self, state):
+ """Return True if this is a final state for the game."""
+ return not self.actions(state)
+
+ def to_move(self, state):
+ """Return the player whose move it is in this state."""
+ return state.to_move
+
+ def display(self, state):
+ """Print or otherwise display the state."""
+ print(state)
+
+ def __repr__(self):
+ return '<{}>'.format(self.__class__.__name__)
+
+ def play_game(self, *players):
+ """Play an n-person, move-alternating game."""
+ state = self.initial
+ while True:
+ for player in players:
+ move = player(self, state)
+ state = self.result(state, move)
+ if self.terminal_test(state):
+ self.display(state)
+ return self.utility(state, self.to_move(self.initial))
+
+
+class StochasticGame(Game):
+ """A stochastic game includes uncertain events which influence
+ the moves of players at each state. To create a stochastic game, subclass
+ this class and implement chances and outcome along with the other
+ unimplemented game class methods."""
+
+ def chances(self, state):
+ """Return a list of all possible uncertain events at a state."""
+ raise NotImplementedError
+
+ def outcome(self, state, chance):
+ """Return the state which is the outcome of a chance trial."""
+ raise NotImplementedError
+
+ def probability(self, chance):
+ """Return the probability of occurrence of a chance."""
+ raise NotImplementedError
+
+ def play_game(self, *players):
+ """Play an n-person, move-alternating stochastic game."""
+ state = self.initial
+ while True:
+ for player in players:
+ chance = random.choice(self.chances(state))
+ state = self.outcome(state, chance)
+ move = player(self, state)
+ state = self.result(state, move)
+ if self.terminal_test(state):
+ self.display(state)
+ return self.utility(state, self.to_move(self.initial))
+
+
+class Fig52Game(Game):
+ """The game represented in [Figure 5.2]. Serves as a simple test case."""
+
+ succs = dict(A=dict(a1='B', a2='C', a3='D'),
+ B=dict(b1='B1', b2='B2', b3='B3'),
+ C=dict(c1='C1', c2='C2', c3='C3'),
+ D=dict(d1='D1', d2='D2', d3='D3'))
+ utils = dict(B1=3, B2=12, B3=8, C1=2, C2=4, C3=6, D1=14, D2=5, D3=2)
+ initial = 'A'
+
+ def actions(self, state):
+ return list(self.succs.get(state, {}).keys())
+
+ def result(self, state, move):
+ return self.succs[state][move]
+
+ def utility(self, state, player):
+ if player == 'MAX':
+ return self.utils[state]
+ else:
+ return -self.utils[state]
+
+ def terminal_test(self, state):
+ return state not in ('A', 'B', 'C', 'D')
+
+ def to_move(self, state):
+ return 'MIN' if state in 'BCD' else 'MAX'
+
+
+class Fig52Extended(Game):
+ """Similar to Fig52Game but bigger. Useful for visualisation"""
+
+ succs = {i: dict(l=i * 3 + 1, m=i * 3 + 2, r=i * 3 + 3) for i in range(13)}
+ utils = dict()
+
+ def actions(self, state):
+ return sorted(list(self.succs.get(state, {}).keys()))
+
+ def result(self, state, move):
+ return self.succs[state][move]
+
+ def utility(self, state, player):
+ if player == 'MAX':
+ return self.utils[state]
+ else:
+ return -self.utils[state]
+
+ def terminal_test(self, state):
+ return state not in range(13)
+
+ def to_move(self, state):
+ return 'MIN' if state in {1, 2, 3} else 'MAX'
+
+
+class TicTacToe(Game):
+ """Play TicTacToe on an h x v board, with Max (first player) playing 'X'.
+ A state has the player to move, a cached utility, a list of moves in
+ the form of a list of (x, y) positions, and a board, in the form of
+ a dict of {(x, y): Player} entries, where Player is 'X' or 'O'."""
+
+ def __init__(self, h=3, v=3, k=3):
+ self.h = h
+ self.v = v
+ self.k = k
+ moves = [(x, y) for x in range(1, h + 1)
+ for y in range(1, v + 1)]
+ self.initial = GameState(to_move='X', utility=0, board={}, moves=moves)
+
+ def actions(self, state):
+ """Legal moves are any square not yet taken."""
+ return state.moves
+
+ def result(self, state, move):
+ if move not in state.moves:
+ return state # Illegal move has no effect
+ board = state.board.copy()
+ board[move] = state.to_move
+ moves = list(state.moves)
+ moves.remove(move)
+ return GameState(to_move=('O' if state.to_move == 'X' else 'X'),
+ utility=self.compute_utility(board, move, state.to_move),
+ board=board, moves=moves)
+
+ def utility(self, state, player):
+ """Return the value to player; 1 for win, -1 for loss, 0 otherwise."""
+ return state.utility if player == 'X' else -state.utility
+
+ def terminal_test(self, state):
+ """A state is terminal if it is won or there are no empty squares."""
+ return state.utility != 0 or len(state.moves) == 0
+
+ def display(self, state):
+ board = state.board
+ for x in range(1, self.h + 1):
+ for y in range(1, self.v + 1):
+ print(board.get((x, y), '.'), end=' ')
+ print()
+
+ def compute_utility(self, board, move, player):
+ """If 'X' wins with this move, return 1; if 'O' wins return -1; else return 0."""
+ if (self.k_in_row(board, move, player, (0, 1)) or
+ self.k_in_row(board, move, player, (1, 0)) or
+ self.k_in_row(board, move, player, (1, -1)) or
+ self.k_in_row(board, move, player, (1, 1))):
+ return +1 if player == 'X' else -1
+ else:
+ return 0
+
+ def k_in_row(self, board, move, player, delta_x_y):
+ """Return true if there is a line through move on board for player."""
+ (delta_x, delta_y) = delta_x_y
+ x, y = move
+ n = 0 # n is number of moves in row
+ while board.get((x, y)) == player:
+ n += 1
+ x, y = x + delta_x, y + delta_y
+ x, y = move
+ while board.get((x, y)) == player:
+ n += 1
+ x, y = x - delta_x, y - delta_y
+ n -= 1 # Because we counted move itself twice
+ return n >= self.k
+
+
+class ConnectFour(TicTacToe):
+ """A TicTacToe-like game in which you can only make a move on the bottom
+ row, or in a square directly above an occupied square. Traditionally
+ played on a 7x6 board and requiring 4 in a row."""
+
+ def __init__(self, h=7, v=6, k=4):
+ TicTacToe.__init__(self, h, v, k)
+
+ def actions(self, state):
+ return [(x, y) for (x, y) in state.moves
+ if y == 1 or (x, y - 1) in state.board]
+
+
+class Backgammon(StochasticGame):
+ """A two player game where the goal of each player is to move all the
+ checkers off the board. The moves for each state are determined by
+ rolling a pair of dice."""
+
+ def __init__(self):
+ """Initial state of the game"""
+ point = {'W': 0, 'B': 0}
+ board = [point.copy() for index in range(24)]
+ board[0]['B'] = board[23]['W'] = 2
+ board[5]['W'] = board[18]['B'] = 5
+ board[7]['W'] = board[16]['B'] = 3
+ board[11]['B'] = board[12]['W'] = 5
+ self.allow_bear_off = {'W': False, 'B': False}
+ self.direction = {'W': -1, 'B': 1}
+ self.initial = StochasticGameState(to_move='W',
+ utility=0,
+ board=board,
+ moves=self.get_all_moves(board, 'W'), chance=None)
+
+ def actions(self, state):
+ """Return a list of legal moves for a state."""
+ player = state.to_move
+ moves = state.moves
+ if len(moves) == 1 and len(moves[0]) == 1:
+ return moves
+ legal_moves = []
+ for move in moves:
+ board = copy.deepcopy(state.board)
+ if self.is_legal_move(board, move, state.chance, player):
+ legal_moves.append(move)
+ return legal_moves
+
+ def result(self, state, move):
+ board = copy.deepcopy(state.board)
+ player = state.to_move
+ self.move_checker(board, move[0], state.chance[0], player)
+ if len(move) == 2:
+ self.move_checker(board, move[1], state.chance[1], player)
+ to_move = ('W' if player == 'B' else 'B')
+ return StochasticGameState(to_move=to_move,
+ utility=self.compute_utility(board, move, player),
+ board=board,
+ moves=self.get_all_moves(board, to_move), chance=None)
+
+ def utility(self, state, player):
+ """Return the value to player; 1 for win, -1 for loss, 0 otherwise."""
+ return state.utility if player == 'W' else -state.utility
+
+ def terminal_test(self, state):
+ """A state is terminal if one player wins."""
+ return state.utility != 0
+
+ def get_all_moves(self, board, player):
+ """All possible moves for a player i.e. all possible ways of
+ choosing two checkers of a player from the board for a move
+ at a given state."""
+ all_points = board
+ taken_points = [index for index, point in enumerate(all_points)
+ if point[player] > 0]
+ if self.checkers_at_home(board, player) == 1:
+ return [(taken_points[0],)]
+ moves = list(itertools.permutations(taken_points, 2))
+ moves = moves + [(index, index) for index, point in enumerate(all_points)
+ if point[player] >= 2]
+ return moves
+
+ def display(self, state):
+ """Display state of the game."""
+ board = state.board
+ player = state.to_move
+ print("current state : ")
+ for index, point in enumerate(board):
+ print("point : ", index, " W : ", point['W'], " B : ", point['B'])
+ print("to play : ", player)
+
+ def compute_utility(self, board, move, player):
+ """If 'W' wins with this move, return 1; if 'B' wins return -1; else return 0."""
+ util = {'W': 1, 'B': -1}
+ for idx in range(0, 24):
+ if board[idx][player] > 0:
+ return 0
+ return util[player]
+
+ def checkers_at_home(self, board, player):
+ """Return the no. of checkers at home for a player."""
+ sum_range = range(0, 7) if player == 'W' else range(17, 24)
+ count = 0
+ for idx in sum_range:
+ count = count + board[idx][player]
+ return count
+
+ def is_legal_move(self, board, start, steps, player):
+ """Move is a tuple which contains starting points of checkers to be
+ moved during a player's turn. An on-board move is legal if both the destinations
+ are open. A bear-off move is the one where a checker is moved off-board.
+ It is legal only after a player has moved all his checkers to his home."""
+ dest1, dest2 = vector_add(start, steps)
+ dest_range = range(0, 24)
+ move1_legal = move2_legal = False
+ if dest1 in dest_range:
+ if self.is_point_open(player, board[dest1]):
+ self.move_checker(board, start[0], steps[0], player)
+ move1_legal = True
+ else:
+ if self.allow_bear_off[player]:
+ self.move_checker(board, start[0], steps[0], player)
+ move1_legal = True
+ if not move1_legal:
+ return False
+ if dest2 in dest_range:
+ if self.is_point_open(player, board[dest2]):
+ move2_legal = True
+ else:
+ if self.allow_bear_off[player]:
+ move2_legal = True
+ return move1_legal and move2_legal
+
+ def move_checker(self, board, start, steps, player):
+ """Move a checker from starting point by a given number of steps"""
+ dest = start + steps
+ dest_range = range(0, 24)
+ board[start][player] -= 1
+ if dest in dest_range:
+ board[dest][player] += 1
+ if self.checkers_at_home(board, player) == 15:
+ self.allow_bear_off[player] = True
+
+ def is_point_open(self, player, point):
+ """A point is open for a player if the no. of opponent's
+ checkers already present on it is 0 or 1. A player can
+ move a checker to a point only if it is open."""
+ opponent = 'B' if player == 'W' else 'W'
+ return point[opponent] <= 1
+
+ def chances(self, state):
+ """Return a list of all possible dice rolls at a state."""
+ dice_rolls = list(itertools.combinations_with_replacement([1, 2, 3, 4, 5, 6], 2))
+ return dice_rolls
+
+ def outcome(self, state, chance):
+ """Return the state which is the outcome of a dice roll."""
+ dice = tuple(map((self.direction[state.to_move]).__mul__, chance))
+ return StochasticGameState(to_move=state.to_move,
+ utility=state.utility,
+ board=state.board,
+ moves=state.moves, chance=dice)
+
+ def probability(self, chance):
+ """Return the probability of occurrence of a dice roll."""
+ return 1 / 36 if chance[0] == chance[1] else 1 / 18
diff --git a/gui/eight_puzzle.py b/gui/eight_puzzle.py
new file mode 100644
index 000000000..5733228d7
--- /dev/null
+++ b/gui/eight_puzzle.py
@@ -0,0 +1,151 @@
+import os.path
+import random
+import time
+from functools import partial
+from tkinter import *
+
+from search import astar_search, EightPuzzle
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+
+root = Tk()
+
+state = [1, 2, 3, 4, 5, 6, 7, 8, 0]
+puzzle = EightPuzzle(tuple(state))
+solution = None
+
+b = [None] * 9
+
+
+# TODO: refactor into OOP, remove global variables
+
+def scramble():
+ """Scrambles the puzzle starting from the goal state"""
+
+ global state
+ global puzzle
+ possible_actions = ['UP', 'DOWN', 'LEFT', 'RIGHT']
+ scramble = []
+ for _ in range(60):
+ scramble.append(random.choice(possible_actions))
+
+ for move in scramble:
+ if move in puzzle.actions(state):
+ state = list(puzzle.result(state, move))
+ puzzle = EightPuzzle(tuple(state))
+ create_buttons()
+
+
+def solve():
+ """Solves the puzzle using astar_search"""
+
+ return astar_search(puzzle).solution()
+
+
+def solve_steps():
+ """Solves the puzzle step by step"""
+
+ global puzzle
+ global solution
+ global state
+ solution = solve()
+ print(solution)
+
+ for move in solution:
+ state = puzzle.result(state, move)
+ create_buttons()
+ root.update()
+ root.after(1, time.sleep(0.75))
+
+
+def exchange(index):
+ """Interchanges the position of the selected tile with the zero tile under certain conditions"""
+
+ global state
+ global solution
+ global puzzle
+ zero_ix = list(state).index(0)
+ actions = puzzle.actions(state)
+ current_action = ''
+ i_diff = index // 3 - zero_ix // 3
+ j_diff = index % 3 - zero_ix % 3
+ if i_diff == 1:
+ current_action += 'DOWN'
+ elif i_diff == -1:
+ current_action += 'UP'
+
+ if j_diff == 1:
+ current_action += 'RIGHT'
+ elif j_diff == -1:
+ current_action += 'LEFT'
+
+ if abs(i_diff) + abs(j_diff) != 1:
+ current_action = ''
+
+ if current_action in actions:
+ b[zero_ix].grid_forget()
+ b[zero_ix] = Button(root, text=f'{state[index]}', width=6, font=('Helvetica', 40, 'bold'),
+ command=partial(exchange, zero_ix))
+ b[zero_ix].grid(row=zero_ix // 3, column=zero_ix % 3, ipady=40)
+ b[index].grid_forget()
+ b[index] = Button(root, text=None, width=6, font=('Helvetica', 40, 'bold'), command=partial(exchange, index))
+ b[index].grid(row=index // 3, column=index % 3, ipady=40)
+ state[zero_ix], state[index] = state[index], state[zero_ix]
+ puzzle = EightPuzzle(tuple(state))
+
+
+def create_buttons():
+ """Creates dynamic buttons"""
+
+ # TODO: Find a way to use grid_forget() with a for loop for initialization
+ b[0] = Button(root, text=f'{state[0]}' if state[0] != 0 else None, width=6, font=('Helvetica', 40, 'bold'),
+ command=partial(exchange, 0))
+ b[0].grid(row=0, column=0, ipady=40)
+ b[1] = Button(root, text=f'{state[1]}' if state[1] != 0 else None, width=6, font=('Helvetica', 40, 'bold'),
+ command=partial(exchange, 1))
+ b[1].grid(row=0, column=1, ipady=40)
+ b[2] = Button(root, text=f'{state[2]}' if state[2] != 0 else None, width=6, font=('Helvetica', 40, 'bold'),
+ command=partial(exchange, 2))
+ b[2].grid(row=0, column=2, ipady=40)
+ b[3] = Button(root, text=f'{state[3]}' if state[3] != 0 else None, width=6, font=('Helvetica', 40, 'bold'),
+ command=partial(exchange, 3))
+ b[3].grid(row=1, column=0, ipady=40)
+ b[4] = Button(root, text=f'{state[4]}' if state[4] != 0 else None, width=6, font=('Helvetica', 40, 'bold'),
+ command=partial(exchange, 4))
+ b[4].grid(row=1, column=1, ipady=40)
+ b[5] = Button(root, text=f'{state[5]}' if state[5] != 0 else None, width=6, font=('Helvetica', 40, 'bold'),
+ command=partial(exchange, 5))
+ b[5].grid(row=1, column=2, ipady=40)
+ b[6] = Button(root, text=f'{state[6]}' if state[6] != 0 else None, width=6, font=('Helvetica', 40, 'bold'),
+ command=partial(exchange, 6))
+ b[6].grid(row=2, column=0, ipady=40)
+ b[7] = Button(root, text=f'{state[7]}' if state[7] != 0 else None, width=6, font=('Helvetica', 40, 'bold'),
+ command=partial(exchange, 7))
+ b[7].grid(row=2, column=1, ipady=40)
+ b[8] = Button(root, text=f'{state[8]}' if state[8] != 0 else None, width=6, font=('Helvetica', 40, 'bold'),
+ command=partial(exchange, 8))
+ b[8].grid(row=2, column=2, ipady=40)
+
+
+def create_static_buttons():
+ """Creates scramble and solve buttons"""
+
+ scramble_btn = Button(root, text='Scramble', font=('Helvetica', 30, 'bold'), width=8, command=partial(init))
+ scramble_btn.grid(row=3, column=0, ipady=10)
+ solve_btn = Button(root, text='Solve', font=('Helvetica', 30, 'bold'), width=8, command=partial(solve_steps))
+ solve_btn.grid(row=3, column=2, ipady=10)
+
+
+def init():
+ """Calls necessary functions"""
+
+ global state
+ global solution
+ state = [1, 2, 3, 4, 5, 6, 7, 8, 0]
+ scramble()
+ create_buttons()
+ create_static_buttons()
+
+
+init()
+root.mainloop()
diff --git a/gui/genetic_algorithm_example.py b/gui/genetic_algorithm_example.py
new file mode 100644
index 000000000..c987151c8
--- /dev/null
+++ b/gui/genetic_algorithm_example.py
@@ -0,0 +1,189 @@
+# A simple program that implements the solution to the phrase generation problem using
+# genetic algorithms as given in the search.ipynb notebook.
+#
+# Type on the home screen to change the target phrase
+# Click on the slider to change genetic algorithm parameters
+# Click 'GO' to run the algorithm with the specified variables
+# Displays best individual of the current generation
+# Displays a progress bar that indicates the amount of completion of the algorithm
+# Displays the first few individuals of the current generation
+
+import os.path
+from tkinter import *
+from tkinter import ttk
+
+import search
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+
+LARGE_FONT = ('Verdana', 12)
+EXTRA_LARGE_FONT = ('Consolas', 36, 'bold')
+
+canvas_width = 800
+canvas_height = 600
+
+black = '#000000'
+white = '#ffffff'
+p_blue = '#042533'
+lp_blue = '#0c394c'
+
+# genetic algorithm variables
+# feel free to play around with these
+target = 'Genetic Algorithm' # the phrase to be generated
+max_population = 100 # number of samples in each population
+mutation_rate = 0.1 # probability of mutation
+f_thres = len(target) # fitness threshold
+ngen = 1200 # max number of generations to run the genetic algorithm
+
+generation = 0 # counter to keep track of generation number
+
+u_case = [chr(x) for x in range(65, 91)] # list containing all uppercase characters
+l_case = [chr(x) for x in range(97, 123)] # list containing all lowercase characters
+punctuations1 = [chr(x) for x in range(33, 48)] # lists containing punctuation symbols
+punctuations2 = [chr(x) for x in range(58, 65)]
+punctuations3 = [chr(x) for x in range(91, 97)]
+numerals = [chr(x) for x in range(48, 58)] # list containing numbers
+
+# extend the gene pool with the required lists and append the space character
+gene_pool = []
+gene_pool.extend(u_case)
+gene_pool.extend(l_case)
+gene_pool.append(' ')
+
+
+# callbacks to update global variables from the slider values
+def update_max_population(slider_value):
+ global max_population
+ max_population = slider_value
+
+
+def update_mutation_rate(slider_value):
+ global mutation_rate
+ mutation_rate = slider_value
+
+
+def update_f_thres(slider_value):
+ global f_thres
+ f_thres = slider_value
+
+
+def update_ngen(slider_value):
+ global ngen
+ ngen = slider_value
+
+
+# fitness function
+def fitness_fn(_list):
+ fitness = 0
+ # create string from list of characters
+ phrase = ''.join(_list)
+ # add 1 to fitness value for every matching character
+ for i in range(len(phrase)):
+ if target[i] == phrase[i]:
+ fitness += 1
+ return fitness
+
+
+# function to bring a new frame on top
+def raise_frame(frame, init=False, update_target=False, target_entry=None, f_thres_slider=None):
+ frame.tkraise()
+ global target
+ if update_target and target_entry is not None:
+ target = target_entry.get()
+ f_thres_slider.config(to=len(target))
+ if init:
+ population = search.init_population(max_population, gene_pool, len(target))
+ genetic_algorithm_stepwise(population)
+
+
+# defining root and child frames
+root = Tk()
+f1 = Frame(root)
+f2 = Frame(root)
+
+# pack frames on top of one another
+for frame in (f1, f2):
+ frame.grid(row=0, column=0, sticky='news')
+
+# Home Screen (f1) widgets
+target_entry = Entry(f1, font=('Consolas 46 bold'), exportselection=0, foreground=p_blue, justify=CENTER)
+target_entry.insert(0, target)
+target_entry.pack(expand=YES, side=TOP, fill=X, padx=50)
+target_entry.focus_force()
+
+max_population_slider = Scale(f1, from_=3, to=1000, orient=HORIZONTAL, label='Max population',
+ command=lambda value: update_max_population(int(value)))
+max_population_slider.set(max_population)
+max_population_slider.pack(expand=YES, side=TOP, fill=X, padx=40)
+
+mutation_rate_slider = Scale(f1, from_=0, to=1, orient=HORIZONTAL, label='Mutation rate', resolution=0.0001,
+ command=lambda value: update_mutation_rate(float(value)))
+mutation_rate_slider.set(mutation_rate)
+mutation_rate_slider.pack(expand=YES, side=TOP, fill=X, padx=40)
+
+f_thres_slider = Scale(f1, from_=0, to=len(target), orient=HORIZONTAL, label='Fitness threshold',
+ command=lambda value: update_f_thres(int(value)))
+f_thres_slider.set(f_thres)
+f_thres_slider.pack(expand=YES, side=TOP, fill=X, padx=40)
+
+ngen_slider = Scale(f1, from_=1, to=5000, orient=HORIZONTAL, label='Max number of generations',
+ command=lambda value: update_ngen(int(value)))
+ngen_slider.set(ngen)
+ngen_slider.pack(expand=YES, side=TOP, fill=X, padx=40)
+
+button = ttk.Button(f1, text='RUN',
+ command=lambda: raise_frame(f2, init=True, update_target=True, target_entry=target_entry,
+ f_thres_slider=f_thres_slider)).pack(side=BOTTOM, pady=50)
+
+# f2 widgets
+canvas = Canvas(f2, width=canvas_width, height=canvas_height)
+canvas.pack(expand=YES, fill=BOTH, padx=20, pady=15)
+button = ttk.Button(f2, text='EXIT', command=lambda: raise_frame(f1)).pack(side=BOTTOM, pady=15)
+
+
+# function to run the genetic algorithm and update text on the canvas
+def genetic_algorithm_stepwise(population):
+ root.title('Genetic Algorithm')
+ for generation in range(ngen):
+ # generating new population after selecting, recombining and mutating the existing population
+ population = [
+ search.mutate(search.recombine(*search.select(2, population, fitness_fn)), gene_pool, mutation_rate) for i
+ in range(len(population))]
+ # genome with the highest fitness in the current generation
+ current_best = ''.join(max(population, key=fitness_fn))
+ # collecting first few examples from the current population
+ members = [''.join(x) for x in population][:48]
+
+ # clear the canvas
+ canvas.delete('all')
+ # displays current best on top of the screen
+ canvas.create_text(canvas_width / 2, 40, fill=p_blue, font='Consolas 46 bold', text=current_best)
+
+ # displaying a part of the population on the screen
+ for i in range(len(members) // 3):
+ canvas.create_text((canvas_width * .175), (canvas_height * .25 + (25 * i)), fill=lp_blue,
+ font='Consolas 16', text=members[3 * i])
+ canvas.create_text((canvas_width * .500), (canvas_height * .25 + (25 * i)), fill=lp_blue,
+ font='Consolas 16', text=members[3 * i + 1])
+ canvas.create_text((canvas_width * .825), (canvas_height * .25 + (25 * i)), fill=lp_blue,
+ font='Consolas 16', text=members[3 * i + 2])
+
+ # displays current generation number
+ canvas.create_text((canvas_width * .5), (canvas_height * 0.95), fill=p_blue, font='Consolas 18 bold',
+ text=f'Generation {generation}')
+
+ # displays blue bar that indicates current maximum fitness compared to maximum possible fitness
+ scaling_factor = fitness_fn(current_best) / len(target)
+ canvas.create_rectangle(canvas_width * 0.1, 90, canvas_width * 0.9, 100, outline=p_blue)
+ canvas.create_rectangle(canvas_width * 0.1, 90, canvas_width * 0.1 + scaling_factor * canvas_width * 0.8, 100,
+ fill=lp_blue)
+ canvas.update()
+
+ # checks for completion
+ fittest_individual = search.fitness_threshold(fitness_fn, f_thres, population)
+ if fittest_individual:
+ break
+
+
+raise_frame(f1)
+root.mainloop()
diff --git a/gui/grid_mdp.py b/gui/grid_mdp.py
new file mode 100644
index 000000000..e60b49247
--- /dev/null
+++ b/gui/grid_mdp.py
@@ -0,0 +1,676 @@
+import os.path
+import sys
+import tkinter as tk
+import tkinter.messagebox
+from functools import partial
+from tkinter import ttk
+
+import matplotlib
+import matplotlib.animation as animation
+from matplotlib import pyplot as plt
+from matplotlib import style
+from matplotlib.backends.backend_tkagg import FigureCanvasTkAgg
+from matplotlib.figure import Figure
+from matplotlib.ticker import MaxNLocator
+
+from mdp import *
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+
+matplotlib.use('TkAgg')
+style.use('ggplot')
+
+fig = Figure(figsize=(20, 15))
+sub = fig.add_subplot(111)
+plt.rcParams['axes.grid'] = False
+
+WALL_VALUE = -99999.0
+TERM_VALUE = -999999.0
+
+black = '#000'
+white = '#fff'
+gray2 = '#222'
+gray9 = '#999'
+grayd = '#ddd'
+grayef = '#efefef'
+pblue = '#000040'
+green8 = '#008080'
+green4 = '#004040'
+
+cell_window_mantainer = None
+
+
+def extents(f):
+ """adjusts axis markers for heatmap"""
+
+ delta = f[1] - f[0]
+ return [f[0] - delta / 2, f[-1] + delta / 2]
+
+
+def display(gridmdp, _height, _width):
+ """displays matrix"""
+
+ dialog = tk.Toplevel()
+ dialog.wm_title('Values')
+
+ container = tk.Frame(dialog)
+ container.pack(side=tk.TOP, fill=tk.BOTH, expand=True)
+
+ for i in range(max(1, _height)):
+ for j in range(max(1, _width)):
+ label = ttk.Label(container, text=f'{gridmdp[_height - i - 1][j]:.3f}', font=('Helvetica', 12))
+ label.grid(row=i + 1, column=j + 1, padx=3, pady=3)
+
+ dialog.mainloop()
+
+
+def display_best_policy(_best_policy, _height, _width):
+ """displays best policy"""
+ dialog = tk.Toplevel()
+ dialog.wm_title('Best Policy')
+
+ container = tk.Frame(dialog)
+ container.pack(side=tk.TOP, fill=tk.BOTH, expand=True)
+
+ for i in range(max(1, _height)):
+ for j in range(max(1, _width)):
+ label = ttk.Label(container, text=_best_policy[i][j], font=('Helvetica', 12, 'bold'))
+ label.grid(row=i + 1, column=j + 1, padx=3, pady=3)
+
+ dialog.mainloop()
+
+
+def initialize_dialogbox(_width, _height, gridmdp, terminals, buttons):
+ """creates dialogbox for initialization"""
+
+ dialog = tk.Toplevel()
+ dialog.wm_title('Initialize')
+
+ container = tk.Frame(dialog)
+ container.pack(side=tk.TOP, fill=tk.BOTH, expand=True)
+ container.grid_rowconfigure(0, weight=1)
+ container.grid_columnconfigure(0, weight=1)
+
+ wall = tk.IntVar()
+ wall.set(0)
+ term = tk.IntVar()
+ term.set(0)
+ reward = tk.DoubleVar()
+ reward.set(0.0)
+
+ label = ttk.Label(container, text='Initialize', font=('Helvetica', 12), anchor=tk.N)
+ label.grid(row=0, column=0, columnspan=3, sticky='new', pady=15, padx=5)
+ label_reward = ttk.Label(container, text='Reward', font=('Helvetica', 10), anchor=tk.N)
+ label_reward.grid(row=1, column=0, columnspan=3, sticky='new', pady=1, padx=5)
+ entry_reward = ttk.Entry(container, font=('Helvetica', 10), justify=tk.CENTER, exportselection=0,
+ textvariable=reward)
+ entry_reward.grid(row=2, column=0, columnspan=3, sticky='new', pady=5, padx=50)
+
+ rbtn_term = ttk.Radiobutton(container, text='Terminal', variable=term, value=TERM_VALUE)
+ rbtn_term.grid(row=3, column=0, columnspan=3, sticky='nsew', padx=160, pady=5)
+ rbtn_wall = ttk.Radiobutton(container, text='Wall', variable=wall, value=WALL_VALUE)
+ rbtn_wall.grid(row=4, column=0, columnspan=3, sticky='nsew', padx=172, pady=5)
+
+ initialize_widget_disability_checks(_width, _height, gridmdp, terminals, label_reward, entry_reward, rbtn_wall,
+ rbtn_term)
+
+ btn_apply = ttk.Button(container, text='Apply',
+ command=partial(initialize_update_table, _width, _height, gridmdp, terminals, buttons,
+ reward, term, wall, label_reward, entry_reward, rbtn_term, rbtn_wall))
+ btn_apply.grid(row=5, column=0, sticky='nsew', pady=5, padx=5)
+ btn_reset = ttk.Button(container, text='Reset',
+ command=partial(initialize_reset_all, _width, _height, gridmdp, terminals, buttons, reward,
+ term, wall, label_reward, entry_reward, rbtn_wall, rbtn_term))
+ btn_reset.grid(row=5, column=1, sticky='nsew', pady=5, padx=5)
+ btn_ok = ttk.Button(container, text='Ok', command=dialog.destroy)
+ btn_ok.grid(row=5, column=2, sticky='nsew', pady=5, padx=5)
+
+ dialog.geometry('400x200')
+ dialog.mainloop()
+
+
+def update_table(i, j, gridmdp, terminals, buttons, reward, term, wall, label_reward, entry_reward, rbtn_term,
+ rbtn_wall):
+ """functionality for 'apply' button"""
+ if wall.get() == WALL_VALUE:
+ buttons[i][j].configure(style='wall.TButton')
+ buttons[i][j].config(text='Wall')
+ label_reward.config(foreground='#999')
+ entry_reward.config(state=tk.DISABLED)
+ rbtn_term.state(['!focus', '!selected'])
+ rbtn_term.config(state=tk.DISABLED)
+ gridmdp[i][j] = WALL_VALUE
+
+ elif wall.get() != WALL_VALUE:
+ if reward.get() != 0.0:
+ gridmdp[i][j] = reward.get()
+ buttons[i][j].configure(style='reward.TButton')
+ buttons[i][j].config(text=f'R = {reward.get()}')
+
+ if term.get() == TERM_VALUE:
+ if (i, j) not in terminals:
+ terminals.append((i, j))
+ rbtn_wall.state(['!focus', '!selected'])
+ rbtn_wall.config(state=tk.DISABLED)
+
+ if gridmdp[i][j] < 0:
+ buttons[i][j].configure(style='-term.TButton')
+
+ elif gridmdp[i][j] > 0:
+ buttons[i][j].configure(style='+term.TButton')
+
+ elif gridmdp[i][j] == 0.0:
+ buttons[i][j].configure(style='=term.TButton')
+
+
+def initialize_update_table(_width, _height, gridmdp, terminals, buttons, reward, term, wall, label_reward,
+ entry_reward, rbtn_term, rbtn_wall):
+ """runs update_table for all cells"""
+
+ for i in range(max(1, _height)):
+ for j in range(max(1, _width)):
+ update_table(i, j, gridmdp, terminals, buttons, reward, term, wall, label_reward, entry_reward, rbtn_term,
+ rbtn_wall)
+
+
+def reset_all(_height, i, j, gridmdp, terminals, buttons, reward, term, wall, label_reward, entry_reward, rbtn_wall,
+ rbtn_term):
+ """functionality for reset button"""
+ reward.set(0.0)
+ term.set(0)
+ wall.set(0)
+ gridmdp[i][j] = 0.0
+ buttons[i][j].configure(style='TButton')
+ buttons[i][j].config(text=f'({_height - i - 1}, {j})')
+
+ if (i, j) in terminals:
+ terminals.remove((i, j))
+
+ label_reward.config(foreground='#000')
+ entry_reward.config(state=tk.NORMAL)
+ rbtn_term.config(state=tk.NORMAL)
+ rbtn_wall.config(state=tk.NORMAL)
+ rbtn_wall.state(['!focus', '!selected'])
+ rbtn_term.state(['!focus', '!selected'])
+
+
+def initialize_reset_all(_width, _height, gridmdp, terminals, buttons, reward, term, wall, label_reward, entry_reward,
+ rbtn_wall, rbtn_term):
+ """runs reset_all for all cells"""
+
+ for i in range(max(1, _height)):
+ for j in range(max(1, _width)):
+ reset_all(_height, i, j, gridmdp, terminals, buttons, reward, term, wall, label_reward, entry_reward,
+ rbtn_wall, rbtn_term)
+
+
+def external_reset(_width, _height, gridmdp, terminals, buttons):
+ """reset from edit menu"""
+ for i in range(max(1, _height)):
+ for j in range(max(1, _width)):
+ gridmdp[i][j] = 0.0
+ buttons[i][j].configure(style='TButton')
+ buttons[i][j].config(text=f'({_height - i - 1}, {j})')
+
+
+def widget_disability_checks(i, j, gridmdp, terminals, label_reward, entry_reward, rbtn_wall, rbtn_term):
+ """checks for required state of widgets in dialog boxes"""
+
+ if gridmdp[i][j] == WALL_VALUE:
+ label_reward.config(foreground='#999')
+ entry_reward.config(state=tk.DISABLED)
+ rbtn_term.config(state=tk.DISABLED)
+ rbtn_wall.state(['!focus', 'selected'])
+ rbtn_term.state(['!focus', '!selected'])
+
+ if (i, j) in terminals:
+ rbtn_wall.config(state=tk.DISABLED)
+ rbtn_wall.state(['!focus', '!selected'])
+
+
+def flatten_list(_list):
+ """returns a flattened list"""
+ return sum(_list, [])
+
+
+def initialize_widget_disability_checks(_width, _height, gridmdp, terminals, label_reward, entry_reward, rbtn_wall,
+ rbtn_term):
+ """checks for required state of widgets when cells are initialized"""
+
+ bool_walls = [['False'] * max(1, _width) for _ in range(max(1, _height))]
+ bool_terms = [['False'] * max(1, _width) for _ in range(max(1, _height))]
+
+ for i in range(max(1, _height)):
+ for j in range(max(1, _width)):
+ if gridmdp[i][j] == WALL_VALUE:
+ bool_walls[i][j] = 'True'
+
+ if (i, j) in terminals:
+ bool_terms[i][j] = 'True'
+
+ bool_walls_fl = flatten_list(bool_walls)
+ bool_terms_fl = flatten_list(bool_terms)
+
+ if bool_walls_fl.count('True') == len(bool_walls_fl):
+ print('`')
+ label_reward.config(foreground='#999')
+ entry_reward.config(state=tk.DISABLED)
+ rbtn_term.config(state=tk.DISABLED)
+ rbtn_wall.state(['!focus', 'selected'])
+ rbtn_term.state(['!focus', '!selected'])
+
+ if bool_terms_fl.count('True') == len(bool_terms_fl):
+ rbtn_wall.config(state=tk.DISABLED)
+ rbtn_wall.state(['!focus', '!selected'])
+ rbtn_term.state(['!focus', 'selected'])
+
+
+def dialogbox(i, j, gridmdp, terminals, buttons, _height):
+ """creates dialogbox for each cell"""
+ global cell_window_mantainer
+ if (cell_window_mantainer != None):
+ cell_window_mantainer.destroy()
+
+ dialog = tk.Toplevel()
+ cell_window_mantainer = dialog
+ dialog.wm_title(f'{_height - i - 1}, {j}')
+
+ container = tk.Frame(dialog)
+ container.pack(side=tk.TOP, fill=tk.BOTH, expand=True)
+ container.grid_rowconfigure(0, weight=1)
+ container.grid_columnconfigure(0, weight=1)
+
+ wall = tk.IntVar()
+ wall.set(gridmdp[i][j])
+ term = tk.IntVar()
+ term.set(TERM_VALUE if (i, j) in terminals else 0.0)
+ reward = tk.DoubleVar()
+ reward.set(gridmdp[i][j] if gridmdp[i][j] != WALL_VALUE else 0.0)
+
+ label = ttk.Label(container, text=f'Configure cell {_height - i - 1}, {j}', font=('Helvetica', 12), anchor=tk.N)
+ label.grid(row=0, column=0, columnspan=3, sticky='new', pady=15, padx=5)
+ label_reward = ttk.Label(container, text='Reward', font=('Helvetica', 10), anchor=tk.N)
+ label_reward.grid(row=1, column=0, columnspan=3, sticky='new', pady=1, padx=5)
+ entry_reward = ttk.Entry(container, font=('Helvetica', 10), justify=tk.CENTER, exportselection=0,
+ textvariable=reward)
+ entry_reward.grid(row=2, column=0, columnspan=3, sticky='new', pady=5, padx=50)
+
+ rbtn_term = ttk.Radiobutton(container, text='Terminal', variable=term, value=TERM_VALUE)
+ rbtn_term.grid(row=3, column=0, columnspan=3, sticky='nsew', padx=160, pady=5)
+ rbtn_wall = ttk.Radiobutton(container, text='Wall', variable=wall, value=WALL_VALUE)
+ rbtn_wall.grid(row=4, column=0, columnspan=3, sticky='nsew', padx=172, pady=5)
+
+ widget_disability_checks(i, j, gridmdp, terminals, label_reward, entry_reward, rbtn_wall, rbtn_term)
+
+ btn_apply = ttk.Button(container, text='Apply',
+ command=partial(update_table, i, j, gridmdp, terminals, buttons, reward, term, wall,
+ label_reward, entry_reward, rbtn_term, rbtn_wall))
+ btn_apply.grid(row=5, column=0, sticky='nsew', pady=5, padx=5)
+ btn_reset = ttk.Button(container, text='Reset',
+ command=partial(reset_all, _height, i, j, gridmdp, terminals, buttons, reward, term, wall,
+ label_reward, entry_reward, rbtn_wall, rbtn_term))
+ btn_reset.grid(row=5, column=1, sticky='nsew', pady=5, padx=5)
+ btn_ok = ttk.Button(container, text='Ok', command=dialog.destroy)
+ btn_ok.grid(row=5, column=2, sticky='nsew', pady=5, padx=5)
+
+ dialog.geometry('400x200')
+ dialog.mainloop()
+
+
+class MDPapp(tk.Tk):
+
+ def __init__(self, *args, **kwargs):
+
+ tk.Tk.__init__(self, *args, **kwargs)
+ tk.Tk.wm_title(self, 'Grid MDP')
+ self.shared_data = {
+ 'height': tk.IntVar(),
+ 'width': tk.IntVar()}
+ self.shared_data['height'].set(1)
+ self.shared_data['width'].set(1)
+ self.container = tk.Frame(self)
+ self.container.pack(side='top', fill='both', expand=True)
+ self.container.grid_rowconfigure(0, weight=1)
+ self.container.grid_columnconfigure(0, weight=1)
+
+ self.frames = {}
+
+ self.menu_bar = tk.Menu(self.container)
+ self.file_menu = tk.Menu(self.menu_bar, tearoff=0)
+ self.file_menu.add_command(label='Exit', command=self.exit)
+ self.menu_bar.add_cascade(label='File', menu=self.file_menu)
+
+ self.edit_menu = tk.Menu(self.menu_bar, tearoff=1)
+ self.edit_menu.add_command(label='Reset', command=self.master_reset)
+ self.edit_menu.add_command(label='Initialize', command=self.initialize)
+ self.edit_menu.add_separator()
+ self.edit_menu.add_command(label='View matrix', command=self.view_matrix)
+ self.edit_menu.add_command(label='View terminals', command=self.view_terminals)
+ self.menu_bar.add_cascade(label='Edit', menu=self.edit_menu)
+ self.menu_bar.entryconfig('Edit', state=tk.DISABLED)
+
+ self.build_menu = tk.Menu(self.menu_bar, tearoff=1)
+ self.build_menu.add_command(label='Build and Run', command=self.build)
+ self.menu_bar.add_cascade(label='Build', menu=self.build_menu)
+ self.menu_bar.entryconfig('Build', state=tk.DISABLED)
+ tk.Tk.config(self, menu=self.menu_bar)
+
+ for F in (HomePage, BuildMDP, SolveMDP):
+ frame = F(self.container, self)
+ self.frames[F] = frame
+ frame.grid(row=0, column=0, sticky='nsew')
+
+ self.show_frame(HomePage)
+
+ def placeholder_function(self):
+ """placeholder function"""
+
+ print('Not supported yet!')
+
+ def exit(self):
+ """function to exit"""
+ if tkinter.messagebox.askokcancel('Exit?', 'All changes will be lost'):
+ quit()
+
+ def new(self):
+ """function to create new GridMDP"""
+
+ self.master_reset()
+ build_page = self.get_page(BuildMDP)
+ build_page.gridmdp = None
+ build_page.terminals = None
+ build_page.buttons = None
+ self.show_frame(HomePage)
+
+ def get_page(self, page_class):
+ """returns pages from stored frames"""
+ return self.frames[page_class]
+
+ def view_matrix(self):
+ """prints current matrix to console"""
+
+ build_page = self.get_page(BuildMDP)
+ _height = self.shared_data['height'].get()
+ _width = self.shared_data['width'].get()
+ print(build_page.gridmdp)
+ display(build_page.gridmdp, _height, _width)
+
+ def view_terminals(self):
+ """prints current terminals to console"""
+ build_page = self.get_page(BuildMDP)
+ print('Terminals', build_page.terminals)
+
+ def initialize(self):
+ """calls initialize from BuildMDP"""
+
+ build_page = self.get_page(BuildMDP)
+ build_page.initialize()
+
+ def master_reset(self):
+ """calls master_reset from BuildMDP"""
+ build_page = self.get_page(BuildMDP)
+ build_page.master_reset()
+
+ def build(self):
+ """runs specified mdp solving algorithm"""
+
+ frame = SolveMDP(self.container, self)
+ self.frames[SolveMDP] = frame
+ frame.grid(row=0, column=0, sticky='nsew')
+ self.show_frame(SolveMDP)
+ build_page = self.get_page(BuildMDP)
+ gridmdp = build_page.gridmdp
+ terminals = build_page.terminals
+ solve_page = self.get_page(SolveMDP)
+ _height = self.shared_data['height'].get()
+ _width = self.shared_data['width'].get()
+ solve_page.create_graph(gridmdp, terminals, _height, _width)
+
+ def show_frame(self, controller, cb=False):
+ """shows specified frame and optionally runs create_buttons"""
+ if cb:
+ build_page = self.get_page(BuildMDP)
+ build_page.create_buttons()
+ frame = self.frames[controller]
+ frame.tkraise()
+
+
+class HomePage(tk.Frame):
+
+ def __init__(self, parent, controller):
+ """HomePage constructor"""
+
+ tk.Frame.__init__(self, parent)
+ self.controller = controller
+ frame1 = tk.Frame(self)
+ frame1.pack(side=tk.TOP)
+ frame3 = tk.Frame(self)
+ frame3.pack(side=tk.TOP)
+ frame4 = tk.Frame(self)
+ frame4.pack(side=tk.TOP)
+ frame2 = tk.Frame(self)
+ frame2.pack(side=tk.TOP)
+
+ s = ttk.Style()
+ s.theme_use('clam')
+ s.configure('TButton', background=grayd, padding=0)
+ s.configure('wall.TButton', background=gray2, foreground=white)
+ s.configure('reward.TButton', background=gray9)
+ s.configure('+term.TButton', background=green8)
+ s.configure('-term.TButton', background=pblue, foreground=white)
+ s.configure('=term.TButton', background=green4)
+
+ label = ttk.Label(frame1, text='GridMDP builder', font=('Helvetica', 18, 'bold'), background=grayef)
+ label.pack(pady=75, padx=50, side=tk.TOP)
+
+ ec_btn = ttk.Button(frame3, text='Empty cells', width=20)
+ ec_btn.pack(pady=0, padx=0, side=tk.LEFT, ipady=10)
+ ec_btn.configure(style='TButton')
+
+ w_btn = ttk.Button(frame3, text='Walls', width=20)
+ w_btn.pack(pady=0, padx=0, side=tk.LEFT, ipady=10)
+ w_btn.configure(style='wall.TButton')
+
+ r_btn = ttk.Button(frame3, text='Rewards', width=20)
+ r_btn.pack(pady=0, padx=0, side=tk.LEFT, ipady=10)
+ r_btn.configure(style='reward.TButton')
+
+ term_p = ttk.Button(frame3, text='Positive terminals', width=20)
+ term_p.pack(pady=0, padx=0, side=tk.LEFT, ipady=10)
+ term_p.configure(style='+term.TButton')
+
+ term_z = ttk.Button(frame3, text='Neutral terminals', width=20)
+ term_z.pack(pady=0, padx=0, side=tk.LEFT, ipady=10)
+ term_z.configure(style='=term.TButton')
+
+ term_n = ttk.Button(frame3, text='Negative terminals', width=20)
+ term_n.pack(pady=0, padx=0, side=tk.LEFT, ipady=10)
+ term_n.configure(style='-term.TButton')
+
+ label = ttk.Label(frame4, text='Dimensions', font=('Verdana', 14), background=grayef)
+ label.pack(pady=15, padx=10, side=tk.TOP)
+ entry_h = tk.Entry(frame2, textvariable=self.controller.shared_data['height'], font=('Verdana', 10), width=3,
+ justify=tk.CENTER)
+ entry_h.pack(pady=10, padx=10, side=tk.LEFT)
+ label_x = ttk.Label(frame2, text='X', font=('Verdana', 10), background=grayef)
+ label_x.pack(pady=10, padx=4, side=tk.LEFT)
+ entry_w = tk.Entry(frame2, textvariable=self.controller.shared_data['width'], font=('Verdana', 10), width=3,
+ justify=tk.CENTER)
+ entry_w.pack(pady=10, padx=10, side=tk.LEFT)
+ button = ttk.Button(self, text='Build a GridMDP', command=lambda: controller.show_frame(BuildMDP, cb=True))
+ button.pack(pady=10, padx=10, side=tk.TOP, ipadx=20, ipady=10)
+ button.configure(style='reward.TButton')
+
+
+class BuildMDP(tk.Frame):
+
+ def __init__(self, parent, controller):
+
+ tk.Frame.__init__(self, parent)
+ self.grid_rowconfigure(0, weight=1)
+ self.grid_columnconfigure(0, weight=1)
+ self.frame = tk.Frame(self)
+ self.frame.pack()
+ self.controller = controller
+
+ def create_buttons(self):
+ """creates interactive cells to build MDP"""
+ _height = self.controller.shared_data['height'].get()
+ _width = self.controller.shared_data['width'].get()
+ self.controller.menu_bar.entryconfig('Edit', state=tk.NORMAL)
+ self.controller.menu_bar.entryconfig('Build', state=tk.NORMAL)
+ self.gridmdp = [[0.0] * max(1, _width) for _ in range(max(1, _height))]
+ self.buttons = [[None] * max(1, _width) for _ in range(max(1, _height))]
+ self.terminals = []
+
+ s = ttk.Style()
+ s.theme_use('clam')
+ s.configure('TButton', background=grayd, padding=0)
+ s.configure('wall.TButton', background=gray2, foreground=white)
+ s.configure('reward.TButton', background=gray9)
+ s.configure('+term.TButton', background=green8)
+ s.configure('-term.TButton', background=pblue, foreground=white)
+ s.configure('=term.TButton', background=green4)
+
+ for i in range(max(1, _height)):
+ for j in range(max(1, _width)):
+ self.buttons[i][j] = ttk.Button(self.frame, text=f'({_height - i - 1}, {j})',
+ width=int(196 / max(1, _width)),
+ command=partial(dialogbox, i, j, self.gridmdp, self.terminals,
+ self.buttons, _height))
+ self.buttons[i][j].grid(row=i, column=j, ipady=int(336 / max(1, _height)) - 12)
+
+ def initialize(self):
+ """runs initialize_dialogbox"""
+
+ _height = self.controller.shared_data['height'].get()
+ _width = self.controller.shared_data['width'].get()
+ initialize_dialogbox(_width, _height, self.gridmdp, self.terminals, self.buttons)
+
+ def master_reset(self):
+ """runs external reset"""
+ _height = self.controller.shared_data['height'].get()
+ _width = self.controller.shared_data['width'].get()
+ if tkinter.messagebox.askokcancel('Reset', 'Are you sure you want to reset all cells?'):
+ external_reset(_width, _height, self.gridmdp, self.terminals, self.buttons)
+
+
+class SolveMDP(tk.Frame):
+
+ def __init__(self, parent, controller):
+
+ tk.Frame.__init__(self, parent)
+ self.grid_rowconfigure(0, weight=1)
+ self.grid_columnconfigure(0, weight=1)
+ self.frame = tk.Frame(self)
+ self.frame.pack()
+ self.controller = controller
+ self.terminated = False
+ self.iterations = 0
+ self.epsilon = 0.001
+ self.delta = 0
+
+ def process_data(self, terminals, _height, _width, gridmdp):
+ """preprocess variables"""
+
+ flipped_terminals = []
+
+ for terminal in terminals:
+ flipped_terminals.append((terminal[1], _height - terminal[0] - 1))
+
+ grid_to_solve = [[0.0] * max(1, _width) for _ in range(max(1, _height))]
+ grid_to_show = [[0.0] * max(1, _width) for _ in range(max(1, _height))]
+
+ for i in range(max(1, _height)):
+ for j in range(max(1, _width)):
+ if gridmdp[i][j] == WALL_VALUE:
+ grid_to_show[i][j] = 0.0
+ grid_to_solve[i][j] = None
+
+ else:
+ grid_to_show[i][j] = grid_to_solve[i][j] = gridmdp[i][j]
+
+ return flipped_terminals, grid_to_solve, np.flipud(grid_to_show)
+
+ def create_graph(self, gridmdp, terminals, _height, _width):
+ """creates canvas and initializes value_iteration_parameters"""
+ self._height = _height
+ self._width = _width
+ self.controller.menu_bar.entryconfig('Edit', state=tk.DISABLED)
+ self.controller.menu_bar.entryconfig('Build', state=tk.DISABLED)
+
+ self.terminals, self.gridmdp, self.grid_to_show = self.process_data(terminals, _height, _width, gridmdp)
+ self.sequential_decision_environment = GridMDP(self.gridmdp, terminals=self.terminals)
+
+ self.initialize_value_iteration_parameters(self.sequential_decision_environment)
+
+ self.canvas = FigureCanvasTkAgg(fig, self.frame)
+ self.canvas.get_tk_widget().pack(side=tk.TOP, fill=tk.BOTH, expand=True)
+ self.anim = animation.FuncAnimation(fig, self.animate_graph, interval=50)
+ self.canvas.show()
+
+ def animate_graph(self, i):
+ """performs value iteration and animates graph"""
+
+ # cmaps to use: bone_r, Oranges, inferno, BrBG, copper
+ self.iterations += 1
+ x_interval = max(2, len(self.gridmdp[0]))
+ y_interval = max(2, len(self.gridmdp))
+ x = np.linspace(0, len(self.gridmdp[0]) - 1, x_interval)
+ y = np.linspace(0, len(self.gridmdp) - 1, y_interval)
+
+ sub.clear()
+ sub.imshow(self.grid_to_show, cmap='BrBG', aspect='auto', interpolation='none', extent=extents(x) + extents(y),
+ origin='lower')
+ fig.tight_layout()
+
+ U = self.U1.copy()
+
+ for s in self.sequential_decision_environment.states:
+ self.U1[s] = self.R(s) + self.gamma * max(
+ [sum([p * U[s1] for (p, s1) in self.T(s, a)]) for a in self.sequential_decision_environment.actions(s)])
+ self.delta = max(self.delta, abs(self.U1[s] - U[s]))
+
+ self.grid_to_show = grid_to_show = [[0.0] * max(1, self._width) for _ in range(max(1, self._height))]
+ for k, v in U.items():
+ self.grid_to_show[k[1]][k[0]] = v
+
+ if (self.delta < self.epsilon * (1 - self.gamma) / self.gamma) or (
+ self.iterations > 60) and self.terminated is False:
+ self.terminated = True
+ display(self.grid_to_show, self._height, self._width)
+
+ pi = best_policy(self.sequential_decision_environment,
+ value_iteration(self.sequential_decision_environment, .01))
+ display_best_policy(self.sequential_decision_environment.to_arrows(pi), self._height, self._width)
+
+ ax = fig.gca()
+ ax.xaxis.set_major_locator(MaxNLocator(integer=True))
+ ax.yaxis.set_major_locator(MaxNLocator(integer=True))
+
+ def initialize_value_iteration_parameters(self, mdp):
+ """initializes value_iteration parameters"""
+ self.U1 = {s: 0 for s in mdp.states}
+ self.R, self.T, self.gamma = mdp.R, mdp.T, mdp.gamma
+
+ def value_iteration_metastep(self, mdp, iterations=20):
+ """runs value_iteration"""
+
+ U_over_time = []
+ U1 = {s: 0 for s in mdp.states}
+ R, T, gamma = mdp.R, mdp.T, mdp.gamma
+
+ for _ in range(iterations):
+ U = U1.copy()
+
+ for s in mdp.states:
+ U1[s] = R(s) + gamma * max([sum([p * U[s1] for (p, s1) in T(s, a)]) for a in mdp.actions(s)])
+
+ U_over_time.append(U)
+ return U_over_time
+
+
+if __name__ == '__main__':
+ app = MDPapp()
+ app.geometry('1280x720')
+ app.mainloop()
diff --git a/gui/romania_problem.py b/gui/romania_problem.py
new file mode 100644
index 000000000..9ec94099d
--- /dev/null
+++ b/gui/romania_problem.py
@@ -0,0 +1,672 @@
+from copy import deepcopy
+from tkinter import *
+
+from search import *
+from utils import PriorityQueue
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+
+root = None
+city_coord = {}
+romania_problem = None
+algo = None
+start = None
+goal = None
+counter = -1
+city_map = None
+frontier = None
+front = None
+node = None
+next_button = None
+explored = None
+
+
+def create_map(root):
+ """This function draws out the required map."""
+ global city_map, start, goal
+ romania_locations = romania_map.locations
+ width = 750
+ height = 670
+ margin = 5
+ city_map = Canvas(root, width=width, height=height)
+ city_map.pack()
+
+ # Since lines have to be drawn between particular points, we need to list
+ # them separately
+ make_line(
+ city_map,
+ romania_locations['Arad'][0],
+ height -
+ romania_locations['Arad'][1],
+ romania_locations['Sibiu'][0],
+ height -
+ romania_locations['Sibiu'][1],
+ romania_map.get('Arad', 'Sibiu'))
+ make_line(
+ city_map,
+ romania_locations['Arad'][0],
+ height -
+ romania_locations['Arad'][1],
+ romania_locations['Zerind'][0],
+ height -
+ romania_locations['Zerind'][1],
+ romania_map.get('Arad', 'Zerind'))
+ make_line(
+ city_map,
+ romania_locations['Arad'][0],
+ height -
+ romania_locations['Arad'][1],
+ romania_locations['Timisoara'][0],
+ height -
+ romania_locations['Timisoara'][1],
+ romania_map.get('Arad', 'Timisoara'))
+ make_line(
+ city_map,
+ romania_locations['Oradea'][0],
+ height -
+ romania_locations['Oradea'][1],
+ romania_locations['Zerind'][0],
+ height -
+ romania_locations['Zerind'][1],
+ romania_map.get('Oradea', 'Zerind'))
+ make_line(
+ city_map,
+ romania_locations['Oradea'][0],
+ height -
+ romania_locations['Oradea'][1],
+ romania_locations['Sibiu'][0],
+ height -
+ romania_locations['Sibiu'][1],
+ romania_map.get('Oradea', 'Sibiu'))
+ make_line(
+ city_map,
+ romania_locations['Lugoj'][0],
+ height -
+ romania_locations['Lugoj'][1],
+ romania_locations['Timisoara'][0],
+ height -
+ romania_locations['Timisoara'][1],
+ romania_map.get('Lugoj', 'Timisoara'))
+ make_line(
+ city_map,
+ romania_locations['Lugoj'][0],
+ height -
+ romania_locations['Lugoj'][1],
+ romania_locations['Mehadia'][0],
+ height -
+ romania_locations['Mehadia'][1],
+ romania_map.get('Lugoj', 'Mehadia'))
+ make_line(
+ city_map,
+ romania_locations['Drobeta'][0],
+ height -
+ romania_locations['Drobeta'][1],
+ romania_locations['Mehadia'][0],
+ height -
+ romania_locations['Mehadia'][1],
+ romania_map.get('Drobeta', 'Mehadia'))
+ make_line(
+ city_map,
+ romania_locations['Drobeta'][0],
+ height -
+ romania_locations['Drobeta'][1],
+ romania_locations['Craiova'][0],
+ height -
+ romania_locations['Craiova'][1],
+ romania_map.get('Drobeta', 'Craiova'))
+ make_line(
+ city_map,
+ romania_locations['Pitesti'][0],
+ height -
+ romania_locations['Pitesti'][1],
+ romania_locations['Craiova'][0],
+ height -
+ romania_locations['Craiova'][1],
+ romania_map.get('Pitesti', 'Craiova'))
+ make_line(
+ city_map,
+ romania_locations['Rimnicu'][0],
+ height -
+ romania_locations['Rimnicu'][1],
+ romania_locations['Craiova'][0],
+ height -
+ romania_locations['Craiova'][1],
+ romania_map.get('Rimnicu', 'Craiova'))
+ make_line(
+ city_map,
+ romania_locations['Rimnicu'][0],
+ height -
+ romania_locations['Rimnicu'][1],
+ romania_locations['Sibiu'][0],
+ height -
+ romania_locations['Sibiu'][1],
+ romania_map.get('Rimnicu', 'Sibiu'))
+ make_line(
+ city_map,
+ romania_locations['Rimnicu'][0],
+ height -
+ romania_locations['Rimnicu'][1],
+ romania_locations['Pitesti'][0],
+ height -
+ romania_locations['Pitesti'][1],
+ romania_map.get('Rimnicu', 'Pitesti'))
+ make_line(
+ city_map,
+ romania_locations['Bucharest'][0],
+ height -
+ romania_locations['Bucharest'][1],
+ romania_locations['Pitesti'][0],
+ height -
+ romania_locations['Pitesti'][1],
+ romania_map.get('Bucharest', 'Pitesti'))
+ make_line(
+ city_map,
+ romania_locations['Fagaras'][0],
+ height -
+ romania_locations['Fagaras'][1],
+ romania_locations['Sibiu'][0],
+ height -
+ romania_locations['Sibiu'][1],
+ romania_map.get('Fagaras', 'Sibiu'))
+ make_line(
+ city_map,
+ romania_locations['Fagaras'][0],
+ height -
+ romania_locations['Fagaras'][1],
+ romania_locations['Bucharest'][0],
+ height -
+ romania_locations['Bucharest'][1],
+ romania_map.get('Fagaras', 'Bucharest'))
+ make_line(
+ city_map,
+ romania_locations['Giurgiu'][0],
+ height -
+ romania_locations['Giurgiu'][1],
+ romania_locations['Bucharest'][0],
+ height -
+ romania_locations['Bucharest'][1],
+ romania_map.get('Giurgiu', 'Bucharest'))
+ make_line(
+ city_map,
+ romania_locations['Urziceni'][0],
+ height -
+ romania_locations['Urziceni'][1],
+ romania_locations['Bucharest'][0],
+ height -
+ romania_locations['Bucharest'][1],
+ romania_map.get('Urziceni', 'Bucharest'))
+ make_line(
+ city_map,
+ romania_locations['Urziceni'][0],
+ height -
+ romania_locations['Urziceni'][1],
+ romania_locations['Hirsova'][0],
+ height -
+ romania_locations['Hirsova'][1],
+ romania_map.get('Urziceni', 'Hirsova'))
+ make_line(
+ city_map,
+ romania_locations['Eforie'][0],
+ height -
+ romania_locations['Eforie'][1],
+ romania_locations['Hirsova'][0],
+ height -
+ romania_locations['Hirsova'][1],
+ romania_map.get('Eforie', 'Hirsova'))
+ make_line(
+ city_map,
+ romania_locations['Urziceni'][0],
+ height -
+ romania_locations['Urziceni'][1],
+ romania_locations['Vaslui'][0],
+ height -
+ romania_locations['Vaslui'][1],
+ romania_map.get('Urziceni', 'Vaslui'))
+ make_line(
+ city_map,
+ romania_locations['Iasi'][0],
+ height -
+ romania_locations['Iasi'][1],
+ romania_locations['Vaslui'][0],
+ height -
+ romania_locations['Vaslui'][1],
+ romania_map.get('Iasi', 'Vaslui'))
+ make_line(
+ city_map,
+ romania_locations['Iasi'][0],
+ height -
+ romania_locations['Iasi'][1],
+ romania_locations['Neamt'][0],
+ height -
+ romania_locations['Neamt'][1],
+ romania_map.get('Iasi', 'Neamt'))
+
+ for city in romania_locations.keys():
+ make_rectangle(
+ city_map,
+ romania_locations[city][0],
+ height -
+ romania_locations[city][1],
+ margin,
+ city)
+
+ make_legend(city_map)
+
+
+def make_line(map, x0, y0, x1, y1, distance):
+ """This function draws out the lines joining various points."""
+ map.create_line(x0, y0, x1, y1)
+ map.create_text((x0 + x1) / 2, (y0 + y1) / 2, text=distance)
+
+
+def make_rectangle(map, x0, y0, margin, city_name):
+ """This function draws out rectangles for various points."""
+ global city_coord
+ rect = map.create_rectangle(
+ x0 - margin,
+ y0 - margin,
+ x0 + margin,
+ y0 + margin,
+ fill="white")
+ if "Bucharest" in city_name or "Pitesti" in city_name or "Lugoj" in city_name \
+ or "Mehadia" in city_name or "Drobeta" in city_name:
+ map.create_text(
+ x0 - 2 * margin,
+ y0 - 2 * margin,
+ text=city_name,
+ anchor=E)
+ else:
+ map.create_text(
+ x0 - 2 * margin,
+ y0 - 2 * margin,
+ text=city_name,
+ anchor=SE)
+ city_coord.update({city_name: rect})
+
+
+def make_legend(map):
+ rect1 = map.create_rectangle(600, 100, 610, 110, fill="white")
+ text1 = map.create_text(615, 105, anchor=W, text="Un-explored")
+
+ rect2 = map.create_rectangle(600, 115, 610, 125, fill="orange")
+ text2 = map.create_text(615, 120, anchor=W, text="Frontier")
+
+ rect3 = map.create_rectangle(600, 130, 610, 140, fill="red")
+ text3 = map.create_text(615, 135, anchor=W, text="Currently Exploring")
+
+ rect4 = map.create_rectangle(600, 145, 610, 155, fill="grey")
+ text4 = map.create_text(615, 150, anchor=W, text="Explored")
+
+ rect5 = map.create_rectangle(600, 160, 610, 170, fill="dark green")
+ text5 = map.create_text(615, 165, anchor=W, text="Final Solution")
+
+
+def tree_search(problem):
+ """
+ Search through the successors of a problem to find a goal.
+ The argument frontier should be an empty queue.
+ Don't worry about repeated paths to a state. [Figure 3.7]
+ This function has been changed to make it suitable for the Tkinter GUI.
+ """
+ global counter, frontier, node
+
+ if counter == -1:
+ frontier.append(Node(problem.initial))
+
+ display_frontier(frontier)
+ if counter % 3 == 0 and counter >= 0:
+ node = frontier.pop()
+
+ display_current(node)
+ if counter % 3 == 1 and counter >= 0:
+ if problem.goal_test(node.state):
+ return node
+ frontier.extend(node.expand(problem))
+
+ display_frontier(frontier)
+ if counter % 3 == 2 and counter >= 0:
+ display_explored(node)
+ return None
+
+
+def graph_search(problem):
+ """
+ Search through the successors of a problem to find a goal.
+ The argument frontier should be an empty queue.
+ If two paths reach a state, only use the first one. [Figure 3.7]
+ This function has been changed to make it suitable for the Tkinter GUI.
+ """
+ global counter, frontier, node, explored
+ if counter == -1:
+ frontier.append(Node(problem.initial))
+ explored = set()
+
+ display_frontier(frontier)
+ if counter % 3 == 0 and counter >= 0:
+ node = frontier.pop()
+
+ display_current(node)
+ if counter % 3 == 1 and counter >= 0:
+ if problem.goal_test(node.state):
+ return node
+ explored.add(node.state)
+ frontier.extend(child for child in node.expand(problem)
+ if child.state not in explored and
+ child not in frontier)
+
+ display_frontier(frontier)
+ if counter % 3 == 2 and counter >= 0:
+ display_explored(node)
+ return None
+
+
+def display_frontier(queue):
+ """This function marks the frontier nodes (orange) on the map."""
+ global city_map, city_coord
+ qu = deepcopy(queue)
+ while qu:
+ node = qu.pop()
+ for city in city_coord.keys():
+ if node.state == city:
+ city_map.itemconfig(city_coord[city], fill="orange")
+
+
+def display_current(node):
+ """This function marks the currently exploring node (red) on the map."""
+ global city_map, city_coord
+ city = node.state
+ city_map.itemconfig(city_coord[city], fill="red")
+
+
+def display_explored(node):
+ """This function marks the already explored node (gray) on the map."""
+ global city_map, city_coord
+ city = node.state
+ city_map.itemconfig(city_coord[city], fill="gray")
+
+
+def display_final(cities):
+ """This function marks the final solution nodes (green) on the map."""
+ global city_map, city_coord
+ for city in cities:
+ city_map.itemconfig(city_coord[city], fill="green")
+
+
+def breadth_first_tree_search(problem):
+ """Search the shallowest nodes in the search tree first."""
+ global frontier, counter, node
+ if counter == -1:
+ frontier = deque()
+
+ if counter == -1:
+ frontier.append(Node(problem.initial))
+
+ display_frontier(frontier)
+ if counter % 3 == 0 and counter >= 0:
+ node = frontier.popleft()
+
+ display_current(node)
+ if counter % 3 == 1 and counter >= 0:
+ if problem.goal_test(node.state):
+ return node
+ frontier.extend(node.expand(problem))
+
+ display_frontier(frontier)
+ if counter % 3 == 2 and counter >= 0:
+ display_explored(node)
+ return None
+
+
+def depth_first_tree_search(problem):
+ """Search the deepest nodes in the search tree first."""
+ # This search algorithm might not work in case of repeated paths.
+ global frontier, counter, node
+ if counter == -1:
+ frontier = [] # stack
+
+ if counter == -1:
+ frontier.append(Node(problem.initial))
+
+ display_frontier(frontier)
+ if counter % 3 == 0 and counter >= 0:
+ node = frontier.pop()
+
+ display_current(node)
+ if counter % 3 == 1 and counter >= 0:
+ if problem.goal_test(node.state):
+ return node
+ frontier.extend(node.expand(problem))
+
+ display_frontier(frontier)
+ if counter % 3 == 2 and counter >= 0:
+ display_explored(node)
+ return None
+
+
+def breadth_first_graph_search(problem):
+ """[Figure 3.11]"""
+ global frontier, node, explored, counter
+ if counter == -1:
+ node = Node(problem.initial)
+ display_current(node)
+ if problem.goal_test(node.state):
+ return node
+
+ frontier = deque([node]) # FIFO queue
+
+ display_frontier(frontier)
+ explored = set()
+ if counter % 3 == 0 and counter >= 0:
+ node = frontier.popleft()
+ display_current(node)
+ explored.add(node.state)
+ if counter % 3 == 1 and counter >= 0:
+ for child in node.expand(problem):
+ if child.state not in explored and child not in frontier:
+ if problem.goal_test(child.state):
+ return child
+ frontier.append(child)
+ display_frontier(frontier)
+ if counter % 3 == 2 and counter >= 0:
+ display_explored(node)
+ return None
+
+
+def depth_first_graph_search(problem):
+ """Search the deepest nodes in the search tree first."""
+ global counter, frontier, node, explored
+ if counter == -1:
+ frontier = [] # stack
+ if counter == -1:
+ frontier.append(Node(problem.initial))
+ explored = set()
+
+ display_frontier(frontier)
+ if counter % 3 == 0 and counter >= 0:
+ node = frontier.pop()
+
+ display_current(node)
+ if counter % 3 == 1 and counter >= 0:
+ if problem.goal_test(node.state):
+ return node
+ explored.add(node.state)
+ frontier.extend(child for child in node.expand(problem)
+ if child.state not in explored and
+ child not in frontier)
+
+ display_frontier(frontier)
+ if counter % 3 == 2 and counter >= 0:
+ display_explored(node)
+ return None
+
+
+def best_first_graph_search(problem, f):
+ """Search the nodes with the lowest f scores first.
+ You specify the function f(node) that you want to minimize; for example,
+ if f is a heuristic estimate to the goal, then we have greedy best
+ first search; if f is node.depth then we have breadth-first search.
+ There is a subtlety: the line "f = memoize(f, 'f')" means that the f
+ values will be cached on the nodes as they are computed. So after doing
+ a best first search you can examine the f values of the path returned."""
+ global frontier, node, explored, counter
+
+ if counter == -1:
+ f = memoize(f, 'f')
+ node = Node(problem.initial)
+ display_current(node)
+ if problem.goal_test(node.state):
+ return node
+ frontier = PriorityQueue('min', f)
+ frontier.append(node)
+ display_frontier(frontier)
+ explored = set()
+ if counter % 3 == 0 and counter >= 0:
+ node = frontier.pop()
+ display_current(node)
+ if problem.goal_test(node.state):
+ return node
+ explored.add(node.state)
+ if counter % 3 == 1 and counter >= 0:
+ for child in node.expand(problem):
+ if child.state not in explored and child not in frontier:
+ frontier.append(child)
+ elif child in frontier:
+ if f(child) < frontier[child]:
+ del frontier[child]
+ frontier.append(child)
+ display_frontier(frontier)
+ if counter % 3 == 2 and counter >= 0:
+ display_explored(node)
+ return None
+
+
+def uniform_cost_search(problem):
+ """[Figure 3.14]"""
+ return best_first_graph_search(problem, lambda node: node.path_cost)
+
+
+def astar_search(problem, h=None):
+ """A* search is best-first graph search with f(n) = g(n)+h(n).
+ You need to specify the h function when you call astar_search, or
+ else in your Problem subclass."""
+ h = memoize(h or problem.h, 'h')
+ return best_first_graph_search(problem, lambda n: n.path_cost + h(n))
+
+
+# TODO:
+# Remove redundant code.
+# Make the interchangeability work between various algorithms at each step.
+def on_click():
+ """
+ This function defines the action of the 'Next' button.
+ """
+ global algo, counter, next_button, romania_problem, start, goal
+ romania_problem = GraphProblem(start.get(), goal.get(), romania_map)
+ if "Breadth-First Tree Search" == algo.get():
+ node = breadth_first_tree_search(romania_problem)
+ if node is not None:
+ final_path = breadth_first_tree_search(romania_problem).solution()
+ final_path.append(start.get())
+ display_final(final_path)
+ next_button.config(state="disabled")
+ counter += 1
+ elif "Depth-First Tree Search" == algo.get():
+ node = depth_first_tree_search(romania_problem)
+ if node is not None:
+ final_path = depth_first_tree_search(romania_problem).solution()
+ final_path.append(start.get())
+ display_final(final_path)
+ next_button.config(state="disabled")
+ counter += 1
+ elif "Breadth-First Graph Search" == algo.get():
+ node = breadth_first_graph_search(romania_problem)
+ if node is not None:
+ final_path = breadth_first_graph_search(romania_problem).solution()
+ final_path.append(start.get())
+ display_final(final_path)
+ next_button.config(state="disabled")
+ counter += 1
+ elif "Depth-First Graph Search" == algo.get():
+ node = depth_first_graph_search(romania_problem)
+ if node is not None:
+ final_path = depth_first_graph_search(romania_problem).solution()
+ final_path.append(start.get())
+ display_final(final_path)
+ next_button.config(state="disabled")
+ counter += 1
+ elif "Uniform Cost Search" == algo.get():
+ node = uniform_cost_search(romania_problem)
+ if node is not None:
+ final_path = uniform_cost_search(romania_problem).solution()
+ final_path.append(start.get())
+ display_final(final_path)
+ next_button.config(state="disabled")
+ counter += 1
+ elif "A* - Search" == algo.get():
+ node = astar_search(romania_problem)
+ if node is not None:
+ final_path = astar_search(romania_problem).solution()
+ final_path.append(start.get())
+ display_final(final_path)
+ next_button.config(state="disabled")
+ counter += 1
+
+
+def reset_map():
+ global counter, city_coord, city_map, next_button
+ counter = -1
+ for city in city_coord.keys():
+ city_map.itemconfig(city_coord[city], fill="white")
+ next_button.config(state="normal")
+
+
+# TODO: Add more search algorithms in the OptionMenu
+if __name__ == "__main__":
+ global algo, start, goal, next_button
+ root = Tk()
+ root.title("Road Map of Romania")
+ root.geometry("950x1150")
+ algo = StringVar(root)
+ start = StringVar(root)
+ goal = StringVar(root)
+ algo.set("Breadth-First Tree Search")
+ start.set('Arad')
+ goal.set('Bucharest')
+ cities = sorted(romania_map.locations.keys())
+ algorithm_menu = OptionMenu(
+ root,
+ algo, "Breadth-First Tree Search", "Depth-First Tree Search",
+ "Breadth-First Graph Search", "Depth-First Graph Search",
+ "Uniform Cost Search", "A* - Search")
+ Label(root, text="\n Search Algorithm").pack()
+ algorithm_menu.pack()
+ Label(root, text="\n Start City").pack()
+ start_menu = OptionMenu(root, start, *cities)
+ start_menu.pack()
+ Label(root, text="\n Goal City").pack()
+ goal_menu = OptionMenu(root, goal, *cities)
+ goal_menu.pack()
+ frame1 = Frame(root)
+ next_button = Button(
+ frame1,
+ width=6,
+ height=2,
+ text="Next",
+ command=on_click,
+ padx=2,
+ pady=2,
+ relief=GROOVE)
+ next_button.pack(side=RIGHT)
+ reset_button = Button(
+ frame1,
+ width=6,
+ height=2,
+ text="Reset",
+ command=reset_map,
+ padx=2,
+ pady=2,
+ relief=GROOVE)
+ reset_button.pack(side=RIGHT)
+ frame1.pack(side=BOTTOM)
+ create_map(root)
+ root.mainloop()
diff --git a/gui/tic-tac-toe.py b/gui/tic-tac-toe.py
new file mode 100644
index 000000000..66d9d6e75
--- /dev/null
+++ b/gui/tic-tac-toe.py
@@ -0,0 +1,232 @@
+import os.path
+from tkinter import *
+
+from games import minmax_decision, alpha_beta_player, random_player, TicTacToe
+# "gen_state" can be used to generate a game state to apply the algorithm
+from tests.test_games import gen_state
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+
+ttt = TicTacToe()
+root = None
+buttons = []
+frames = []
+x_pos = []
+o_pos = []
+count = 0
+sym = ""
+result = None
+choices = None
+
+
+def create_frames(root):
+ """
+ This function creates the necessary structure of the game.
+ """
+ frame1 = Frame(root)
+ frame2 = Frame(root)
+ frame3 = Frame(root)
+ frame4 = Frame(root)
+ create_buttons(frame1)
+ create_buttons(frame2)
+ create_buttons(frame3)
+ buttonExit = Button(
+ frame4, height=1, width=2,
+ text="Exit",
+ command=lambda: exit_game(root))
+ buttonExit.pack(side=LEFT)
+ frame4.pack(side=BOTTOM)
+ frame3.pack(side=BOTTOM)
+ frame2.pack(side=BOTTOM)
+ frame1.pack(side=BOTTOM)
+ frames.append(frame1)
+ frames.append(frame2)
+ frames.append(frame3)
+ for x in frames:
+ buttons_in_frame = []
+ for y in x.winfo_children():
+ buttons_in_frame.append(y)
+ buttons.append(buttons_in_frame)
+ buttonReset = Button(frame4, height=1, width=2,
+ text="Reset", command=lambda: reset_game())
+ buttonReset.pack(side=LEFT)
+
+
+def create_buttons(frame):
+ """
+ This function creates the buttons to be pressed/clicked during the game.
+ """
+ button0 = Button(frame, height=2, width=2, text=" ",
+ command=lambda: on_click(button0))
+ button0.pack(side=LEFT)
+ button1 = Button(frame, height=2, width=2, text=" ",
+ command=lambda: on_click(button1))
+ button1.pack(side=LEFT)
+ button2 = Button(frame, height=2, width=2, text=" ",
+ command=lambda: on_click(button2))
+ button2.pack(side=LEFT)
+
+
+# TODO: Add a choice option for the user.
+def on_click(button):
+ """
+ This function determines the action of any button.
+ """
+ global ttt, choices, count, sym, result, x_pos, o_pos
+
+ if count % 2 == 0:
+ sym = "X"
+ else:
+ sym = "O"
+ count += 1
+
+ button.config(
+ text=sym,
+ state='disabled',
+ disabledforeground="red") # For cross
+
+ x, y = get_coordinates(button)
+ x += 1
+ y += 1
+ x_pos.append((x, y))
+ state = gen_state(to_move='O', x_positions=x_pos,
+ o_positions=o_pos)
+ try:
+ choice = choices.get()
+ if "Random" in choice:
+ a, b = random_player(ttt, state)
+ elif "Pro" in choice:
+ a, b = minmax_decision(state, ttt)
+ else:
+ a, b = alpha_beta_player(ttt, state)
+ except (ValueError, IndexError, TypeError) as e:
+ disable_game()
+ result.set("It's a draw :|")
+ return
+ if 1 <= a <= 3 and 1 <= b <= 3:
+ o_pos.append((a, b))
+ button_to_change = get_button(a - 1, b - 1)
+ if count % 2 == 0: # Used again, will become handy when user is given the choice of turn.
+ sym = "X"
+ else:
+ sym = "O"
+ count += 1
+
+ if check_victory(button):
+ result.set("You win :)")
+ disable_game()
+ else:
+ button_to_change.config(text=sym, state='disabled',
+ disabledforeground="black")
+ if check_victory(button_to_change):
+ result.set("You lose :(")
+ disable_game()
+
+
+# TODO: Replace "check_victory" by "k_in_row" function.
+def check_victory(button):
+ """
+ This function checks various winning conditions of the game.
+ """
+ # check if previous move caused a win on vertical line
+ global buttons
+ x, y = get_coordinates(button)
+ tt = button['text']
+ if buttons[0][y]['text'] == buttons[1][y]['text'] == buttons[2][y]['text'] != " ":
+ buttons[0][y].config(text="|" + tt + "|")
+ buttons[1][y].config(text="|" + tt + "|")
+ buttons[2][y].config(text="|" + tt + "|")
+ return True
+
+ # check if previous move caused a win on horizontal line
+ if buttons[x][0]['text'] == buttons[x][1]['text'] == buttons[x][2]['text'] != " ":
+ buttons[x][0].config(text="--" + tt + "--")
+ buttons[x][1].config(text="--" + tt + "--")
+ buttons[x][2].config(text="--" + tt + "--")
+ return True
+
+ # check if previous move was on the main diagonal and caused a win
+ if x == y and buttons[0][0]['text'] == buttons[1][1]['text'] == buttons[2][2]['text'] != " ":
+ buttons[0][0].config(text="\\" + tt + "\\")
+ buttons[1][1].config(text="\\" + tt + "\\")
+ buttons[2][2].config(text="\\" + tt + "\\")
+ return True
+
+ # check if previous move was on the secondary diagonal and caused a win
+ if x + y == 2 and buttons[0][2]['text'] == buttons[1][1]['text'] == buttons[2][0]['text'] != " ":
+ buttons[0][2].config(text="/" + tt + "/")
+ buttons[1][1].config(text="/" + tt + "/")
+ buttons[2][0].config(text="/" + tt + "/")
+ return True
+
+ return False
+
+
+def get_coordinates(button):
+ """
+ This function returns the coordinates of the button clicked.
+ """
+ global buttons
+ for x in range(len(buttons)):
+ for y in range(len(buttons[x])):
+ if buttons[x][y] == button:
+ return x, y
+
+
+def get_button(x, y):
+ """
+ This function returns the button memory location corresponding to a coordinate.
+ """
+ global buttons
+ return buttons[x][y]
+
+
+def reset_game():
+ """
+ This function will reset all the tiles to the initial null value.
+ """
+ global x_pos, o_pos, frames, count
+
+ count = 0
+ x_pos = []
+ o_pos = []
+ result.set("Your Turn!")
+ for x in frames:
+ for y in x.winfo_children():
+ y.config(text=" ", state='normal')
+
+
+def disable_game():
+ """
+ This function deactivates the game after a win, loss or draw.
+ """
+ global frames
+ for x in frames:
+ for y in x.winfo_children():
+ y.config(state='disabled')
+
+
+def exit_game(root):
+ """
+ This function will exit the game by killing the root.
+ """
+ root.destroy()
+
+
+if __name__ == "__main__":
+ global result, choices
+
+ root = Tk()
+ root.title("TicTacToe")
+ root.geometry("150x200") # Improved the window geometry
+ root.resizable(0, 0) # To remove the maximize window option
+ result = StringVar()
+ result.set("Your Turn!")
+ w = Label(root, textvariable=result)
+ w.pack(side=BOTTOM)
+ create_frames(root)
+ choices = StringVar(root)
+ choices.set("Vs Pro")
+ menu = OptionMenu(root, choices, "Vs Random", "Vs Pro", "Vs Legend")
+ menu.pack()
+ root.mainloop()
diff --git a/gui/tsp.py b/gui/tsp.py
new file mode 100644
index 000000000..590fff354
--- /dev/null
+++ b/gui/tsp.py
@@ -0,0 +1,342 @@
+from tkinter import *
+from tkinter import messagebox
+
+import utils
+from search import *
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+
+distances = {}
+
+
+class TSProblem(Problem):
+ """subclass of Problem to define various functions"""
+
+ def two_opt(self, state):
+ """Neighbour generating function for Traveling Salesman Problem"""
+ neighbour_state = state[:]
+ left = random.randint(0, len(neighbour_state) - 1)
+ right = random.randint(0, len(neighbour_state) - 1)
+ if left > right:
+ left, right = right, left
+ neighbour_state[left: right + 1] = reversed(neighbour_state[left: right + 1])
+ return neighbour_state
+
+ def actions(self, state):
+ """action that can be executed in given state"""
+ return [self.two_opt]
+
+ def result(self, state, action):
+ """result after applying the given action on the given state"""
+ return action(state)
+
+ def path_cost(self, c, state1, action, state2):
+ """total distance for the Traveling Salesman to be covered if in state2"""
+ cost = 0
+ for i in range(len(state2) - 1):
+ cost += distances[state2[i]][state2[i + 1]]
+ cost += distances[state2[0]][state2[-1]]
+ return cost
+
+ def value(self, state):
+ """value of path cost given negative for the given state"""
+ return -1 * self.path_cost(None, None, None, state)
+
+
+class TSPGui():
+ """Class to create gui of Traveling Salesman using simulated annealing where one can
+ select cities, change speed and temperature. Distances between cities are euclidean
+ distances between them.
+ """
+
+ def __init__(self, root, all_cities):
+ self.root = root
+ self.vars = []
+ self.frame_locations = {}
+ self.calculate_canvas_size()
+ self.button_text = StringVar()
+ self.button_text.set("Start")
+ self.algo_var = StringVar()
+ self.all_cities = all_cities
+ self.frame_select_cities = Frame(self.root)
+ self.frame_select_cities.grid(row=1)
+ self.frame_canvas = Frame(self.root)
+ self.frame_canvas.grid(row=2)
+ Label(self.root, text="Map of Romania", font="Times 13 bold").grid(row=0, columnspan=10)
+
+ def create_checkboxes(self, side=LEFT, anchor=W):
+ """To select cities which are to be a part of Traveling Salesman Problem"""
+
+ row_number = 0
+ column_number = 0
+
+ for city in self.all_cities:
+ var = IntVar()
+ var.set(1)
+ Checkbutton(self.frame_select_cities, text=city, variable=var).grid(
+ row=row_number, column=column_number, sticky=W)
+
+ self.vars.append(var)
+ column_number += 1
+ if column_number == 10:
+ column_number = 0
+ row_number += 1
+
+ def create_buttons(self):
+ """Create start and quit button"""
+
+ Button(self.frame_select_cities, textvariable=self.button_text,
+ command=self.run_traveling_salesman).grid(row=5, column=4, sticky=E + W)
+ Button(self.frame_select_cities, text='Quit', command=self.on_closing).grid(
+ row=5, column=5, sticky=E + W)
+
+ def create_dropdown_menu(self):
+ """Create dropdown menu for algorithm selection"""
+
+ choices = {'Simulated Annealing', 'Genetic Algorithm', 'Hill Climbing'}
+ self.algo_var.set('Simulated Annealing')
+ dropdown_menu = OptionMenu(self.frame_select_cities, self.algo_var, *choices)
+ dropdown_menu.grid(row=4, column=4, columnspan=2, sticky=E + W)
+ dropdown_menu.config(width=19)
+
+ def run_traveling_salesman(self):
+ """Choose selected cities"""
+
+ cities = []
+ for i in range(len(self.vars)):
+ if self.vars[i].get() == 1:
+ cities.append(self.all_cities[i])
+
+ tsp_problem = TSProblem(cities)
+ self.button_text.set("Reset")
+ self.create_canvas(tsp_problem)
+
+ def calculate_canvas_size(self):
+ """Width and height for canvas"""
+
+ minx, maxx = sys.maxsize, -1 * sys.maxsize
+ miny, maxy = sys.maxsize, -1 * sys.maxsize
+
+ for value in romania_map.locations.values():
+ minx = min(minx, value[0])
+ maxx = max(maxx, value[0])
+ miny = min(miny, value[1])
+ maxy = max(maxy, value[1])
+
+ # New locations squeezed to fit inside the map of romania
+ for name, coordinates in romania_map.locations.items():
+ self.frame_locations[name] = (coordinates[0] / 1.2 - minx +
+ 150, coordinates[1] / 1.2 - miny + 165)
+
+ canvas_width = maxx - minx + 200
+ canvas_height = maxy - miny + 200
+
+ self.canvas_width = canvas_width
+ self.canvas_height = canvas_height
+
+ def create_canvas(self, problem):
+ """creating map with cities"""
+
+ map_canvas = Canvas(self.frame_canvas, width=self.canvas_width, height=self.canvas_height)
+ map_canvas.grid(row=3, columnspan=10)
+ current = Node(problem.initial)
+ map_canvas.delete("all")
+ self.romania_image = PhotoImage(file="../images/romania_map.png")
+ map_canvas.create_image(self.canvas_width / 2, self.canvas_height / 2,
+ image=self.romania_image)
+ cities = current.state
+ for city in cities:
+ x = self.frame_locations[city][0]
+ y = self.frame_locations[city][1]
+ map_canvas.create_oval(x - 3, y - 3, x + 3, y + 3,
+ fill="red", outline="red")
+ map_canvas.create_text(x - 15, y - 10, text=city)
+
+ self.cost = StringVar()
+ Label(self.frame_canvas, textvariable=self.cost, relief="sunken").grid(
+ row=2, columnspan=10)
+
+ self.speed = IntVar()
+ speed_scale = Scale(self.frame_canvas, from_=500, to=1, orient=HORIZONTAL,
+ variable=self.speed, label="Speed ----> ", showvalue=0, font="Times 11",
+ relief="sunken", cursor="gumby")
+ speed_scale.grid(row=1, columnspan=5, sticky=N + S + E + W)
+
+ if self.algo_var.get() == 'Simulated Annealing':
+ self.temperature = IntVar()
+ temperature_scale = Scale(self.frame_canvas, from_=100, to=0, orient=HORIZONTAL,
+ length=200, variable=self.temperature, label="Temperature ---->",
+ font="Times 11", relief="sunken", showvalue=0, cursor="gumby")
+ temperature_scale.grid(row=1, column=5, columnspan=5, sticky=N + S + E + W)
+ self.simulated_annealing_with_tunable_T(problem, map_canvas)
+ elif self.algo_var.get() == 'Genetic Algorithm':
+ self.mutation_rate = DoubleVar()
+ self.mutation_rate.set(0.05)
+ mutation_rate_scale = Scale(self.frame_canvas, from_=0, to=1, orient=HORIZONTAL,
+ length=200, variable=self.mutation_rate, label='Mutation Rate ---->',
+ font='Times 11', relief='sunken', showvalue=0, cursor='gumby', resolution=0.001)
+ mutation_rate_scale.grid(row=1, column=5, columnspan=5, sticky='nsew')
+ self.genetic_algorithm(problem, map_canvas)
+ elif self.algo_var.get() == 'Hill Climbing':
+ self.no_of_neighbors = IntVar()
+ self.no_of_neighbors.set(100)
+ no_of_neighbors_scale = Scale(self.frame_canvas, from_=10, to=1000, orient=HORIZONTAL,
+ length=200, variable=self.no_of_neighbors, label='Number of neighbors ---->',
+ font='Times 11', relief='sunken', showvalue=0, cursor='gumby')
+ no_of_neighbors_scale.grid(row=1, column=5, columnspan=5, sticky='nsew')
+ self.hill_climbing(problem, map_canvas)
+
+ def exp_schedule(k=100, lam=0.03, limit=1000):
+ """One possible schedule function for simulated annealing"""
+
+ return lambda t: (k * np.exp(-lam * t) if t < limit else 0)
+
+ def simulated_annealing_with_tunable_T(self, problem, map_canvas, schedule=exp_schedule()):
+ """Simulated annealing where temperature is taken as user input"""
+
+ current = Node(problem.initial)
+
+ while True:
+ T = schedule(self.temperature.get())
+ if T == 0:
+ return current.state
+ neighbors = current.expand(problem)
+ if not neighbors:
+ return current.state
+ next = random.choice(neighbors)
+ delta_e = problem.value(next.state) - problem.value(current.state)
+ if delta_e > 0 or probability(np.exp(delta_e / T)):
+ map_canvas.delete("poly")
+
+ current = next
+ self.cost.set("Cost = " + str('%0.3f' % (-1 * problem.value(current.state))))
+ points = []
+ for city in current.state:
+ points.append(self.frame_locations[city][0])
+ points.append(self.frame_locations[city][1])
+ map_canvas.create_polygon(points, outline='red', width=3, fill='', tag="poly")
+ map_canvas.update()
+ map_canvas.after(self.speed.get())
+
+ def genetic_algorithm(self, problem, map_canvas):
+ """Genetic Algorithm modified for the given problem"""
+
+ def init_population(pop_number, gene_pool, state_length):
+ """initialize population"""
+
+ population = []
+ for i in range(pop_number):
+ population.append(utils.shuffled(gene_pool))
+ return population
+
+ def recombine(state_a, state_b):
+ """recombine two problem states"""
+
+ start = random.randint(0, len(state_a) - 1)
+ end = random.randint(start + 1, len(state_a))
+ new_state = state_a[start:end]
+ for city in state_b:
+ if city not in new_state:
+ new_state.append(city)
+ return new_state
+
+ def mutate(state, mutation_rate):
+ """mutate problem states"""
+
+ if random.uniform(0, 1) < mutation_rate:
+ sample = random.sample(range(len(state)), 2)
+ state[sample[0]], state[sample[1]] = state[sample[1]], state[sample[0]]
+ return state
+
+ def fitness_fn(state):
+ """calculate fitness of a particular state"""
+
+ fitness = problem.value(state)
+ return int((5600 + fitness) ** 2)
+
+ current = Node(problem.initial)
+ population = init_population(100, current.state, len(current.state))
+ all_time_best = current.state
+ while True:
+ population = [mutate(recombine(*select(2, population, fitness_fn)), self.mutation_rate.get())
+ for _ in range(len(population))]
+ current_best = np.argmax(population, key=fitness_fn)
+ if fitness_fn(current_best) > fitness_fn(all_time_best):
+ all_time_best = current_best
+ self.cost.set("Cost = " + str('%0.3f' % (-1 * problem.value(all_time_best))))
+ map_canvas.delete('poly')
+ points = []
+ for city in current_best:
+ points.append(self.frame_locations[city][0])
+ points.append(self.frame_locations[city][1])
+ map_canvas.create_polygon(points, outline='red', width=1, fill='', tag='poly')
+ best_points = []
+ for city in all_time_best:
+ best_points.append(self.frame_locations[city][0])
+ best_points.append(self.frame_locations[city][1])
+ map_canvas.create_polygon(best_points, outline='red', width=3, fill='', tag='poly')
+ map_canvas.update()
+ map_canvas.after(self.speed.get())
+
+ def hill_climbing(self, problem, map_canvas):
+ """hill climbing where number of neighbors is taken as user input"""
+
+ def find_neighbors(state, number_of_neighbors=100):
+ """finds neighbors using two_opt method"""
+
+ neighbors = []
+ for i in range(number_of_neighbors):
+ new_state = problem.two_opt(state)
+ neighbors.append(Node(new_state))
+ state = new_state
+ return neighbors
+
+ current = Node(problem.initial)
+ while True:
+ neighbors = find_neighbors(current.state, self.no_of_neighbors.get())
+ neighbor = np.argmax_random_tie(neighbors, key=lambda node: problem.value(node.state))
+ map_canvas.delete('poly')
+ points = []
+ for city in current.state:
+ points.append(self.frame_locations[city][0])
+ points.append(self.frame_locations[city][1])
+ map_canvas.create_polygon(points, outline='red', width=3, fill='', tag='poly')
+ neighbor_points = []
+ for city in neighbor.state:
+ neighbor_points.append(self.frame_locations[city][0])
+ neighbor_points.append(self.frame_locations[city][1])
+ map_canvas.create_polygon(neighbor_points, outline='red', width=1, fill='', tag='poly')
+ map_canvas.update()
+ map_canvas.after(self.speed.get())
+ if problem.value(neighbor.state) > problem.value(current.state):
+ current.state = neighbor.state
+ self.cost.set("Cost = " + str('%0.3f' % (-1 * problem.value(current.state))))
+
+ def on_closing(self):
+ if messagebox.askokcancel('Quit', 'Do you want to quit?'):
+ self.root.destroy()
+
+
+if __name__ == '__main__':
+ all_cities = []
+ for city in romania_map.locations.keys():
+ distances[city] = {}
+ all_cities.append(city)
+ all_cities.sort()
+
+ # distances['city1']['city2'] contains euclidean distance between their coordinates
+ for name_1, coordinates_1 in romania_map.locations.items():
+ for name_2, coordinates_2 in romania_map.locations.items():
+ distances[name_1][name_2] = np.linalg.norm(
+ [coordinates_1[0] - coordinates_2[0], coordinates_1[1] - coordinates_2[1]])
+ distances[name_2][name_1] = np.linalg.norm(
+ [coordinates_1[0] - coordinates_2[0], coordinates_1[1] - coordinates_2[1]])
+
+ root = Tk()
+ root.title("Traveling Salesman Problem")
+ cities_selection_panel = TSPGui(root, all_cities)
+ cities_selection_panel.create_checkboxes()
+ cities_selection_panel.create_buttons()
+ cities_selection_panel.create_dropdown_menu()
+ root.protocol('WM_DELETE_WINDOW', cities_selection_panel.on_closing)
+ root.mainloop()
diff --git a/gui/vacuum_agent.py b/gui/vacuum_agent.py
new file mode 100644
index 000000000..b07dab282
--- /dev/null
+++ b/gui/vacuum_agent.py
@@ -0,0 +1,154 @@
+import os.path
+from tkinter import *
+
+from agents import *
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+
+loc_A, loc_B = (0, 0), (1, 0) # The two locations for the Vacuum world
+
+
+class Gui(Environment):
+ """This GUI environment has two locations, A and B. Each can be Dirty
+ or Clean. The agent perceives its location and the location's
+ status."""
+
+ def __init__(self, root, height=300, width=380):
+ super().__init__()
+ self.status = {loc_A: 'Clean',
+ loc_B: 'Clean'}
+ self.root = root
+ self.height = height
+ self.width = width
+ self.canvas = None
+ self.buttons = []
+ self.create_canvas()
+ self.create_buttons()
+
+ def thing_classes(self):
+ """The list of things which can be used in the environment."""
+ return [Wall, Dirt, ReflexVacuumAgent, RandomVacuumAgent,
+ TableDrivenVacuumAgent, ModelBasedVacuumAgent]
+
+ def percept(self, agent):
+ """Returns the agent's location, and the location status (Dirty/Clean)."""
+ return agent.location, self.status[agent.location]
+
+ def execute_action(self, agent, action):
+ """Change the location status (Dirty/Clean); track performance.
+ Score 10 for each dirt cleaned; -1 for each move."""
+ if action == 'Right':
+ agent.location = loc_B
+ agent.performance -= 1
+ elif action == 'Left':
+ agent.location = loc_A
+ agent.performance -= 1
+ elif action == 'Suck':
+ if self.status[agent.location] == 'Dirty':
+ if agent.location == loc_A:
+ self.buttons[0].config(bg='white', activebackground='light grey')
+ else:
+ self.buttons[1].config(bg='white', activebackground='light grey')
+ agent.performance += 10
+ self.status[agent.location] = 'Clean'
+
+ def default_location(self, thing):
+ """Agents start in either location at random."""
+ return random.choice([loc_A, loc_B])
+
+ def create_canvas(self):
+ """Creates Canvas element in the GUI."""
+ self.canvas = Canvas(
+ self.root,
+ width=self.width,
+ height=self.height,
+ background='powder blue')
+ self.canvas.pack(side='bottom')
+
+ def create_buttons(self):
+ """Creates the buttons required in the GUI."""
+ button_left = Button(self.root, height=4, width=12, padx=2, pady=2, bg='white')
+ button_left.config(command=lambda btn=button_left: self.dirt_switch(btn))
+ self.buttons.append(button_left)
+ button_left_window = self.canvas.create_window(130, 200, anchor=N, window=button_left)
+ button_right = Button(self.root, height=4, width=12, padx=2, pady=2, bg='white')
+ button_right.config(command=lambda btn=button_right: self.dirt_switch(btn))
+ self.buttons.append(button_right)
+ button_right_window = self.canvas.create_window(250, 200, anchor=N, window=button_right)
+
+ def dirt_switch(self, button):
+ """Gives user the option to put dirt in any tile."""
+ bg_color = button['bg']
+ if bg_color == 'saddle brown':
+ button.config(bg='white', activebackground='light grey')
+ elif bg_color == 'white':
+ button.config(bg='saddle brown', activebackground='light goldenrod')
+
+ def read_env(self):
+ """Reads the current state of the GUI."""
+ for i, btn in enumerate(self.buttons):
+ if i == 0:
+ if btn['bg'] == 'white':
+ self.status[loc_A] = 'Clean'
+ else:
+ self.status[loc_A] = 'Dirty'
+ else:
+ if btn['bg'] == 'white':
+ self.status[loc_B] = 'Clean'
+ else:
+ self.status[loc_B] = 'Dirty'
+
+ def update_env(self, agent):
+ """Updates the GUI according to the agent's action."""
+ self.read_env()
+ # print(self.status)
+ before_step = agent.location
+ self.step()
+ # print(self.status)
+ # print(agent.location)
+ move_agent(self, agent, before_step)
+
+
+def create_agent(env, agent):
+ """Creates the agent in the GUI and is kept independent of the environment."""
+ env.add_thing(agent)
+ # print(agent.location)
+ if agent.location == (0, 0):
+ env.agent_rect = env.canvas.create_rectangle(80, 100, 175, 180, fill='lime green')
+ env.text = env.canvas.create_text(128, 140, font="Helvetica 10 bold italic", text="Agent")
+ else:
+ env.agent_rect = env.canvas.create_rectangle(200, 100, 295, 180, fill='lime green')
+ env.text = env.canvas.create_text(248, 140, font="Helvetica 10 bold italic", text="Agent")
+
+
+def move_agent(env, agent, before_step):
+ """Moves the agent in the GUI when 'next' button is pressed."""
+ if agent.location == before_step:
+ pass
+ else:
+ if agent.location == (1, 0):
+ env.canvas.move(env.text, 120, 0)
+ env.canvas.move(env.agent_rect, 120, 0)
+ elif agent.location == (0, 0):
+ env.canvas.move(env.text, -120, 0)
+ env.canvas.move(env.agent_rect, -120, 0)
+
+
+# TODO: Add more agents to the environment.
+# TODO: Expand the environment to XYEnvironment.
+if __name__ == "__main__":
+ root = Tk()
+ root.title("Vacuum Environment")
+ root.geometry("420x380")
+ root.resizable(0, 0)
+ frame = Frame(root, bg='black')
+ # reset_button = Button(frame, text='Reset', height=2, width=6, padx=2, pady=2, command=None)
+ # reset_button.pack(side='left')
+ next_button = Button(frame, text='Next', height=2, width=6, padx=2, pady=2)
+ next_button.pack(side='left')
+ frame.pack(side='bottom')
+ env = Gui(root)
+ agent = ReflexVacuumAgent()
+ create_agent(env, agent)
+ next_button.config(command=lambda: env.update_env(agent))
+ root.mainloop()
diff --git a/gui/xy_vacuum_environment.py b/gui/xy_vacuum_environment.py
new file mode 100644
index 000000000..093abc6c3
--- /dev/null
+++ b/gui/xy_vacuum_environment.py
@@ -0,0 +1,191 @@
+import os.path
+from tkinter import *
+
+from agents import *
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+
+
+class Gui(VacuumEnvironment):
+ """This is a two-dimensional GUI environment. Each location may be
+ dirty, clean or can have a wall. The user can change these at each step.
+ """
+ xi, yi = (0, 0)
+ perceptible_distance = 1
+
+ def __init__(self, root, width=7, height=7, elements=None):
+ super().__init__(width, height)
+ if elements is None:
+ elements = ['D', 'W']
+ self.root = root
+ self.create_frames()
+ self.create_buttons()
+ self.create_walls()
+ self.elements = elements
+
+ def create_frames(self):
+ """Adds frames to the GUI environment."""
+ self.frames = []
+ for _ in range(7):
+ frame = Frame(self.root, bg='grey')
+ frame.pack(side='bottom')
+ self.frames.append(frame)
+
+ def create_buttons(self):
+ """Adds buttons to the respective frames in the GUI."""
+ self.buttons = []
+ for frame in self.frames:
+ button_row = []
+ for _ in range(7):
+ button = Button(frame, height=3, width=5, padx=2, pady=2)
+ button.config(
+ command=lambda btn=button: self.display_element(btn))
+ button.pack(side='left')
+ button_row.append(button)
+ self.buttons.append(button_row)
+
+ def create_walls(self):
+ """Creates the outer boundary walls which do not move."""
+ for row, button_row in enumerate(self.buttons):
+ if row == 0 or row == len(self.buttons) - 1:
+ for button in button_row:
+ button.config(text='W', state='disabled',
+ disabledforeground='black')
+ else:
+ button_row[0].config(
+ text='W', state='disabled', disabledforeground='black')
+ button_row[len(button_row) - 1].config(text='W',
+ state='disabled', disabledforeground='black')
+ # Place the agent in the centre of the grid.
+ self.buttons[3][3].config(
+ text='A', state='disabled', disabledforeground='black')
+
+ def display_element(self, button):
+ """Show the things on the GUI."""
+ txt = button['text']
+ if txt != 'A':
+ if txt == 'W':
+ button.config(text='D')
+ elif txt == 'D':
+ button.config(text='')
+ elif txt == '':
+ button.config(text='W')
+
+ def execute_action(self, agent, action):
+ """Determines the action the agent performs."""
+ xi, yi = (self.xi, self.yi)
+ if action == 'Suck':
+ dirt_list = self.list_things_at(agent.location, Dirt)
+ if dirt_list:
+ dirt = dirt_list[0]
+ agent.performance += 100
+ self.delete_thing(dirt)
+ self.buttons[xi][yi].config(text='', state='normal')
+ xf, yf = agent.location
+ self.buttons[xf][yf].config(
+ text='A', state='disabled', disabledforeground='black')
+
+ else:
+ agent.bump = False
+ if action == 'TurnRight':
+ agent.direction += Direction.R
+ elif action == 'TurnLeft':
+ agent.direction += Direction.L
+ elif action == 'Forward':
+ agent.bump = self.move_to(agent, agent.direction.move_forward(agent.location))
+ if not agent.bump:
+ self.buttons[xi][yi].config(text='', state='normal')
+ xf, yf = agent.location
+ self.buttons[xf][yf].config(
+ text='A', state='disabled', disabledforeground='black')
+
+ if action != 'NoOp':
+ agent.performance -= 1
+
+ def read_env(self):
+ """Reads the current state of the GUI environment."""
+ for i, btn_row in enumerate(self.buttons):
+ for j, btn in enumerate(btn_row):
+ if (i != 0 and i != len(self.buttons) - 1) and (j != 0 and j != len(btn_row) - 1):
+ agt_loc = self.agents[0].location
+ if self.some_things_at((i, j)) and (i, j) != agt_loc:
+ for thing in self.list_things_at((i, j)):
+ self.delete_thing(thing)
+ if btn['text'] == self.elements[0]:
+ self.add_thing(Dirt(), (i, j))
+ elif btn['text'] == self.elements[1]:
+ self.add_thing(Wall(), (i, j))
+
+ def update_env(self):
+ """Updates the GUI environment according to the current state."""
+ self.read_env()
+ agt = self.agents[0]
+ previous_agent_location = agt.location
+ self.xi, self.yi = previous_agent_location
+ self.step()
+ xf, yf = agt.location
+
+ def reset_env(self, agt):
+ """Resets the GUI environment to the initial state."""
+ self.read_env()
+ for i, btn_row in enumerate(self.buttons):
+ for j, btn in enumerate(btn_row):
+ if (i != 0 and i != len(self.buttons) - 1) and (j != 0 and j != len(btn_row) - 1):
+ if self.some_things_at((i, j)):
+ for thing in self.list_things_at((i, j)):
+ self.delete_thing(thing)
+ btn.config(text='', state='normal')
+ self.add_thing(agt, location=(3, 3))
+ self.buttons[3][3].config(
+ text='A', state='disabled', disabledforeground='black')
+
+
+def XYReflexAgentProgram(percept):
+ """The modified SimpleReflexAgentProgram for the GUI environment."""
+ status, bump = percept
+ if status == 'Dirty':
+ return 'Suck'
+
+ if bump == 'Bump':
+ value = random.choice((1, 2))
+ else:
+ value = random.choice((1, 2, 3, 4)) # 1-right, 2-left, others-forward
+
+ if value == 1:
+ return 'TurnRight'
+ elif value == 2:
+ return 'TurnLeft'
+ else:
+ return 'Forward'
+
+
+class XYReflexAgent(Agent):
+ """The modified SimpleReflexAgent for the GUI environment."""
+
+ def __init__(self, program=None):
+ super().__init__(program)
+ self.location = (3, 3)
+ self.direction = Direction("up")
+
+
+# TODO: Check the coordinate system.
+# TODO: Give manual choice for agent's location.
+if __name__ == "__main__":
+ root = Tk()
+ root.title("Vacuum Environment")
+ root.geometry("420x440")
+ root.resizable(0, 0)
+ frame = Frame(root, bg='black')
+ reset_button = Button(frame, text='Reset', height=2,
+ width=6, padx=2, pady=2)
+ reset_button.pack(side='left')
+ next_button = Button(frame, text='Next', height=2,
+ width=6, padx=2, pady=2)
+ next_button.pack(side='left')
+ frame.pack(side='bottom')
+ env = Gui(root)
+ agt = XYReflexAgent(program=XYReflexAgentProgram)
+ env.add_thing(agt, location=(3, 3))
+ next_button.config(command=env.update_env)
+ reset_button.config(command=lambda: env.reset_env(agt))
+ root.mainloop()
diff --git a/images/-0.04.jpg b/images/-0.04.jpg
new file mode 100644
index 000000000..3cf276421
Binary files /dev/null and b/images/-0.04.jpg differ
diff --git a/images/-0.4.jpg b/images/-0.4.jpg
new file mode 100644
index 000000000..b274d2ce3
Binary files /dev/null and b/images/-0.4.jpg differ
diff --git a/images/-4.jpg b/images/-4.jpg
new file mode 100644
index 000000000..79eefb0cd
Binary files /dev/null and b/images/-4.jpg differ
diff --git a/images/4.jpg b/images/4.jpg
new file mode 100644
index 000000000..55e75001d
Binary files /dev/null and b/images/4.jpg differ
diff --git a/images/broxrevised.png b/images/broxrevised.png
new file mode 100644
index 000000000..87051a383
Binary files /dev/null and b/images/broxrevised.png differ
diff --git a/images/cake_graph.jpg b/images/cake_graph.jpg
new file mode 100644
index 000000000..160a413ca
Binary files /dev/null and b/images/cake_graph.jpg differ
diff --git a/images/ensemble_learner.jpg b/images/ensemble_learner.jpg
new file mode 100644
index 000000000..b1edd1ec5
Binary files /dev/null and b/images/ensemble_learner.jpg differ
diff --git a/images/ge0.jpg b/images/ge0.jpg
new file mode 100644
index 000000000..a70b18703
Binary files /dev/null and b/images/ge0.jpg differ
diff --git a/images/ge1.jpg b/images/ge1.jpg
new file mode 100644
index 000000000..624f16e25
Binary files /dev/null and b/images/ge1.jpg differ
diff --git a/images/ge2.jpg b/images/ge2.jpg
new file mode 100644
index 000000000..3a29f8f4c
Binary files /dev/null and b/images/ge2.jpg differ
diff --git a/images/ge4.jpg b/images/ge4.jpg
new file mode 100644
index 000000000..b3a4b4acd
Binary files /dev/null and b/images/ge4.jpg differ
diff --git a/images/general_learning_agent.jpg b/images/general_learning_agent.jpg
new file mode 100644
index 000000000..a8153bef8
Binary files /dev/null and b/images/general_learning_agent.jpg differ
diff --git a/images/grid_mdp.jpg b/images/grid_mdp.jpg
new file mode 100644
index 000000000..fa77fa276
Binary files /dev/null and b/images/grid_mdp.jpg differ
diff --git a/images/grid_mdp_agent.jpg b/images/grid_mdp_agent.jpg
new file mode 100644
index 000000000..3f247b6f2
Binary files /dev/null and b/images/grid_mdp_agent.jpg differ
diff --git a/images/hillclimb-tsp.png b/images/hillclimb-tsp.png
new file mode 100644
index 000000000..8446bbafc
Binary files /dev/null and b/images/hillclimb-tsp.png differ
diff --git a/images/knowledge_FOIL_grandparent.png b/images/knowledge_FOIL_grandparent.png
new file mode 100644
index 000000000..dbc6e7729
Binary files /dev/null and b/images/knowledge_FOIL_grandparent.png differ
diff --git a/images/knowledge_foil_family.png b/images/knowledge_foil_family.png
new file mode 100644
index 000000000..356f22d8d
Binary files /dev/null and b/images/knowledge_foil_family.png differ
diff --git a/images/maze.png b/images/maze.png
new file mode 100644
index 000000000..f3fcd1990
Binary files /dev/null and b/images/maze.png differ
diff --git a/images/mdp-b.png b/images/mdp-b.png
new file mode 100644
index 000000000..f21a3760c
Binary files /dev/null and b/images/mdp-b.png differ
diff --git a/images/mdp-c.png b/images/mdp-c.png
new file mode 100644
index 000000000..1034079a2
Binary files /dev/null and b/images/mdp-c.png differ
diff --git a/images/mdp-d.png b/images/mdp-d.png
new file mode 100644
index 000000000..8ba7cf073
Binary files /dev/null and b/images/mdp-d.png differ
diff --git a/images/model_based_reflex_agent.jpg b/images/model_based_reflex_agent.jpg
new file mode 100644
index 000000000..b6c12ed09
Binary files /dev/null and b/images/model_based_reflex_agent.jpg differ
diff --git a/images/model_goal_based_agent.jpg b/images/model_goal_based_agent.jpg
new file mode 100644
index 000000000..93d6182b4
Binary files /dev/null and b/images/model_goal_based_agent.jpg differ
diff --git a/images/model_utility_based_agent.jpg b/images/model_utility_based_agent.jpg
new file mode 100644
index 000000000..693230c00
Binary files /dev/null and b/images/model_utility_based_agent.jpg differ
diff --git a/images/pop.jpg b/images/pop.jpg
new file mode 100644
index 000000000..52b3e3756
Binary files /dev/null and b/images/pop.jpg differ
diff --git a/images/queen_s.png b/images/queen_s.png
new file mode 100644
index 000000000..cc693102a
Binary files /dev/null and b/images/queen_s.png differ
diff --git a/images/random_forest.png b/images/random_forest.png
new file mode 100644
index 000000000..e0ab1d658
Binary files /dev/null and b/images/random_forest.png differ
diff --git a/images/refinement.png b/images/refinement.png
new file mode 100644
index 000000000..8270d81d0
Binary files /dev/null and b/images/refinement.png differ
diff --git a/images/romania_map.png b/images/romania_map.png
new file mode 100644
index 000000000..426c76f1e
Binary files /dev/null and b/images/romania_map.png differ
diff --git a/images/simple_problem_solving_agent.jpg b/images/simple_problem_solving_agent.jpg
new file mode 100644
index 000000000..80fb904b5
Binary files /dev/null and b/images/simple_problem_solving_agent.jpg differ
diff --git a/images/simple_reflex_agent.jpg b/images/simple_reflex_agent.jpg
new file mode 100644
index 000000000..74002a720
Binary files /dev/null and b/images/simple_reflex_agent.jpg differ
diff --git a/images/stapler1-test.png b/images/stapler1-test.png
new file mode 100644
index 000000000..e550d83f9
Binary files /dev/null and b/images/stapler1-test.png differ
diff --git a/improving_sat_algorithms.ipynb b/improving_sat_algorithms.ipynb
new file mode 100644
index 000000000..d461e99c4
--- /dev/null
+++ b/improving_sat_algorithms.ipynb
@@ -0,0 +1,2539 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "pycharm": {}
+ },
+ "source": [
+ "# Propositional Logic\n",
+ "---\n",
+ "# Improving Boolean Satisfiability Algorithms\n",
+ "\n",
+ "## Introduction\n",
+ "A propositional formula $\\Phi$ in *Conjunctive Normal Form* (CNF) is a conjunction of clauses $\\omega_j$, with $j \\in \\{1,...,m\\}$. Each clause being a disjunction of literals and each literal being either a positive ($x_i$) or a negative ($\\lnot{x_i}$) propositional variable, with $i \\in \\{1,...,n\\}$. By denoting with $[\\lnot]$ the possible presence of $\\lnot$, we can formally define $\\Phi$ as:\n",
+ "\n",
+ "$$\\bigwedge_{j = 1,...,m}\\bigg(\\bigvee_{i \\in \\omega_j} [\\lnot] x_i\\bigg)$$\n",
+ "\n",
+ "The ***Boolean Satisfiability Problem*** (SAT) consists in determining whether there exists a truth assignment in $\\{0, 1\\}$ (or equivalently in $\\{True,False\\}$) for the variables in $\\Phi$."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from logic import *"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## DPLL with Branching Heuristics\n",
+ "The ***Davis-Putnam-Logemann-Loveland*** (DPLL) algorithm is a *complete* (will answer SAT if a solution exists) and *sound* (it will not answer SAT for an unsatisfiable formula) procedue that combines *backtracking search* and *deduction* to decide satisfiability of propositional logic formula in CNF. At each search step a variable and a propositional value are selected for branching purposes. With each branching step, two values can be assigned to a variable, either 0 or 1. Branching corresponds to assigning the chosen value to the chosen variable. Afterwards, the logical consequences of each branching step are evaluated. Each time an unsatisfied clause (ie a *conflict*) is identified, backtracking is executed. Backtracking corresponds to undoing branching steps until an unflipped branch is reached. When both values have been assigned to the selected variable at a branching step, backtracking will undo this branching step. If for the first branching step both values have been considered, and backtracking undoes this first branching step, then the CNF formula can be declared unsatisfiable. This kind of backtracking is called *chronological backtracking*.\n",
+ "\n",
+ "Essentially, `DPLL` is a backtracking depth-first search through partial truth assignments which uses a *splitting rule* to replaces the original problem with two smaller subproblems, whereas the original Davis-Putnam procedure uses a variable elimination rule which replaces the original problem with one larger subproblem. Over the years, many heuristics have been proposed in choosing the splitting variable (which variable should be assigned a truth value next).\n",
+ "\n",
+ "Search algorithms that are based on a predetermined order of search are called static algorithms, whereas the ones that select them at the runtime are called dynamic. The first SAT search algorithm, the Davis-Putnam procedure is a static algorithm. Static search algorithms are usually very slow in practice and for this reason perform worse than dynamic search algorithms. However, dynamic search algorithms are much harder to design, since they require a heuristic for predetermining the order of search. The fundamental element of a heuristic is a branching strategy for selecting the next branching literal. This must not require a lot of time to compute and yet it must provide a powerful insight into the problem instance.\n",
+ "\n",
+ "Two basic heuristics are applied to this algorithm with the potential of cutting the search space in half. These are the *pure literal rule* and the *unit clause rule*.\n",
+ "- the *pure literal* rule is applied whenever a variable appears with a single polarity in all the unsatisfied clauses. In this case, assigning a truth value to the variable so that all the involved clauses are satisfied is highly effective in the search;\n",
+ "- if some variable occurs in the current formula in a clause of length 1 then the *unit clause* rule is applied. Here, the literal is selected and a truth value so the respective clause is satisfied is assigned. The iterative application of the unit rule is commonly reffered to as *Boolean Constraint Propagation* (BCP)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "\u001b[0;32mdef\u001b[0m \u001b[0mdpll_satisfiable\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0ms\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mbranching_heuristic\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mno_branching_heuristic\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;34m\"\"\"Check satisfiability of a propositional sentence.\u001b[0m\n",
+ "\u001b[0;34m This differs from the book code in two ways: (1) it returns a model\u001b[0m\n",
+ "\u001b[0;34m rather than True when it succeeds; this is more useful. (2) The\u001b[0m\n",
+ "\u001b[0;34m function find_pure_symbol is passed a list of unknown clauses, rather\u001b[0m\n",
+ "\u001b[0;34m than a list of all clauses and the model; this is more efficient.\u001b[0m\n",
+ "\u001b[0;34m >>> dpll_satisfiable(A |'<=>'| B) == {A: True, B: True}\u001b[0m\n",
+ "\u001b[0;34m True\u001b[0m\n",
+ "\u001b[0;34m \"\"\"\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mreturn\u001b[0m \u001b[0mdpll\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mconjuncts\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mto_cnf\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0ms\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mprop_symbols\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0ms\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m{\u001b[0m\u001b[0;34m}\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mbranching_heuristic\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "%psource dpll_satisfiable"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "\u001b[0;32mdef\u001b[0m \u001b[0mdpll\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mclauses\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0msymbols\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mmodel\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mbranching_heuristic\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mno_branching_heuristic\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;34m\"\"\"See if the clauses are true in a partial model.\"\"\"\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0munknown_clauses\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;34m[\u001b[0m\u001b[0;34m]\u001b[0m \u001b[0;31m# clauses with an unknown truth value\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mfor\u001b[0m \u001b[0mc\u001b[0m \u001b[0;32min\u001b[0m \u001b[0mclauses\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0mval\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mpl_true\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mc\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mmodel\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0mval\u001b[0m \u001b[0;32mis\u001b[0m \u001b[0;32mFalse\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mreturn\u001b[0m \u001b[0;32mFalse\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0mval\u001b[0m \u001b[0;32mis\u001b[0m \u001b[0;32mNone\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0munknown_clauses\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mappend\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mc\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0;32mnot\u001b[0m \u001b[0munknown_clauses\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mreturn\u001b[0m \u001b[0mmodel\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0mP\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mvalue\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mfind_pure_symbol\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msymbols\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0munknown_clauses\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0mP\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mreturn\u001b[0m \u001b[0mdpll\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mclauses\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mremove_all\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mP\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0msymbols\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mextend\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mmodel\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mP\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mvalue\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mbranching_heuristic\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0mP\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mvalue\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mfind_unit_clause\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mclauses\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mmodel\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0mP\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mreturn\u001b[0m \u001b[0mdpll\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mclauses\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mremove_all\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mP\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0msymbols\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mextend\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mmodel\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mP\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mvalue\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mbranching_heuristic\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0mP\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mvalue\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mbranching_heuristic\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msymbols\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0munknown_clauses\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mreturn\u001b[0m \u001b[0;34m(\u001b[0m\u001b[0mdpll\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mclauses\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mremove_all\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mP\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0msymbols\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mextend\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mmodel\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mP\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mvalue\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mbranching_heuristic\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;32mor\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0mdpll\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mclauses\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mremove_all\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mP\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0msymbols\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mextend\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mmodel\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mP\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;32mnot\u001b[0m \u001b[0mvalue\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mbranching_heuristic\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "%psource dpll"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Each of these branching heuristics was applied only after the *pure literal* and the *unit clause* heuristic failed in selecting a splitting variable."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### MOMs"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "MOMs heuristics are simple, efficient and easy to implement. The goal of these heuristics is to prefer the literal having ***Maximum number of Occurences in the Minimum length clauses***. Intuitively, the literals belonging to the minimum length clauses are the most constrained literals in the formula. Branching on them will maximize the effect of BCP and the likelihood of hitting a dead end early in the search tree (for unsatisfiable problems). Conversely, in the case of satisfiable formulas, branching on a highly constrained variable early in the tree will also increase the likelihood of a correct assignment of the remained open literals.\n",
+ "The MOMs heuristics main disadvatage is that their effectiveness highly depends on the problem instance. It is easy to see that the ideal setting for these heuristics is considering the unsatisfied binary clauses."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "\u001b[0;32mdef\u001b[0m \u001b[0mmin_clauses\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mclauses\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0mmin_len\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mmin\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mmap\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;32mlambda\u001b[0m \u001b[0mc\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0mlen\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mc\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0margs\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mclauses\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mdefault\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;36m2\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mreturn\u001b[0m \u001b[0mfilter\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;32mlambda\u001b[0m \u001b[0mc\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0mlen\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mc\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0margs\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m==\u001b[0m \u001b[0;34m(\u001b[0m\u001b[0mmin_len\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0mmin_len\u001b[0m \u001b[0;34m>\u001b[0m \u001b[0;36m1\u001b[0m \u001b[0;32melse\u001b[0m \u001b[0;36m2\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mclauses\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "%psource min_clauses"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "\u001b[0;32mdef\u001b[0m \u001b[0mmoms\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msymbols\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mclauses\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;34m\"\"\"\u001b[0m\n",
+ "\u001b[0;34m MOMS (Maximum Occurrence in clauses of Minimum Size) heuristic\u001b[0m\n",
+ "\u001b[0;34m Returns the literal with the most occurrences in all clauses of minimum size\u001b[0m\n",
+ "\u001b[0;34m \"\"\"\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0mscores\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mCounter\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0ml\u001b[0m \u001b[0;32mfor\u001b[0m \u001b[0mc\u001b[0m \u001b[0;32min\u001b[0m \u001b[0mmin_clauses\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mclauses\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;32mfor\u001b[0m \u001b[0ml\u001b[0m \u001b[0;32min\u001b[0m \u001b[0mprop_symbols\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mc\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mreturn\u001b[0m \u001b[0mmax\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msymbols\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mkey\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;32mlambda\u001b[0m \u001b[0msymbol\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0mscores\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0msymbol\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;32mTrue\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "%psource moms"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Over the years, many types of MOMs heuristics have been proposed.\n",
+ "\n",
+ "***MOMSf*** choose the variable $x$ with a maximize the function:\n",
+ "\n",
+ "$$[f(x) + f(\\lnot{x})] * 2^k + f(x) * f(\\lnot{x})$$\n",
+ "\n",
+ "where $f(x)$ is the number of occurrences of $x$ in the smallest unknown clauses, k is a parameter."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "\u001b[0;32mdef\u001b[0m \u001b[0mmomsf\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msymbols\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mclauses\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mk\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;36m0\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;34m\"\"\"\u001b[0m\n",
+ "\u001b[0;34m MOMS alternative heuristic\u001b[0m\n",
+ "\u001b[0;34m If f(x) the number of occurrences of the variable x in clauses with minimum size,\u001b[0m\n",
+ "\u001b[0;34m we choose the variable maximizing [f(x) + f(-x)] * 2^k + f(x) * f(-x)\u001b[0m\n",
+ "\u001b[0;34m Returns x if f(x) >= f(-x) otherwise -x\u001b[0m\n",
+ "\u001b[0;34m \"\"\"\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0mscores\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mCounter\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0ml\u001b[0m \u001b[0;32mfor\u001b[0m \u001b[0mc\u001b[0m \u001b[0;32min\u001b[0m \u001b[0mmin_clauses\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mclauses\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;32mfor\u001b[0m \u001b[0ml\u001b[0m \u001b[0;32min\u001b[0m \u001b[0mdisjuncts\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mc\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0mP\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mmax\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msymbols\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0mkey\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;32mlambda\u001b[0m \u001b[0msymbol\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;34m(\u001b[0m\u001b[0mscores\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0msymbol\u001b[0m\u001b[0;34m]\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0mscores\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m~\u001b[0m\u001b[0msymbol\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m*\u001b[0m \u001b[0mpow\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;36m2\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mk\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0mscores\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0msymbol\u001b[0m\u001b[0;34m]\u001b[0m \u001b[0;34m*\u001b[0m \u001b[0mscores\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m~\u001b[0m\u001b[0msymbol\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
+ "\u001b[0;34m\u001b[0m \u001b[0;32mreturn\u001b[0m \u001b[0mP\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;32mTrue\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0mscores\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0mP\u001b[0m\u001b[0;34m]\u001b[0m \u001b[0;34m>=\u001b[0m \u001b[0mscores\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m~\u001b[0m\u001b[0mP\u001b[0m\u001b[0;34m]\u001b[0m \u001b[0;32melse\u001b[0m \u001b[0;32mFalse\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "%psource momsf"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "***Freeman’s POSIT*** ![](\"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",
+ " ![](\"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",
+ " ![](\"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",
+ " ![](\"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 \"![](\"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",
+ "