---huntergatherers.nlogo

NETLOGO

; Script:  HunterGatherers.nlogo
; Author:  David Hyland-Wood ([e-mail])
; Date:    31 January 2004
; Modification History:
;          1 February 2004:  Turtles expend energy and recover it by eating.
;                            Patches recover energy with time.
;                            Turtles die if they don't eat.
;                            Turtles hunt for food (non-randomly).
;          5 February 2004:  Xenophobic turtles (simple avoidance).
;                            Turtles leave tracks (to allow xenophobic response).
;                            Hunger can override xenophobia if no other option exists.
;                            Forests can degrade so badly that they turn into Plains.
;          9 February 2004   Documentation.

; Pri
; 1.  TODO:  Implement capacity to learn to exploit environements (and forgetfulness)
; 2.  TODO:  Implement population changes when food surpluses/famine exist
; 3.  TODO:  Remove DBGs
; 4.  TODO:  Pull details into procedures
; Nice:  Define breed for hunter-gatherers and use (instead of default turtles)
; Nice:  Allow environment to be pre-defined
; NB:  If amountTurtlesEat/Burn is the same, they can't make up for lost energy.

; Variable Definitions
globals [ authorEmailAddress     ;; Contact info for bug reports
          turnTime               ;; Number of seconds for a unit time
          ;; numberOfTurtles        ;; Total number of turtles
          ;; maxTurtleEnergy        ;; Amount of energy each turtle has initially and can later attain
          ;; maxForestGrowthLimit   ;; Maximum energy that a Forest patch can attain
          ;; maxPlainsGrowthLimit   ;; Maximum energy that a Plains patch can attain
          initialForestFoliage   ;; Initial energy of a Forest patch
          initialPlainsFoliage   ;; Initial energy of a Plains patch
          forestDegradationLimit ;; Amount of energy a Forest has to reach to degrade into Plains
          ;; amountTurtlesEat       ;; Amount of energy turtles extract from a patch per unit time (if they can)
          ;; amountTurtlesBurn      ;; Amount of energy turtles use per unit time
          ;; amountForestsRecover   ;; Amount of energy forests recover per unit time
          ;; amountPlainsRecover    ;; Amount of energy plains recover per unit time
          foliageColors          ;; Colors for foliage, a list from lowest to highest energy levels
          foliageSumForest       ;; Total energy stored in Forest patches
          foliageSumPlains       ;; Total energy stored in Plains patches
          tracksExpireAfter      ;; How many turns do turtles tracks stay on patches?
        ]

turtles-own [ myEnergyLevel]     ;; myEnergyLevel = A turtle's energy level

patches-own [ patchType          ;; A patch's type (Forest or Plains)
              myFoliage          ;; A patch's energy level
              myGrowthLimit      ;; How much energy a patch can have
              tracks             ;; Tracks left by a turtle (kept for tracksExpireAfter turns)
              turtleTracksID     ;; The turtle which left the tracks
            ]

to startup                       ;; Ensure setup is run when the model is opened.  This prevents an error
  setup                          ;; if the "go" or "step" buttons are pressed before the "setup" button.
end


to setup

  ca                                    ;; clear the screen, kill all turtles, reset global variables to 0!
  
  ; Global Variable Settings
  ; CHANGE THESE TO IMPACT THE MODEL
  set authorEmailAddress "[e-mail]"  ;; Define the contact details for bug reports
  set turnTime 0.5                      ;; Define the length of time in seconds for one turn
  ;; set numberOfTurtles 2                 ;; Define the number of turtles to use
  ;; set maxTurtleEnergy 610               ;; Define the initial energy of a turtle
  ;; set maxForestGrowthLimit 1500         ;; Define the amount of energy a Forest patch may attain
  ;; set maxPlainsGrowthLimit 200           ;; Define the amount of energy a Plains patch may attain
  set initialForestFoliage maxForestGrowthLimit   ;; Define the initial energy of a Forest patch
  set initialPlainsFoliage maxPlainsGrowthLimit   ;; Define the initial energy of a Plains patch
  set forestDegradationLimit maxPlainsGrowthLimit / 2 ;; Define how much energy a Forest patch has when it gets permanently degraded
  ;; set amountTurtlesEat 210              ;; Define how much energy turtles gain from eating per unit time
  ;; set amountTurtlesBurn 200             ;; Define how much energy turtles lose per unit time
  ;; set amountForestsRecover 1            ;; Define how much energy forests gain per unit time
  ;; set amountPlainsRecover 1             ;; Define how much energy plains gain per unit time
  
  set foliageColors [ 9 69 68 67 66 65 64 63 ]  ;; Define patch colors from lowest to highest energy state
  
  set foliageSumForest 0                ;; Initialise energy recorded in Forest patches
  set foliageSumPlains 0                ;; Initialise energy recorded in Plains patches
  set tracksExpireAfter 20              ;; Define how long to keep tracks on patches
  
  ;; Set up the turtles
  crt numberOfTurtles                   ;; Make the turtles
  ask turtles
    [
      setxy ( random-normal 0 5 ) ( random-normal 0 5 )
      set color 90 + random 6       ;; TODO: Change this is a unique list (not green, wraps when needed)
      set myEnergyLevel maxTurtleEnergy  ;; Start with fully charged turtles
    ]

  ;; Set up a Forest and Plains
  ask patches
               ;; TODO - change amount of foliage to variable based on neighbors?
    [
      set tracks -1                                    ;; Start with no turtle tracks
      set turtleTracksID -1
      
      ifelse ( pxcor > -10 )
        [ ;; Forest
          set patchType "Forest"
          set myGrowthLimit maxForestGrowthLimit
          set myFoliage initialForestFoliage
          set pcolor findColor myFoliage
        ]
        [ ;; Plains
          set patchType "Plains"
          set myGrowthLimit maxPlainsGrowthLimit
          set myFoliage initialPlainsFoliage
          set pcolor findColor myFoliage
        ]
    ]
    
end

to go

  locals [ myEnergeticNeighbors  ;; Semi-cardinal neighbors with the most energy for a given turtle
           maxLocalFoliage       ;; The highest amount of foliage in any neighbor of a turtle
           energeticPatch        ;; A patch with the most energy neighboring a turtle
           foundSuitablePatch    ;; Boolean test to determine whether a turtle has found somewhere to move
           currentTurtle         ;; The current turtle ID, so it may be used in a patch context
         ]
           
   set foliageSumForest 0        ;; Record total energy stored in Forest each turn
   set foliageSumPlains 0        ;; Record total energy stored in Plains each turn

   ask turtles
    [
      set currentTurtle who         ;; Initialise the current turtle ID
      set foundSuitablePatch false  ;; Initialise tracking of next turtle's new patch
      
      ;; Make turtles look for food.
      ;; Find the most energy in neighboring patches
      set maxLocalFoliage myFoliage-of (max-one-of neighbors [myFoliage])
      while [ foundSuitablePatch = false ]
        [
          ;; Try to randomly choose a high-energy neighbor that has not had recent visitors.
          set energeticPatch random-one-of neighbors with
            [
              (myFoliage = maxLocalFoliage) and
              ( (turtleTracksID < 0) or (turtleTracksID = currentTurtle) ) and
              ( count turtles-here <= 0 )
            ]
          ifelse ( is-patch? energeticPatch )                       ;; Don't cause a runtime exception if there is
            [                                                       ;; no energeticPatch.
              set foundSuitablePatch true                           ;; Found a suitable patch!
            ]  ;; end if condition
            [  ;; If that didn't work, try to find just a neighbor that has not had recent visitors.
               set energeticPatch random-one-of neighbors with
                 [
                   (myFoliage != maxLocalFoliage) and
                   ( (turtleTracksID < 0) or (turtleTracksID = currentTurtle) ) and
                   ( count turtles-here <= 0 )
                 ]
               ifelse ( is-patch? energeticPatch )                ;; Don't cause a runtime exception if there is
                 [                                                ;; no energeticPatch.
                   set foundSuitablePatch true                    ;; Found a suitable patch!
                 ] ;; end if condition
                 [ ;; If that didn't work, try to just find a place to go!
                   ;; TODO:  NB:  Violates xenophobia when pushed.
                   set energeticPatch random-one-of neighbors with
                     [ ( count turtles-here <= 0 ) ]
                   ifelse ( is-patch? energeticPatch )                ;; Don't cause a runtime exception if there is
                     [                                                ;; no energeticPatch.
                       set foundSuitablePatch true                    ;; Found a suitable patch!
                     ] ;; end if condition
                     [ ;; If can't even find a place to go (because we are surrounded by patches
                       ;; containing turtles, a rare case!), just stay put.
                       set energeticPatch patch-here
                       ifelse ( is-patch? energeticPatch )                ;; Don't cause a runtime exception if there is
                         [                                                ;; no energeticPatch.
                           set foundSuitablePatch true                    ;; Found a suitable patch!
                         ] ;; end if condition
                         [ ;; This condition should never be reached.
                           user-message "Error!  Stopped.  Turtle " + who + " could not find an energetic patch." 
                             + " This should never happen and is evidence of a serious bug.  Please report it to "
                             + authorEmailAddress
                           stop
                         ] ;; end ifelse is-patch?
                   ] ;; end ifelse is-patch?
                 ]  ;; end ifelse is-patch?
            ]  ;; end ifelse is-patch?
            if (foundSuitablePatch = true)
              [
                   setxy ( pxcor-of energeticPatch ) ( pycor-of energeticPatch )  ;; Move turtle to new patch
                   set turtleTracksID who                         ;; Tell the patch who is on it
                   set tracks tracksExpireAfter                   ;; Start track counter on this patch
              ]
        ]  ;; end while
      
      ;; TODO:  Vary amount turtles eat/burn in this area to implement learning.
      set myEnergyLevel (myEnergyLevel - amountTurtlesBurn)    ;; All turtles burn energy every turn
      
      ;; Turtles only feed if the patch will support it
      if ( myFoliage > amountTurtlesEat )
        [ 
          set myFoliage (myFoliage - amountTurtlesEat)         ;; Patches are eaten...
          ifelse ( patchType = "Forest" )                      ;; Patches aren't allowed to grow this time
            [ set myFoliage (myFoliage - amountForestsRecover) ]
            [ set myFoliage (myFoliage - amountPlainsRecover) ]
          set myEnergyLevel (myEnergyLevel + amountTurtlesEat) ;; Turtles get energy by eating
          if (myEnergyLevel > maxTurtleEnergy) [ set myEnergyLevel maxTurtleEnergy ] ;; but not too much!
            ;; TODO:  Add population when lots of excess food?
        ]
        
      ;;plot-energy-of-turtle-0                                  ;; DBG:  Plot the energy of turtle 0
      if ( myEnergyLevel < 0 ) [ die ]                         ;; Turtles die if they run out of energy
      
     ]  ;; end ask turtles
     
  ask patches
    [
      
      if ( ( patchType = "Forest" ) and ( myFoliage <= forestDegradationLimit ) )
        [ set patchType "Plains" ]                               ;; Degrade badly damaged Forest into Plains
            
      ifelse ( patchType = "Forest" )
        [ 
          set myFoliage (myFoliage + amountForestsRecover)     ;; Grow foliage
          set foliageSumForest foliageSumForest + myFoliage    ;; Determine total energy level
        ]
        [ set myFoliage (myFoliage + amountPlainsRecover)
          set foliageSumPlains foliageSumPlains + myFoliage
        ]
        
      if ( myFoliage > maxForestGrowthLimit )                  ;; Ensure patches can't overgrow
        [ set myFoliage maxForestGrowthLimit ]
      if ( myFoliage > maxPlainsGrowthLimit ) and ( patchType = "Plains" ) [ set myFoliage maxPlainsGrowthLimit ]
        
      set pcolor findColor myFoliage                           ;; Update patch coloring
      
      if ( tracks > 0 )                                        ;; If this patch has tracks...
        [
          set tracks tracks - 1                                ;; Expire tracks slowly
          if ( tracks <= 0 )
            [ set turtleTracksID -1 ]                          ;; Expire turtle ID for tracks when tracks expire
        ]
    ]
      
  plot-patch-energy-levels-by-type                             ;; Plot total patch energy levels by type
  plot-number-of-turtles                                       ;; Plot the total number of turtles
  
  wait turnTime                                                ;; Slow progress
  
end

to-report findColor [ energyLevel ]

  ;; Returns a color to match a patch's energy level
  locals [ index ]  ;; Index in the array foliageColors
  
  set index ( energyLevel * ( length foliageColors - 1 ) ) / maxForestGrowthLimit
            ;; NB: Sic (compares to maxForestGrowthLimit as global maximum)
  report item index foliageColors

end

to plot-patch-energy-levels-by-type

  ;; Plot patches' energy levels by type
  
  set-current-plot "Patch Energy Levels by Type"
  set-current-plot-pen "Forest"
  plot foliageSumForest
  set-current-plot-pen "Plains"
  plot foliageSumPlains
  
end

to plot-number-of-turtles