Project 2 Heap. Out: March 16 In: March Mechanics: Installing, Handing In, Demos, and Location of Documentation

Transcription

1 Project 2 Heap Out: March 16 In: 1 Mechanics: Installing, Handing In, Demos, and Location of Documentation 1. To install, type cs016 install heap into a shell. The script will create the appropriate directories and deposit the stencil code files into them. 2. To compile your code, type make in your heap directory. To run your code, type make run in the same directory. 3. To hand in your project, go to the directory you wish to hand in, and type cs016_handin heap into a shell. Before using this script, make sure that you are in the correct directory! It will hand in the entire current directory, and we don t really want all of your files just the ones pertinent to this project. (So be sure to save your README and any other files you need to hand in in the same directory as your code.) 4. To run a demo of this project, type cs016_rundemo heap into a shell. 5. The Heap documentation can be found here: This is also linked off of the class website on the Assignments page. 2 Introduction 2.1 What You ll Do in this Project In this assignment you will implement a priority queue, using a heap as the underlying data structure. Your heap implementation will be based on a version of a link-based binary tree, which you will modify. 2.2 Purpose The purpose of this assignment is to help you: Understand a link-based binary tree, and its use in implementing a heap-based priority queue. Identify the advantages of the interface provided by a complete binary tree. March 18,

2 Gain experience in implementing and using a heap and a priority queue. Extend your understanding of Positions and how they differ from Entries. Learn about using comparators. Increase your familiarity with throwing exceptions and using try/catch blocks. Practice coding efficiently to meet specific runtime requirements. 3 Overview of Your Tasks We have provided stencil code for the following classes: MyLinkedHeapTree<E>, MyHeap<K,V>, and MyHeapEntry<K,V>. Your job will be to fill in all three classes, which are described below: 1. MyLinkedHeapTree<E>: This class is an implementation of the CompleteBinaryTree<E> interface (from the net.datastructures 4.0 (NDS4) package), and extends the NDS4 LinkedBinaryTree<E> data structure. It will serve as the modified link-based binary tree on top of which your heap will be constructed. Since much of the binary tree functionality of this class is inherited from LinkedBinaryTree<E>, you should read the documentation for this class carefully in order to understand how the class you are extending operates. Note that the generic E represents the type of the elements that the tree is capable of holding. 2. MyHeap<K,V>: This class is an implementation of the interface AdaptablePriorityQueue<K,V>, from the NDS4 package. This class represents the heap itself, relying on an underlying complete binary tree (your MyLinkedHeapTree<E>) to hold its data. The generics K and V represent the types of the keys and values for the key/value pair of each element in the heap. There is an important distinction between normal and adaptable priority queues: adaptable priority queues have the ability to replace the key or value of an entry after it has been added, and additionally have the option of removing from the priority queue an item that is not at the top of the heap. 3. MyHeapEntry<K,V>: This class is an implementation of the Entry<K,V> interface, and represents an element that will be stored in the heap. Such elements of the heap consist of mutable key/value pairs. While classes that hold such pairs are available within NDS4, your implementation will require several additional accessors and mutators, which will allow you to perform all of the actions associated with an adaptable PQ. Think about the relationship between your Entry implementation and the Positions (or nodes, as you may want to think of them), which will hold each element in the binary tree. March 18,

3 3.1 Requirements 1. Fill in the three classes listed above: MyLinkedHeapTree<E>, MyHeap<K,V>, MyHeapEntry<K,V>. The methods you need to fill in for each class are specified in the stencil code. 2. The methods you write for this project must adhere to strict runtime requirements. These requirements are listed in the Javadocs (more on this in Section 3.10), as well as in the method comments in the stencil code. Running time is a significant portion of your grade, so don t gloss over this requirement! 3. You will need to throw a number of exceptions for this project, each of which is welldefined in the stencil code, and below. Every method that requires an exception is specified in the stencil code, so you do not need to come up with any other times when these exceptions should be thrown. You will, however, need to identify (within a given method) the conditions that will cause a problem which necessitates throwing an exception, and write code to check whether these conditions exist. Here is a list of the exceptions: IllegalStateException: An exception from the java.lang package intended to be thrown when a method has been invoked at an illegal or inappropriate time. In this project, we are using it to signal that a priority queue cannot change the comparator it is using unless it is currently empty. This exception is thrown in MyHeap.setComparator(...). EmptyPriorityQueueException: An exception from NDS4 that indicates that a priority queue cannot fulfill the requested operation because it is empty. This exception is thrown in MyHeap.min() and MyHeap.removeMin() as you would expect, since you can t look at/remove elements from an empty heap. InvalidKeyException: An exception from NDS4 indicating that the key which is being handled has been determined to be invalid. The Comparator in use is the only object that can determine a key s validity. The Comparator has a compare(...) method which can compare two keys. You can use this method to test whether a key is valid: if you pass an invalid key as an argument to your Comparator, it will throw a ClassCastException. Thus, you can use the Comparator to compare a key to itself; if the Comparator throws an exception, you should catch it, and throw your own exception the InvalidKeyException. Don t forget that a null key is also invalid. MyHeap.insert() is the only method with a signature explicity throwing this exception, but you may find that it makes sense to also throw it from MyHeap.replaceKey(...). InvalidEntryException: An exception from NDS4 that is thrown when the Entry<K,V> that is being handled is invalid. For example, an Entry<K,V> that is null would be invalid, as would an Entry<K,V> that is not of the type being used in your heap. (Think about or research ways that you might detect March 18,

4 this.) If you find yourself needing to cast MyHeapEntry<K,V> objects to access additional methods, a helper method in MyHeap<K,V> that first checks validity might be useful to write. This exception is thrown in MyHeap.remove(...), MyHeap.replaceKey(), and MyHeap.replaceValue(...); it should be thrown if you give any of those three methods an invalid Entry<K,V> as a parameter. EmptyTreeException: An exception from NDS4 indicating that the tree cannot fulfill the requested operation because it is empty. Note that this is very similar to the EmptyPriorityQueueException which was described above. In fact, you should never see this exception thrown from your heap, because EmptyPriorityQueueException should intercept the same condition first. However, you still need to throw this exception from your MyLinkedHeapTree.remove() method. This may seem silly, but it is good coding practice to make your code extensible; that is, you know that in this project you are using your MyLinkedHeapTree underneath your MyHeap class, and thus will catch this condition with an EmptyPriorityQueueException, but including this exception will ensure that your CompleteBinaryTree<E> implementation is usable in other contexts in which you may not necessarily catch an empty priority queue condition elsewhere in the code. 4. We are providing you with a visualizer to help you test and debug your code; this visualizer is described in Section 5. You will need to correctly fill in the gettree() and size() methods in the MyHeap class in order for the visualizer to work properly; this is discussed more thoroughly in Section 5 of this handout. 3.2 README The README for this project has some specific points that you need to address. Make a text file entitled README, which should be saved in the same directory as is your project; it will be handed in along with your code. (You can create a text file by opening it in kate or any other editor just cd into the directory in which you want to save the README, then type, for example, kate README & to create the file.) Each of the questions should be answered in about 1-4 lines, unless otherwise stated. Discuss the design choices you made in your MyHeapEntry<K,V> implementation. If you defined your own methods, explain why you chose to add them. Explain how you implemented a CompleteBinaryTree<E>; in particular, you should talk about the connection to LinkedBinaryTree<E>, which should have been your starting point. Describe the method you used to keep track of where to add and remove nodes in the tree. Please characterize the running time of of the MyLinkedHeapTree<E> methods. March 18,

5 Include anything else particularly notable about your implementation. Don t forget to talk about any bugs you are aware of in your code. (And of course, you should thoroughly test your code to find any bugs that exist.) The CS16 staff uses automated testing utilities for Heap that help to assess the functionality of your program; this means that if there is a bug in your code, we will find it. If you find a bug yourself and just can t get it fixed before turning in your project, make sure to let us know in your README you will be rewarded! Tell us what goes wrong, what functionality is affected, and roughly where you think the problem is, and we ll give you some points back. You won t get full credit, but you will lose fewer points than you would if you either pretended the bug wasn t there, or didn t bother to find it in the first place. 4 Reading The in-class lecture slides for Heap and Heap-Sort, which can be found here: 12.pdf. This is also linked off of the class website on the Assignments page. A reference for Adaptable Priority Queues: *Note: You need to have a solid grasp of the information in both of these readings before you begin coding, so make sure that you read and understand them!! If you are confused about anything in either of these readings, go see a TA before you start your project. 5 Visualizer We are providing you with a visualizer that will graphically display your heap. The top portion of the visualizer will display your tree, with a circle representing a node of the tree (so, an entry in your heap) and a black line conneting two nodes representing an edge of the tree. Nodes will display a number and a string of letters; the number in a node represents that heap entry s key and the string in a node represents that heap entry s value. The visualizer will display parent/child relationships by making parents appear higher in the window than their children do. As your tree grows, the scrollable window will shift to accommodate the extra branches. You can select a node in the visualizer by clicking on it; selected nodes are colored pink, while un-selected nodes are colored blue. You can use the visualizer to create heaps with (key, value) pairs stored at the nodes, where keys are numbers and values are combinations of letters. You will have the option to either create entries with random keys and/or values, or to create entries with keys/values that you specify. When you click certain buttons on the visualizer, it will display information to you in a text box at the bottom of the screen; for example, if you click size(), the March 18,

6 size of your heap will be displayed in the box. You can clear the text box by clicking the Clear Text Area button on the visualizer. The buttons are self-explanatory, but will also be discussed in more detail below. In order for the following functionality of the visualizer to work, you will need to correctly implement the specific methods in the MyHeap class which correspond to the action in the visualizer. For example, in order to be able to check whether the graphical heap is empty, you need to properly implement the isempty() method. check the size of the heap: click on the size() button (requires size()) check whether the heap is empty: click on the isempty() button (requires isempty()) insert a new node into the heap: choose whether you want a random, invalid, or specific key and/or value to be generated for your new node; if you want a specific key and/or value, input appropriate values into the text boxes in the third row of the visualizer. (Note that keys must be integers between 0 and 99, inclusive, and that values should be strings of 1, 2, or 3 letters; the visualizer will not let you input valid keys or values.) If you want a random key or value, check the appropriate box(es) and then click the Make Random Item button. If you want an invalid item, click the Make Invalid Item button. This will create a K,V pair with an invalid key, but a valid value of INV. The visualizer has no way of making a K,V pair with an invalid value, so you can t use the visualizer to trigger an InvalidEntryException. (Creating an entry with an invalid key constitutes an invalid entry, but in this case the InvalidKeyException will be thrown first, and the call will terminate before throwing an InvalidEntryException.) Once you have generated your key and value, click on the insert(key, val) button to make a node with the values currently in the text boxes (requires insert(k,v)) remove the minimum-key entry from the heap: click on the removemin() button (requires removemin()) highlight the minimum of the heap: click on the min() button to print the minimum element to the text window and to highlight the minimum node in pink in your graphical window (requires min()) remove a specific entry from the heap: click on the node in the visualizer window that you want to remove (it should turn pink to indicate that it has been selected), then click the remove(entry) button (requires remove(entry<k,v>)) replace the key of an entry in the heap: click on the node in the visualizer window whose key you want to replace (it should turn pink to indicate that it has been selected), then click the replacekey(entry, key) button (requires replacekey(entry<k,v>,k)) March 18,

7 replace the value of an entry in the heap: click on the node in the visualizer window whose value you want to replace (it should turn pink to indicate that it has been selected), then click the replacevalue(entry, val) button (requires replacevalue(entry(<k,v>), V)) deselect a node: click on the background inside the graphical window of the visualizer (no methods required) In order for the visualizer to function, you will need to correctly implement the following two methods in the MyHeap class: gettree(): necessary in order for the visualizer to access the data in your heap and display it graphically size(): necessary in order to correctly size the visualizer window You should note that the gettree() method breaks encapsulation by allowing the binary tree underlying your heap to be publicly exposed. Violating encapsulation is generally bad design practice, but is necessary in this case in order for our visualizer to know what entries your heap is holding. 6 Application: Fishfood We are also providing you with a more interesting application for your heap: Fishfood. Fishfood animates a race between an octopus and a single flagellum: it generates a random graph of vertices and edges, and then has the two organisms follow specific paths through the graph. Dijkstra s shortest-path-finding algorithm (which you will be learning about in class soon!) uses a min-priority-queue as its underlying data structure. Fishfood uses Dijkstra s algorithm to calculate the optimal (shortest) path from the start node to the finish node in the graph using the TAs version of Heap, and the octopus follows that path. Fishfood also runs Dikjstra s algorithm using your heap as this min-priority-queue, and the single flagellum will follow the path generated by that run of Dijkstra s. If your heap is implemented correctly, the path generated using your heap will be the same as the path generated by the TAs heap. Nodes in the graph are colored yellow, with the start node in pale green and the end node in orange. If your path matches the TAs path completely, optimal path nodes will be shown in dark green. If your path differs from the TAs path, your path will be given in red, the TAs path will be given in blue, and the overlap between your path and the TAs path will be given in purple. To start the race, click the Start button. (You can restart a race at any time.) You can also hit the Reset button to generate a new graph on which to race your octopus and March 18,

8 flagellum. *Note: if you quit Fishfood, it will also close the visualizer, so don t run Fishfood and close it if you don t want to lose whatever you have in your visualizer. (You can, however, work in the visualizer while Fishfood is open.) 7 Design You will construct your heap-based priority queue on top of a link-based binary tree. You should design the program in its entirety before you even think about starting to code it s no fun to be forced to start over after you ve written a significant amount of code because you did not put enough thought into your design! Feel free to come to TA hours if you have questions about your design. When working through the design process, here are a number of things that you should consider: Positions vs. Entries: Before you begin thinking about how to implement your classes, you need to have a solid understanding of the distinction between Positions and Entries in the data structure. A Position is a tree node. It is a container for an Entry: once created, a Position stays in the same place in the tree until it is deleted. However, Entries can be moved among Positions freely. Notice that the NDS4 Position<E> interface contains a generic, E, which is the type of the element that a Position contains. Entry Key/Value Pairs: So what elements do the Positions of your tree contain? They contain references to other Positions (specifically, the Positions of the children and parent) and an Entry<K,V>. Entries contain a key/value pair (hence, K and V) and are the data-containing elements of your heap. For example, the entries used in the visualizer consist of an integer key between 1 and 99 and a string value of three characters. Positions are tied down in a single location on the heap because it s too much work to re-link parent and child nodes every time you want to up-heap or down-heap. Instead, the Entries contained within the Positions move, swapping themselves between Postions when called for in heap-order restoration. It s a subtle distinction, so re-examine the adaptable prioirty queue reference and see a TA if you re still confused. Extra MyHeap Methods: In this project, we ask you to write the class MyHeapEntry<K,V>. This task requires some thinking: you cannot simply implement the two accessor methods getkey() and getvalue() that are defined by the Entry<K,V> interface and be done with it. Think about the replacekey(...) and replacevalue(...) methods of your MyHeap class. It doesn t make sense to simply instantiate a new Entry<K,V> every time you need to alter the contents of an existing one. Perhaps some mutator, or set, methods would be helpful? More substantially, you need to think about the Entry s relationship with the Position holding March 18,

9 it. Why does an Entry need to know its location in the heap? What should happen when an Entry s key is changed? See the description of location-aware entry in the adaptable priority queue reference. First and Last Nodes: One of your major tasks in this project is to adapt the NDS4 class LinkedBinaryTree<E> so that it represents a complete binary tree your MyLinkedHeapTree class. Doing so means ensuring that the tree always knows where its last node is (the node to be moved to a different position within the tree in case of a remove() call), and where the next node to be inserted should go. This is far more complicated than it may first appear, as not only are the two nodes not necessarily close to each other, but the stringent running time requirements of the methods in MyHeap<K,V> depend on the MyLinkedHeapTree s add(...) and remove() methods being implemented efficiently. This means that the methods you implement in the MyLinkedHeapTree<E> must run in (amortized) O(1) time! More on this in the next two bullets... Node-Tracking Algorithms: We re not explicity going to tell you how to implement your node-tracking in MyLinkedHeapTree<E>, so you have some options. The in-class slides on Heaps and Heap-Sort, as well as the adaptable priority queue reference, contain the sketch of an algorithm for finding the parent under which to insert new nodes given the current last node. Note that the algorithm sketch does not handle all insertion cases in particular, you should think about what to do when you ve inserted a node in the right-most position in a given level of a tree. This algorithm runs in worst-case time proportional to the height of the tree (i.e., O(nlogn)), but over a series of insertions and deletions, its amortized running time is in fact O(1). Put plainly, this means that, yes, you can use it in your MyLinkedHeapTree<E>. The question now becomes, how do I track the last node as I insert and remove elements? A fundamental data structure may help you with this... perhaps something in which you can push and pop nodes? Alternative Node-Tracking : There are, in fact, more efficient (and more elegant) ways to keep track of your last node and your insertion parent node than the algorithm we ve hinted at above. (In fact, you can implement a clever algorithm that will run in worst-case rather than amortized O(1) time!) Think about what types of data structures might be useful here, and remember that your choice of implementation is completely up to you. All the classes of the NDS4 package are at your disposal, and anything that will make the add(...) and remove() methods of MyLinkedHeapTree run in O(1) time and with reasonable space usage is acceptable. Feel free to do a sanity check with a TA if you d like to try a more ambituous method. Creativity will be rewarded! (Hint: the Deque variety of a standard queue in NDS4 may be helpful for one approach to solving the problem.) Understanding MyHeap: This class will contain the majority of the code you write, but writing that code does not have to be too difficult. In Section 3.1, we March 18,

10 discussed the distinction between an adaptable priority queue (which you are implementing) and a normal priority queue (which the Goodrich and Tamassia textbook explores in depth, including code samples.) If you re confused by the big picture idea of adaptable priority queues, we encourage you to do the reading in the book; you won t be able to just copy the code, but doing the reading will certainly get you started on modifying the heap for adaptable methods. 8 Testing We are not requiring you to turn in test cases for this project. However, that does not mean that you don t have to test your project! While you don t have to explicitly write up a file of test cases, we want you to think about testing just as thoroughly as you would otherwise this means that you need to come up with a list of all functionality that needs to be tested, and figure out all of the edge cases, etc., that you need to test in order to be sure that each specific part of the functionality was implemented correctly. The visualizer will be a very helpful debugging tool once you start going through your functionality checklist! 9 What to Hand In 1. Code for the classes MyHeap, MyHeapEntry, and MyLinkedHeapTree. 2. A README as described in Section Support Code Instead of providing you with a list of method signatures and running time requirements for the classes you will implement in this project, we are asking you to examine the Javadocs for Heap. (The documentation is linked off of the class website on the Assignments page; the URL is also given in Section 1 of this handout.) These documents contain all of the information you ll need, so if you haven t used Javadocs before, now is a great time to learn. (And it s a valuable skill to have! Being able to look up this information yourself will make you a more independent programmer, which will be especially important as you move on to upper-level CS classes.) If you re new to Javadocs, feel free to drop by TA hours, and we ll get you started. Javadocs are highly self-explanatory and are quite useful for linking together information such as the classes that implement certain interfaces, what parameters need to be passed to methods, the return type and exception-throwing signature of a method, etc. The documentation is automatically generated from comments in the stencil code, so you ll have a ready reference in the Java files as you write your code as well. We re expecting you to concentrate on the classes in the heap package (rather than the support.heap package) while browsing the Javadocs, as the former is where the essential March 18,

11 information is. The latter is simply the classes we use to launch the visualizer, so it probably won t be especially useful for you to go through the support.heap documentation but feel free to do so if you re curious! March 18,