Introduction to the Swarm/RePast Heatbugs Demonstration Program

The heatbugs program is a simple demostration of a Swarm agent-based
model. This note first describes the kind of scenario that might lead
you to create a model like heatbugs. Then it describes how to run the
model, and some simple experiments you can do with it as it stands.

Imagine you want to model bugs which

    * Emit heat (or some other diffusable factor) into their enviroment 
      as they go about living.
    * Have a built-in "ideal temperature" in which they would prefer to 
      be immersed (i.e., they would prefer to have the environment around 
      them be at that temperature)
    * Have a sensor that allows them to sense the amount of heat coming 
      from their local enviroment in different directions
    * Have a mechanism that allows them to figure out in which direction 
      the ambient temperature is closer to their ideal temperature.
    * Have a mechanism to allow them to move (at a finite rate), e.g., 
      in the direction toward a desired temperature. 

You want to model heterogenous bugs, in that each bug has

    * its own ideal temperature (from some range of values)
    * its own heat emission rate (from some range of values) 

The environment the bugs live in has two main characteristics:

    * heat diffuses equally in all directions, at a rate proportional to 
      the heat differential between points.
    * heat evaporates at a rate proportional to the amount of heat. 

For an initial cut at the model, you want it very simple, just to see
how the bugs behave, to see how well they can each attain their ideal
temperature, and perhaps to see how simple parameters (e.g., diffusion
rate of heat) affects the behavior of the bugs and the resultant
global patterns of activity.

Even so, a model of such a system is likely to result in complex
dynamics that may be difficult to predict ahead of time. For example,
note that the bugs behavior is influenced by their local environment,
in that they try to move toward a temperature closer to their ideal
temperature. But also note that the bugs *change* their enviroment,
and the environment of other bugs around them. For example, a bug may
be in a spot that has a temperture that matches its ideal temperature,
but (1) just by being there the bug itself will change the enviroment,
because it gives off heat (2) other bugs may move into the area,
following their own heat-trophisms, and again change the environment
for the once happy bug.

And if you begin to allow the bugs to adapt in various ways, the
behavior is likely to become very complex indeed!

So...to make a simple initial model, lets assume:

    * N bugs live in a 2D discrete torus-shaped square lattice of 
      size X by X. No more than one bug can occupy a cell at a time.

    * Time is discrete. Every time step a number of changes take place, 
      i.e. bugs move, heat diffuses and evaporates.

    * Each cell in the world has a particular amount of heat present. 
      Heat diffuses synchronously between Moore-neighbor (8) cells, 
      and heat evaporates from each cell. In particular, the update rule 
      for heat in a cell is something like:
         H(t+1) = e * ( H(t) * k( AvgH(t) - H(t)) )
      where
         e = evaporation rate (0..1)
         k = diffusion rate (0..1)
         AvgH = average H in 8 neighbors of cell

    * bugs move asynchronously, one at a time.

    * heat difuses/evaporates synchronously.

Also, assume each bug:

* is created with a fixed idealTemperature, drawn at random from a fixed range.

* is created with a fixed outputHeat, drawn at random from a fixed range.

* Gets at most one chance to move each time step. It moves into the neighbor
  cell (8 cells 1 step away) which has a temperature that is
  a) warmer, if bug is too cold now (i.e., in a cell with heat < idealTemp)
  b) colder, if bug is too warm now (i.e., in a cell with heat > idealTemp)
  It selects the neighbor cell that has the most extreme heat (highest/lowest)
  of the type (hotter/colder) the bug wants to move toward.

* However, each bug also has a probability that it moves to a random neighbor 
  instead of moving "rationally."

* Each bug emits heat into the cell it occupies once each time step.

* Each bug has an "unhappiness" rating of its own situation, i.e., a function 
  of the heat in the cell it occupies and its ideal temperature. In particular:
      U = abs( H - I ) / max(H)
  where U is the unhappiness, H is heat present in the cell it occupies, 
  I is the agent's ideal temperature, and max(H) is the maximum possible 
  heat value.