AntPheromones1/Readme.txt
-------------------------

This program was developed by starting with a program similar to the 
RandomMoveInGrid program, and changing it so that it also supports  a 
"pheromone space", i.e.,  a discrete cellular "layer" that stores a value 
in each cell (location).  Those values represent some attribute of  
the space--in this case, they represent  the amount of some 
pheromone (chemical) at  that location.  We also introduce a dynamics 
into the non-agent enviroment, in the form of synchronous diffusion.

In the basic version of this program, the pheromone will be injected 
by some exogenous process at a fixed site, and it will diffuse by 
a (synchronous) process from cells with high amounts to cells with less.
Each step each bug will get a chance to "read" the state of the PSpace 
at specified locations (e.g., in the bug's local neighborhood) and will 
try to move "uphill" toward cells with higher amounts of the pheromone.
Then additional pheromone will be added by the exogenous source.
Note that the 2D space is now a torus, using the RePast Object2DTorus class.

See the Repast Diffuse2D API page for details on the diffusion algorithm.
Note that

  evapRate   in [0,1], 1 means none evaporates, 0 means it all does.
  diffusionK in [0,1], 1 means faster, 0 means no diffusion.

Please read about the Diffuse2D class in the RePast API.  You can also
see another example of its use (as well as the Value2DDisplay class)
in the Repast Heatbugs demos.

Note we also have to add a Repast Value2DDisplay object to display
the pheromone on the DisplaySurface, similar to the way the 
Object2DDisplay object displays bugs on that same DisplaceSurface.
We will display the pheromone first, and then the bugs.  
Also see how we set up the Value2DDisplay so that it displays
a range of redness, corresponding to the range of pheromone allowed.
In particular, see how the ColorMap mapping function is set up
in GUIModel-buildDisplay().

An *important* exercise for the reader is to change the program
so that the bugs themselves put pheromone in the world,
e.g., before or after they move.  (Clearly this is what
you will want the Ants to do in your Project #1 program!)

To get a copy of this program, in the directory where
you have your Repast programs:

   mkdir AntPheromones1
   cd AntPheromones1
   mkdir classes Saves
   cp -r /users/rlr/Courses/530/Src/AntPheromones1/src .    << note the dot!
   cp -r /users/rlr/Courses/530/Src/AntPheromones1/bin .    << note the dot!
   cp /users/rlr/Courses/530/Src/AntPheromones1/build.xml .

The java files for this program are in the subdirectory
called src/AntPheromones1/  and include:
   AntPheromones1.java -- the mail "Model" class (called AntPheromones1 here)
   Bug.java            -- the "ant" agent
   GUIModel.java       -- gui extension of AntPheromones1
   BatchModel.java     -- batch run extension
   ModelParameters.java -- superclass of AntPheromones1 

Note that AntPheromones1 uses the ModelParameters object, so you can
set parameters at run time, run in batch mode, etc.
(See Demos-3/RandomMoveInGrid for more information about ModelParameters.)

Edit and modify the bin/compile.sh bin/guirun.sh and bin/batchrun.sh
files so that the PROJECTDIR is the directory where you put your AntPheromones1/
(as you did for RandomMoveInGrid/bin/*.sh files).
What i do is, while in the AntPheromones project dir, enter
  pwd               "print working directory"
and then copy/paste the directory shown into the *.sh file.

To make a date-time-stamped "jar" archive of your program, you
can issue this command:

   ant save

It will create a file like this (in the Saves/ directory you created):

   Saves/AntPheromones1-070125-1905.jar

where the date and time will be whatever date/time is at the time
you enter that command.  You can see what is in that jar file with:

   jar tvf Saves/AntPheromones1-070125-1905.jar

Its often a good idea to make the "save" before/after you make
a lot of changes.  That way, if you decide you don't like the
changes (e.g., they are not working!), you can easily get back
to the prior version by extracting it from the appropriate jar file.

-----------------------------------------------------------------
In a little more detail, the basic dynamics of the model:

When the model is initialized:
  Inject exogenously supplied "pheromone" to a selected cell
  Create and randomly distribute some bugs

Each time step of the model:
  1. the existing pheromone will be diffused.

  2. bugs will move around by:
     a. pick one neighbor cell randomly
     b. if it us is open and has more pheromone than 
        where the bug is currently,  move there.
     c. otherwise, move randomly (1 step) as in RandomMoveInGrid and
        other example programs.

  3. the exogenous source will add pheromone to the same selected
     site in the world (e.g., near the center).

  4. update the pSpace (synchronous update!)

  5. update the dsurf display (i.e., update the screen display)

Note a report file is produced which includes the average distance
of the bugs to the location of the exogenous source of pheromones.

You can also set the rDebug parameter to values > 0 and
see the debugging messages, that report on various things happening
each time step.


-------------------------------------------------------------------
Exercises:

0. Try different diffusion constants, evaporation rates, and
   exogenous infusion rates.
   How fast do bugs "clump" under different conditions?

   Please read the diffuse() method in the Repast API docs online.
   Can you explain why we see the pattern of diffusion that we see, i.e.,
   why is the diffusion greatest in the NEWS directions from the source cell?

1. Try to make the bugs clump more tightly. For example,
   have the bugs look at all 8 possible 1 step moves, and
   pick the one that has the *most* pheromone (and is open) and move there.
   Compare the performance with this algorithm to the original?
   Ie, do the bugs clump faster?

2. In a new method added to AntPheromones1, add up the total pheromone in the space.
   Calculate the average and print the total and average,
   as well as the total amount added during the run, in the report files.

3. Can you think of a very simple measure that would measure "clumpiness"
   of the bugs?   Implement it and print out the values in the report files.

4. Create two external sources of pheromone, one with more pheromone added 
   each step than the other.  (Also increase the world size and number of bugs.)
   See how many bugs clump around each source (in the short/medium term, say).
   (You might want to create some measures that indicate how many bugs
    go to each source.)

5. Turn off the exogenous supply of pheromone.
   Have each bug put some pheromone in the world before it moves.
   Now what happens?

Harder:

n.   Add instance variables to count the number of times each bug
     moves for different reasons, i.e.
       - #times it sampled a random cell to find a better one,
         and it was not open
       - #times it sampled a random cell to find a better one and
         it was open, but it was not better.
       - #times it moved to a better cell
       - #times it moved to a randomly selected cell
     You could print this out for all the bugs, but that would be
     a lot of output.  Instead, in basic AntPheromones class
     add a method calculateAverages() which calculates the
     average number of each of those move types across all the bugs,
     and print those out in the report files.

Even harder:

n+1. Implement a "breeze" --- e.g., have the pheromone values
     "blown" to the right.
-------------------------------------------------------------------------