Assignment 1

This programming assignment is the first of a series of assignments centered around a common theme. The idea is to get some programming practice in Java, while also improving programming skills (for example: critical thinking, problem solving, software engineering).

In this assignment, you will simulate a stock-car race featuring several vehicles on a 2-dimensional grid of cells. Essentially, think of the grid as a 2-dimensional array and the vehicles as integers. Then, each vehicle will start at some location (a particular cell, such as (2,3)) and be assigned a destination location (such as (9,6)). At every time step, each vehicle gets its chance to move towards its assigned destination by a distance of one cell (horizontal or vertical, but not diagonal). A vehicle cannot move into an occupied cell, allowing for the possibility of a "standoff". In this case, both vehicles stay in the "standoff" until one of them can move or the simulation ends. The overall goal is to estimate the fraction of vehicles that make it to their destination, and to do this for various parameters.

This vehicle simulation that you will write is part of a long tradition of simulating "macro" behaviors (for example: traffic congestion) that arise from groups of independent small units (vehicles). This type of simulation is often called an agent or artificial society simulation. Indeed, there is a whole institute, the Santa Fe Institute, devoted to such studies. In keeping with tradition, we will sometimes refer to the vehicles as agents. (Think "agents driving vehicles").

Start by downloading this JAR file. (Note: we had some problems downloading this file with Netscape on Win98/NT - you might try Internet Explorer instead. Also, save it as a file - it's not viewable). A JAR file is really a ZIP file containing other files. Use the Java command-line tool jar to "unpack" the JAR file. For example, on Unix, you would type:

% jar xvf assign1.jar
  

Examine the file Assign1.java and observe the following:

• There are two integer variables M and N. Here,
  • M is the "side" of the 2D grid. That is, there are M x M cells in the grid.
  • N is the number of agents (vehicles).
  You will vary both M and N for various experiments once the simulation is written. Initially, it's best to start with small numbers like M=4 and N=2.
• There are two integer arrays called startX and startY:
  • These contain X and Y coordinates for the start cells of the agents.
  • startX[k] is the X coordinate of the starting cell for agent k.
  • Similarly, startY[k] is the Y coordinate of the starting cell for agent k.
  • For example, if agent 5 is designated to start in cell (2,0) then startX[5]==2 and startY[5]==0. In other words, agent k starts in cell (startX[k],startY[k]).
• Note: all numbering starts from 0. Thus, for example, the agents are numbered 0,...,N-1 and grid X coordinates range from 0,...,M-1.
• There are two integer arrays called endX and endY:
  • These contain X and Y coordinates for the destination cells of the agents.
  • endX[k] is the X coordinate of the destination cell for agent k.
  • Similarly, endY[k] is the Y coordinate of the destination cell for agent k.
  • For example, if agent 5 is supposed to go to cell (1,3) then endX[5]==1 and endY[5]==3. In other words, agent k must try to go to cell (endX[k],endY[k]).
• The method initializeRandomList() is called just once in main(). This method creates arrays like startX[] and initializes a list that will later be used to fill the arrays. You do not need to understand this method for the assignment.
• The createStartAndEndPositions() method is a method you will call every time you need a random initial and destination locations assigned to the agents. With each call, random values are placed in the arrays startX, startY, endX, endY. The idea is, you should be able to use several such random configurations to be able to estimate probabilities, one configuration per trial.

You are to write your code in the main() method as well as methods you create. Note the following:

• You will simulate a discrete-time system, in which time progresses in steps: step1, step2, step 3, etc. At each step, each agent (that has not already reached) will get a chance to move closer to its prescribed destination. Thus, in step 1, agent 0 will get a chance to move, then agent 1 gets its opportunity to move, then agent 2, etc. Once all of them have moved (or remained stuck because it was not possible to move), step 1 is over. Then, the time clock is advanced one step. In step 2, the cycle repeats: agent 0 tries to move, then agent 1, then agent 2 etc.
• Each agent can only move horizontally or vertically (not diagonally) and is allowed to only move closer to its destination (not away from). An agent can choose which direction to move, if both neighboring cells are available.
• An agent may not move into an occupied cell. If an agent cannot move (both neigboring cells are occupied), it is temporarily "stuck".
• The simulation ends if all agents have reached their prescribed destinations or if all remaining agents are stuck. Sometimes all agents make it, other times only a fraction of the agents make it - your primary job is to estimate the fraction of agents that make it to their destination.
• The "fraction of agents that reach their destination" is one example of a "macro" characteristic of the system. You will estimate a few other such macro characteristic as well.
• Once an agent reaches its destination, it lies there for T time steps. Consider the case T=1. This means that if an agent reaches its destination in time step 12, then it is removed from the cell at time step 13. Note that such removal may allow other agents freedom to move.
• To help debug your program it will help to "view" the landscape of cells at any given time. Accordingly, write a printGrid() method that prints the current location of agents as a matrix. This way, you can observe the movement step by step. Such debugging output is not needed once your program is working correctly. So, define a boolean variable called debug such that: when debug==true, you will print out the grid, and when it's false the method printGrid doesn't get called.

Deliverables:

• The source code for program. Please write all your code in the same file (Assign1.java).
• In your jar file, include all the .class files needed to compile and execute your program; this includes the files you downloaded in the JAR file for this assignment.
• You will estimate the following:
  • What is the fraction of agents that reach their destination?
    Obtain this number for each simulation run and then take the average across the 10,000 runs (simulations).
  • Define a simulation as "wildly successful" if all the agents make it to their destination. What is the probability that a simulation is wildly successful?
  • Define a simulation as "catastrophic" if no agent makes it to their destination. What is the probability that a simulation is catastrophic?
  Estimate each probability using an average of 10,000 simulations.
• You are to report the above three numbers for the following parameters:
  • M=4, and each value of N in the range {2,4,6, ..., 16}. Take T=1.
  • M=4, and each value of N in the range {2,4,6, ..., 16}. Take T to be infinity.
  Put these numbers (manually) in a plain text file called results.txt in your directory. For a few extra points, you might plot a graph with N on the X-axis, and each estimate on the Y-axis.
• What did you do to ensure that your code is working correctly? You will also need to provide some evidence, test cases (and output) to validate your program.
• Your code will be graded on both correctness and documentation (comments).

Submission:

• The name of subdirectory for this exercise should be: your username followed by _a1.
  Example: if your username is beavis your subdirectory will be called beavis_a1.
• Follow the submission instructions carefully as usual.
• Submit a printout (hardcopy) of your code before the due date in my mailbox.