ABM - Butterfly Hilltopping

xholonWorkbook.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--Xholon Workbook http://www.primordion.com/Xholon/gwt/ MIT License, Copyright (C) Ken Webb, Thu Nov 14 2019 12:18:04 GMT-0500 (Eastern Standard Time)-->
<XholonWorkbook>

<Notes><![CDATA[
Xholon
------
Title: ABM - Butterfly Hilltopping
Description: 
Url: http://www.primordion.com/Xholon/gwt/
InternalName: 1f6ec1a1a65fd7304950f2d19d0862f2
Keywords: 

My Notes
--------
November 11, 2019

In this Xholon workbook, I reimplement the Butterfly Hilltopping Agent-based Model (ABM) described in ref 1 and 2.

sin
---
JavaScript Math.sin(radians)  A number (given in radians).
NetLogo    sin (degrees)      Reports the sine of the given angle. Assumes angle is given in degrees.

The ODD description obtained from ref 2:
---------------------------------------
# Butterfly Model ODD Description
This file describes the model of Pe’er et al. (2005). The description is taken from Section 3.4 of Railsback and Grimm (2019). The file uses the markup language used by NetLogo's Info tab starting with NetLogo version 5.0.

## 1. Purpose and patterns
The model was designed to explore questions about virtual corridors. Under what conditions do the interactions of butterfly hilltopping behavior and landscape topography lead to the emergence of virtual corridors, that is, relatively narrow paths along which many butterflies move? How does variability in the butterflies’ tendency to move uphill affect the emergence of virtual corridors? This model does not represent a specific place or species of butterfly, so only general patterns are used as criteria for its usefulness for answering these questions: that butterflies can reach hilltops, and that their movement has a strong stochastic element representing the effects of factors other than elevation.

## 2. Entities, State Variables, and Scales
The model has two kinds of entities: butterflies and square patches of land. The patches make up a square grid landscape of 150 × 150 patches, and each patch has one state variable: its elevation. Butterflies are characterized only by their location, described as the patch they are on. Therefore, butterfly locations are in discrete units, the x- and y- coordinates of the center of their patch. Patch size and the length of one time step in the simulation are not specified because the model is generic, but when real landscapes are used, a patch corresponds to 25 × 25 m<sup>2</sup>. Simulations last for 1000 time steps; the length of one time step is not specified but should be about the time it takes a butterfly to move 25–35 m (the distance from one cell to one of its neighbor cells).

## 3. Process Overview and Scheduling
There is only one process in the model: movement of the butterflies. On each time step, each butterfly moves once. The order in which the butterflies execute this action is unimportant because there are no interactions among the butterflies.

## 4. Design Concepts
The _basic principle_ addressed by this model is the concept of virtual corridors—pathways used by many individuals when there is nothing particularly beneficial about the habitat in them. This concept is addressed by seeing when corridors _emerge_ from two parts of the model: the adaptive movement behavior of butterflies and the landscape they move through. This _adaptive behavior_ is modeled via a simple empirical rule that reproduces the behavior observed in real butterflies: moving uphill. This behavior is based on the understanding (not included in the model) that moving uphill leads to mating, which conveys fitness (success at passing on genes, the presumed ultimate objective of organisms). Because the hilltopping behavior is assumed a priori to be the objective of the butterflies, the concepts of _Objectives_ and _Prediction_ are not explicitly considered. There is no _learning_ in the model.

_Sensing_ is important in this model: butterflies are assumed able to identify which of the surrounding patches has the highest elevation, but to use no information about elevation at further distances. (The field studies of Pe’er 2003 addressed this question of how far butterflies sense elevation differences.)

The model does not include _interaction_ among butterflies; in field studies, Pe’er (2003) found that real butterflies do interact (they sometimes stop to visit each other on the way uphill) but decided it is not important to include interaction in a model of virtual corridors.

_Stochasticity_ is used to represent two sources of variability in movement that are too complex to represent mechanistically. Real butterflies do not always move directly uphill, likely because of (1) limits in the ability of the butterflies to sense the highest area in their neighborhood, and (2) factors other than topography (e.g., flowers that need investigation along the way) that influence movement direction. This variability is represented by assuming butterflies do not move uphill every time step; sometimes they move randomly instead. Whether a butterfly moves directly uphill or randomly at any time step is modeled stochastically, using a parameter _q_ that is the probability of an individual moving directly uphillinstead of randomly.

_Collectives_ are not represented in this model.

To allow _observation_ of the two patterns used to define the model’s usefulness, we use graphical display of topography and butterfly locations. Observing virtual corridors requires a specific “corridor width” measure that characterizes the width of butterfly paths from their starting patches to hilltops.

## 5. Initialization
The topography of the landscape (the elevation of each patch) is initialized when the model starts. Two kinds of landscapes are used in different versions of the model: (1) a simple artificial topography, and (2) the topography of a real study site, imported from a file containing elevation values for each patch. The butterflies are initialized by creating five hundred of them and dispersing them throughout the landscape: each butterfly’s initial location is set to a patch selected randomly from among all patches.

## 6. Input Data
The environment is assumed to be constant, so the model has no input data.

## 7. Submodels
The movement submodel defines exactly how butterflies decide whether to move uphill or randomly. First, to “move uphill” is defined specifically as moving to the neighbor patch that has the highest elevation; if two patches have the same elevation, one is chosen randomly. “Move randomly” is defined as moving to one of the neighboring patches, with equal probability of choosing any patch. “Neighbor patches” are the eight patches surrounding the butterfly’s current patch. The decision of whether to move uphill or randomly is controlled by the parameter _q_, which ranges from 0.0 to 1.0 (_q_ is a global variable: all butterflies use the same value). On each time step, each butterfly draws a random number from a uniform distribution between 0.0 and 1.0. If this random number is less than _q_, the butterfly moves uphill; otherwise, the butterfly moves randomly.

## CREDITS AND REFERENCES
Pe’er, G., Saltz, D. & Frank, K. 2005. Virtual corridors for conservation management. _Conservation Biology_, 19, 1997–2003.

Pe’er, G. 2003. Spatial and behavioral determinants of butterfly movement patterns in topographically complex landscapes. Ph.D. thesis, Ben-Gurion University of the Negev.

Railsback, S. & Grimm, V. 2018. _Agent-based and individual-based modeling: A practical introduction, Second edition_. Princeton University Press, Princeton, NJ.


Paste the following into a Patch:
--------------------------------------
<Butterfly><script>
var me, beh = {
postConfigure: function() {
  me = this.cnode.parent();
  me.println("Butterfly01");
  me.action("color 25"); // orange
  me.action("pd");
  me.action("fd 10");
  me.action("rt 90");
  me.action("fd 10");
  me.action("rt 90");
  me.action("fd 10");
  me.action("rt 90");
  me.action("fd 10");
  me.action("rt 90");
}
}
//# sourceURL=Butterfly01.js
</script></Butterfly>

Or this:
-------
<Butterfly roleName="Franklin">
  <Attribute_String>
    pu
    color 25
    pd
    fd 10
    rt 90
    fd 10
    rt 90
    fd 10
    rt 90
    fd 10
  </Attribute_String>
</Butterfly>

Control butterfly from Dev Tools:
--------------------------------
var space = xh.root().first().first().next().next();
console.log(space.name()); // "space_49"
var bfly = space.xpath("descendant::Butterfly");
console.log(bfly);
bfly.action("fd 2");

Create and control butterflies from Dev Tools:
---------------------------------------------


References
----------
(1) http://www.railsback-grimm-abm-book.com/
    Agent-based and Individual-based Modeling: A Practical Introduction
    Steven F. Railsback and Volker Grimm
    second edition
    2019

(2) http://www.railsback-grimm-abm-book.com/E2-Downloads/Chapter04/ButterflyModelODD.txt
    the above ODD document starting with "# Butterfly Model ODD Description"

]]></Notes> 

<params>
  <param name="MaxProcessLoops" value="1000"/>
</params>

<_-.XholonClass>
  <PhysicalSystem/>
  <!--<Space/>-->
  <TurtleObserver/>
  
  <Butterfly/>
  <!--<Patch/>-->
  
</_-.XholonClass>

<xholonClassDetails>
  
  <!--<Space implName="org.primordion.xholon.base.PatchOwner"/>-->
  <TurtleObserver xhType="XhtypePureActiveObject">
    <port name="port" index="0" connector="#xpointer(ancestor::PhysicalSystem/Space)"/>
  </TurtleObserver>
  
  <Butterfly implName="org.primordion.xholon.base.Turtle"/>
  <!--<Patch implName="org.primordion.xholon.base.Patch"/>-->
  
</xholonClassDetails>

<PhysicalSystem>
  
  <!-- should be 150 x 150 -->
  <GridGenerator rows="50"
                 cols="50"
                 gridType="Gvt"
                 names="Space,FieldRow,Patch"
                 gridEntityImplName="org.primordion.xholon.base.Patch"
                 gridOwnerImplName="org.primordion.xholon.base.PatchOwner"
                 columnColor="171c8f"
                 gridViewerParams="PhysicalSystem/Space,5,Butterfly Viewer,true"
                 shouldBuildXhc="true"
                 shouldBuildCsh="true"
                 cellsCanSupplyOwnColor="true"/>
  
  <TurtleObserver/>
  
  <Butterfly/>
  
</PhysicalSystem>

<PhysicalSystembehavior implName="org.primordion.xholon.base.Behavior_gwtjs"><![CDATA[
  // each patch has one state variable: its elevation
  var deg2rad = function (degrees) {
    //var pi = Math.PI;
    return degrees * (Math.PI/180);
  }
  
  var row = this.parent().xpath("Space/FieldRow");
  var pycor = 1;
  //this.println(row);
  while (row != null) {
    var patch = row.first();
    var pxcor = 1;
    while (patch != null) {
      patch.elevation = 200 + (100 * (Math.sin(deg2rad(pxcor * 3.8)) + Math.sin(deg2rad(pycor * 3.8))));
      patch.print("," + Math.floor(patch.elevation));
      patch = patch.next();
      pxcor++;
    }
    row.print("\n");
    row = row.next();
    pycor++;
  }
  //# sourceURL=PhysicalSystembehavior.js
]]></PhysicalSystembehavior>

<TurtleObserverbehavior implName="org.primordion.xholon.base.Behavior_gwtjs"><![CDATA[
  var me;
  var beh = {
    postConfigure: function() {
      me = this.cnode.parent();
      me.println(me.name());
      me.println(me.port(0)); //.name());
      me.port(0).action("cp"); // clear patches  Set all patch variables to their initial values.
      me.port(0).action("crt 2 Butterfly"); // create 2 turtles of breed Butterfly
    },
    act: function() {
      //me.println(this.toString());
    },
    toString: function() {
      return "testing:" + "123";
    }
  }
  //# sourceURL=TurtleObserverbehavior.js
]]></TurtleObserverbehavior>

<SvgClient><Attribute_String roleName="svgUri"><![CDATA[data:image/svg+xml,
<svg width="120" height="50" xmlns="http://www.w3.org/2000/svg">
  <g>
    <title>Space</title>
    <rect id="PhysicalSystem/Space" fill="#98FB98" height="50" width="50" x="25" y="0"/>
    <g>
      <title>TurtleObserver</title>
      <rect id="PhysicalSystem/TurtleObserver" fill="#6AB06A" height="50" width="10" x="80" y="0"/>
    </g>
    <g>
      <title>Butterfly</title>
      <rect id="PhysicalSystem/Butterfly" fill="#6AB06A" height="50" width="10" x="100" y="0"/>
    </g>
  </g>
</svg>
]]></Attribute_String><Attribute_String roleName="setup">${MODELNAME_DEFAULT},${SVGURI_DEFAULT}</Attribute_String></SvgClient>

</XholonWorkbook>