heatbugs2/Readme.txt
--------------------

[ From /appl/repast/Demos-3/heatBugs2/ ]

This is a modified version of the basic RePast heatbugs demo,
itself copied from the original Swarm heatbugs demo.
For a "conceptual" level description of this model, see
   cscs.umich.edu/lab/documentation/RePastStuff/Demos-2/heatBugs/heatBugs-conceptual-model.txt
which is the same as
   /users/rlr/RePast/Demos-2/heatBugs/heatBugs-conceptual-model.txt

This version has had several features added to it:

- Bug's have a size, currently just assigned from a normal distribution.
  This could be tied to unHappiness.
  In the display, size > avgSize are closed circles, <= avgSize are open.

- If idealTemp < heatHere (where bug is), color is blue; otherwise its red.

- Graph plots average unHappiness and size. 

- Some parameters can be changed during the run and have immediate effect:
     randomMoveProb, evapRate, diffusionConstant

- Two report files are produced, reporting on aggregate values each step
  (avgUnhappiness, avgSize).  These reports are in plain ascii and xml formats.
  The report files also have the parameter values at the top of the file,
  as well as record of changes to parameters during the run embedded.
  The report file can be used as an input file to replicate a run.

- A parameter rDebug can be set to 1, 2, ... to control the printing
  of debugging messages added to the methods.

- Parameters can be set on the run command, and other features have been 
  added so the model can be run via Drone.
  There are a number of generic paramters useful for running with drone.
  Enter the command:   ant run -Dargs="--help"
  to see a list of all the parameters (and their aliases).
  This is all possible because the class HeatBugsModel extends ModelParameters,
  a class that provides some basic parameters and parameter processing.

- The model can be run in GUI mode via the ant command (using the build.xml file):
      ant run -Dargs="--help"   
      ant run -Dargs="numBugs=200 evapRate=0.95"
      ant run -Dargs="numBugs=200 randomMoveProbability=1.0 S=424242111 rN=01"
  Note the last one includes the RNG seed and the runNumber (rN), the later
  being appended to the report files (report.01 and report.xml.01).

- The model can be run in batch mode (no gui) via the shell script:
     bin/batchrun.sh T=500 numBugs=200 randomMoveProbability=1.0 rN=02
  This runs for 500 steps, with default parameters except for those over-ridden
  by the paramter=value settings on that command line.
  (Note you will have to change 3 lines near the stop of bin/batchrun.sh
  if you make your own copy of heatBugs2 .)

- See the file notes-run-examples.txt in this directory (heatbugs2/)
  for more example runs.

- To see how to set up a drone experiment control file, see the file
       exp01.ctrl
  in this directory.   Of course to use it you will want to change
  the rootDir, the programDir, the email address and any base parameters
  and the sweep line, as appropriate.
  Note that the file
       exp01.in
  has the "base parameters" for this exp01.ctrl file.  Its a good idea
  to make such a *.in file and test it by
       bin/batchrun.sh  iPFN=exp01.in
  to be sure you have the format, parameter names, etc, correct.
  **Note that the input parameters are in xml format.
  You can see the proper format at the top of any report.xml file
  produced when this program is run.
  ***NOTE: You will have to change the exp*.ctrl files to be sure
    they point to your version of this program, your email address, etc.

There is a simple script to make a copy of heatBugs2 into some other
directory, even changing the name (eg to heatBugs3) if you wish:
    bin/copyProject.pl -h 
for information on what it does and how to use it.
For example you can make a copy of this project in your
directory /users/YOURLOGIN/heatBugs2 by entering:

 /users/rlr/RePast/Demos-3/bin/copyProject.pl -S/users/rlr/RePast/Demos-2 \
         -XheatBugs2  -R/users/YOURLOGIN/ -PheatBugs2

where you replace YOURLOGIN with your login.


-----------------------------------------------------------------------------
FYI, but you will generally not need to do this:

See the file Notes/notes-setup.txt for the general instructions for making a
copy of a RePast project like heatBugs2.  (That file tells how to set up
heatBugs2 from heatBugs1, but you just need to translate the package, file
and directory names to make some new version, in your own space.)

The file Notes/notes-make-drone-ready.txt give a general description,
followed by details, of the steps I took to convert the basic RePast
heatbugs demo (i.e., heatBugs1) to heatBugs2, which is ready for use
with drone.  Similar steps can be used to convert most RePast programs
into versions that will be usable by drone.
    

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