Project 4: Ghostbusters

I can hear you, ghost.
Running won't save you from my
Particle filter!

Introduction

Pacman spends his life running from ghosts, but things were not always so. Legend has it that many years ago, Pacman's great grandfather Grandpac learned to hunt ghosts for sport. However, he was blinded by his power and could only track ghosts by their banging and clanging.

In this project, you will design Pacman agents that use sensors to locate and eat invisible ghosts. You'll advance from locating single, stationary ghosts to hunting packs of multiple moving ghosts with ruthless efficiency.

The code for this project contains the following files, available as a zip archive.

Files you will edit

bustersAgents.py	Agents for playing the Ghostbusters variant of Pacman.
inference.py	Code for tracking ghosts over time using their sounds.

Files you will not edit

busters.py	The main entry to Ghostbusters (replacing pacman.py)
bustersGhostAgents.py	New ghost agents for Ghostbusters
distanceCalculator.py	Computes maze distances
game.py	Inner workings and helper classes for Pacman
ghostAgents.py	Agents to control ghosts
graphicsDisplay.py	Graphics for Pacman
graphicsUtils.py	Support for Pacman graphics
keyboardAgents.py	Keyboard interfaces to control Pacman
layout.py	Code for reading layout files and storing their contents
util.py	Utility functions
autograder.py	autograder file
testParser.py	Parses autograder test and solution files
testClasses.py	General autograding test classes
test_cases/	Directory containing the test cases for each question
trackingTestClasses.py	Project 4 specific autograding test classes

What to submit: You will fill in portions of bustersAgents.py and inference.py during the assignment. You should submit this files with your code and comments. Please do not change the other files in this distribution or submit any of our original files other than inference.py and bustersAgents.py.

This assignment should be submitted via turnin with the assignment name cs343-4-tracking using these submission instructions.

Evaluation: Your code will be autograded for technical correctness. Please do not change the names of any provided functions or classes within the code, or you will wreak havoc on the autograder. However, the correctness of your implementation -- not the highlight --out-format=xhtml -B '*.cpp' -d /home/you/html_code/ autograder's judgements -- will be the final judge of your score. If necessary, we will review and grade assignments individually to ensure that you receive due credit for your work.

Academic Dishonesty: We will be checking your code against other submissions in the class for logical redundancy. If you copy someone else's code and submit it with minor changes, we will know. These cheat detectors are quite hard to fool, so please don't try. We trust you all to submit your own work only; please don't let us down. If you do, we will pursue the strongest consequences available to us.

Getting Help: You are not alone! If you find yourself stuck on something, contact the course staff for help. Office hours, and Piazza are there for your support; please use them. If you can't make our office hours, let us know and we will schedule more. We want these projects to be rewarding and instructional, not frustrating and demoralizing. But, we don't know when or how to help unless you ask. One more piece of advice: if you don't know what a variable does or what kind of values it takes, print it out.

Ghostbusters and BNs

In the cs343 version of Ghostbusters, the goal is to hunt down scared but invisible ghosts. Pacman, ever resourceful, is equipped with sonar (ears) that provides noisy readings of the Manhattan distance to each ghost. The game ends when pacman has eaten all the ghosts. To start, try playing a game yourself using the keyboard.

  python busters.py

The blocks of color indicate where each ghost could possibly be, given the noisy distance readings provided to Pacman. The noisy distances at the bottom of the display are always non-negative, and always within 7 of the true distance. The probability of a distance reading decreases exponentially with its difference from the true distance.

Your primary task in this project is to implement inference to track the ghosts. A crude form of inference is implemented for you by default: all squares in which a ghost could possibly be are shaded by the color of the ghost. Option -s shows where the ghost actually is.

  python busters.py -s -k 1

Naturally, we want a better estimate of the ghost's position. We will start by locating a single, stationary ghost using multiple noisy distance readings. The default BustersKeyboardAgent in bustersAgents.py uses the ExactInference module in inference.py to track ghosts.

While watching and debugging your code with the autograder, it will be helpful to have some understanding of what the autograder is doing. There are 2 types of tests in this project, as differentiated by their *.test files found in the subdirectories of the test_cases folder. For tests of class DoubleInferenceAgentTest, your will see visualizations of the inference distributions generated by your code, but all Pacman actions will be preselected according to the actions of the staff implementation. This is necessary in order to allow comparision of your distributions with the staff's distributions. The second type of test is GameScoreTest, in which your BustersAgent will actually select actions for Pacman and you will watch your Pacman play and win games.

As you implement and debug your code, you may find it useful to run a single test at a time. In order to do this you will need to use the -t flag with the autograder. For example if you only want to run the first test of question 1, use:

 python autograder.py -t test_cases/q1/1-ExactObserve 

In general, all test cases can be found inside test_cases/q*.

Question 1 (3 points) Update the observe method in ExactInference class of inference.py to correctly update the agent's belief distribution over ghost positions. When complete, you should be able to accurately locate a ghost by circling it.

  python busters.py -s -k 1 -g StationaryGhost

Because the default RandomGhost ghost agents move independently of one another, you can track each one separately. The default BustersKeyboardAgent is set up to do this for you. Hence, you should be able to locate multiple stationary ghosts simultaneously. Encircling the ghosts should give you precise distributions over the ghosts' locations.

  python busters.py -s -g StationaryGhost

Note: your busters agents have a separate inference module for each ghost they are tracking. That's why if you print an observation inside the observe function, you'll only see a single number even though there may be multiple ghosts on the board.

Hints:

• You are implementing the online belief update for observing new evidence. Before any readings, pacman believes the ghost could be anywhere: a uniform prior (see initializeUniformly. After receiving a reading, the observe function is called, which must update the belief at every position.
• Before typing any code, write down the equation of the inference problem you are trying to solve.
• Try printing noisyDistance, emissionModel, and pacmanPosition (in the observe function) to get started.
• In the Pacman display, high posterior beliefs are represented by bright colors, while low beliefs are represented by dim colors. You should start with a large cloud of belief that shrinks over time as more evidence accumulates.
• Beliefs are stored as util.Counter objects (like dictionaries) in a field called self.beliefs, which you should update.
• You should not need to store any evidence. The only thing you need to store in ExactInference is self.beliefs.

To run the autograder for this question and visualize the output use:

python autograder.py -q q1

Ghosts don't hold still forever. Fortunately, your agent has access to the action distribution for any GhostAgent. Your next task is to use the ghost's move distribution to update your agent's beliefs when time elapses, taking into account this knowledge of how the ghosts may move.

Question 2 (4 points) Fill in the elapseTime method in ExactInference to correctly update the agent's belief distribution over the ghost's position when the ghost moves. When complete, you should be able to accurately locate moving ghosts, but some uncertainty will always remain about a ghost's position as it moves.

  python busters.py -s -k 1

  python busters.py -s -k 1 -g DirectionalGhost

Note: ghosts choose their action distributions based on whole GameState objects, for instance so that they can choose to move toward Pacman, avoid walls, etc. However, we only track the ghosts' positions for convenience. In order to obtain a distribution over a ghost's actions, you will need to create a complete GameState by placing the ghost in the game state where you think it is. Hints:

• Instructions for obtaining a distribution over where a ghost will go next, given its current position and the gameState, appears in the comments of ExactInference.elapseTime in inference.py.
• A DirectionalGhost is easier to track because it is more predictable. After running away from one for a while, your agent should have a good idea where it is.
• We assume that ghosts still move independently of one another, so while you can develop all of your code for one ghost at a time, adding multiple ghosts should still work correctly.

Now that Pacman can track ghosts, try playing without peeking at the ghost locations. Beliefs about each ghost will be overlaid on the screen. The game should be challenging, but not impossible.

  python busters.py -l bigHunt

For the tests in this question we will sometimes use a ghost with random movements and other times we will use the GoSouthGhost. This ghost tends to move south so over time, and without any observations, Pacman's belief distribution should begin to focus around the bottom of the board. To see which ghost is used for each test case you can look in the .test files.

To run the autograder for this question and visualize the output:

python autograder.py -q q2

As an example of the GoSouthGhostAgent, you can run

python autograder.py -t test_cases/q2/2-ExactElapse

and observe that the distribution becomes concentrated at the bottom of the board.

As you watch the autograder output, remember that lighter squares indicate that pacman believes a ghost is more likely to occupy that location, and darker squares indicate a ghost is less likely to occupy that location. For which of the test cases do you notice differences emerging in the shading of the squares? Can you explain why some squares get lighter and some squares get darker?

Now, pacman is ready to hunt down ghosts on his own. You will implement a simple greedy hunting strategy, where Pacman assumes that each ghost is in its most likely position according to its beliefs, then moves toward the closest ghost.

Question 3 (4 points) Implement the chooseAction method in GreedyBustersAgent in bustersAgents.py. Your agent should first find the most likely position of each remaining (uncaptured) ghost, then choose an action that minimizes the distance to the closest ghost. If correctly implemented, your agent should win smallHunt with a score greater than 700 at least 8 out of 10 times.

  python busters.py -p GreedyBustersAgent -l smallHunt

Hints:

• When correctly implemented, your agent will thrash around a bit in order to capture a ghost.
• The comments of chooseAction provide you with useful method calls for computing maze distance and successor positions.
• Make sure to only consider the living ghosts. The function gameState.getLivingGhosts() may come in handy.

To run the autograder for this question and visualize the output:

python autograder.py -q q3

Note: If you want to run this test (or any of the other tests) without graphics you can add the following flag:

python autograder.py -q q3 --no-graphics

Approximate Inference

Approximate inference is very trendy among ghost hunters this season. Next, you will implement a particle filtering algorithm for tracking a single ghost.

Question 4 (5 points) Implement all necessary methods for the ParticleFilter class in inference.py. When complete, you should be able to track ghosts nearly as effectively as with exact inference. This means that your agent should win oneHunt with a score greater than 100 at least 8 out of 10 times.

  python busters.py -k 1 -s -a inference=ParticleFilter

  python busters.py -p GreedyBustersAgent -l oneHunt -k 1 -n 10 -s -a inference=ParticleFilter

Hints:

• A particle (sample) is a ghost position in this inference problem.
• The belief cloud generated by a particle filter will look noisy compared to the one for exact inference.
• To debug, you may want to start with -g StationaryGhost.

To run the autograder for this question and visualize the output:

python autograder.py -q q4

So far, we have tracked each ghost independently, which works fine for the default RandomGhost or more advanced DirectionalGhost. However, the prized DispersingGhost chooses actions that avoid other ghosts. Since the ghosts' transition models are no longer independent, all ghosts must be tracked jointly in a dynamic Bayes net!

Since the ghosts move in sequence, the Bayes net has the following structure, where the hidden variables G represent ghost positions and the emission variables are the noisy distances to each ghost. This structure can be extended to more ghosts, but only two are shown below.

You will now implement a particle filter that tracks multiple ghosts simultaneously. Each particle will represent a tuple of ghost positions that is a sample of where all the ghosts are at the present time. The code is already set up to extract marginal distributions about each ghost from the joint inference algorithm you will create, so that belief clouds about individual ghosts can be displayed.

Question 5 (3 points) Complete the elapseTime method in JointParticleFilter in inference.py to resample each particle correctly for the Bayes net. The comments in the method provide instructions for helpful support functions. With only this part of the particle filter completed, you should be able to predict that ghosts will flee to the perimeter of the layout to avoid each other, though you won't know which ghost is in which corner (see image).

  python busters.py -s -a inference=MarginalInference -g DispersingGhost

Note that in this question, we will test both the elapseTime function in isolation, as well as the full implementation of the particle filter combining elapseTime and observe.

To run the autograder for this question and visualize the output:

python autograder.py -q q5

For the tests in this question we will sometimes use a ghost with random movements and other times we will use the GoSouthGhost. This ghost tends to move south so over time, and without any observations, Pacman's belief distribution should begin to focus around the bottom of the board. To see which ghost is used for each test case you can look in the .test files. As an example, you can run

python autograder.py -t test_cases/q5/2-ParticleElapse

and observe that the distribution becomes concentrated at the bottom of the board.

Question 6 (6 points) Complete the initializeParticles, getBeliefDistribution, and observeState methods in JointParticleFilter to weight and resample the whole list of particles based on new evidence. A correct implementation should also handle two special cases: (1) when all your particles receive zero weight based on the evidence, you should resample all particles from the prior to recover. (2) when a ghost is eaten, you should update all particles to place that ghost in its prison cell. The ghost with index i (starting at 1) is imprisoned in (2 * i - 1, 1). Further instructions appear in the comments of observeState. You should now effectively track dispersing ghosts. If correctly implemented, your agent should win oneHunt with a 10-game average score greater than 480.

  python busters.py -s -k 3 -a inference=MarginalInference -g DispersingGhost

  python busters.py -p GreedyBustersAgent -l oneHunt -s -k 3 -a inference=MarginalInference -g DispersingGhost -n 10 

To run the autograder for this question and visualize the output:

python autograder.py -q q6

Congratulations! Only one more project left. Don't forget about the course contest.