heatbugs3/Readme.txt
--------------------
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/education/CSCS-courses/cscs530-07w/Handouts/
        heatBugs-conceptual-model.txt

which is the same as
   /users/rlr/RePast/Demos-3/heatBugs-conceptual-model.txt

This version has had several features beyound the Repast demo version:

- 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, by default named
      report.00    and   report.xml.00
  reporting on aggregate values each step (avgUnhappiness, avgSize).  
  These reports are in plain ascii and xml formats, respectively.
  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 xml report file can be used as an input file to replicate a run, e.g.:
      bin/batchrun.sh iPFN=report.xml.00 rFN=report-rerun 
  This next command:
      diff  report-rerun.00 report.00
  should so only the reportFileName is different in the two report files!

- 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:  
      /users/rlr/RePast/Demos-3/heatBugs3/bin/guirun.sh --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 a simple script, e.g.:

    ~rlr/RePast/Demos-3/heatBugs3/bin/guirun.sh numBugs=200 evapRate=0.95
    ~rlr/RePast/Demos-3/heatBugs3/bin/guirun.sh nB=200 rMP=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).
  If you create your own heatBugs3 directory with the scripts and program in it,
  you can leave off the full path, of course.

- The model can be run in GUI mode using ant (and the build.xml file):
      ant run -Dargs="numBugs=200 evapRate=0.95"
  ("ant" is a bit like the linux "make" command.)

- The model can be run in batch mode (no gui) via the following shell script
  (assuming you are in the directory with the bin/ directory):

     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 heatBugs3 .)

- See the file notes-run-examples.txt in this directory (heatBugs3/)
  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/heatBugs3 by entering:

 /users/rlr/RePast/Demos-3/bin/copyProject.pl 
    -S/users/rlr/RePast/Demos-3 -XheatBugs3 \
    -R/users/YOURLOGIN/YourDir -PheatBugs3

where you replace YOURLOGIN/YourDir with your login and the path
to the place you want the project to be placed.

If you want to use these scripts (and you do!):
   bin/compile.sh
   bin/guirun.sh
   bin/batchrun.sh
you must edit those and change these lines:
   PROJECTDIR=/users/rlr/RePast/Demos-3/heatBugs3
   PACKAGENAME=heatbugs3
to match any changes in the location of the project or the package name.

After you have done that, you can compile the program with
   bin/compile.sh
and then run it as described above with the two scripts guirun.sh or batchrun.sh .

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

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.
======================================================================================