CS 231: Assignment #2

Spatial Simulation

This week begins a multi-week project during which we'll explore the simulation of entities on a 2D grid. The entities will interact with the grid and with each other, simulating various social phenomena.

The inspiration for this project comes from work at the Brookings Institute by Epstein and Axtell on modeling human social dynamics. There are a number of newer publications and white papers on their web site with more recent results, including significant models of the spread of disease.

If you are interested in the subject, the book Growing Artificial Societies provides a nice introduction.

Documentation for Java 1.5 is located at: Java 1.5 SE API.

Documentation for Java 1.6 is located at: Java 1.6 SE API


You want to keep your code on your network directory, as the computers in the lab will be periodically cleaned off. If you are on a terminal on a mac, you can get to the working directory using

cd /Volumes/Personal/<your user folder name here>


This week you'll first develop two classes and make use of a third, provided class. The third class will count on your classes doing the right thing.

Once you have the base simulation working, you'll create a new child Simulation class and modify the entity update rule function to create a new kind of simulation.

  1. Entity - create a java class called Entity, which should hold all of the information unique to an entity in the simulation. The Entity class will play the role of a parent class in future weeks, and does not need to be complicated.

    The Entity class should have the following fields, all of which should be protected.

    • Boolean active - specifies if the Entity is active
    • int row - the current row of the Entity, default value of -1
    • int col - the current column of the Entity, default value of -1
    • int type - the type of the Entity, default value of 0

    The Entity class should have the following methods for setting and accessing fields. For the most part these are accessor functions that return or set the fields of an Entity object.

    • public Entity() - a default constructor.
    • public Entity( int r, int c, int t ) - a constructor that takes in the row, column, and type of the Entity.
    • public int Row() - returns the current row value.
    • public int Col() - returns the current column value.
    • public int Type() - returns the current type value.
    • public boolean Active() - returns the current active value.
    • public void setActive( boolean a ) - sets the active field.
    • public void setType( int t ) - sets the type field.
    • public void SetPosition( int r, int c ) - sets the row and col fields.
    • public String toString() - returns a 1-character String representating the Entity.

  2. Landscape - create a java class called Landscape, which will hold a grid of Entity object references. The Landscape class should have variables for specifying the number of rows, number of columns, and the array of Entity object references. Each of these fields should be protected.

    For the Entity grid, you could use a declaration like:

    protected Entity[][] egrid;


    protected Entity egrid[][];

    Both expressions to do the same thing; they declare a variable egrid that is a 2D array reference.

    The Landscape class should implement the following methods.

    • public Landscape() - sets the number of rows and columns to zero.
    • public Landscape( int nRows, int nCols ) - sets the number of rows and columns to the specified values and allocates the grid of Entity references. Since each row of the grid has the same number of columns, you can allocate the grid in a single new statement, as we went over in the lab. Note that this does not actually create an Entity objects, it just creates a 2D array of Entity object references.
        egrid = new Entity[rows][cols];
    • public int Rows() - returns the number of rows in the landscape.
    • public int Cols() - returns the number of columns in the landscape.
    • public Entity GetEntity( int r, int c ) - returns the Entity located at position (r, c) or null if there is no Entity there.
    • public Entity PutEntity( int r, int c, Entity e ) - puts the specified Entity at location (r, c) and returns whatever used to be in position (r, c) (null if there was nothing there). If the function is returning an actual Entity, then its position should be set to (-1, -1).
    • public Entity RemoveEntity( int r, int c ) - returns the entity at location (r, c) and sets the Entity grid at that location to null. The function should also set the position of the removed Entity to (-1, -1).
    • public String toString() - converts the Landscape into a text-based string representation. You can do this by using a double for loop over the rows and columns of the grid. First, initialize a string to the empty string. Within the for loop, at each location, if the value is NULL, add a '.' to the string. Otherwise, there is an Entity at the location and you can call its toString method. At the end of each row, put a carriage return (\n).
  3. Download the Simulation class. If you compile the Simulation class, it should compile the other classes as well. Then you can run the simulation using:

    java Simulation

  4. You can modify the simulation parameters in the main method of the Simulation class. All of the simulation parameters are defined at the top of the main method except for one, which is defined in the EntityUpdateRule().
    • Try changing the various parameters and see what happens. Keep track and include your observations in your writeup. Make sure you recompile (javac Simulation.java) whenever you make a change.
    • Try changing the EntityUpdateRule method so that an Entity prefers entities of different type instead of the same. Making this change requires editing one character in the function. What happens?


  1. Modify the main method in Simulation to make use of command line parameters. The args field of the main function holds all of the strings from the command line, and you can convert them from strings into other data types as necessary. For example, it would be nice to control the number of rows and columns used by the simulation by typing:

    java Simulation 30 50

  2. Create a class that inherits the Simulation class. Use the child class to override the EntityUpdateRule and do exactly the same thing as the last task above.
  3. Give different type Entities different rules. For example, create four types and have types 1 and 2 like one another but not 3 and 4. Similarly, 3 and 4 should dislike 1 and 2, but like one another. Try other mixtures.
  4. Try other variations, like adding or removing an entity under certain conditions


Make your writeup for the project a wiki page in your personal space. If you have questions about making a wiki page, stop by my office or ask in lab.

Your writeup should have a simple format.

Once you have written up your assignment, give the page the label:


You can give any page a label when you're editing it using the label field at the bottom of the page.

Do not put code on your writeup page or anywhere it can be publicly accessed. To hand in code, attach it to an email and send it to the prof.