Merge pull request udacity#16 from jared-weed/machine-learning-branch

Add robot motion planning capstone project

Author: jared-weed

projects/capstone/README.md

@@ -1 +1,3 @@
-# Project 5: Capstone
+# Project 5: Capstone
+
+The Capstone Project for the Machine Learning Engineer Nanodegree does not have any requirements for code, libraries, or datasets. You are free to choose your project as you wish! For students who are unable to construct a capstone project on their own imagination, a pre-built project has been provided in `robot_motion_planning`.

projects/capstone/robot_motion_planning/maze.py

@@ -0,0 +1,94 @@
+import numpy as np
+
+class Maze(object):
+    def __init__(self, filename):
+        '''
+        Maze objects have two main attributes:
+        - dim: mazes should be square, with sides of even length. (integer)
+        - walls: passages are coded as a 4-bit number, with a bit value taking
+            0 if there is a wall and 1 if there is no wall. The 1s register
+            corresponds with a square's top edge, 2s register the right edge,
+            4s register the bottom edge, and 8s register the left edge. (numpy
+            array)
+
+        The initialization function also performs some consistency checks for
+        wall positioning.
+        '''
+        with open(filename, 'rb') as f_in:
+
+            # First line should be an integer with the maze dimensions
+            self.dim = int(f_in.next())
+
+            # Subsequent lines describe the permissability of walls
+            walls = []
+            for line in f_in:
+                walls.append(map(int,line.split(',')))
+            self.walls = np.array(walls)
+
+        # Perform validation on maze
+        # Maze dimensions
+        if self.dim % 2:
+            raise Exception('Maze dimensions must be even in length!')
+        if self.walls.shape != (self.dim, self.dim):
+            raise Exception('Maze shape does not match dimension attribute!')
+
+        # Wall permeability
+        wall_errors = []
+        # vertical walls
+        for x in range(self.dim-1):
+            for y in range(self.dim):
+                if (self.walls[x,y] & 2 != 0) != (self.walls[x+1,y] & 8 != 0):
+                    wall_errors.append([(x,y), 'v'])
+        # horizontal walls
+        for y in range(self.dim-1):
+            for x in range(self.dim):
+                if (self.walls[x,y] & 1 != 0) != (self.walls[x,y+1] & 4 != 0):
+                    wall_errors.append([(x,y), 'h'])
+
+        if wall_errors:
+            for cell, wall_type in wall_errors:
+                if wall_type == 'v':
+                    cell2 = (cell[0]+1, cell[1])
+                    print 'Inconsistent vertical wall betweeen {} and {}'.format(cell, cell2)
+                else:
+                    cell2 = (cell[0], cell[1]+1)
+                    print 'Inconsistent horizontal wall betweeen {} and {}'.format(cell, cell2)
+            raise Exception('Consistency errors found in wall specifications!')
+
+
+    def is_permissible(self, cell, direction):
+        """
+        Returns a boolean designating whether or not a cell is passable in the
+        given direction. Cell is input as a list. Directions may be
+        input as single letter 'u', 'r', 'd', 'l', or complete words 'up', 
+        'right', 'down', 'left'.
+        """
+        dir_int = {'u': 1, 'r': 2, 'd': 4, 'l': 8,
+                   'up': 1, 'right': 2, 'down': 4, 'left': 8}
+        try:
+            return (self.walls[tuple(cell)] & dir_int[direction] != 0)
+        except:
+            print 'Invalid direction provided!'
+
+
+    def dist_to_wall(self, cell, direction):
+        """
+        Returns a number designating the number of open cells to the nearest
+        wall in the indicated direction. Cell is input as a list. Directions
+        may be input as a single letter 'u', 'r', 'd', 'l', or complete words
+        'up', 'right', 'down', 'left'.
+        """
+        dir_move = {'u': [0, 1], 'r': [1, 0], 'd': [0, -1], 'l': [-1, 0],
+                    'up': [0, 1], 'right': [1, 0], 'down': [0, -1], 'left': [-1, 0]}
+
+        sensing = True
+        distance = 0
+        curr_cell = list(cell) # make copy to preserve original
+        while sensing:
+            if self.is_permissible(curr_cell, direction):
+                distance += 1
+                curr_cell[0] += dir_move[direction][0]
+                curr_cell[1] += dir_move[direction][1]
+            else:
+                sensing = False
+        return distance

projects/capstone/robot_motion_planning/robot.py

@@ -0,0 +1,41 @@
+import numpy as np
+
+class Robot(object):
+    def __init__(self, maze_dim):
+        '''
+        Use the initialization function to set up attributes that your robot
+        will use to learn and navigate the maze. Some initial attributes are
+        provided based on common information, including the size of the maze
+        the robot is placed in.
+        '''
+
+        self.location = [0, 0]
+        self.heading = 'up'
+        self.maze_dim = maze_dim
+
+    def next_move(self, sensors):
+        '''
+        Use this function to determine the next move the robot should make,
+        based on the input from the sensors after its previous move. Sensor
+        inputs are a list of three distances from the robot's left, front, and
+        right-facing sensors, in that order.
+
+        Outputs should be a tuple of two values. The first value indicates
+        robot rotation (if any), as a number: 0 for no rotation, +90 for a
+        90-degree rotation clockwise, and -90 for a 90-degree rotation
+        counterclockwise. Other values will result in no rotation. The second
+        value indicates robot movement, and the robot will attempt to move the
+        number of indicated squares: a positive number indicates forwards
+        movement, while a negative number indicates backwards movement. The
+        robot may move a maximum of three units per turn. Any excess movement
+        is ignored.
+
+        If the robot wants to end a run (e.g. during the first training run in
+        the maze) then returing the tuple ('Reset', 'Reset') will indicate to
+        the tester to end the run and return the robot to the start.
+        '''
+
+        rotation = 0
+        movement = 0
+
+        return rotation, movement

projects/capstone/robot_motion_planning/showmaze.py

@@ -0,0 +1,58 @@
+from maze import Maze
+import turtle
+import sys
+
+if __name__ == '__main__':
+    '''
+    This function uses Python's turtle library to draw a picture of the maze
+    given as an argument when running the script.
+    '''
+
+    # Create a maze based on input argument on command line.
+    testmaze = Maze( str(sys.argv[1]) )
+
+    # Intialize the window and drawing turtle.
+    window = turtle.Screen()
+    wally = turtle.Turtle()
+    wally.speed(0)
+    wally.hideturtle()
+    wally.penup()
+
+    # maze centered on (0,0), squares are 20 units in length.
+    sq_size = 20
+    origin = testmaze.dim * sq_size / -2
+
+    # iterate through squares one by one to decide where to draw walls
+    for x in range(testmaze.dim):
+        for y in range(testmaze.dim):
+            if not testmaze.is_permissible([x,y], 'up'):
+                wally.goto(origin + sq_size * x, origin + sq_size * (y+1))
+                wally.setheading(0)
+                wally.pendown()
+                wally.forward(sq_size)
+                wally.penup()
+
+            if not testmaze.is_permissible([x,y], 'right'):
+                wally.goto(origin + sq_size * (x+1), origin + sq_size * y)
+                wally.setheading(90)
+                wally.pendown()
+                wally.forward(sq_size)
+                wally.penup()
+
+            # only check bottom wall if on lowest row
+            if y == 0 and not testmaze.is_permissible([x,y], 'down'):
+                wally.goto(origin + sq_size * x, origin)
+                wally.setheading(0)
+                wally.pendown()
+                wally.forward(sq_size)
+                wally.penup()
+
+            # only check left wall if on leftmost column
+            if x == 0 and not testmaze.is_permissible([x,y], 'left'):
+                wally.goto(origin, origin + sq_size * y)
+                wally.setheading(90)
+                wally.pendown()
+                wally.forward(sq_size)
+                wally.penup()
+
+    window.exitonclick()

projects/capstone/robot_motion_planning/test_maze_01.txt

@@ -0,0 +1,13 @@
+12
+1,5,7,5,5,5,7,5,7,5,5,6
+3,5,14,3,7,5,15,4,9,5,7,12
+11,6,10,10,9,7,13,6,3,5,13,4
+10,9,13,12,3,13,5,12,9,5,7,6
+9,5,6,3,15,5,5,7,7,4,10,10
+3,5,15,14,10,3,6,10,11,6,10,10
+9,7,12,11,12,9,14,9,14,11,13,14
+3,13,5,12,2,3,13,6,9,14,3,14
+11,4,1,7,15,13,7,13,6,9,14,10
+11,5,6,10,9,7,13,5,15,7,14,8
+11,5,12,10,2,9,5,6,10,8,9,6
+9,5,5,13,13,5,5,12,9,5,5,12

projects/capstone/robot_motion_planning/test_maze_02.txt

@@ -0,0 +1,15 @@
+14
+1,5,5,7,7,5,5,6,3,6,3,5,5,6
+3,5,6,10,9,5,5,15,14,11,14,3,7,14
+11,6,11,14,1,7,6,10,10,10,11,12,8,10
+10,9,12,10,3,12,11,14,11,14,10,3,5,14
+11,5,6,8,11,7,12,8,10,9,12,9,7,12
+11,7,13,7,14,11,5,5,13,5,4,3,13,6
+8,9,5,14,9,12,3,7,6,3,6,11,6,10
+3,5,5,14,3,6,9,12,11,12,10,10,10,10
+10,3,5,13,14,10,3,5,13,7,14,8,9,14
+9,14,3,6,11,14,9,5,6,10,10,3,6,10
+3,13,14,11,14,11,4,3,13,15,13,14,10,10
+10,3,15,12,9,12,3,13,5,14,3,12,11,14
+11,12,11,7,5,6,10,1,5,15,13,7,12,10
+9,5,12,9,5,13,13,5,5,12,1,13,5,12

projects/capstone/robot_motion_planning/test_maze_03.txt

@@ -0,0 +1,17 @@
+16
+1,5,5,6,3,7,5,5,5,5,7,5,5,5,5,6
+3,5,6,10,10,9,6,3,5,5,13,7,5,5,6,10
+11,6,11,15,15,5,14,8,2,3,5,13,5,6,10,10
+10,10,10,10,11,5,13,5,12,9,7,6,3,15,13,14
+10,10,10,9,12,3,5,6,3,6,10,11,14,11,6,10
+9,14,9,4,3,13,6,11,14,10,9,12,11,12,10,10
+1,13,6,3,14,3,15,12,9,15,6,3,13,7,12,10
+3,6,10,10,9,14,8,3,6,8,10,9,7,13,7,12
+10,10,10,10,3,13,7,13,12,3,14,3,13,7,13,6
+10,10,10,11,12,3,14,3,6,10,10,10,3,15,7,14
+10,9,12,9,7,14,11,14,10,8,10,10,10,10,10,10
+11,5,5,6,10,11,14,11,15,6,9,13,14,10,10,10
+11,7,6,10,9,14,9,14,10,10,3,7,15,14,10,10
+10,10,9,12,2,9,5,15,14,10,10,10,10,11,14,10
+10,11,5,5,12,3,5,12,10,11,13,12,10,10,9,14
+9,13,5,5,5,13,5,5,13,13,5,5,12,9,5,12

projects/capstone/robot_motion_planning/tester.py

@@ -0,0 +1,114 @@
+from maze import Maze
+from robot import Robot
+import sys
+
+# global dictionaries for robot movement and sensing
+dir_sensors = {'u': ['l', 'u', 'r'], 'r': ['u', 'r', 'd'],
+               'd': ['r', 'd', 'l'], 'l': ['d', 'l', 'u'],
+               'up': ['l', 'u', 'r'], 'right': ['u', 'r', 'd'],
+               'down': ['r', 'd', 'l'], 'left': ['d', 'l', 'u']}
+dir_move = {'u': [0, 1], 'r': [1, 0], 'd': [0, -1], 'l': [-1, 0],
+            'up': [0, 1], 'right': [1, 0], 'down': [0, -1], 'left': [-1, 0]}
+dir_reverse = {'u': 'd', 'r': 'l', 'd': 'u', 'l': 'r',
+               'up': 'd', 'right': 'l', 'down': 'u', 'left': 'r'}
+
+# test and score parameters
+max_time = 1000
+train_score_mult = 1/30.
+
+if __name__ == '__main__':
+    '''
+    This script tests a robot based on the code in robot.py on a maze given
+    as an argument when running the script.
+    '''
+
+    # Create a maze based on input argument on command line.
+    testmaze = Maze( str(sys.argv[1]) )
+
+    # Intitialize a robot; robot receives info about maze dimensions.
+    testrobot = Robot(testmaze.dim)
+
+    # Record robot performance over two runs.
+    runtimes = []
+    total_time = 0
+    for run in range(2):
+        print "Starting run {}.".format(run)
+
+        # Set the robot in the start position. Note that robot position
+        # parameters are independent of the robot itself.
+        robot_pos = {'location': [0, 0], 'heading': 'up'}
+
+        run_active = True
+        hit_goal = False
+        while run_active:
+            # check for end of time
+            total_time += 1
+            if total_time > max_time:
+                run_active = False
+                print "Allotted time exceeded."
+                break
+
+            # provide robot with sensor information, get actions
+            sensing = [testmaze.dist_to_wall(robot_pos['location'], heading)
+                       for heading in dir_sensors[robot_pos['heading']]]
+            rotation, movement = testrobot.next_move(sensing)
+
+            # check for a reset
+            if (rotation, movement) == ('Reset', 'Reset'):
+                if run == 0 and hit_goal:
+                    run_active = False
+                    runtimes.append(total_time)
+                    print "Ending first run. Starting next run."
+                    break
+                elif run == 0 and not hit_goal:
+                    print "Cannot reset - robot has not hit goal yet."
+                    continue
+                else:
+                    print "Cannot reset on runs after the first."
+                    continue
+
+            # perform rotation
+            if rotation == -90:
+                robot_pos['heading'] = dir_sensors[robot_pos['heading']][0]
+            elif rotation == 90:
+                robot_pos['heading'] = dir_sensors[robot_pos['heading']][2]
+            elif rotation == 0:
+                pass
+            else:
+                print "Invalid rotation value, no rotation performed."
+
+            # perform movement
+            if abs(movement) > 3:
+                print "Movement limited to three squares in a turn."
+            movement = max(min(int(movement), 3), -3) # fix to range [-3, 3]
+            while movement:
+                if movement > 0:
+                    if testmaze.is_permissible(robot_pos['location'], robot_pos['heading']):
+                        robot_pos['location'][0] += dir_move[robot_pos['heading']][0]
+                        robot_pos['location'][1] += dir_move[robot_pos['heading']][1]
+                        movement -= 1
+                    else:
+                        print "Movement stopped by wall."
+                        movement = 0
+                else:
+                    rev_heading = dir_reverse[robot_pos['heading']]
+                    if testmaze.is_permissible(robot_pos['location'], rev_heading):
+                        robot_pos['location'][0] += dir_move[rev_heading][0]
+                        robot_pos['location'][1] += dir_move[rev_heading][1]
+                        movement += 1
+                    else:
+                        print "Movement stopped by wall."
+                        movement = 0
+
+            # check for goal entered
+            goal_bounds = [testmaze.dim/2 - 1, testmaze.dim/2]
+            if robot_pos['location'][0] in goal_bounds and robot_pos['location'][1] in goal_bounds:
+                hit_goal = True
+                if run != 0:
+                    runtimes.append(total_time - sum(runtimes))
+                    run_active = False
+                    print "Goal found; run {} completed!".format(run)
+
+    # Report score if robot is successful.
+    if len(runtimes) == 2:
+        print "Task complete! Score: {:4.3f}".format(runtimes[1] + train_score_mult*runtimes[0])