Heatbugs is the Canonical Swarm Application, a simple but nontrivial
complex system. It is the best place to start when reading Swarm
source code: it is intended to provide a guide for writing your own
models. Heatbugs is is copiously commented and uses several nontrivial
aspects of Swarm's capabilities.

The heatbugs simulation takes place in a 2d world with wraparound
boundaries. Across the world is one property, heat, that diffuses and
evapourates over time. Living in the world are a bunch of "heatbugs",
critters that add heat to the world and each try to seek their own
local idea of an optimal temperature. The interaction between
individual heatbugs locally optimizing and the shared heat variable is
what yields the interesting behaviour in the simulation. In the
default parameters, they tend to cluster for warmth.

Assuming you're running on an X terminal, a control panel will pop up
as well as a couple of forms for parameters. To run the simulation,
just press "Go". Try clicking with the right mouse button on the
heatbugs in the display of the world, or also on the slots in the
probe windows. Try quitting and restarting with a different set of
parameters (go to one of the parameters lots, type in a new value, and
hit return).


As a piece of code, heatbugs makes use of several features without
being overwhelming in its scope. It's a good place to learn how to
build a simulation that uses several library objects, both directly
and by subclassing them.

A heatbugs simulation uses two swarms. The HeatbugModelSwarm stores
all the objects needed for the model itself:
  a bunch of Heatbugs (as implemented in HeatBug.m) stored in a list
  a HeatSpace object (as implemented in HeatSpace.m, inherits from Diffuse)
  a Grid2d object maintaining Heatbug positions (from the Space library)

The HeatbugModelSwarm runs underneath a controlling swarm. In the case
of running with graphics, a HeatbugObserverSwarm is created to store
all the visualization objects. These include:
  an instance of a HeatbugModelSwarm
  probes on the HeatbugModelSwarm and HeatbugObserverSwarm to allow
    the user to set parameters
  a control panel (created in HeatbugObserverSwarm's parent class)
  a worldDisplay window to show heat and agents (a combination of
    a ZoomRaster, a Ca2dDisplay, and an Object2dDisplay)
  a graph of average unhappiness (a combination of a BLTGraph, an
    Average, and an ActiveGraph)
  probe window showing one heatbug's state (by default)

If you're not running graphics code (as indicated by having no DISPLAY
environment variable set), then instead of creating a HeatbugObserverSwarm
to control model execution we use a HeatbugBatchSwarm. The batch swarm
is simpler. It contains:
  an instance of a HeatbugModelSwarm
  an averager object
  special file handling code to write out data.