The Advanced Placement® Marine Biology Simulation case study is a simulation program designed to help marine biologists study fish movement in a small, bounded environment such as a lake or bay.
The simulation program is distributed with a graphical user interface (MBSGUI),
described in this help file. Topics include:
Notes:
|
The Marine Biology Simulation (MBS) case study is distributed with a number
of initial configuration files in the DataFiles folder, including
the fish.dat, manyFish.dat, and onefish.dat
files mentioned in Chapter 1. (You may not see the .dat extensions
if your computer environment doesn't show them automatically.) To choose
an initial configuration file:
fish.dat") from the DataFiles
folder.
The dialog box will come up in the program's current execution folder,
so you will probably have to navigate to the DataFiles folder
to find the initial configuration files. Depending on how and where
you are running the program, its current directory may be the JavaMBS
folder or one of the other folders under it, such as the Code
folder, the ExecutionInformation folder, or a project folder
under either Code or ExecutionInformation (or
possibly some other folder altogether). DataFiles is
another of the folders under the JavaMBS folder, so you will
need to first navigate to the JavaMBS folder and then to the
DataFiles folder. Then select the configuration file
you want to open.
The configuration files in the DataFiles folder represent
bounded environments. If you wish to read in a configuration file for an
unbounded environment (see Chapter 5 of the MBS case study), navigate to
the UnboundedEnvDataFiles folder in the DataFiles
folder and select a configuration file from there.
The program will display the environment for the configuration file you chose as a rectangular grid of locations, with fish in the locations specified in the initial configuration file.
You can run the Marine Biology Simulation program one timestep at a time, or continuously for many timesteps.
By default, the Run button will cause the simulation to run indefinitely, until you select Stop. You can also run the simulation for a specific number of steps. If you choose "Use fixed number of steps..." from the Run menu, you will be prompted for a certain number of steps. If you specify a number and click on OK, you will notice the label on the Run button change. For example, if you chose 10 steps, the button will read "Run for 10 steps." When you click on the button, it will run for 10 timesteps, or until you select Stop. If you choose "Prompt for number of steps" from the Run menu, the label on the Run button will change to "Run..." and you will be prompted for the number of steps every time you click on it. Again, the program will run that number of timesteps unless you select Stop. To return to running the simulation continuously, choose "Run Indefinitely" from the Run menu.
At any time while running the Marine Biology Simulation program, you can save the current state of the environment as a configuration file. You can then use this file later as an initial configuration file for a new run of the simulation, to continue the current run of the simulation, or to compare results from a different run of the simulation (see Chapters 3 and 4 of the MBS case study for more information about regression testing).
myConfigFile.dat. (
If you don't specify a .dat extension, the program will add it.
Again, you may not see the .dat extension if your computer environment
doesn't display file extensions.) If you try to save to a file that
already exists, the program will verify that you wish to replace the existing
file.
You can use the graphical user interface for the Marine Biology Simulation program to create new environments in several ways. You can open an initial configuration file, run it for several timesteps, and then save that environment to a file. (See "Opening an existing initial configuration file," "Running the simulation," and "Saving the current state as a new configuration file.") You can also create a new environment from scratch, specifying the size of the environment and the initial locations and directions of all the fish in it. Or, you can edit the current state of an environment, adding and removing fish. This section describes creating new environments and editing environments.
main method of the MBSGUI class (see
"Customizing the graphical user interface").
When you are creating or editing an environment, a new panel appears with two pull-down menus. The first allows you to choose the type of the next fish to add to the environment. The second allows you to choose the next fish's color.
After you create or edit an environment, you may wish to Save it to a configuration file. You can run the simulation on the new or modified environment by clicking on the Step or Run buttons, at which time the extra panel for creating new fish will disappear.
You can set a seed for the random number generator when opening or creating new environments. If you use the same seed for several simulation runs, starting with the same initial configuration, the fish in the simulation will exhibit the same behavior each time.
The environment display adjusts the size of the grid cells depending on the number of cells in the grid. The cells in a grid with very few cells will be quite large, whereas the cells in a grid with many cells will be much smaller. If, however, the cells would be too small to show fish clearly, then the graphical user interface displays only part of the environment and provides scroll bars for viewing other parts of the environment. There are also several options in the View menu for viewing large environments.
You can customize the MBS graphical user interface in several ways. (These are advanced features of the graphical user interface.)
main method
in the MBSGUI class and look for the statement that associates
a FishDisplay object with the Fish class in the
display map. There are several other commented-out statements that illustrate
how to associate a different display object (such as a RoundFishDisplay
or a FishImageDisplay object) with a particular class, such as
Fish or DarterFish. To use an image to display
fish, you will need to pass the image filename and the direction the fish
in the image is facing to the FishImageDisplay constructor.
You will also need to put the image file in the folder where the simulation
program is executed. This is probably the Code or ExecutionInformation
folder, or a sub-folder under one of those folders. One image file,
smallfish.gif, is provided in the mbsgui.jar file;
you do not need to put that image file in the program's execution folder in
order to use it.
main method in the MBSGUI class and look
for the statement that sets the fishClassNames variable.
To add darter fish and slow fish to the list (see Chapter 4 of the MBS case
study), comment out the existing statement and uncomment the later one that
lists Fish, DarterFish, and SlowFish.
If you create new Fish subclasses of your own, you will need
to add them to this list if you want to be able to add objects of your new
subclasses to environments using the graphical user interface. (You
do not need to change the fishClassNames variable in order to
open files or run simulations with Fish subclasses, just to add
them to environments using the graphical user interface.)
main method in
the MBSGUI class and look for the statements that set the boundedClassNames
and unboundedClassNames variables. There are several commented-out
statements that illustrate how to specify additional implementation classes
for either bounded or unbounded environments. (See the exercises at
the end of Chapter 5 of the MBS case study for why this might be useful.)
Once you have added alternative environment implementation classes to the
lists in the MBSGUI class, you will need to choose the bounded
or unbounded implementation class you wish to use whenever you open an initial
configuration file. An additional pull-down menu of class choices
will appear in the dialog box. The new classes will also appear
in the environment type pull-down menu in the dialog box for creating a
new environment.
Fish class that has the modifications
from Chapter 3 (either the file in the DynamicPopulation folder,
or the original file in the Code folder to which you have added
the code from FishModsForChap3.txt). Add a new class variable
to the Fish class that specifies whether breeding and dying should
be turned on or off. (Example: private static boolean allowBreedingAndDying
= true;) Add the following method to the Fish class.
Note that the signature and return type for the method must be exactly as
shown below.
/** Enables or disables fish breeding and dying. If this method
* is present, MBSGUI will provide a way for users to specify
* whether they want to run the program with breeding and dying
* turned on or off.
* @param flag true if the simulation should allow
* breeding and dying; false otherwise.
**/
public static void enableBreedDie(boolean flag)
{
// Set class variable from flag parameter.
// Example: allowBreedingAndDying = flag;
}
Finally, edit either the act method or the breed
and die methods so that fish only breed and die when the class
variable is set to true.
The graphical user interface looks to see if the Fish class has a public
static void enableBreedDie method that takes a boolean
value as a parameter. If it does, the graphical user interface adds a new
menu, called Special, with two choices, "Enable breed and die"
and "Disable breed and die." When you enable or disable
breeding and dying by choosing the appropriate menu item, the graphical
user interface calls the enableBreedDie method in the Fish
class, passing it true if breeding and dying should be enabled,
or false if they should not be enabled. This advanced
feature allows you to turn breeding and dying on and off from the graphical
user interface as the program is running, rather than turning it on and
off by changing the code or compiling with different implementations of
the Fish class. For example, in Chapter 4 the MBS case
study suggests running the simulation without breeding and dying to see
the difference between darter and normal fish movement more clearly, without
the added complexity of fish breeding and dying.
This document describes the 1 August 2002 release of the Marine Biology Simulation Graphical User Interface (MBSGUI).
Copyright© 2002 College Entrance Examination Board (www.collegeboard.com).