Heatbugs preview image

1 collaborator

Uri_dolphin3 Uri Wilensky (Author)



Tagged by Reuven M. Lerner about 9 years ago

Model group CCL | Visible to everyone | Changeable by group members (CCL)
Model was written in NetLogo 5.0.4 • Viewed 595 times • Downloaded 38 times • Run 1 time
Download the 'Heatbugs' modelDownload this modelEmbed this model

Do you have questions or comments about this model? Ask them here! (You'll first need to log in.)


Heatbugs is an abstract model of the behavior of biologically-inspired agents that attempt to maintain an optimum temperature around themselves. It demonstrates how simple rules defining the behavior of agents can produce several different kinds of emergent behavior.

Heatbugs has been used as a demonstration model for many agent-based modeling toolkits. We provide a NetLogo version to assist users in learning and comparing different toolkits. It demonstrates coding techniques in NetLogo and may be useful as a starting point for building other models.

While this NetLogo model attempts to match the Repast and Swarm versions (see "Credits" below), we haven't done a rigorous comparative analysis of the different versions, so it is possible that there are small inadvertent differences in the underlying rules and behavior.


The bugs move around on a grid of square "patches". A bug may not move to a patch that already has another bug on it.

Each bug radiates a small amount of heat. Heat gradually diffuses through the world; some heat is lost to cooling.

Each bug has an "ideal" temperature it wants to be. The bigger the difference between the temperature of the patch where the bug is and the bug's ideal temperature, the more "unhappy" the bug is. When a bug is unhappy, it moves. If it is too hot, it moves to the coolest adjacent empty patch. Conversely, if a bug is too cold, it moves to the warmest adjacent empty patch. (Note that these bugs aren't smart enough to always move to the best available patch.)


After choosing the number of bugs to create, and setting the model variables, press the GO button to set the heatbugs into motion.

BUG-COUNT: The number of bugs that will inhabit the model

EVAPORATION-RATE: The percentage of the world's heat that evaporates each cycle. A lower number means a world which cools slowly, a higher number is a world which cools quickly.

DIFFUSION-RATE: How much heat a patch (a spot in the world) diffuses to its neighbors. A higher number means that heat diffuses through the world quickly. A lower number means that patches retain more of their heat.

MIN/MAX-IDEAL-TEMP: The minimum and maximum ideal temperatures for heatbugs. Each bug is given an ideal temperature between the min and max ideal temperature.

MIN/MAX-OUTPUT-HEAT: The minimum and maximum heat that heatbugs generate each cycle. Each bug is given a output-heat value between the min and max output heat.

RANDOM-MOVE-CHANCE: The chance that a bug will make a random move even if it would prefer to stay where it is (because no more ideal patch is available).

DEEP-FREEZE: This button removes all heat from the world.

HEAT-UP: This button adds MAX-OUTPUT-HEAT to every patch in the world.

Beneath the view are two "Color By:" buttons. The IDEAL-TEMP button colors the bugs according to their IDEAL-TEMP value. Bugs with higher IDEAL-TEMP values will be brighter. The HAPPINESS button does the same, but is based upon the HAPPINESS value of each agent, with happier bugs being brighter.

The WATCH-HAPPIEST and WATCH-SADDEST buttons will highlight the happiest or saddest bug at the time the button is pressed.


Depending on their ideal temperatures, some bugs will tend to clump together, while others will tend to avoid all other bugs, and others still flutter around the edges of clumps. All of these behaviors are affected as well by the evaporation rate.

The diffusion rate affects the cohesiveness of clumps. If diffusion-rate is slow, many tiny clumps form. Why?

Most interesting behaviors occur when the number of bugs, how much heat they generate, and how quickly the world cools are balanced such that excessive heat does not build up.



Vary EVAPORATION-RATE in relation to the output-heat range of the bugs.

Use the HEAT-UP button to scramble clumped heatbugs and watch as they re-assemble into new clumps.


Randomize the amount of heat bugs generate each cycle.

Allow users to introduce heat into the system with the mouse.


n-of and sprout together let us initially place each bug on its own patch with a minimum of code.

Notice how the code does not make any use of X and Y coordinates. The neighbors and move-to primitives take care of sensing and motion on a toroidal grid without the need for any explicit coordinate math.

The diffuse command is used to diffuse the heat around the patch grid.




Swarm version of Heatbugs -- http://www.swarm.org/wiki/ExamplesofSwarm_applications

RePast version of Heatbugs -- http://repast.sourceforge.net/examples/index.html


If you mention this model in a publication, we ask that you include these citations for the model itself and for the NetLogo software:

  • Wilensky, U. (2004). NetLogo Heatbugs model. http://ccl.northwestern.edu/netlogo/models/Heatbugs. Center for Connected Learning and Computer-Based Modeling, Northwestern Institute on Complex Systems, Northwestern University, Evanston, IL.
  • Wilensky, U. (1999). NetLogo. http://ccl.northwestern.edu/netlogo/. Center for Connected Learning and Computer-Based Modeling, Northwestern Institute on Complex Systems, Northwestern University, Evanston, IL.


Copyright 2004 Uri Wilensky.


This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

Commercial licenses are also available. To inquire about commercial licenses, please contact Uri Wilensky at uri@northwestern.edu.

This model was created as part of the projects: PARTICIPATORY SIMULATIONS: NETWORK-BASED DESIGN FOR SYSTEMS LEARNING IN CLASSROOMS and/or INTEGRATED SIMULATION AND MODELING ENVIRONMENT. The project gratefully acknowledges the support of the National Science Foundation (REPP & ROLE programs) -- grant numbers REC #9814682 and REC-0126227.

Comments and Questions

Please start the discussion about this model! (You'll first need to log in.)

Click to Run Model

globals [ color-by-unhappiness? ]

  ideal-temp       ;; The temperature I want to be at
  output-heat      ;; How much heat I emit per time step
  unhappiness      ;; The magnitude of the difference between my ideal
                   ;;   temperature and the actual current temperature here

  temp             ;; short for "temperature"

to setup
  set color-by-unhappiness? false

  ;; creating the bugs the following way ensures that we won't
  ;; wind up with more than one bug on a patch
  ask n-of bug-count patches [
    sprout 1 [
      set ideal-temp  min-ideal-temp  + random (max-ideal-temp  - min-ideal-temp)
      set output-heat min-output-heat + random (max-output-heat - min-output-heat)
      set unhappiness abs (ideal-temp - temp)
      face one-of neighbors
      set size 2  ;; easier to see
  ;; plot the initial state of the system

to color-by-ideal-temp
  ;; when scaling the color of turtles, adjust the value
  ;; range by this amount to avoid turtles being too dark or too light.
  let range-adjustment ( max-ideal-temp - min-ideal-temp ) / 2
  set color scale-color lime ideal-temp ( min-ideal-temp - range-adjustment )
                                        ( max-ideal-temp + range-adjustment )

to color-by-unhappiness [ max-unhappiness ]
  set color scale-color blue unhappiness  max-unhappiness 0

to go
  if not any? turtles [ stop ]
  ;; diffuse heat through world
  diffuse temp diffusion-rate
  ;; The world retains a percentage of its heat each cycle.
  ;; (The Swarm and Repast versions have 1.0 meaning no
  ;; evaporation and 0.0 meaning complete evaporation;
  ;; we reverse the scale to better match the name.)
  ask patches [ set temp temp * (1 - evaporation-rate) ]
  ;; agentsets in NetLogo are always in random order, so
  ;; "ask turtles" automatically shuffles the order of execution
  ;; each time.
  ask turtles [ step ]

to recolor-turtles
  if color-by-unhappiness?
    let max-unhappiness max [unhappiness] of turtles
    ask turtles [ color-by-unhappiness max-unhappiness ]

to recolor-patches
  ;; hotter patches will be red verging on white;
  ;; cooler patches will be black
  ask patches [ set pcolor scale-color red temp 0 150 ]

to step  ;; turtle procedure
  ;; my unhappiness is the magnitude or absolute value of the difference
  ;; between by ideal temperature and the temperature of this patch
  set unhappiness abs (ideal-temp - temp)
  ;; if unhappy and not at the hottest neighbor,
  ;; then move to an open neighbor
  if unhappiness > 0
    [ ifelse random-float 100 < random-move-chance
        [ bug-move one-of neighbors ]
        [ bug-move best-patch ] ]
  set temp temp + output-heat

;; find the hottest or coolest location next to me; also
;; take my current patch into consideration

to-report best-patch  ;; turtle procedure
  ifelse temp < ideal-temp
    [ let winner max-one-of neighbors [temp]
      ifelse [temp] of winner > temp
        [ report winner ]
        [ report patch-here ] ]
    [ let winner min-one-of neighbors [temp]
      ifelse [temp] of winner < temp
        [ report winner ]
        [ report patch-here ] ]

to bug-move [target]  ;; turtle procedure
  ;; if we're already there, there's nothing to do
  if target = patch-here [ stop ]
  ;; move to the target patch (if it is not already occupied)
  if not any? turtles-on target [
    face target
    move-to target
  set target one-of neighbors with [not any? turtles-here]
  if target != nobody [ move-to target ]
  ;; The code above is a bit different from the original Heatbugs
  ;; model in Swarm.  In the NetLogo version, the bug will always
  ;; find an empty patch if one is available.
  ;; In the Swarm version, the bug picks a random
  ;; nearby patch, checks to see if it is occupied, and if it is,
  ;; picks again.  If after 10 tries it hasn't found an empty
  ;; patch, it gives up and stays where it is.  Since each try
  ;; is random and independent, even if there is an available
  ;; empty patch the bug will not always find it.  Presumably
  ;; the Swarm version is coded that way because there is no
  ;; concise equivalent in Swarm/Objective C to NetLogo's
  ;; 'one-of neighbors with [not any? turtles-here]'.
  ;; If you want to match the Swarm version exactly, remove the
  ;; last two lines of code above and replace them with this:
  ; let tries 0
  ; while [tries <= 9]
  ;   [ set tries tries + 1
  ;     set target one-of neighbors
  ;     if not any? turtles-on target [
  ;       move-to target
  ;       stop
  ;     ]
  ;   ]

;;; the following procedures support the two extra buttons
;;; in the interface

;; remove all heat from the world

to deep-freeze
  ask patches [ set temp 0 ]

;; add max-output-heat to all locations in the world, heating it evenly

to heat-up
  ask patches [ set temp temp + max-output-heat ]

; Copyright 2004 Uri Wilensky.
; See Info tab for full copyright and license.

There are 10 versions of this model.

Uploaded by When Description Download
Uri Wilensky over 9 years ago Updated to NetLogo 5.0.4 Download this version
Uri Wilensky almost 10 years ago Updated version tag Download this version
Uri Wilensky almost 10 years ago Updated to version from NetLogo 5.0.3 distribution Download this version
Uri Wilensky over 10 years ago Updated to NetLogo 5.0 Download this version
Uri Wilensky over 12 years ago Updated from NetLogo 4.1 Download this version
Uri Wilensky over 12 years ago Updated from NetLogo 4.1 Download this version
Uri Wilensky over 12 years ago Updated from NetLogo 4.1 Download this version
Uri Wilensky over 12 years ago Updated from NetLogo 4.1 Download this version
Uri Wilensky over 12 years ago Model from NetLogo distribution Download this version
Uri Wilensky over 12 years ago Heatbugs Download this version

Attached files

File Type Description Last updated
Heatbugs.png preview Preview for 'Heatbugs' over 9 years ago, by Uri Wilensky Download

This model does not have any ancestors.

This model does not have any descendants.