Minnow Project

A Supplemental Project to the
Marine Biology Simulation Case Study

Alyce Brady
Kalamazoo College

 

Getting Started

The Minnow program simulates three small fish, the minnows, swimming in a small, bounded environment such as a pond or aquarium.  The small, bounded environment is represented as a rectangular grid of cells.  Through a graphical user interface, the user can control how the program is run, stepping through it one step at a time or running it for many steps until the Stop button is pressed.  In each step, the three minnows move one cell.

The exercises in this project are designed to introduce you to the Minnow class, which represents the small, simple fish swimming in the environment.  You will be modifying the Minnow class to improve the way minnows move.  To do this you will use methods from three other classes: Environment, Location, and Direction.  An Environment object represents the environment in which minnows swim, a Location object represents the row and column of a specific cell in the environment, and a Direction object represents a direction, such as north, south, east, or west.  Each minnow in the environment is at a particular location and facing a certain direction. 

Environment provides two kinds of methods.  One set deals with the objects in the environment, such as numObjects (how many objects are there?), allObjects (get me all the objects), isEmpty (is there an object at a particular location?), and objectAt (get me the object at a particular location).  Environment also provides methods for navigating around the environment; for example, a minnow at a particular location can ask the environment what location is to its north or south (getNeighbor), or what direction it needs to go to get to another location (getDirection).  The exercises in this project will focus on using the getDirection, getNeighbor, and isEmpty methods.

Some of the classes in the Minnow project, including Environment, Location, and Direction, come directly from the AP® Marine Biology Simulation case study.  Others, such as Minnow, are based on classes in the case study.†

[Educational prerequisites for this project: Students should be familiar with reading class documentation, constructing objects and invoking methods, the format of a class implementation (instance variables and methods), the basic flow control constructs (conditions and loops), and reading class documentation. Students should also be familiar with the add, get, remove, and size methods of the ArrayList class.]

Exercise 1 — Running the program:

  1. Download the zip file that contains the starting code files for the Minnow Project (Minnow.zip) and unzip it. When you unzip the file and look in the Code folder, you will see files representing the following classes.
    • MinnowApp (contains the main method)
    • Minnow (the class you will be modifying and improving)
    • MinnowGUI (a class that implements the program's graphical user interface; you are not expected to read or understand this class)
    • MinnowDisplay (the graphics code to draw a minnow; you are not expected to read or understand this class)
     
    There are also three jar files (mbsbb.jar, mbsenv.jar, and genericEnv.jar) that contain additional classes the program needs in order to run, including Environment, Location, Direction, and classes used by the graphical user interface. You can find documentation for all of these classes in the Documentation folder. (Note: All of the classes are covered by the GNU General Public License, including the BoundedEnv and Location classes which come from the AP® Marine Biology Simulation case study.†)
     
  2. Compile and run the Minnow program.  (If you do not know how to compile with jar files, read the information in the ExecutionInformation folder of the Marine Biology Simulation case study.) Run the program for a number of timesteps. 

    Analysis Questions: What is the behavior of the three minnows in the environment?  Run the program several more times.  In what ways is the behavior the same each time, and in what ways is it different?  Did you ever see two minnows facing each other?  If so, what happened?

 

A Minnow object has instance variables to keep track of the environment in which it lives, its location and direction in that environment, and its color.  Its constructor initializes those variables.  It also provides accessor methods that allow client code to find out those values — what environment the minnow lives in, what its location or direction is, or what color the minnow is.  Its most important method, though, is the act method, because that is the method that gets called in each timestep.  When the user clicks on the step or run buttons, the program asks each object in the environment to "act."  For a minnow, acting means to move, so the act method calls an internal move method.

The move method calls another internal method, nextLocation, to determine the next location to which the minnow should move.  If the minnow is blocked, nextLocation returns the minnow's current location, indicating that it can't move.   If the next location is not equal to the current location, the minnow moves there (calling changeLocation), possibly changing direction in the process.  The minnow's new direction is determined by asking the environment what direction the minnow had to swim to get from its old location to its next location. (The separate changeLocation method handles updating the minnow's location and notifying the environment of the move.)

Exercise 2 — Understanding the code:

  1. Read the Minnow class, focusing on the move method.  Trace through the method to see how the code matches (or doesn't match) the description in the paragraph above.  Read the class documentation for Environment to better understand what the getDirection method does.
  2. Read the nextLocation method.  Trace through it to see how the method implements the behavior you observed in Exercise 1.  Read the class documentation for Environment to better understand what the getNeighbor and isEmpty methods do.  Why does the nextLocation method call isEmpty?
  3. Analysis Question: Did you ever observe minnows swimming out of their environment?  What aspect(s) of the Minnow class code explain this?  (Hint: look at the description of the isEmpty method in Environment.)

 

Modifying How Minnows Move

In the next exercise you will modify the Minnow class so that a minnow moves forward if possible; otherwise it turns around and moves in that direction.

Exercise 3 — Turning around:

  1. Read the class documentation for Direction to find out how to refer to the opposite direction to that in which the minnow is facing.
  2. Modify the nextLocation method so that a minnow moves forward if the location in front of it is empty, turns around and moves backward if it cannot move forward and the location behind it is empty, or stays still if the locations in front of and behind it are blocked.

 

In the next exercise you will modify the Minnow class so that a minnow moves forward, right, left, or backward, if possible.  You may search the locations in the four directions in any order to find one that is empty.

Exercise 4 — Rotating:

  1. Read the class documentation for Direction to find out how to the directions to the right or left of that in which the minnow is facing.
  2. Modify the nextLocation method.  Introduce two local Direction variables to represent the directions to the right and left of the minnow's current direction and a third variable to represent the direction opposite to the minnow's current direction.  Use these three direction objects and the minnow's current direction and location to find an empty location in one of the four neighboring cells, if there is one.  You may check the four locations in any order.  (You may also wish to introduce four Location objects to represent the locations in the four directions around the minnow's current location.)
  3. Run the program with the modified Minnow class.  How would you describe a minnow's movement pattern at this point?
  4. Change the order in which you check the four locations.  Run your program again.  How does this change the minnow's pattern of movement? Come up with a third ordering and run the program again.  How has the pattern of movement changed?
  5. Analysis Question: If the first direction is defined as in the statement below, how many ways can you come up with to define the direction to the left and the direction behind?  Look over the descriptions of all the Direction methods. 
        Direction rightDir = myDir.toRight();

 

In the next exercise you will modify the Minnow class to make use of the emptyNeighbors helper method.  A minnow will still move forward, right, left, or backward, if possible, but now you should use a location returned by emptyNeighbors.

Exercise 5 — Using emptyNeighbors:

  1. Read the emptyNeighbors method.  Trace through the method to understand what it does and how it does it.  Read the class documentation for Environment to better understand what the neighborsOf method does.
  2. Modify the nextLocation method to call the emptyNeighbors helper method to find the empty neighboring locations, and to return the first location found by emptyNeighbors (if there is one).  If there are no empty neighbors, the method should act as before, keeping the minnow in the current location.
  3. Analysis Question: Explain why the call to isEmpty in the previous exercises now becomes a test of the size of the list returned by emptyNeighbors.

 

In the next exercise you will modify the Minnow class to randomly choose an empty location to which to move. 

Exercise 6 — Random behavior:

  1. Modify the nextLocation method to randomly choose one of the empty neighboring locations from the list returned by emptyNeighbors(if there is one).  If there are no empty neighbors, the method should act as before, keeping the minnow in the current location.  The randomColor method used by the Minnow constructor illustrates how to get an instance of a random number generator (actually a pseudo-random number generator) and how to use it to randomly choose one of the 256 random numbers between 0 and 255.  In this case you will want to get an instance of a random number generator and then use it to choose one of the N numbers between 0 and N-1, where N is the number of items in the list of empty neighbors.  Use the random number as your index into the list.

 

In the next exercise you will modify the Minnow class to prevent minnows from moving backward or turning completely around in one step.

Exercise 7 — No turning back:

  1. Modify the nextLocation method to remove the location behind the minnow's current location from the list of empty neighboring locations before randomly choosing one them to return.

 

Transition to the Marine Biology Simulation Case Study

After completing these exercises, you are ready to explore the Fish class in the Marine Biology Simulation (MBS) case study.* When moving on to the MBS case study, notice the following differences between the Minnow and Fish classes: