Marine Biology Simulation Program:
Using the Graphical User Interface

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:

• Choosing an initial fish configuration file. (Open)
• Running the simulation for one timestep or continuously. (Step/Run)
• Saving the state of the simulation for future use. (Save)
• Creating a new environment and populating it with fish.  (Create)
• Seeding the random number generator to get repeatable results. (Seed)
• Viewing large environments. (View)
• Customizing the graphical user interface.  (Advanced Features)

Opening an existing initial configuration file

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:

• Select the "Open environment file..." item from the File menu.
• In the dialog box (window) that comes up, select the configuration file you want (such as "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.

(Go to top of help file.)

Running the simulation

You can run the Marine Biology Simulation program one timestep at a time, or continuously for many timesteps.

• To run the program one step at a time, click on the Step button.  Each time you click on the Step button, the program will run one timestep in the simulation, with fish moving from cell to cell in the grid.  See Chapters 1 and 2 of the MBS case study for more information about how fish move in the simulation.
• To run the program continuously for many timesteps, click on the Run button.  Click on the Stop button to stop the simulation.  You can then click on either Step or Run to continue the simulation for one more timestep or for many timesteps.  You can adjust the speed of the simulation by dragging the indicator on the Slow/Fast slider to the left or right.

  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.

(Go to top of help file.)

Saving the current state as a new configuration file

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).

• Select "Save environment as..." from the File menu.
• A dialog box will come up in the program's current execution folder.   Navigate to the folder where you want to save the new configuration file.
• Give the new file a name, such as 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.

(Go to top of help file.)

Creating and populating a new environment

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.

Creating a new environment:

• Select "Create new environment..." from the File menu.
• Choose the environment type.  For Chapters 1 - 4 of the Marine Biology Simulation case study, you can use the default "BoundedEnv" choice without doing anything.  For Chapter 5, choose whichever environment type you want to create.  The choices will be the "BoundedEnv" and "UnboundedEnv" types, unless you specify additional environment types in the main method of the MBSGUI class (see "Customizing the graphical user interface").
• If you choose the "BoundedEnv" environment type, you will be prompted to specify the number of rows and columns in the bounded environment.  The program will use the default values shown in the text fields if you do not change them.
• Click on the Create button.
• Add and remove fish as described below.

Editing an existing environment:

• Select "Edit environment..." from the File menu.
• Add and remove fish as described below.  (You cannot change the type or size of the environment using the "Edit environment..." feature.)

Adding fish to, and removing them from, an environment:

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.

• Choose the desired fish type.  (This is only necessary once you introduce additional fish types in Chapter 4 — see "Customizing the graphical user interface" below.)
• Choose the desired fish color.  There are a number of colors available, or you can choose "Other ..." to specify your own colors.  Every fish you add to the environment will be of that color until you choose a different color from the pull-down menu.  If you choose "Random," then every fish you add will be a different, randomly-chosen color.
• Click in an empty cell in the grid to add a fish to that location.
• Click on a fish to rotate it to a new direction.
• Rotating a fish all the way around will remove it from the environment.

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.

(Go to top of help file.)

Seeding the random number generator

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.

• To run the simulation without seeding the random number generator, select "Don't reset seed" from the Seed menu.  This is the default behavior when the program starts.
• To run the simulation with a specific seed, select "Use fixed seed..." from the Seed menu, and then enter the seed value in the dialog box that comes up.  Once you have chosen a seed, it will be used to seed the random number generator every time you open an initial configuration file or create a new environment (until you choose another alternative from the Seed menu).  If you open or create the same environment several times using the same seed, the fish behavior will be the same each time.
• To run the simulation with different seed values for each run, select "Prompt for seed" from the Seed menu.  When this alternative is selected, you will be prompted for a seed value every time you open a configuration file or create a new environment.

(Go to top of help file.)

Viewing large environments

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.

• Choose "Zoom in" from the View menu to view a smaller section of the environment in greater detail.  Since the smaller section has fewer cells, each cell will be drawn larger.
• Choose "Zoom out" from the View menu to view a larger section of the environment.  Since the larger section has more cells, the cells will be smaller.
• Choose "Bring (0, 0) to upper left" from the View menu if you have scrolled around the environment and want to pan quickly back to location (0, 0).  This option will shift the display back to its original orientation, with location (0, 0) in the upper-left corner of the display.  If the environment is bounded, this action is the same as scrolling all the way up and all the way to the left.  If the environment is unbounded, this action will bring the scroll bars to the center.

(Go to top of help file.)

Customizing the graphical user interface

You can customize the MBS graphical user interface in several ways. (These are advanced features of the graphical user interface.)

• Changing the way fish are displayed: Edit the 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.
• Changing the types of fish you can add when you create or edit an environment: Edit the 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.)
• Changing the list of environment implementation classes available when you open or create an environment: Edit the 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.

• Adding a menu to the GUI that allows you to turn breeding and dying on and off: Edit your 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.

(Go to top of help file.)

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).