Swarm at UM's CSCS -- Readme

As of May 2002:

The latest version of Swarm installed at CSCS is 2.1.1 . To use it, set (usually in the Makefile for your application):
SWARMHOME=/appl/swarm2.1.1-um/opt
for the optimized version, or to
SWARMHOME=/appl/swarm2.1.1-um/debug
for a debug version.
(NOTE: Currently Swarm2.1.1 is only installed on our Linux machines.)

Go to for pointers to various online docs for Swarm. In particular, novices should start with the Overview at UM, and then the Users Guide at UM.

Source for swarm2.1.1 is in /appl/swarm2.1.1-um/swarm-2.1.1/src , including some example applications in:
/appl/swarm2.1.1-um/UM-HeatbugsPlus/
/appl/swarm2.1.1-um/swarmapps-2.1.1/
/appl/swarm2.1.1-um/jheatbugs-2.1/
(a java version of heatbugs--not tested yet at UM!)

Some suggestions for starting with Swarm

1. Look at the HeatBugs sample application in
        /appl/swarm2.1.1-um/swarmapps-2.1.1/heatbugs
   It is fairly well commented; in addition,
   The Top-Down Introduction
   gives additional commentary on this application.
   To establish a copy of this model in your own directory space:
   
        cd ~
        mkdir Heatbugs
        cd Heatbugs
        cp /appl/swarm2.1.1-um/swarmapps-2.1.1/heatbugs/Makefile .
        cp /appl/swarm2.1.1-um/swarmapps-2.1.1/heatbugs/*.m .
        cp /appl/swarm2.1.1-um/swarmapps-2.1.1/heatbugs/*.h .
        cp /appl/swarm2.1.1-um/swarmapps-2.1.1/heatbugs/*.png .
        cp /appl/swarm2.1.1-um/swarmapps-2.1.1/heatbugs/*.scm .
        make
   

   and then to run your version:
   
        ./heatbugs
   

   There is also another brief introduction
   on heatbugs, its parameters, how to run it, etc.
 
2. A simple tutorial on using Probes, with the Heatbugs and UM-HeatbugsPlus
   demos, is given here.
   This goes step-by-step through some of the things
   you can do with probes, including watching agents
   state as the model runs, changing agents state
   and seeing how the dynamics change, and creating and 
   adding new agents to the model.

3. There is a series of tutorial programs, going from
   C to objectiveC to Swarm, in 
       /appl/swarm2.1.1-um/swarmapps-2.1.1/tutorial
   Several users have found going through this series
   of examples in order was a particularly good way
   to learn Swarm.   Please try this tuturial and let 
   me know how you liked it.  
   Start by reading the README file.

4. Some pointers to some useful sources of information
   about objective-C can be found at rlriolo's home page.
   There are also some on the SFI Swarm pages.
   In particular, there are some tutorials and
   the full text of the NeXT Objective-C Reference manual.

5. There is a simple Sugarscape implementation at the 
   SDG pages.  
   If you are interested in SugarScape, contact us
   as we have a version that adds several features to
   the basic version available through the SDG.

6. There is an enhanced version of the heatbugs demo
    UM-HeatbugsPlus, in the directory UM-HeatbugsPlus/  (see above).  
   This has a few new features (e.g., it uses a histogram object),
   and it shows how to use the parameter handling
   objects/approach provided by the tools in 
       UM-ExpTools-4/      (see below)
   There is a Readme.txt file in the UM-HeatbugsPlus
   directory which has more information on the features
   it provides and how to use them, and how to
   add those features to other Swarm programs.

8. The UM-ExpTools-4 directory contains
   tools that make it easier to:
   - processing of command line arguments, in GUI or Batch mode.
   - processing of parameters from an input-file
   - a pre-built set of parameters, including a RNG seed,
     report file name, output directory, inputfile, and run number.
   - automatic writing of parameters to the head of the report
     file (or other user opened files) in a format ready for re-reading,
     so that runs can be replicated.
   - utility macros and methods for RNG access, parameter access, etc.
   For more information, see the Readme.txt file in that
   directory.  

9. Note that the UM-ExpTools-4  make it possible to use the experiment
   management program, drone, which is described at the Drone home page.
   This provides easy ways to set up experiments that sweep
   arbitrary combinations of parameters, to log experiments,
   and to rerun all or parts of experiments, on single computers
   or on multiple computers which share disks space.



Please let me know if you have problems with Swarm,
or with the instructions in this file, or if you have
suggestions on how to make it easier to get started.
(Yes...the obvious suggestion is to have an introductory
manual for Swarm...we are all waiting for that!)

- Rick Riolo 
  (rlriolo@umich.edu)