CMSC 202 Project 4

Ants and Doodlebugs
A Predator-Prey Simulation

Assigned Wed Oct 24
Program Due 10:00AM, Wed Nov 7
Design Due 10:00AM, Wed Oct 31
10:00AM Wed Nov 7
Weight 9%
Updates Because the questions in p4design.txt are more oriented towards implementation than design, the due date for p4design.txt has been changed to coincide with the project

Objectives

Project Description
 This project is a predator-prey simulation. Your program will simulate a field filled with Ants and DoodleBugs which are kinds of Critters. DoodleBugs move, eat Ants, and reproduce; they might starve to death. Ants move and reproduce, but they always have enough to eat. Neither Ants nor DoodleBugs ever die of old age. The field in which the Ants and DoodleBugs live is an 20 x 20 array. Each location in the array can be empty, or it can hold one Ant or one DoodleBug (but not both). The simulation should be cyclical over time. As the DoodleBugs eat the Ants, more DoodleBugs breed. The more the DoodleBugs breed, the more Ants they eat until there aren't enough Ants for all the Doodlebugs, so the DoodleBugs begin to starve. As the DoodleBugs starve off, more Ants live long enough to breed. As the Ant population increases, fewer DoodleBugs starve so more DoodleBugs breed and eat more Ants starting the cycle again. It's also possible, but not likely, that one species may die out.

At the beginning of the simulation, the Ants and DoodleBugs are distributed in random locations in the field. The simulation then progresses in a series of "steps".

At each step the simulation first walks through each cell in the field and asks each Critter which direction it would like move. If the request can be honored the Critter is moved, otherwise the Critter stays where it is. Ants can only move to empty cells. DoodleBugs can move to empty cells or move to a cell that contains an Ant, in which case the DoodleBug eats the Ant.

The simulation then asks each Critter if it should breed. If so, a new Critter is created in an adjacent empty cell. If no adjacent cell is empty, no new Critter is created.

Finally, the simulation asks each Critter if they have starved to death. If so, the Critter is removed from the field.

Note that the Critters do not actually move, breed, or starve. The simulation performs the actual actions after asking the Critters what to do.
Ant Behavior
 Ants behave according to the following model.
  1. Ants randomly choose one of the four possible directions (North, South, East, West) to move.
  2. If an Ant survives for three (3) steps, then it will breed.
  3. Ants never starve.
DoodleBug Behavior
 DoodleBugs behave according to the following model:
  1. If a DoodleBug sees an Ant in an adjacent (N, S, E, W) cell, it will choose to move to that cell. Otherwise, the DoodleBug randomly chooses a direction.
  2. If a DoodleBug survives for eight (8) steps, then it will breed.
  3. If a DoodleBugs has not eaten an Ant in the last three (3) steps, it will starve to death.
This project will use a GUI to allow the user to enter the simulation parameters (initial number of Ants, and initial number of DoodleBugs with basic input error checking) and to run the simulation. The simulation may be run one step at a time, or be placed into automatic mode which performs one simulation step approximately once per second. Once in automatic mode, the simulation can be paused and later continued using step or automatic mode. The GUI and the main driver will be provided for you. The files AntGUI.java and ImageGrid.java can be found in Mr. Frey's public directory and should be incorporated into your project. You're welcome to examine the code, but no changes to these files are required or permitted.
Project Specification
Your job is to implement the classes defined below which implement the simulation as described above. All classes must be defined in a package named ants.
The AntWorld Class
 The AntWorld class contains the field in which the Critters live and the code to run the simulation. Some static utility methods should also be provided for use by Critters. This Javadoc description the public methods of the AntWorld class required by the AntGUI class. No other public methods are necessary or permitted. All other methods and variables should be private or have package access.
Critters, Ants, and DoodleBugs
 The Critter, Ant, and DoodleBug classes form a class hierarchy. The Critter class is an abstract base class from which the Ant and DoodleBug classes are derived.

A skeleton for the Critter class is defined in Critter.java which should be copied from Mr. Frey's public directory and incorporated into your project. Comments are provided in the code to guide you in completing the skeleton. Javadoc is also available for the Critter class. No other methods other than those found in the Javadoc are necessary or permitted. You should of course define instance and/or static variables with the appropriate visibility in the Critter and/or Ant and/or DoodleBug classes.

The Ant and DoodleBug classes extend the Critter class. They must implement the abstract methods defined in the Critter class. To support the GUI display, these classes must track the current number of Ants and DoodleBugs (respectively). Check the code in AntGUI.java for the required names.

Requirements, Hints, and Tips
  1. The field in which the Critters live is a "wrap around" array. I.e. moving left (WEST) from column 0 puts the Citter in the rightmost column, moving down (SOUTH) from the bottom row puts the Critter in the top row, etc.
  2. Be careful not to move the same Critter twice in the same simulation step.
  3. The clone( ) method must be used to create new Critters when breeding occurs.
  4. The instanceof operator can be used to determine whether a Critter is an Ant or a DoodleBug. The use of this operator is strictly limited. It may only be used to determine whether a DoodleBug is about to eat an Ant. The main objective of this project is to write and use polymorphic methods. The use of the instanceof operator runs counter to polymorphism.
  5. Each file you write for this project should be part of a package named ants.
  6. Note that the AntGUI and ImageGrid classes are not in the ants package. This requires that some static/instance variables/methods in the classes contained in the ants package must be public while others can have (and should have) default (package) visibilty. This page has a summary of visibility provided by the different visibility modifiers.
  7. The Javadoc for the AntWorld class specifies the only public methods necessary or permitted (the ones used by AntGUI). The AntWorld class should make good use of default (package) access, while still keeping private things private.
  8. To generate a random integer between 0 and N (inclusive) use int x = (int)(Math.random() * (N + 1)
  9. Use different sets of simulation parameters to help test your code. For example, you can test DoodleBug starvation by starting the simulation with a few DoodleBugs, but no Ants for them to eat. You can test Ant breeding by starting with some Ants but no DoodleBugs.
  10. The GUI provides the following input error checking. If we missed anything that would be helpful, let us know and we'll update the GUI.
  11. You must implement code in main( ) as a unit test for both the Ant and DoodleBug classes. See Testing Your Class in Main for help writing main to test your classes.

  12. Mr. Frey's public directory for this project is /afs/umbc.edu/users/f/r/frey/pub/CMSC202/Proj4
  13. In the event that there is a discrepancy between the Javadoc and this description, this description should be considered correct.
  14. The picture files ant.jpg and bug.jpg should be copied to your Eclipse workspace from Mr. Frey's public directory. These files must be located at the same level as the src directory.

Project Policy
This project is considered an CLOSED project. This means
  1. You should try as much as possible to complete the project by yourself.
  2. You may get assistance only from the TAs or instructors
  3. You must document all outside help you get as part of your file header comment.
As usual, you MAY NOT
  1. copy anyone else's code
  2. have someone else write your code for you
  3. submit someone else's code as your own
  4. look at someone else's code
  5. have someone else's code in your possession at any time
Such offenses are violations of the student code of academic conduct.
Grading

The grade for this project will be broken down as follows. A more detailed breakdown will be provided in the grade form you receive with your project grade.

10% - Project Design
Copy p4design.txt from Mr. Frey's public directory and edit the file to answer the questions. Be sure to submit this file by its due date.
80% - Correctness
This list may not be comprehensive, but everything on this list will be verified by the graders.
10% - Coding Standards
Your code adheres to the CMSC 202 coding standards as discussed and reviewed in class.
In particular, pay particular attention to the list below. Graders will check all applicable items in the coding standards.
  1. Your class comments (particularly class invariant)
  2. Your method header comments (particularly pre- and post-conditions)
  3. In-line comments
  4. Code readability
  5. Limiting variable scope
Project Submission
  1. submit p4design.txt, Critter.java, Ant.Java, DoodleBug.java, AntWorld.java
  2. Use submitls to verify they are in the remote directory
  3. DO NOT submit AntGUI.java, ImageGrid.java, ant.jpg, bug.jpg. Grading scripts will remove these files if found in your submittal directory.
The order in which the files are listed doesn't matter. However, you must make sure that all files necessary to compile and run your project are submitted. You need not submit all files at the same time. You may resubmit your files as often as you like, but only the last submittal will be graded and will be used to determine if your project is late. For more information, see the projects page on the course website.

You can check to see what files you have submitted by typing

submitls cs202 Proj4 More complete documentation for submit and related commands can be found here.

Remember -- if you make any change to your program, no matter how insignificant it may seem, you should recompile and retest your program before submitting it. Even the smallest typo can cause compiler errors and a reduction in your grade.

Avoid unpleasant surprises!