Programming Guide

To facilitate the composition of micro-behaviours new commands and reporters have been added to NetLogo. The Behaviour Composer processes code that uses these new commands into ordinary NetLogo code for NetLogo execution. All the NetLogo commands and reporters are available for use in micro-behaviours. New commands and reporters can be added as well using NetLogo's to and to-report.

Behaviour Composer Scheduling Extensions to NetLogo

Each agent in the model has a schedule that is defined by the following commands:

* do-at-setup [actions] performs actions when the simulation is initialized (actions can be any NetLogo commands)
* do-after-setup [actions] performs actions just after the simulation is initialized
* do-now [actions] performs actions immediately
* do-at time [actions] performs actions when the clock has reached time
* do-after interval [actions] performs actions after interval time units
* do-every interval [actions] performs actions now and every interval time units

In addition to the scheduler actions can be triggered when some condition becomes true by the following commands:

* when [condition] [actions] performs actions one time as soon as condition holds
* whenever [condition] [actions] performs actions every time condition holds

NetLogo commands to support probabilistic and repeated executions

* do-with-probability odds [actions] performs actions with probability odds
* do-with-probabilities odds1 [behaviour1] … performs behaviouri with probability of the sum of oddsj where j <= i
* do-repeatedly count [actions] performs actions count times (if count is a non-integer then the actions may be performed an additional time where the odds are the fractional part of count)

The following command is useful when you want a subset of agents to perform some action.

* do-for-n n agents [actions]

Selects n of the agents and runs actions for each agent. If n is a non-integer the remainder is used as the odds of selecting an additional agent. If there are fewer than n agents then all agents run the actions. While the actions are run the code can refer to the agent that is running do-for-n using the-other.

A typical example is from RANDOM_ENCOUNTER:

do-every 1
    [do-if my-state = "infected"
          [do-for-n the-encounter-rate
                         all-individuals with [my-state != "dead"]
                [add-behaviour POSSIBLE-INFECTION]]]

It selects the-encounter-rate of those not dead and adds the POSSIBLE-INFECTION micro-behaviour.

In some cases it is possible to observe an animation of the execution of a model or the graphing of some aspects of the state of the model with a constant ratio between real elapsed time and simulation time. The units for the scheduler are optionally interpreted as seconds, and if the simulation is running faster than real time, the system slows down in order to reproduce a smooth and temporally accurate playback. If the simulation is run "un-clocked" it proceeds as normal, but there will not be a constant ratio between simulation time and real-time due to varying or excessive computational demands.

NetLogo Extensions for Adding Micro-Behaviours

These commands are for adding micro-behaviours to prototypes. A micro-behaviour is referenced by linking to a web page containing the micro-behaviour itself. This can be either hard-coded as a URL or editable using the list-of-micro-behaviours token.

* add-behaviour micro-behaviour adds the micro-behaviour to the current prototype (the prototype running the micro-behaviour that is executing the add-behaviour command). Another name for this command is add-behaviour-to-me.
* add-behaviours [micro-behaviour1 micro-behaviour2 … micro-behaviourn] adds the micro-behaviours defined by links to the current prototype
* add-behaviour-to agent micro-behaviour adds the micro-behaviour to the agent (typically the agent is referenced by using the-other)
* add-behaviours-to agent [micro-behaviour1 micro-behaviour2 … micro-behaviourn] adds the micro-behaviours defined by links to the agent

* add-link-behaviour micro-behaviour when-to-add when asked of a link or set of links adds the micro-behaviour to the links at time when-to-add. when-to-add can be time so that they are added immediately.
* add-link-behaviours [micro-behaviour1 micro-behaviour2 … micro-behaviourn] when-to-add when asked of a link or set of links adds the micro-behaviours to the links at time when-to-add. when-to-add can be time so that they are added immediately.

Micro-behaviours can also be added to NetLogo links between agents.

Referring to another agent

In addition to the full richness of the ways in which NetLogo supports ways to refer to other agents there are the following extensions:

* can-pick-one agents if agents is not empty reports true and the-other will return the agent chosen
* any prototype name reports true if there are any (non-hidden) agents other than the caller created as copies of the prototype named prototype name and the-other will return the agent chosen
* anyone-who-is [conditions] [actions] runs actions for any agent that satisfies conditions and the-other will return the agent chosen
* all-who-are [conditions] [actions] runs actions for all agents that satisfy conditions and the-other can be used actions to refer to the agent running this

the-other can be used in NetLogo code in the Behaviour Composer to refer to an agent defined by the most recent execution of one of the above extensions. An example of its use is in EAT-WHEN-HUNGRY. A simplified version is

when
  [can-pick-one all-individuals with [distance-to-me < 5]]
  [add-behaviour-to the-other DIE]

When there is at least one individual whose distance to the agent running this code fragment is less than 5 units then the behaviour DIE is added to the the-other, can-pick-one sets the-other when it randomly chose one of the agents from all-individuals with [distance-to-me < 5].

Miscellaneous additions to NetLogo

* ask-every-patch [actions] performs action for every patch of the environment (note that unlike ask patches in NetLogo this can be run from the "turtle context")

Naming and Using Attributes in the Behaviour Composer

NetLogo, like many programming languages, expects agent attributes ("breed variables" in NetLogo parlance) to be declared before use. The BehaviourComposer automates this so that any attribute whose name begins with "my-" becomes a breed variable without the need for a declaration. When an attribute needs to be both read and updated then the current and next value can be kept separate by using the "my-next-" form. After all actions scheduled for time t have completed, all attributes whose name begins with "my-" are set to the current value of the "my-next-" version of the attribute.

Predicates in conditionals can refer to the current state of an attribute by using the "my-" version of a variable, while code that updates a variable can use the "my-next-" version. In this way, execution order dependencies are eliminated. For example, agents with the following simultaneous update micro-behaviour will at time t+1 move to the left if that location was unoccupied at time t.

do-every delta-t 
   let step-to-the-left my-x - 1 
   if not any? all-individuals with [my-x = step-to-the-left] 
     [set my-next-x step-to-the-left]

In contrast, agents with the immediate update version of this micro-behaviour will at time t+1 move to the left if that location was unoccupied at time t by agents yet to run and unoccupied at time t+1 by those agents that have already run. It differs from the simultaneous update version in that the last line is:

[set my-x step-to-the-left]

If each agent in a line ran the simultaneous update micro-behaviour only the leftmost agent would move at time 0, then the two leftmost agents at time 1, and so on. If they ran the immediate update micro-behaviour then the same sequence of events may happen, or they may all move left: many other possible outcomes can result from different execution orders. Immediate updates are simplest to implement and are the most common in modelling. We believe their idiosyncratic semantics (a mixture of time states) makes them less desirable, in general, than the simple semantics of simultaneous updates. The choice between the two kinds of update can be made by the micro-behaviour programmers on a case-by-case basis.

Patch variables should be given names that end with "-of-patch", e.g. temperature-of-patch.

The Behaviour Composer also expects global variables (such as those defined by sliders) to begin with "the-" to provide high-level error messages if they are not defined.

Creating New Micro-behaviours

Example markup in Jottit, you can import this micro-behaviour into the composer by pasting in this link: http://jottit.com/m2td2/forward3

BehaviourComposer: ignore everything before this.

Begin micro-behaviour

GO FORWARD

Begin NetLogo code:

substitute-text-area-for go-forward 3

fd go-forward

End NetLogo code

BehaviourComposer: ignore everything after this.

The Behaviour Composer searches web pages for these three tags:

  • Begin micro-behaviour - this begins the section with the behaviour's name and code (Begin micro-behavior also works)
  • Begin NetLogo code: - this ends the section with the behaviour's name and starts the section with the code
  • End NetLogo code - this ends the code section

Each element should correspond to an HTML element. Note that any HTML elements can be between Begin micro-behaviour and Begin NetLogo code: including images (IMG elements) and will be used to display the "name" of the micro-behaviour. This HTML will determine the appearance of the micro-behaviour button as well as the tab label.

Between Begin NetLogo code: and End NetLogo code can be any HTML whose "inner text" is valid NetLogo code. If the micro-behaviour needs to reference other micro-behaviours just use links in the NetLogo code to the pages hosting the other micro-behaviours.

And optionally use the following to select the micro-behaviour material from surrounding material (e.g. on a wiki or a blog).

  • BehaviourComposer: ignore everything before this. - everything prior to this is ignored
  • BehaviourComposer: ignore everything after this. - everything after this is ignored

You can add a list of micro-behaviours to a micro-behaviour (e.g. as the argument to add-behaviours) by entering

list-of-micro-behaviours "any text describing the list" [url1 url2 …]

If a URL contains a space then quote the entire URL. The URLs can be relative to the page hosting the list.

To add a text area to a micro-behaviour to enable users to easily edit parameters use

substitute-text-area-for name-of-text-area any text on one line — can include space to make the default area larger

The first occurrence of name-of-text-area in the following code is then replaced with a text area whose default contents are the text that followed the name. Choose good names for text areas since they will show up in the history of changes to a model.

We recommend using you start with the template for creating new micro-behaviours. We suggest you browse the library of micro-behaviours provided by the Modelling4All team.

Adding an externally hosted micro-behaviour to the Behavior Composer

Just click on a macro-behaviour and select the "Add micro-behaviour…" menu item. Then paste in the URL of micro-behaviour.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License