Tipping1/Readme.txt
-------------------

[ From /users/rlr/RePast/Demos-3/Tipping1/ ]

This is a modified version of the basic RePast SchellingGIS demo.

This version has had several features added to it:

- Two report files are produced, reporting on aggregate values each step.
  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:   
        /users/rlr/RePast/Demos-3/Tipping1/bin/guirun.sh --help
  to see a list of all the parameters (and their aliases).

- The model can be run in guimode via a script:
     /users/rlr/RePast/Demos-3/Tipping1/bin/guirun.sh
  You can also set parameters on the run command:

     /users/rlr/RePast/Demos-3/Tipping1/bin/guirun.sh \
              numAgents=200 thresholdRed=0.2 thresholdGreen=0.3

  NOTE: that \ tell linux to continue reading the command on the next line!

     /users/rlr/RePast/Demos-3/Tipping1/bin/guirun.sh nA=200 rMP=0.001 S=42 rN=01

  Note the above command uses parameter aliases.

- The model can be run in batch mode (no gui) via the shell script:

     /users/rlr/RePast/Demos-3/Tipping1/bin/batchrun.sh \
         T=500 numAgents=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 Tipping1 .)

- The model can be run using "ant" (a make like utility).
  For example, if you are the owner of the program/project dir,
  to run in GUI mode via the ant command (using the build.xml file),
      ant run -Dargs="--help"   
      ant run -Dargs="numAgents=200 thresholdRed=0.2 thresholdGreen=0.3"
      ant run -Dargs="numAgents=200 randomMoveProbability=0.001 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).

  ***
  *** NOTE:  in batch mode, if the randomMoveProbability=0.0, and there
  ***        were no moves in a give step, it stops the sim run!!
  ***        if you want to turn that off, see the step() method in BatchModel.java 
  ***

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

There is a simple script to make a copy of Tipping1 into some other
directory, even changing the name (eg to Tipping2) 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/Tipping1 by entering:

   /users/rlr/RePast/Demos-3/bin/copyProject.pl \
      -S/users/rlr/RePast/Demos-3 -OTipping1  -R/users/YOURLOGIN/ -PTipping1

where you replace YOURLOGIN with your login.
NOTE: the \ at the end of the first line above tells linux to continue
      reading the same command on the next line.
      You can put all that on one line if you leave that \ out.

If you want to use these scripts (which you do!):
   bin/compile.sh
   bin/guirun.sh
   bin/batchrun.sh
you must edit those files (eg with emacs) and change these lines:
   PROJECTDIR=/users/rlr/RePast/Demos-3/Tipping1
   PACKAGENAME=Tipping1
to match any changes in the location of the project or the package name, e.g.,
change just the path to:
   PROJECTDIR=/users/YOURLOGIN/RePast/Tipping1

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 .

Note if you are the owner of the Tipping1/ project dir,
you can cd into that directory and then run it without the full path, eg.

   bin/guirun.sh numAgents=200 thresholdRed=0.2 thresholdGreen=0.3

To get a feel for how the model behaves, play around with the
threshold parameters and randomMoveProbability. For instance:

Click the initialize button (semi-circle arrow)
Two types. Threshold is 0.20 -- will stay put if 79% different neighbors!
Click step button a few times  (vertical bar, right wedge) 
Stops -- everyone happy.
Note slight increase in segregation (see graphs, and in world).
Repeat:
  Set randomMoveProbability to 1, step a few times.
  Set rMP=0, run (right wedge) till stops
Note average segregation at end of each "run".
Change thresholds to 0.3, run;  0.4, run.  (randomize between runs)
Change thresholds back to 0.2, rMP=0.3, run/pause (two vertical bars)
Change to rMP=0.1, run; 0.01, run; 0.001 run;
======================================================================================