CSCS 530 Project #1 Description

Due date: TBA ** DO NOT wait for the LAST MOMENT **

The basic goal is to take a written description of a simple model and implement it in Repast, running experiments as you go, to see if/how the behavior in the original description can be (qualitatively) replicated.

In particular, you are to create a RePast program that implements the ants and their food gathering behavior as described below. You will be starting from a Repast program, AntPheromones1, that will be handed out and discussed in class (approximately 28 January). The program should be documented internally and there should be a Readme.txt that describes how to run it, including some example runs (including parameter values to reproduce them) and some notes on the behaviour one should see for those typical and/or "interesting" cases. There should be some measures that could be used to compare to the original program (if it had similar measures) quantitatively (in addition to "qualitative" similarity of system behavior).

Documentation of the program (conceptual and implementation), how to run it, and what experiments you ran and observations made will be important. Thus document the program and keep good notes!

Remember: You want your documentation to make it easy for me and for the people who will extend your program to:

• get a copy, modify and compile it;
• run the program and see how it behaves in "interesting" cases, i.e., you will want to show guirun.sh commands with parameters on the command line, and then describe what the user should see when run under those conditions
• describe the "conceptual model" -- what rules do ants use, how is food represented, etc.
• describe any measures you have, what to expect those to show under various conditions, and what actually happens.

and in general make it easy to

• read your program java files: indent and space regularly, use descriptive variable and method names, use comments to describe what methods do, etc.

Note grades will be based only slightly on whether you actually got it to replicate the originally described behavior (although you should try hard to get it to "work"). More important will be your justification for the approach you tried, how you programmed and documented it, both for understanding and using it. Also important is the notes you keep as you implement your first ideas, run experiments, add/change things, etc.

You may want to put your notes and documentation on pages you create on the course wiki, under this page:

The password for editing will be given out in class (or ask me). Put commands and notes for your demo on Feb 20th on this project #1 demos page.

From the netlogo description:       (PLEASE DO NOT LOOK AT NETLOGO PROGRAM)
-----------------------------
In this project, a colony of ants forages for food. Each ant follows a
set of simple rules, but the colony as a whole acts in a sophisticated way.

There is a "central" nest, and three piles of food, one closer to the
east, one farther to the sw, and one farther still to the nw.

When an ant finds a piece of food, it carries the food back to the
nest, dropping a chemical as it moves. When other ants "sniff" the
chemical, they follow the chemical toward the food. As more ants carry
food to the nest, they reinforce the chemical trail.

The ant colony generally exploits the food source in order, starting
with the food closest to the nest, and finishing with the food most
distant from the nest. It is more difficult for the ants to form a
stable trail to the more distant food, since the chemical trail has
more time to evaporate and diffuse before being reinforced.

Once the colony finishes collecting the closest food, the chemical
trail to that food naturally disappears, freeing up ants to help
collect the other food sources. The more distant food sources require
a larger "critical number" of ants to form a stable trail.

You may run the netlogo program as follows:

Then select File->ModelsLibrary, expand Biology, and select Ants, and Open . Click on Setup, then Go. (Your ants don't have to look like cartoon ants!)
PLEASE DO NOT LOOK AT THEIR PROGRAM!

I suggest you spend some time first sketching out some ideas at a "conceptual level" --- see the notes at the bottom of this page for some general guidance about designing an ABM. For this model, you will in effect have available some classes--think of them as "building blocks" --- that provide:

• A 2D discrete world in which objects (e.g., ants) are located. Each cell in the world can have 0 or 1 object in it. Objects (e.g., ants) can sense what, if anything, is in other (nearby) cells. Ants (or other objects) can move in the world to empty cells, and could pick up or put down objects in cells. (To be in the spirit of the model, you will want ants to only sense and act "locally" -- on nearby cells.)
• A 2D discrete "diffusion" space in which ants can deposit and sense pheromone, which diffusions and evaporates according to some build in rules.
• Each time step, every ant will be given a chance to do something (or to do nothing). Again, to be in the spirit, an ant should only sense/act "locally" (in space and time), following simple rules like "move 1 step in direction D" or "pick up the piece of food in front of you", etc. Also, pheromone will diffuse and evaporate each step.

Given those building blocks, consider what each Ant should do when its given its chance to act each "time step," given the different state it can be in or sense. Structure the ant's choice of action as a high level set of conditionals, and then fill in what happens for each of those conditions, e.g.:

   If  ( X is the case ) {
       if ( Z is the case ) 
          do A1
       else
          do A2
   else if ( Y is the case ) {
       if ( Z is the case ) 
          do A3
       else
          do A4

where, e.g., "X is the case" might be "Not carrying food", and A1 might be "pick up food". Once you have sketched out the logic at a high level, then fill in more details, a bit at a time, eventually start writing the methods for the Ant (and other) classes to implement your model.

In this case you will be starting with a program, AntPheromones1, which we will go over in class (after we go over TermintesInGrid, a similar but simpler program.) Both of those are RepastJ (Java) programs with architectures like the various programs we went over in CSCS 531 in Fall term (staring with class 6 or so).

If you want to get a start at some of the details, note that the AntPheromones1 program uses:

• the Diffuse2D class in Repast for representing
  the pheromone (chemical) distribution and dynamics.
• synchronous dynamics for the pheromone evaporation and diffusion
  (as done by the Repast Diffuse2D class and its methods).
• asynchronous updating of ant's as they move (or take other actions) in a discrete space build on top of the Repast Object2DGrid class.

Thus you could read in the Repast API documentation about those classes. You also may look at the heatBugs4 demo program

for another example "bugs" using the Diffuse2D and Object2DGrid.

Your program should have (at least) these parameters:

worldSize          -- size of world sides (assume a square world)
                      Default: 50    

densityOfAnts      -- the density of termites created.   Default: ?

evaporationRate    -- rate at which the pheromone evaporates
                      (ie, it is removed from the model world)

diffusionRate      -- controls rate of diffusion of pheromone from
                      one cell into its neighbor cells.

We will see how to add parameters to models next week.

You might want to start just one food source. An advanced version would parameterize the number, size and location of the food piles, and the location of the nest.

Some things to measure, display and include in report files:

• Size of each food pile vs time
• Amount of food returned to nest vs time. (Total, or maybe from each source?)

What else might be interesting to measure? Look at the behavior you see via the GUI -- what "patterns" do you see? What measures could you define to capture (aspects of) those patterns? What could you measure to reflect the ant's behavior/ability to find/transport food efficienty?

In general to design an ABM, we want to specify:

What is the non-Agent world?
   What state?
   What dynamics?

What are the Agents?  For each agent type:
   What state does it need?            (instance variables)
   What can the agent sense?           (methods)
   What can the agent do?              (methods)
   What behavior rules does it use?    (methods)
   How does it select agents to interact with?
      (could be variables or methods)

How to initialize the model?
   - What are run-time setable parameters?
   - The state of the world
   - The agents (and their locations, if any)

What is the schedule of events?
   What agents do what, in what order?
   Does the enviroment have its own dynamics?
   - discrete time:  synchronous
                     asynchronous
   - discrete event

What to measure?

Note that the above questions imply thinking about both a "conceptual" model and then thinking about various ways to implement those concepts. For example, what are the different ways one might implement ant movement, including random movement? What about "sniffing" and deciding what direction to move? These and similar abstract descriptions of agent state and behavior can be implemented in many ways--deciding how to do it for a given modeling project is part of the "art" of modeling.

Up: Main

• View
• Edit
• History
• Print