Project 2 Fall 2008

CMSC 201
Programming Project Two

Oil Spill Simulation

Out: Monday 10/6/08
Due: Before 11:59 PM, Sunday 10/19/08

The design document for this project, design2.txt ,
is due: Before 11:59, Sunday 10/12/08

Objective

The objective of this assignment is to give you practice with project and function design. It will also give you an opportunity to work with random numbers, two-dimensional arrays, passing arrays to functions, and using separate compilation.

Description of the Oil Spill and Simulation

Your program will simulate an oil spill involving 8,000 gallons of crude oil and the movement of that oil over time under certain conditions. You will run the simulation over a 225 square mile area, a 15 mile X 15 mile square.

You must keep track of the number of gallons of oil that are present on the surface of each square mile. The number of gallons in a particular square-mile location will vary over time due to environmental factors, i.e. the tides, wind, etc. For this simulation we will be concerned only with the effects of the wind on the oil spill. We will assume a constant wind velocity so that you do not need to consider any fluctuations in your calculations.

If the wind is from the west, then the oil in a particular location will be pushed primarily to the east, affecting the neighboring areas to the north, north-east, east, south-east and south. Some portion of the oil will stay within the original square-mile area. Obviously the area to the east will get the largest influx of oil. Over time, the spill will shift significantly to the east.

The integer time interval value is the number of time intervals that should pass between displaying the values for each square-mile area. The total time is the amount of time for the entire simulation.

The wind direction is to be chosen randomly, by getting a random number between 1 and 4, where 1 is West, 2 is North, 3 is East and 4 is South. You should use a call to time() to seed the random number generator. Feel free to use the SetRandomSeed()and GetRandomNumber() functions from the Cards example in Lecture 5.

More details

To begin, you will need to read in the data from the data file you wish to use. We're providing two files: oilspill515.dat and oilspill17.dat. The files include the viewing time interval (step) and the total time of the simulation, followed by 225 integer values separated by whitespace that represent the original number of gallons per square mile area. You will use unix redirection to read in the contents of this file. There will be little difference in the way you write your program to do the input. You will use calls to the function scanf() as you normally would to read in integers, however, since the user won't be entering the data (it will be the contents of a file instead), there is no need to prompt the user for the values. To use unix redirection you will run your program like this
a.out < oilspill515.dat
The file oilspill515.dat shown below is just one of many files that we may use to test your program. We have files with different time intervals, total times, and different original concentrations of oil that may be used to test your program. So oilspill515.dat and oilspill17.dat are just sample data files provided for your use. You may assume that none of the integers found in any of the files used for testing your program will be larger than 3 digits. We guarantee that there are exactly 227 non-negative integers in each of the test files.
Here is the contents of oilspill515.dat:

You will be reading the 225 initial oil values found in the file into a two-dimensional array. This array will then hold the original number of gallons found in each square-mile area at the time of the spill.
For each unit of time, the amount of oil in each square-mile area must be recalculated. We will chose the wind direction W for the explanation of the calculations. The original amount of oil in the square will be reduced by 50%, because that much will be pushed by the wind into some of it's neighboring squares (mostly easterly). At the same time, however, more oil will be pushed into the area from some of its more westerly neighbors.
For a west wind, the square and its surrounding squares will be affected as follows:
If you view the results of the simulation after each unit of time, the movement of the oil is less noticeable than if you wait for several time units before viewing. Since the user needs to see and interpret the results of the simulation, we have chosen a time interval of 5 (5 time units will pass before you show him the next results) and a total time of 15 (how long a period of time to run the simulation).
Hints
- Be aware that the diagrams of oil movement shown above are the simplest case, where there was no oil originally in any of the neighboring squares. Each square mile that contains oil will lose oil in the fashion indicated, but each square mile may also have an influx of oil from its neighboring squares.
- Since every square may be altered by its neighbors, and you must use the original values of each square for the calculations, you cannot just move through the array making changes as you go. This would give erroneous results. A second two-dimensional array needs to be made that will hold the new amounts of oil that are being calculated for each square, while the original array is still intact to provide the values needed for the calculations.

A Sample Run

linux1[102] a.out < oilspill515.dat Time interval : 5 Total time : 15 Wind direction : From the West Time: 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 500 500 500 500 0 0 0 0 0 0 0 0 0 0 0 500 500 500 500 0 0 0 0 0 0 0 0 0 0 0 500 500 500 500 0 0 0 0 0 0 0 0 0 0 0 500 500 500 500 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Time: 5 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 6 8 7 4 1 0 0 0 0 0 0 0 1 10 28 43 47 39 20 5 0 0 0 0 0 0 0 9 49 108 149 153 114 56 15 1 0 0 0 0 0 0 28 116 229 303 299 213 100 26 3 0 0 0 0 0 0 36 154 305 402 396 282 130 34 3 0 0 0 0 0 0 36 154 305 402 396 282 130 34 3 0 0 0 0 0 0 28 116 229 303 299 213 100 26 3 0 0 0 0 0 0 9 49 108 149 153 114 56 15 1 0 0 0 0 0 0 1 10 28 43 47 39 20 5 0 0 0 0 0 0 0 0 0 3 6 8 7 4 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Time: 10 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 2 5 6 5 3 0 0 0 0 0 0 0 0 1 7 15 23 26 21 13 0 0 0 0 0 0 0 1 10 28 51 69 71 57 35 0 0 0 0 0 0 0 6 28 67 114 145 144 113 68 0 0 0 0 0 0 1 13 49 114 186 231 226 173 102 0 0 0 0 0 0 2 17 65 146 235 289 280 213 124 0 0 0 0 0 0 2 17 65 146 235 289 280 213 124 0 0 0 0 0 0 1 13 49 114 186 231 226 173 102 0 0 0 0 0 0 0 6 28 67 114 145 144 113 68 0 0 0 0 0 0 0 1 10 28 51 69 71 57 35 0 0 0 0 0 0 0 0 1 7 15 23 26 21 13 0 0 0 0 0 0 0 0 0 0 2 5 6 5 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Time: 15 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 2 0 0 0 0 0 0 0 0 0 0 1 3 8 11 12 0 0 0 0 0 0 0 0 0 1 6 15 26 34 36 0 0 0 0 0 0 0 0 0 5 18 38 59 74 75 0 0 0 0 0 0 0 0 2 13 37 72 107 129 128 0 0 0 0 0 0 0 0 5 22 57 106 155 185 180 0 0 0 0 0 0 0 0 7 28 71 129 187 220 213 0 0 0 0 0 0 0 0 7 28 71 129 187 220 213 0 0 0 0 0 0 0 0 5 22 57 106 155 185 180 0 0 0 0 0 0 0 0 2 13 37 72 107 129 128 0 0 0 0 0 0 0 0 0 5 18 38 59 74 75 0 0 0 0 0 0 0 0 0 1 6 15 26 34 36 0 0 0 0 0 0 0 0 0 0 1 3 8 11 12 0 0 0 0 0 0 0 0 0 0 0 0 0 1 2 linux1[103]

Graphics

In addition to printing out the contents of the array on the screen as shown above, we have written a graphics library to be used with this program. There are just two functions for you to call within your code:

CreatePPM(int array[][15], int time) should be called before you go from time step one to two, and again two to three, and so on. This will create an image of the current oil spill so that we can see the size and density of the oil in our ocean.

ShowOilSpill(int numFrames, int step) creates an animated gif file from your oil spill simulation output files that were created from CreatePPM(). This function will be the last function called from your program and will create an animation of your oil spill. This function will also create a window in linux that will show your animation.

We're providing two files for you to use: graphicshelper.h and graphicshelper.o

Change directory until you are in the directory where you will write your code and have the executable, then type the following command at the unix prompt.

The space and the dot at the end of this command are an important part of the command itself. It means that the file(s) indicated as the source is to be copied into your current working directory and have the same name as the original(s), in this case, graphicshelper.h and graphicshelper.o

You will need to #include "graphicshelper.h" and link with graphicshelper.o

If you are working in the Linux operating system, if you have called these functions correctly a gif view window will open and you can watch the oilspill's movement. If not, a .gif file called oil_flow.gif will be written to your pub directory. You can view this file by using a web browser.

The URL for my sample using the oilspill17.dat file is: http://userpages.umbc.edu/~bogar/oil_flow.gif

Yours will be in your own pub directory, so the URL for it will be: http://userpages.umbc.edu/~<your login name>/oil_flow.gif

The data files

We're providing two sample data files for this project: oilspill515.dat and oilspill17.dat. They're found in Evans' pub directory. You should copy these files into your own directory. Your executable and the data file need to be in the same directory. Here's how:
Change directory until you are in the directory where you will write your code and have the executable, then type the following command at the unix prompt. cp /afs/umbc.edu/users/b/o/bogar/pub/oilspill* . The space and the dot at the end of this command are an important part of the command itself. It means that the file(s) indicated as the source is to be copied into your current working directory and have the same name as the original(s), in this case, oilspill515.dat and oilspill17.dat

util.c & util.h

You should continue to build your util.c and util.h files that contain utility functions and their prototypes, respectively. Functions that you keep in this file should be modules that can be used by many projects. You should continue to add functions to these files as the semester progresses. The functions SetRandomSeed() and GetRandomNumber() from the lecture 5 card example would be good to add. You should never remove functions from the util.c file, even if it isn't being used in the current project. There may be some function(s) that deal(s) with 2-D integer arrays that you'll be writing for this project that could be reused and, as such, should be in util.c.

What to Turn In

You must use separate compilation for this project and should have a file, called proj2.c, that contains the function main().

You should have an oilspill.c and oilspill.h, that contain the functions related to an oilspill used by proj2.c and the prototypes for those functions, respectively.

You should also have a util.c and a util.h, that contain utility functions that could be reused by many other projects and the prototypes for those functions, respectively.

Submit as follows:

submit cs201 Proj2 proj2.c oilspill.c oilspill.h util.c util.h The order in which the files are listed doesn't matter. However, you must make sure that all files necessary to compile your project are listed.