| Assigned: | Wednesday, March 20 |
| Due: | Thursday, April 4, 11:59pm |
| Points: | 700 |
The purpose of this assignment is to develop your ability to write a larger application involving arrays, structures and linked lists. It also introduces switchable tracing.
Read the entire assignment before you start working on it.
You will need to define 3 structure types 13 functions, including 'main'.
When faced with a large assignment near the end of a term, many students turn to plagiarism, especially if they have waited too long to start on the assignment.
Do not fall into that trap and submit a plagiarized assignment. Doing so will cost you points. Keep in mind that you must get an overall score of 50% or better on the programming assignments in order to pass this course, and that a plagiarized assignment gets a negative score. Submitting plagiarized or partially plagiarized work can cause you to fail this course.
In the past, many students have started too late on this assignment, and have submitted programs that did not compile or were only the beginnings of full programs. They got very low grades.
Remember that you must get an overall grade of at least 50% on the programming assignments to pass this course, and this assignment counts more than most.
After reading the assignment, you might think this assignment is impossibly difficult. It is not. If you just move ahead, creating one piece after another, you will find this simpler than you thought.
The refinement plan has 20 steps. Some are easier than others. You cannot read this assignment and do all 20 steps in 2 days. Set up a schedule. For example, set aside a day for each of the following tasks. (These tasks should not occupy an entire day. You have other things to do too. But don't try to pack them into two or three days. You will end up working inefficiently if you do that.)
That is just an example schedule. Make your schedule appropriate for you. But Start early. Resolve to finish early.
This assignment uses weighted graphs, as described in assignment 5.
Two vertices are said to be adjacent if there is an edge that connects them directly to one another. A given edge is incident on each of the vertices that it connects.
Think of the vertices of a weighted graph as towns and the edges as roads. The weight of an edge is the length of the road. One thing that you might like to know is how to get from one town to another by the shortest possible route. For example, in the following weighted graph, the shortest route from vertex 1 to vertex 5 is to go from 1 to 3 and then from 3 to 5, and the length of that route is 27. The total distance is the sum of the weights of the edges in the path.
For this assignment, the weights are real numbers (type double). All of the weights are required to be nonnegative. Edges of weight 0 are allowed.
Write a program that reads information about a weighted graph from the standard input. The input format starts with a description of a graph in the same format as for Assignment 5. After that are two vertex numbers: a start vertex vstart and an end vertex vend.
Your program should print, on the standard output,
For example, the input might look
like this.
5
1 2 9.0
1 3 12.0
2 4 18.0
2 3 6.0
2 5 20.0
3 5 15.0
0
1 5
That says that there are five vertices. There is an edge from
vertex 1 to vertex 2 with weight 9.0, an edge from vertex 1 to vertex 3
with weight 12.0, etc. The line containing only 0 indicates the end of the edges.
The start vertex vstart is 1, and the end vertex vend is 5.
The output for this input would be as follows.
There are 5 vertices and 6 edges.
The edges are as follows.
(1,3) weight 12.000
(1,2) weight 9.000
(2,5) weight 20.000
(2,3) weight 6.000
(2,4) weight 18.000
(3,5) weight 15.000
The shortest path from 1 to 5 has length 27.000 and is
1 -> 3 -> 5
The order of the edges is not important, but each edge should
be shown once.
As always, you are required to follow the design that is explained below.
In this assignment, you are allowed to add additional functions. You can also add parameters to required functions that are not mentioned in the design, provided that the roles of those parameters are clearly documented. Feel free to chooses sensible names for parameters. You are not required to use the parameter names that are used in this assignment.
A discrete event simulation performs a simulation of a collection of events, where each event occurs at a specified time. The simulation jumps from one event to the next. If one event occurs at 1:00 and the next occurs at 2:00, the simulation does not sit and wait for an hour. It just updates its internal clock to 2:00 and moves on.
As each event is encountered, it is processed. A key characteristic of discrete event simulations is that processing one event can cause more events to be created.
An example is a simulation of a bank with tellers and customers. There is a teller queue to hold tellers who are ready to serve customers and a customer queue that holds customers waiting to be served. There are five kinds of events.
A teller is ready to serve a customer. This event is processed by placing the teller into the teller queue. If the customer queue is not empty, it also schedules a "teller begins to serve the next customer" event at the current time.
Notice that processing one event can cause another event to be created.
A customer arrives. Processing a customer arrival adds the customer to the customer queue and also schedules another customer arrival event at some randomly chosen future time. That way, customers keep arriving. The distribution of random times determines how rapidly customers arrive.
If there is a teller in the teller queue, then a "teller begins to serve the next customer" event is scheduled at the current time.
A teller begins to serve the next customer. Processing this event removes the first customer from the customer queue and removes the first teller from the teller queue. It also schedules a "teller finishes serving a customer" event at some randomly chosen future time. The distribution of this random number controls how much time it takes to process a transaction.
A teller finishes serving a customer. Processing this event schedules a "teller is ready to serve a customer" event at the current time.
Stop the simulation. Processing this event stops the simulation. At the beginning of the simulation, one of these events is scheduled at a chosen time when the simulation should end.
Typically, when each event is processed, the simulation writes out the current simulation time and the event that is being performed, so that you can see what happened. The simulation also keeps track of some statistics, such as how long a customer waited for service on the average and how long the customer queue got.
It is easy to get the simulation started. If there are t tellers, then schedule t "teller is ready to serve a customer" events at time 0, the beginning of the simulation. Also schedule a "stop" event at some future time so that the simulation will not continue forever.
Here is a typical trace of a simulation. Notice that each trace line begins with the current time.
0.0 teller 1 is ready.
0.0 teller 2 is ready.
0.0 customer 1 arrives.
0.0 teller 1 begins to serve customer 1.
3.5 customer 2 arrives.
3.5 teller 2 begins to serve customer 2.
4.0 teller 1 finishes serving customer 1.
4.0 teller 1 is ready.
5.0 customer 3 arrives.
5.0 teller 1 begins to serve customer 3.
6.1 customer 4 arrives.
10.0 teller 2 finishes serving customer 2.
10.0 teller 2 is ready.
10.0 teller 2 begins to serve customer 4.
11.0 customer 5 arrives.
15.0 customer 6 arrives.
18.5 teller 2 finishes serving customer 4.
18.5 teller 2 is ready.
18.5 teller 2 begins to server customer 5.
end of simulation
Discrete event simulations are useful for implementing games. Each event is something that happens in the game, such as a character taking a step forward. Processing an event can cause new events to be sheduled, such as taking another step forward. It is easy to schedule the arrival of new characters or objects at specific times.
The simulation is performed by an event loop, that is roughly as follows.
loop
Get the chronologically next event. Call it E.
Process event E.
until the simulation has stopped
Dijkstra's algorithm finds shortest paths in weighted graphs, and it can be expressed as a discrete event simulation.
Instead of thinking of each edge as having a distance, think of the weight of an edge as a time, in seconds. Imagine sending signals between adjacent vertices. A signal from vertex u to vertex v along an edge of weight w takes w seconds to reach v. So, if such a signal is sent at time t, it arrives at time t + w.
In effect, the start vertex broadcasts a radio wave that travels along the edges. When the radio wave hits a vertex v, it bounces off v in all directions, traveling along all edges that are incident on v, in a way that is similar to the way real, physical waves propagate. The edge weights determine how fast the radio wave travels along each edge. It is easy to see that the time when the radio wave first reaches vertex v is proportional to v's distance from the start vertex.
During the simulation, the algorithm keeps two pieces of information about each vertex v: time(v) and sender(v).
Time(v) is the arrival time of the first signal to reach v. If no signal has reached v yet, then time(v) is −1.
Sender(v) is the vertex that sent the signal to v that was the first signal to reach v. If no signal has reached v, then sender(v) is −1.
There is just one kind of event, representing the arrival of a signal at vertex r at time t, where the signal was sent by vertex s. So there are three pieces of information in an event: s, r and t. Let's write that event in a more compact form as event(s, r, t), where s is the sender, r is the receiver and t is the arrival time.
Processing event(s, r, t) goes as follows.
If time(r) ≥ 0, then do nothing, since this is not the first signal to reach r. For the remaining cases, assume that time(r) < 0 when the signal arrives.
Set time(r) = t and sender(r) = s.
For each vertex v that is adjacent to r, where no signal has yet reached v, send a signal from r to v by scheduling event(r, v, t + w) where w is the weight of the edge from r to v. That is, this signal arrives at v just w seconds after the signal reaches r.
To get started, create an event that represents a signal arriving at the start vertex from a fictitious vertex 0 at time 0. After that, go into the event loop, which should keep going until a signal has reached the end vertex vend, that is, until time(vend) ≥ 0.
| Getting started |
|---|
|
1. Create a directory for assignment 7 and create
file dijkstra.cpp.
Copy the template into dijkstra.cpp. Edit the template with your information. Get files Makefile and dotest and put them in that directory. Add a comment to dijkstra.cpp telling its purpose. Say what its purpose is. Say what this program reads and what it writes. Include a description of the input format as well as an example input and output. |
This assignment uses a different graph representation from assignment 5. Here, we use the adjacency list representation.
| Types and information representation |
|---|
|
2. Type Edge
In dijkstra.cpp, create and document type Edge. An object of type Edge is a cell in an adjacency list. It represents an edge of the graph. Important note. Although each edge in the graph has no direction associated with it, the adjacency list representation involves splitting the edge into two directed edges, one going each direction. Think of splitting a bidirectional road into two lanes, one for each direction. We will talk about an edge directed from u to v. Because an edge is broken into two one-way parts, an undirected edge between u and v must occur in two adjacency lists. The adjacency list for vertex u contains an edge directed from u to v. The adjacency list for vertex v contains an edge directed from v to u. In the documentation for type Edge, make sure that you say that an object of type Edge is used as a cell in an adjacency list. The Edge structure stores:
Create a constructor that takes four parameters (two vertex numbers, a weight and a next pointer) and installs them into the four fields of an Edge. |
|
3. Type Vertex
In dijkstra.cpp, create and document type Vertex, where an object of type Vertex represents information about one vertex in a graph. A Vertex object that represents information about vertex number v has the following pieces of information.
Create a constructor for type Vertex that takes no parameters, sets the 'time' and 'sender' fields to −1, and sets the adjacency list pointer to NULL. |
|
4. Type Graph
In dijkstra.cpp, create and document type Graph. An object of type Graph represents a weighted graph and stores the following.
Create a contructor for type Graph that takes a number of vertices as a parameter. It should allocate an array for the vertices and set the number of edges to 0. Notice that it is not necessary to have a maximum number of vertices. You allocate the array after you know how many vertices there are. The vertices are numbered starting at 1. The sensible thing is not to use index 0 in the array. Pay attention to that. You will need to allocate an extra slot in the array to account for the unused slot. |
|
5. Draw an accurate picture of the representation of a small
sample graph.
Skipping this step is a big mistake. In the description of Dijkstra's algorithm, I have used time(v) for the time stored with vertex number v. But that is not how it is referred to in the C++ program. If you have Graph g, how can you get the time stored for vertex number 1 in g? How can you get the time stored for vertex number v? Look at your diagram. |
| Tracing |
|---|
|
6. Setting up tracing
You are required to put switchable tracing in your program. For now, just get ready for tracing. In dijkstra.cpp, create a global variable that holds 0 if tracing is not requested and holds 1 if tracing is requested. This is one of the few places where you are allowed to use a global variable in this course. Just create the variable near the beginning of your module, outside of any functions. The program should look at the command line. If the command line contains -t, then tracing should be turned on. If not, tracing should be turned off. When tracing is turned off, there must be no tracing. The command line is passed to main when the program is started. You will find the following heading in the template. int main(int argc, char* argv[])Parameter argc tells how many parts the command line has, and argv[i] is the i-th part (a null-terminated string). For example, if the command is ./dijkstra -tthen argc is 2, argv[0] is "./dijkstra" and argv[1] is "-t". In dijkstra.cpp, write a function that takes parameters argc and argv that are passed to main and that sets your global trace variable either to 0 or to 1, depending on whether the command line contains "-t". Be careful not to look beyond the end of array argv. If some option other than -t is provided,
then your function must write a line
exit(1);Include <cstdlib> to use exit. Watch out when comparing strings. If A and B are null-terminated strings, then expression A == B is true if A and B are the same memory address, since a null-terminated string is a pointer. Use strcmp to compare strings. |
| Input and echoing |
|---|
|
7. Reading the Graph
In dijkstra.cpp, document and define a function to read a graph. You can use your function from assignment 5 as a rough starting point, but be careful to notice that the graph representation has changed. Do not change the graph representation to make the old graph reader work unchanged. Use the adjacency list representation. Do not use duplicate representations. Only store the graph once, using the adjacency list representation. Make this function only read the graph. Do not give it any additional responsibilities. In particular, it should not write anything, except possibly traces. You will want helper functions to avoid code duplication and to avoid making readGraph too long. ReadGraph needs to be able to insert an edge in a graph. That involves inserting an edge in two adjacency lists. That sounds like two functions to me. |
|
8. Writing a Graph
In dijkstra.cpp, document and define a function to print a graph. Again, you can use your function from assignment 5 as a starting point, but make sure to convert it to the new graph representation. Make this function only write the graph. Do not give it any additional responsibilities. Do not write a label for the graph. For example, do not say that it is the "input graph". Just show the information in the graph. It is the caller's responsibility to say what this graph is. If tracing is turned on then show each undirected edge twice, once for each direction. If tracing is turned off, then show each undirected edge only once. That is easy to arrange. When looking at an edge that is directed from u to v, only show it if u < v. |
|
9. Testing
Test reading and echoing the graph, both with tracing turned on and turned off. Do not move on until you are satisfied that this much works. An automated tester is available. You can use it for all tests. |
| Events |
|---|
|
10. Type Event
Create file event.h. In event.h, create and document type Event, where an object of type Event represents the arrival of a signal at a vertex. An event stores: a sender (a vertex number), a receiver (a vertex number) and a time at which the signal arrives. The time is an absolute time since the beginning of the simulation. Include a sensible constructor for Event to make creating events easier. File event.h should look as follows, with the line calling for documentation of type Event replaced by actual documentation and the body of type Event added.
#ifndef EVENT_H
#define EVENT_H
(documentation for type Event)
struct Event
{
…
};
#endif
The #ifndef, #define and #endif ensure that file event.h will only be read once by the compiler, even if it is included more than once. |
|
11. The Event Queue
Notice that the operations needed for events are exactly the ones supported by a priority queue. You need to get the next event in chronological order. That is easy to arrange by making the priority of an event be its time. Let's refer to a priority queue holding events as the event queue. Add the following type definition to dijkstra.cpp. typedef PriorityQueue EventQueueUse type EventQueue for the type of the event queue. Copy files pqueue.h and pqueue.cpp from assignment 6 into your directory for assignment 7. Modify the definition of ItemType in pqueue.h to say typedef Event* ItemType; File pqueue.h must include "event.h" so that it can use type Event. That is, add directive #include "event.h"to pqueue.h before the definition of type ItemType. Allocate all events in the heap. After removing an event from the event queue, delete it when you are finished looking at it. Note 1. File dijkstra.cpp must only use the things in the priority queue module that the priority queue module exports. You are not allowed to make use of the fact that a priority queue is represented as a linked list. You are not allowed to make direct use of a value of type PQCell or PQCell*. Stick to the interface. You will be shocked by the number of points that you lose if you violate the priority queue interface. Don't do it. See the priority queue interface. Note 2. The priority queue module does not export types ItemType or PriorityType. Do not use those types in dijkstra.cpp. Use type Event*, not ItemType. Note 3. When passing the event queue to a function, always pass it by reference or by pointer. There must only be one copy of the event queue. |
|
12. Sending a single signal
In dijkstra.cpp, document and define a function that takes two vertex numbers s and r, a time t and an event queue q. It should send a signal from s to r, arriving at time t, by inserting an event into q. That is all it should do. Don't add other duties. |
|
13. Tracing
In dijkstra.cpp, add tracing to your function that sends a signal. When a signal is sent, the program should say that it is sending a signal. Start the trace with the time at which the signal is sent, as shown in the sample trace above. Also show the sender, the receiver and the signals' arrival time. Make the trace succinct, but make it clear that it is telling about a signal being sent. |
|
14. Propagating Signals
In dijkstra.cpp, document and define a function that takes a graph g, a vertex number v and an event queue q. It should send a signal from v to every vertex that is adjacent to v in g, excluding those that have already received a signal. This function must use the function from step 12 to send each signal. That is all it should do. Don't add other duties. This function should not look at every vertex in graph g. How can it find every vertex that is adjacent to v without looking at every vertex in g? |
|
15. Installing information in a vertex
In dijkstra.cpp, document and define a function that takes a graph g, a vertex number v, a vertex number s and a time t, and stores sender s and time (or distance) t into the Vertex structure that represents vertex number v in g. |
|
16. Processing an Event
In dijkstra.cpp, document and define a function that takes a graph g, an event queue q and an event E, and that processes event E. Note that this function processes a single given event. That is all it does. Don't add any other duties. This function does not get an event out of q. But it might need to add new events to q. Remember that the arrival of a signal at a vertex that has already received a signal should be ignored. Assuming that this is the first signal to reach r, processing an event involves installing information about r and sending a signal to r to each adjacent vertex that has not already received a signal. Use your functions from steps 14 and 15. |
|
17. Tracing
Add tracing to the functions that you wrote in steps 15 and 16. Be sure that each trace line is succinct, begins with the current time and provides enough information to make it clear exactly what is happening in the simulation. Step 15 shows the information that is being installed, and which vertex it is being installed in. Step 16 shows that a signal has arrived, and provides all needed information about the signal. The trace should only be shown if tracing is turned on. |
| Finding Shortest Paths | ||
|---|---|---|
|
18. Running Dijkstra's Algorithm
In dijkstra.cpp, document and define a function that performs Dikjstra's algorithm. It starts by sending a signal to the start vertex that comes from ficticious vertex 0 and that arrives at time 0. (Do not add vertex 0 to the graph! There is no such vertex.) Then it goes into the event loop. It keeps getting and processing events until a time(vend) ≥ 0. Make sure that the event loop is clear and short. It should look like the event loop outlined above. Be sure to get and event before processing it. | ||
|
19. Showing the Path
In dijkstra.cpp, document and define a function that takes a graph g and two vertex numbers vstart and vend. It should be called when the simulation is finished, and should show the path from vstart to vend. It must not do anything but that. Using the information in g, it is easy to follow a path from end vertex vend back to start vertex vstart.
But print that chain out backwards, so that it goes from vstart to vend instead of from vend to vstart. The easiest way to do that is to use recursion. To print a path backwards, starting at vertex u, print the path starting at sender(u) backwards, then print u. Of course, in the special case where u is the start vertex vstart, just print vstart. For arrows, write -> between vertex numbers. | ||
|
20. Show the shortest distance and path
In dijkstra.cpp, modify 'main' so that it shows the shortest distance from the start vertex to the end vertex and also shows the path from the start vertex to the end vertex. Be sure that it is clear, in the output, what is being shown. Don't write out raw information and force the reader to guess what it is. The shortest distance from start vertex vstart to the end vertex vend is time(vend). | ||
|
21. Submit your work.
| ||
If you haven't already, get files Makefile and dotest and put them into the directory that holds assignment 7. Then you can use the following commands.
As always, you are required to follow the design discussed here. Do not try to invent your own algorithm. Follow the coding standards.
If you follow this advice, you should find this program much easier than you originally thought it would be. If you ignore this advice, then you will find yourself stuck in the swamp and this program will be even harder than you originally thought.
This assignment is larger than prior assignments. In the past, students have become overwhelmed and have stopped paying attention to basics. But the basics are even more important as the size of a program increases.
Do not relapse into novice software design methods!
Start early. If you start late, you will end up with a nothing but junk.
Write clear, concise and precise contracts. Pay attention to that. Write a contract before you start to work on a function. Then make the function do exactly what the contract says it does.
It is easy to write contracts. The assignment tells you what each function is supposed to do. It hands you a contract. Just edit it to make sense in a program. For example, a contract should not begin "Write a function that …". It should not describe the function heading, since that is visible.
Avoid complicated algorithms. Keep it simple. Function bodies should be easy to read and understand. Avoid writing a long expression more than once by storing its value in a variable.
Keep your program organized, well-indented, documented and easy to read while you write it, not as an afterthought.
Follow the refinement plan. Write a little bit and test that. Do not try to write the entire program before testing any of it.
Do not ignore compiler warnings. If you do not understand what a warning means, ask about it.
Each function can have at most one loop in its body. Do not use one loop to simulate two nested loops by manipulating the loop parameters.
Be sure to initialize variables before you use them. In the past, this has been a source of mistakes for students.
Be sure to distinguish between vertices and edges. Do not use numEdges where you should have used numVertices. In the past, this has been a common source of mistakes.
In the past, some students have, at some places in dijkstra.cpp, used type int for an edge weight or for a time/distance value. That causes all distances to be forced to integers, which means that the results are incorrect when the correct distance is not an integer. Make sure that all time/distance values have type double. If all distances are integers in the all of the tests, then you have made this mistake.
Keep function definitions short. A function body must have no more than 16 noncomment lines.
Do not use global variables other than one to control tracing, regardless of how appealing you find them.
A function body must not change the value of a call-by-value parameter.
Remember to delete events after processing them.
To turn in your work, log into the Linux system, change your
directory for the one for assignment 7,
use the following command.
~abrahamsonk/2530/bin/submit 7 pqueue.cpp pqueue.h event.h dijkstra.cpp
After submitting, you should receive confirmation that the
submission was successful. If you do not receive confirmation,
assume that the submission did not work.
Command
~abrahamsonk/2530/bin/submit 7
will show you what you have submitted for
assignment 7.
You can do repeated submissions. New submissions will replace old ones.
Late submissions will be accepted for 24 hours after the due date. If you miss a late submission deadline by a microsecond, your work will not be accepted.
To ask a question about your program, first submit it,
but use assignment name q7. For example, use command
~abrahamsonk/2530/bin/submit q7 pqueue.cpp pqueue.h event.h dijkstra.cpp
Include a data file if appropriate.
Then send me an email with your question. Do not expect
me to read your mind. Tell me what your questions are.
I will look at the files that you have submitted as q7.
If you have another question later, resubmit your new file
as assignment q7.