Handouts/ant-food-project.txt
-----------------------------

Project #1:

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.
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) and some notes on the
behaviour you observe.

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!

In particular, the grade will be based only slightly on whether
you actually got it to replicate the originally described behavior.
More important will be your justification for the approach you tried,
how you programmed and documented it, both for using it 
and for others to use and modify.
Also important is the notes you keep as you implemented your
first ideas, ran experiments, then added/changed things, etc.

Due date: 15 Feb 2006        ** DO NOT wait for the LAST MOMENT **

==========================================================================

From the netlogo description:       (PLEASE DO NOT LOOK AT NETLOGO VERSION)
-----------------------------
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.
--------------------------

The program should have (at least) these parameters:

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

densityOfAnts      -- the number of termites created.
                      default: 

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

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

Use the Diffuse2D class in RePast for representing
the pheromone (chemical) distribution and dynamics.
Start with the AntPheromones1 program, which we will discuss in class
in the next week.  Note it uses 
- asynchronous updating of ant's
- synchronous dynamics for the pheromone evaporation and diffusion
  (as done by the Repast Diffuse2D class and its methods).
You could also look in the heatBugs3 demo program
   /appl/repast/Demos-3/heatBugs3/
for another example of using the Diffuse2D space.

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?

=======================================================================

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 instance variables or methods;
      often controled by "model" object.  

How to initialize the model?
   - 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?

======================================================================