Guides‎ > ‎

Programming guide

This is a manual for advanced users of the BehaviourComposer. To learn how to browse, customise, and enhance micro-behaviours and to compose them into models see the on-line tutorials and videos.

Contents

  1. 1 Behaviour Composer Scheduling Extensions to NetLogo
  2. 2 NetLogo commands to support probabilistic and repeated executions
  3. 3 Prototypes - how many instances and hide this agent
  4. 4 NetLogo Extensions for Adding Micro-Behaviours
  5. 5 Referring to another agent
  6. 6 Miscellaneous additions to NetLogo
  7. 7 Naming and Using Attributes in the Behaviour Composer
  8. 8 Movement
  9. 9 Three-dimensional models
  10. 10 Creating New Micro-behaviours
  11. 11 Adding an externally hosted micro-behaviour to the Behaviour Composer
  12. 12 Full details of how Micro-behaviour pages are defined
  13. 13 How to export micro-behaviour web pages from the Modelling4All server to another web server

To facilitate the composition of micro-behaviours new commands and reporters have been added NetLogo. These are described in the dictionary of NetLogo extensions. 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 initialised (actions can be any NetLogo commands)
*  do-after-setup [ actions ] performs actions just after the simulation is initialised
*  do-now [ actions ] performs actions immediately
*  do-at-time  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

These commands are added as needed when you click on one of the Enhancement menu items on the micro-behaviour page.

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 oddsi. If the oddsi that together with the oddsj where j < i adds up to more than 1.0 then only the portion of oddsi  that adds up to 1.0 is used.
*  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. select-n is a reporter that returns the number of agents and also treats fractions probabilistically.

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.

Prototypes - how many instances and hide this agent

The interface to prototypes enables one to specify the initial number of instances of the prototype and whether it should be visible or not.



The area that specifies the number of instances that should be created at set up time. It can be any NetLogo expression that computes a non-negative integer value. For example, it can be a global parameter, perhaps controlled by a slider. More agents can be created later using the create agents micro-behaviour. Also copies of instances can be created using create exact copies of this agent. A value of zero is recommended for prototypes whose instances are only created dynamically during execution or those whose initialisation needs to be delayed because they depend upon completion of other set up initialisations. In the later case some other prototype needs to use create agents to complete the set up. 

Another use of prototypes with zero copies is to use it as a list of micro-behaviours. Prototypes can be added to lists of micro-behaviours to add their micro-behaviours. This differs from using a micro-behaviour to collect micro-behaviours as a unit in that many can share the list without copying the micro-behaviours (and thereby necessitating multiple edits when any of the micro-behaviours needs revision.)

The Hide this agent check box is equivalent to adding the become invisible and continue to run behaviours micro-behaviour to the prototype. This supports the common situation where an agent needs to run in the background (to create new agents, maintain observation gadgets and plots, and the like) but is not an agent one wants to see in the world view of the simulation.

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-behaviour 1 micro-behaviour 2 … micro-behaviour n ]  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-behaviour 1 micro-behaviour 2 … micro-behaviour n ]  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 it is added immediately.
*  add-link-behaviours  [micro-behaviour 1 micro-behaviour 2 … micro-behaviour n ]   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
  * all-of-kind "prototype name " reports all instances of the prototype with that name. Same as NetLogo: objects with [kind = " prototype name"] 
 * all-individuals reports all agents that are not invisible. Same as NetLogo  objects with [my-visibility = true]
  * all-others reports all agents that are not invisible other than the agent calling this.
  * objects-here reports all agents on the same patch as the agent calling 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 choses 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")
  • random-integer-between [number number] for whole numbers or integers between given range
  • random-number-between [number number] creates a random number between given range (including all rational numbers e.g. fractions of whole numbers

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.

Movement

The BehaviourComposer supports three movement attributes:my-x,my-y, andmy-heading. If the corresponding NetLogo variablesxcor,ycor, andheading are not updated (which many NetLogo primitives do such asforward,face,right, ...) then they are set to the values of the attributes. Note that aswith all attributes, one can use my-next-x,my-next-y, and my-next-headingto distinguish between the value the attribute should have when thecurrent cycle ends and the value it currently has.

go-forward is similar to NetLogo's forward except it relies upon my-x , my-y , and my-heading . turn-right and turn-left are like NetLogo's right and leftbut they affect my-heading. The advantage of using go-forward and turn-right is that they work together with any other code that deals with my-x , my-y , and my-heading such that they don't depend upon the order of events.

Three-dimensional models

If a model includes the micro-behaviour Set the initial dimensions of the 3D world where the model runs then the Behaviour Composer generates a 'nlogo3d' file that can be run by the 3D version of NetLogo. Note that there is no applet support for 3D so the models cannot be run in the browser. Any of the 3D NetLogo primitives may be used as well as my-z and my-next-z.

Creating New Micro-behaviours

To define a micro-behaviour from scratch click on the 'Create a new micro-behaviour' button in the Composer area. It will provide four areas where you can add information:

  1. Description area. Plain text that will become the tool tip of the micro-behaviour.
  2. Name. Rich text that can include images, fonts, etc.
  3. Code. Plain text area. Includes a button for inserting the code for a text area and a button for inserting a list of behaviours.
  4. Additional information. A rich text area that can describe how the behaviour works, its implementation history, links to related micro-behaviours, models that use the behaviour and more.
After saving you can make further edits by clicking on the 'Edit page' button. Note that some changes to text areas or lists of behaviours may break micro-behaviours that are depending upon this page. Also note that you are editing a page that different micro-behaviours may be relying upon.

If you want to host the micro-behaviour on another site, open the micro-behaviour as a tab and click on the 'Get links' to obtain the HTML of the page.

Adding an externally hosted micro-behaviour to the Behaviour Composer

Click on the '+' tab in the Composer tab or click on a prototype and select the "Add micro-behaviour…" menu item. Then paste in the URL of micro-behaviour.

Full details of how Micro-behaviour pages are defined

The following is now automated when one clicks on the 'Create a new micro-behaviour' button. It is documented for completeness.

Here is an example authored in Google Sites based upon http://resources.modelling4all.org/libraries/basic-library/Movement/i-jump-forward

BehaviourComposer: ignore everything before this.

Begin micro-behaviour

Begin description:

Jump forward in the direction of my heading.
End description

Jump forward

Begin NetLogo code:

substitute-text-area-for distance-moved 10go-forward distance-moved

End NetLogo code

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 description: - this begins the description that will be used as the tool tip for the behaviour and will appear at the top of the micro-behaviour page. This can be edited by the user later.
  • End description - ends the description.
  • 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.

You can add the following immediately after Begin micro-behaviour to provide a default user-editable description of what the micro-behaviour does.

Begin description:

A description of this behaviour.

End description

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, (you can only reference name-of-text-area once).  Choose good names for text areas since they will show up in the history of changes to a model. The create circle of colour in patches example micro-behaviour shows how substitute-text-area-for can be used in conjunction with let statements so the values entered can be used within a block of NetLogo code.

We suggest you browse the library of micro-behaviours provided by the Modelling4All team.

How to export micro-behaviour web pages from the Modelling4All server to another web server

Pages that were created by using using the New micro-behaviour page button are not suitable for sharing outside of a development team since anyone with access to a model can edit them thereby changing (and perhaps breaking) the model. The best way to migrate a page to another server is to click on Get Links at the bottom of a micro-behaviour page and then on Display the HTML of this page for exporting to a public web site link. Copy and paste the HTML into your web server. Then paste the web page URL into the second box in the Get Links section. If the micro-behaviour web page has been used multiple places you'll need to paste the URL into each one's Get Links section.