IODA NetLogo Tutorial

1. Particles: or, What's different in IODA?
   1. Moving particles: from NetLogo to IODA-NetLogo
   2. Adding behaviors: NetLogo vs. IODA-NetLogo
2. Termites Revisited
   1. The backbone of the simulation program
   2. Definition of the interactions
   3. The interaction matrix: the role of priorities
   4. From abstract to concrete primitives
3. Termites with only agents
   1. Initial program
   2. More details on the interaction matrix
   3. Back to interactions and primitives
4. A simple ecosystem
   1. Grass, Sheep and Wolves: Patches as true agents
   2. The Update Matrix
   3. More details on the simulation step (ioda:go)
   4. Specifying the interactions: parallel vs. exclusive
   5. Interactions in the ecosystem
   6. Implementation of the primitives
   7. To extend the model…
5. Leap years, or: New features since v 2.2
   1. Expressing alternatives in triggers/conditions
   2. Ordering policies for agent scheduling
6. Pheromones, or: Target Selection Policies
   1. Nature of the problem
   2. Introducing a Target Selection Policy
   3. Results and explanations
   4. How to use Target Selection Policies
7. Ants and food Revisited: Your turn to work!
   1. Exercise
   2. Hints
   3. Additional help: definition of interactions
   4. Additional help: interaction and update matrices
   5. What you should get
8. Tuning perception: Enhancements since v 2.3
   1. General principles in IODA perception
   2. Neighborhoods, or: composing built-in perception primitives
   3. Interactions in a network
   4. Termites sorting, or: custom perception tasks
9. Conway's Life, or: a Cellular Automaton with IODA?!??
10. Explosion and multi-target interactions
    1. Description
    2. The default selection policy: RANDOM
    3. Interaction-first selection policy: RANDOM-INT
    4. Property-driven selection policies: BEST, PRORATA and ALL-BEST
    5. "Multicast" interactions: ALL, NUMBER and FILTER
    6. Recommendation for the use of target selection policies
    7. A parenthesis: specifying an alternative metric
11. Advanced features: reflection and meta-interactions
12. Other code examples in the tutorials directory
13. Contact information & authors
14. Terms of use

Let's start with a simple problem: we want to model particles moving randomly. The corresponding NetLogo code is quite simple:

to setup
  clear-all
  set-default-shape turtles "circle"
  crt 1000 [ setxy random-xcor random-ycor
             set color red ]
  reset-ticks
end

to go
  ask turtles [ wiggle ]
  tick
end

to wiggle  
  set heading random 360  fd 1 
end

Since IODA is a generic methodology, it is not really convenient for such a simple simulation, because it requires a bit more code in that case. Yet, we are going to IODA-ify this model to explain the differences between the IODA approach and ad-hoc modelling.

The first step in IODA consists in identifying agents: here, we have only turtles.

Then, we must identify interactions , i.e. abstract conditions/actions rules that describe the behaviors of the agents. An interaction involves a source agent (which performs the interaction) and one (or more) target agents (which undergo the interaction). It is composed of:

• a sequence of actions which are the commands that the source and the target have to execute
• a list of conditions (possibly empty) that must be fulfilled by the source and/or the target to allow the execution of actions
• a list of triggers (possibly empty) which describe why the source or the target are involved in the interaction, and must also be fulfilled.

In the current case, the turtles just have to move randomly, without any restriction. Thus we have to define but one interaction, for instance MoveRandomly, which contains only a single action: wiggle (without any condition or trigger). Put the following lines in a text file named "interactions.txt":

interaction MoveRandomly
actions wiggle
end

Now, you have to specify what interactions can be performed by agents. Thus, you must define an interaction matrix , which assigns interactions to source and target agents.

Here, the agents (turtles) can only perform the MoveRandomly interaction. Additionnally, each turtle moves by itself: the target agent of the interaction is actually the same as the source. This is called a reflexive interaction.

Put the following lines in a text file named "matrix.txt":

turtles MoveRandomly 0

This means any turtle can perform interaction MoveRandomly with itself as a target. The "0" is the priority level of the interaction, from the point of view of the source agent (here it does not matter since there is only one interaction).

Now you have to write some code to build the simulation. First, you must use the IODA simulation engine provided in the IODA extension folder, and the ioda extension for NetLogo.

Put a copy of IODA_2_3.nls in your own folder and rewrite your procedures as follows:

__includes ["IODA_2_3.nls"]        ; include file for the simulation engine
extensions [ioda]                  ; the ioda extension itself

to setup
  clear-all
  set-default-shape turtles "circle"
  crt 1000 
    [ setxy random-xcor random-ycor
      set color red ]
  ioda:setup                       ; initialization of the simulation engine
  reset-ticks
end

to go
  ioda:go                          ; one step of the IODA simulation
  tick
end

to wiggle  
  set heading random 360
  fd 1 
end

The ioda:setup command initializes the IODA parameters of the simulation, while the ioda:go runs one simulation step in IODA. Though, if you press the "go" button, nothing happens. Indeed, at this time you did not specify the IODA model to use, i.e. you did not specify any interaction nor interaction matrix in your NetLogo program.

Rewrite your setup procedure as follows:

to setup
  clear-all
  set-default-shape turtles "circle"
  crt 1000 
    [ setxy random-xcor random-ycor
      set color red ]
  ioda:load-interactions "interactions.txt"
  ioda:load-matrices "matrix.txt" " "
  ioda:setup
  reset-ticks
end

Now, your interactions and your interaction matrix are automatically loaded into the NetLogo program. Unfortunately, if you press "go" at this time, you get an error message:

Indeed, in IODA, the interactions make use of abstract primitives (here, wiggle), which must be instantiated into concrete primitives. Concrete primitives depend on the breed of the agent: thus, in that example, the wiggle abstract primitive is run by turtles, hence it must be renamed turtles::wiggle.

Rename the wiggle procedure: turtles::wiggle.

Congratulations! Your program should now run correctly and produce the same result as the ad-hoc NetLogo program.

Now, we are going to modify the behavior of our turtles as follows: when a turtle perceives another turtle "in radius" 1, the first turtle kills the other one. A turtle may kill at most one other turtle per tick. If it kills no turtle, it just keeps moving randomly.

First, let's examine the classical go procedure that answers those specifications:

to go
  ask turtles 
    [ let n other turtles in-radius 1
      ifelse (any? n)
        [ ask one-of n [ die ]]
        [ wiggle ]
    ] 
  tick
end

The behavior is still quite simple; nevertheless, this modification requires to re-write the go procedure and to introduce ifelse cascades, which would not be very convenient for more sophisticated behaviors.

At the opposite, in the IODA version, the go procedure does not change. Instead, you have first to define a new interaction, which consists in making the target of the interaction die.

Add the following lines to file "interactions.txt":

interaction Delete
  actions target:die
end

Note: in the definition of an interaction, abstract primitives (reporters or commands) are always evaluated and run by the source agent (which owns a reference to its potential or actual target), unless they begin with the target: keyword as above.

Then, you have to change your interaction matrix to take into account the Delete interaction: it can be performed by any turtle on any other turtle, within a distance less or equal to 1.

Add the following line to file "matrix.txt":

turtles Delete 1 turtles 1

This line can be read as follows: Turtles can perform interaction Delete with priority 1 on other turtles with distance ≤ 1

As you changed the matrix file, the agents can perform or undergo new interactions. Thus, you certainly have to write additional primitives for your turtles. Fortunately, the extension can tell you what remains to write.

Push the "setup" button, to ensure your model is loaded. Then, type in the command center:

observer>print ioda:primitives-to-write
to turtles::filter-neighbors
end
 
to turtles::die
end

The procedure turtles::die is required because of the target:die item in the Delete interaction, which means that the target (namely here, a turtle) must implement a concrete primitive for die.

Add the following procedure to your program:

to turtles::die
  ioda:die
end

Note: You MUST NOT use the NetLogo die primitive in a IODA primitive because the IODA simulation engine has its own scheduler. By using ioda:die instead, you ensure that the agent is considered dead (through a convenient attribute), and that it will be actually removed from the NetLogo simulation at the end of the ioda:go procedure.

The other procedure (turtles::filter-neighbors) is required for perception. Indeed, turtles now need to have a look on other agents so as to interact with them: thus you need to specify how neighboring agents are perceived.

We assume here that turtles perceive their neighbors in a circle of radius 1. Then we can use a IODA built-in command:

to turtles::filter-neighbors
  ioda:filter-neighbors-in-radius 1
end

Now, you can ensure that all concrete primitives have been written (click the "setup" button and print ioda:primitives-to-write again, which should print nothing at all) and run your model by clicking the "go" button. It works!

At this point you may feel that a lot of work is required to obtain the same results as in the ad-hoc model. Nevertheless, you will soon discover that for more complex models, which require for instance a step-by-step design, possibly with backtracks or deep modifications (e.g. example 14-age of crisis in this section), the separation between the simulation engine on the one hand, and the primitives of the agents and the abstract definition of the interactions on the other hand, will prove a source a speed-up in you design process, and prevent bugs related to complex ifelse cascades.

First, you have to sketch your program as previously.

__includes ["IODA_2_3.nls"]
extensions [ioda]

to setup
  clear-all
  set-default-shape turtles "bug"
  create-turtles 50 
    [ setxy random-xcor random-ycor
      set color white ]
  ask n-of 500 patches [set pcolor yellow]
  ioda:load-interactions "interactions.txt"
  ioda:load-matrices "matrix.txt" " "
  ioda:setup
  reset-ticks
end

to go
  ioda:go
  tick 
end

Now we have to define possible interactions, by decomposing the activity of the agents into coarse-grained, abstract and coherent sequences:

• MoveRandomly: the same as in previous section
• PickUp: if a wood chip is present and the source agent does not carry anything, it can pick a chip up
• FindEmptyPlace: it has the same effect than MoveRandomly, but is triggered by the presence of a wood chip
• PutDown: the source agent puts a wood chip down, if nothing is already at this place

Put the following lines in a text file named "interactions.txt"

interaction MoveRandomly
  actions   wiggle
end

interaction PickUp
  trigger 	      not:empty-here?
  condition	      not:carrying?
  actions	      take-load get-away
end

interaction FindEmptyPlace
  trigger	not:empty-here?
  condition     carrying?
  actions 	wiggle
end

interaction PutDown
  trigger	something-nearby?
  condition 	carrying?  empty-here?
  actions 	drop-load random-turn get-away	
end

Please note the following IODA features:

• We introduced the not: keyword which inverts the result of a trigger/condition primitive.
• Some interactions contain 2 items in addition to the actions:
  • the trigger represents the motivation or implicit goals that lead to choose the interaction,
  • the condition represents physical or logical prerequisistes that must be fulfilled to execute the actions.

From an operational point of view, there is not much difference between trigger and condition, since ALL primitives found in both must return true to allow the interaction to be selected. The distinction makes sense from a knowledge representation viewpoint. For instance, the PickUp interaction is triggered by the perception of a wood chip (not-empty-here?), which means that the termite tries to perform PickUp because its perceives a wood chip (in order to carry it somewhere); yet, the actions of the interaction cannot take place if its condition is not fulfilled, namely the termite must not already carry any wood chip (not-carrying?). Anyway, if you hesitate, put your tests where you want…

You also have to define an interaction matrix. In that case, you only have one kind of agents, and their interactions are reflexive all the time (you could do exactly the same simulation with only one turtle!). Thus, you have litle to do but think about the priorities of interactions, i.e. if all interactions have their trigger and condition fulfilled, what will the source agent perform?

It appears that the turtle should first try to pick a wood chip up; if not possible, to find an empty place if it is already carrying a wood chip; if not possible, try to put the wood chip down; finally, the random move is the default behavior.

Put the following lines in a text file named "matrix.txt".

turtles MoveRandomly   0
turtles PutDown        10
turtles FindEmptyPlace 20
turtles PickUp         30

Note: the exact values of priorities have no importance. What is taken into account is the resulting order relation.

Finally, you have to write several primitives:

observer>setup
observer>print ioda:primitives-to-write
to-report turtles::something-nearby?
end

to-report turtles::carrying?
end

to-report turtles::empty-here?
end

to turtles::take-load
end

to turtles::wiggle
end

to turtles::drop-load
end

to turtles::random-turn
end

to turtles::get-away
end

Copy-paste those empty primitives to you program and define them. You can try to find what they should do in this model.

Then, compare your proposal to the solution we suggest:

1. add after the extensions line: turtles-own [carrying?]
2. add in the initialization of the turtles: set carrying? false
3. define the concrete primitives through the code below:

to-report turtles::something-nearby?
  report any? neighbors with [pcolor = yellow]
end

to-report turtles::carrying?
  report carrying? 
end

to-report turtles::empty-here?
  report pcolor = black
end

to turtles::take-load
  set carrying? true
  set color red
  set pcolor black
end

to turtles::wiggle
  left random 50 right random 50 fd 1
end

to turtles::drop-load
  set pcolor yellow
  set carrying? false
  set color white
end

to turtles::get-away
  fd 20
end

to turtles::random-turn
    right random 360
end

… and try it !

Here is the squeletton for this new simulation:

__includes ["IODA_2_3.nls"]
extensions [ioda]

breed [ termites termite ]
breed [ chips chip ]

termites-own [carrying?]

to setup
  clear-all
  set-default-shape termites "bug"
  set-default-shape chips "line"
  create-termites nb-termites [ init-termite ]
  create-chips nb-chips [ init-chip ]
  ioda:load-interactions "interactions.txt"
  ioda:load-matrices "matrix.txt" " \t"
  ioda:setup
  reset-ticks
end

to init-termite
  setxy random-xcor random-ycor
  set color white
  set carrying? false
end

to init-chip
  setxy random-xcor random-ycor
  set color yellow
end

to go
  tick 
  ioda:go
end

Now, we can examine the model of the previous tutorial to find out the consequences of the "agentification" of the wood chips. Especially, it appears that several abstract primitives, such as empty-here? or something-nearby?, rely implicitly upon the perception of a wood chip. Thus, handling wood chips as true agents removes this implicit perception: the interactions can be simplified. In particular, the FindEmptyPlace interaction no more exists. In counterpart, the interaction matrix now involves explicitely both termites and wood chips. We can summarize possible interactions as follows:

The matrix above should be read as follows: the first column is the list of source agents; the first row contains the list of target agents. An interaction at row S and column T can be performed by an agent of the kind S (source) on another agent of the kind T (target). The column marked with ∅ represents reflexive interactions (where the target is the source itself). In this category, we find for instance MoveRandomly: a termite can perform such an interaction alone. In the column chips, we find interactions that chips can undergo: for instance, a termite can perform PickUp on a chip.

The association between an interaction, a source agent and a target agent is called an assignation. It comes with a priority and, in regular cases, a limit distance between source and target (this distance has no meaning in reflexive interactions). For instance, in the above matrix, the assignation (PickUp, 30, 1) means that each termite tries to perform the PickUp interaction first (since 30 is the highest priority level on the termites row), on chips situated within a radius of 1.

Please also note that the interaction MoveRandomly is used twice. With the lowest priority level, it is present as a reflexive interaction, to allow termites to wander in search for wood chips. But, it also plays the role of the FindEmptyPlace interaction in the previous tutorial, as an interaction between termites and chips. Indeed, a termite which cannot perform PickUp on a chip (thus is already carrying a chip), is likely to perform MoveRandomly instead, i.e. move around, and it will do that until being far enough from a chip (distance > 1).

To use the matrix above in your model, put the following lines in a text file named "matrix.txt"

termites	MoveRandomly	0
termites 	MoveRandomly 	10	chips	1
termites 	PutDown 	20      chips   0.3
termites 	PickUp 		30 	chips 	1

Those considerations lead us to propose a simplified definition of the interactions needed in that model.

Put the following lines in a text file named "interactions.txt"

interaction MoveRandomly
  actions   wiggle
end

interaction PickUp
  condition       not:carrying?
  actions         take-load get-away
end

interaction PutDown
  condition       carrying?
  actions         drop-load random-turn get-away
end

You also have to write the primitives for termites and chips. Take some time to try by yourself. Useful indication: when running a concrete primitive (reporter or command) either as a source or as a target, you can refer to the other agent through the ioda:my-target reporter.

Here is the set of primitives we propose:

to-report termites::carrying?
  report carrying?
end

to termites::filter-neighbors
  ioda:filter-neighbors-in-radius 1
end

; note that this primitive has an action both on source and target agents
; the target can be accessed through the ioda:my-target reporter
to termites::take-load
  set carrying? true
  set color red
  ask ioda:my-target [ioda:die]
end

to termites::wiggle
  left random 50 right random 50 fd 1
end

to termites::drop-load
  set carrying? false
  set color white
  hatch-chips 1 [init-chip]
end

to termites::get-away
  fd 20
end

to termites::random-turn
  right random 360
end

The simulation of the above model should lead to the formation of compact piles as shown below. The sparseness of the piles depends on the limit distance assigned to the PutDown interaction.

In this section, we try to build a small ecosystem with three species: grass, sheep and wolves. At the beginning, we allow sheep to eat grass, wolves to eat sheep, and only sheep to mate (no death by starvation). In addition, we decide to use patches to represent grass; but, remember, in IODA any relevant entity should be an agent: hence, in the IODA NetLogo extension, patches can be explicitly be used as regular agents in the model. Thus, we can summarize the relations between agents through the interaction matrix below.

Moreover, the grass resource must be at the same time limited (to avoid exponential growth of sheep) and regularly restored (to allow sheep to reproduce). Thus, the state of the patches has to change regularly, without considering interactions that the patches could perform or undergo. In IODA such update operations can be specified in an update matrix as shown below:

Interaction matrix and update matrix can be specified in the same file. To do so, put the following lines in a text file named "matrix.txt":

; interactions performed by wolves
wolves      Eat           20      sheep      1
wolves      Hunt          10      sheep      5
wolves      MoveRandomly  0

; interaction performed by sheep
sheep       Eat           20      patches    1
sheep       Mate          10      sheep      1
sheep       MoveRandomly  0

; interaction performed by patches
patches     Grow          0       UPDATE

Notes:

1. As you can see above, in order to put an interaction in the update matrix instead of the interaction matrix, you just have to write the "UPDATE" keyword after the priority (an interaction used for update is obviously reflexive).
2. If you want to insert comments in the files, you only need to start the line with a non-letter, non-digit character (here, ';').

This small parenthesis explains how the simulation engine works, to help you understand the difference between interactions put in the update matrix and those put in the interaction matrix.

First, when matrices are loaded, the IODA NetLogo extension builds three lists of agents:

• Active agents are those with a non-empty row in the interaction matrix (agents that are able to perform interactions). In the example above, wolves and sheep are active agents; patches are not, because they cannot really perform interactions (only updates).
• Passive agents are those with a non-empty column in the interaction matrix (agents that are able to undergo interactions). In the example above, sheep and patches are passive agents; wolves are not, because the "wolves" column is empty: wolves cannot undergo anything but reflexive interactions.
• Labile agents are those with a non-empty row in the update matrix (agents that are subject to state changes). In the example above, patches are the only labile agents.

From the above definitions, it appears that agents can be at the same time active, passive and labile: this only depends on the contents of the interaction and update matrices.

The ioda:setup and the ioda:go commands make use of this characterization, to respectively initialize the state of all IODA agents and execute each step in the simulation.

Among several operations, the ioda:setup command stamps all agents as alive (they "exist" in the IODA simulation).

At each time step, the ioda:go command handles the behavior of the agents through the following operations:

1. stamp all agents as operative (i.e. ready to work)
2. reset the list of dead agents
3. UPDATE STEP: ask each alive labile agent (by default, in random order; yet, a convenient order can be specified, cf. scheduling policies below) to perform its update interactions, i.e.:
   • for each assignation, by decreasing priority: if both trigger and condition are fulfilled, execute the actions

   It may happen that some actions (typically using ioda:die) stamp the agent dead and put it into the list of dead agents.

4. INTERACTION SELECTION STEP: ask each alive and operative active agent (by default, in random order; yet a convenient order can be specified, cf. scheduling policies below) to select and perform an interaction, i.e.:
   1. perceive the neighboring alive passive agents (agents that cannot be a target are not taken into account)
   2. gather all assignations with the same priority level (starting with the highest level)
   3. for each assignation, determine all interaction/target pairs where trigger and condition are fulfilled (in case of reflexive interaction, the target is nobody)
   4. if some realizable interaction/target pairs have been found:
      1. select one (according to a target selection policy which, by default, is a random choice; a specific policy can also be specified, see below)
      2. execute the corresponding actions with the specified target
      3. stamp the source agent as not operative

      Again, it may happen that some agents (source or targets) are killed through ioda:die and thus put into the list of dead agents.

   5. if no interaction/target pair was found, try again with a lower priority level; if all assignations have been checked without results, this agent does not perform any interaction (yet, it can be the target of several interactions performed by other agents)
5. remove from the NetLogo simulation all agents found in the list of dead agents

As a consequence of this scheduling algorithm, an agent may act as a source (i.e. perform an interaction) at most once during a time step. But it can generally undergo several operations performed by other sources.

Due to the scheduling of agents, actions that happen during a same time step are actually run in sequence. Thus, it can be sometimes very important to prevent some agents to perform and undergo interactions simultaneously, i.e. during the same time step.

For instance, it is clear that several wolves can perform the Hunt interaction with the same sheep as target. Conversely, if we allow a sheep to be the target of Mate twice (or more) during the same time step, the actual birth rate will be higher than expected. It would be more likely that a sheep cannot perform nor undergo Mate but once at a time.

In order to cope with such situations, IODA provides to classes of interactions:

• parallel interactions do not affect the ability to participate in other interactions:
  • the source of a parallel interaction cannot act again as a source, but can still undergo other interactions
  • the target of a parallel interaction can still be the source or the target of other interactions.

Example: interactions such as Hunt or MoveRandomly are parallel interactions.

• exclusive interactions prevent agents from participating in other exclusive interactions:
  • the source of an exclusive interaction cannot be the target of another exclusive interaction; it can still be the target of parallel interactions
  • the target of an exclusive interaction cannot be the source nor the target of another exclusive interaction; it can still be the target of parallel interactions.

Example: interactions such as Mate or Eat are exclusive interactions.

To identify the class of an interaction I, you have to answer the following questions:

1. can a target of I be the source of other interactions, during the same time step?
2. can an agent be twice the target in interaction I with different sources, during the same time step?

If you answer "YES" to one or both questions, then interaction I is parallel. Otherwise

We are now able to define the interactions required to build our little ecosystem. In IODA NetLogo, interactions are considered parallel by default . To modify the class of the interaction, you can put one of the following keywords before interaction: parallel or exclusive. The general algorithm of interaction selection is designed to take automatically into account the class of each interaction. You are strongly recommended to explicitly specify the class of your interactions, in order to make their meaning unambiguous.

Put the following lines in a text file called "interactions.txt":

parallel interaction Hunt
  trigger     hungry?
  condition   adult? target:alone?
  actions     chase
end

exclusive interaction Eat
  trigger     hungry?
  condition   target:healthy?
  actions     digest target:die
end

parallel interaction MoveRandomly
  actions     wiggle
end

parallel interaction Grow
  condition   not:grown?
  actions     increase-size
end

exclusive interaction Mate
  trigger     adult? target:adult?
  condition   not:hungry? target:not:hungry? 
  actions     reproduce decrease-health target:decrease-health
end

Note: The target: and not: keywords can be used together, and can of course be combined in any order (i.e. target:not:hungry? is equivalent to not:target:hungry?).

We propose the following rules regarding the nature of the agents:

• patches have a food attribute (between 0 and max-food), which represents the quantity of food available on the patch; food growth rate is 0.1 per tick; a patch is considered "healthy" if food ≥ 0.2*max-food
• sheep have a stomach attribute to store the food; sheep are hungry when stomach ≤ 20; any move costs 1 food unit; in addition, for now sheep are always considered adult, and healthy means "not hungry"; breeding offspring costs 5 food units to both source and target (sheep::decrease-health): as a counterpart the offspring starts with 10 food units in its stomach
• wolves have a last-dinner attribute to memorize the time (the ticks) they performed the digest action: thus they get hungry when last-dinner ≥ 50; wolves are also considered adult

You can use the following lines as the beginning of your program:

__includes ["IODA_2_3.nls"]
extensions [ioda]
 
breed [wolves wolf]
breed [sheep a-sheep]

wolves-own  [last-dinner]
sheep-own   [stomach]
patches-own [food]
  
to setup
  clear-all
  set-default-shape wolves "wolf"
  set-default-shape sheep "sheep"
  init-agents
  ioda:load-interactions "interactions.txt"
  ioda:load-matrices "matrix.txt" " \t"
  ioda:setup
  reset-ticks
end

to go
  ioda:go
  tick 
end

to init-agents
  ask patches 
    [ set food random max-food  
      recolor-patch ]
  create-sheep 50 
    [ setxy random-xcor random-ycor
      set color white
      set stomach random 20 ]
  create-wolves 5 
    [ setxy random-xcor random-ycor
      set last-dinner (- random 50)
      set color brown ]
end

to recolor-patch
  set pcolor scale-color green food 0 (max-food * 1.2)
end

to wolves::filter-neighbors
  ioda:filter-neighbors-in-radius 5
end

to sheep::filter-neighbors
  ioda:filter-neighbors-in-radius 2
end

The end of the exercise for you is now to program the appropriate primitives according to the above indications and test your simulation. The program named "model1.nlogo" in the "4-simple-ecosystem" folder of the tutorial directory provides a solution, which leads to an equilibrium between grass and sheep:

You should now be familiar enough with IODA to try adding the following extensions to your model (an implementation is proposed in the file named "model2.nlogo"):

• make sheep die by starvation, i.e. if their stomach = 0
• make sheep flee to escape wolves
• introduce sexual differentiation in sheep in order to make the Mate interaction more realistic
• make sheep grow from newborn to adult (become adult after e.g. 40 ticks)
• force newborns to stay with their mother, prevent them from eating grass and make them feed from their mother instead
• allow female to mate only if they have at most 2 newborns
• introduce seasonal variations in the food growth rate

Of course, a challenge here (but not related to IODA) is to find parameters which allow an equilibrium in the ecosystem! Besides this issue, if you are familiar with designing individual-based models, you should be able to notice the speed-up provided by the IODA approach.

A trigger (or a condition) is fulfilled if all primitives report true: the TRIGGER and CONDITION items of an interaction express a logical conjunction of primitives. Yet, sometimes you need to express alternatives (or logical disjunctions). To do so, you just need to put as many TRIGGER (or CONDITION) lines as necessary.

For example, the model provided in folder *4b-leap years* of the tutorials directory involves agents playing the role or years. In order to keep only leap years, agents can perform an interaction called = Survive=, which needs to express that a year is a leap year if, and only if, its value is divisible either by 400, or by 4 but not by 100. This is done using two CONDITION lines:

INTERACTION Survive
  CONDITION multiple-of-400
  CONDITION multiple-of-4 not:multiple-of-100
  ACTIONS   print-value
end

Thus, the interaction can occur if one (at least) of the CONDITION statements is fulfilled. If you have both triggers and conditions, at least one trigger AND at least one condition must be fulfilled. Other examples for using this feature are shown in the model 15-rescue the princess.

In order to avoid simulation biases, the IODA scheduler shuffles the list of labile agents before the update step, and the list of active agents before the interaction selection step (those steps are explained above). Yet, in some (rare) circumstances this is not adequate because the agents must act in a particular order. Thus we allow the user to define its own ordering policy for the update step and the interaction selection step, which consists in providing a two-parameter reporter task which decides whether agent ?1 must be scheduled before agent ?2 or not.

For example, if you want 'year' agents to print their value in the chronological order, they have to perform the Survive interaction according to the ascending order of their values. This can be performed by specifying an appropriate ordering policy for interaction selection after the execution of ioda:setup:

to setup
  clear-all
  init-world
  ioda:load-interactions "interactions.txt"
  ioda:load-matrices "matrix.txt" " \t"
  ioda:setup
  if chronological-order?
    [ ioda:set-ordering-policy-for-interaction-selection task chronological-ordering ]
  reset-ticks
end

to-report chronological-ordering [ag1 ag2]
  report [value] of ag1 < [value] of ag2
end

The ioda:set-ordering-policy-for-interaction-selection primitive specifies the task to use for scheduling active agents before the interaction selection step ; similarly, the ioda:set-ordering-policy-for-update primitive specifies the task to use for scheduling labile agents before the update step. In both cases you can use the string "random" as parameter value so as to restore the default policy (shuffling the lists of agents). In most situations you need no special ordering policy. Use them with caution in order to avoid simulation biases!

In the interaction selection process, all realizable interaction/target pairs with a same priority level (eventually with target = nobody), i.e. pairs for which trigger and condition are fulfilled, can occur with equal probability . But, is some cases, this might lead to an unconvincing behavior, or even to biased actions. For instance, if you consider implementing pheromones following, you expect your agents to go where pheromones have the highest level. In this tutorial, we are going to deal with this very problem.

We are starting with a simple path following problem, with two kinds of agents: patches, which contain a certain amount of pheromones (according to a constant distribution), and ants which have to follow the pheromone gradient uphill. For convenience, ants die when they reach the highest level of pheromones: what is of interest here is the path followed. We can summarize the problem with the interaction matrix below.

Put the following lines in text a file called "interactions.txt":

; FollowGradient is a parallel interaction because
; a same patch can be the target of several ants
parallel interaction FollowGradient
  trigger low-pheromone?
  condition feel-gradient?
  actions move-towards
end

parallel interaction MoveRandomly
  trigger target:no-pheromone?
  actions wiggle
end

parallel interaction Die
  trigger target:high-pheromone?
  actions die
end

Put the following lines in a text file called "matrix.txt":

ants	Die    		20	patches 0.5
ants	FollowGradient	10	patches 2
ants 	MoveRandomly	0	patches	1

Finally, here is the code of the program with appropriate primitives:

__includes ["IODA_2_3.nls"] 
extensions [ioda]
 
breed [ants ant]
patches-own [pheromone]
  
to setup
  clear-all
  set-default-shape ants "ant"
  init-patches
  create-ants 200 
    [ setxy random-xcor random-ycor
      set color brown  pen-down ]
  ioda:load-interactions "interactions.txt"
  ioda:load-matrices "matrix.txt" " \t"
  ioda:setup
  reset-ticks
end

to init-patches
  ask patch -5 5 [ set pheromone 1000 ]
  repeat 10 [ diffuse pheromone 0.5 ]
  let m max [pheromone] of patches
  ask patches 
    [ set pcolor scale-color yellow pheromone 0 m ]
end

to go
  tick 
  ioda:go
  if (not any? ants) [stop]
end

; restricts perception to patch here and surrounding patches
to ants::filter-neighbors
  ioda:filter-neighbors-on-patches (patch-set patch-here neighbors)
end

to ants::die
  ioda:die
end

to-report patches::high-pheromone?
  report pheromone > 40 
end

to-report ants::low-pheromone?
  report pheromone < 40
end

to-report ants::feel-gradient?
  report [pheromone] of ioda:my-target > [pheromone] of patch-here
end

to ants::move-towards
  face ioda:my-target
  fd 1
end

to-report patches::no-pheromone?
  report pheromone < 1
end

to ants::wiggle  
  left random 45 right random 45 fd 1 
end

Try this model. You should see your ants wiggle and go more or less directly to the center of the yellow hill. However, you also can observe that their trails are not quite straight (see figure a below). They can reach the center thanks to the feel-gradient? primitive, which ensures that an ant moves to a neighboring patch only if the value of the pheromone on the new patch is higher than the value on the current patch. But, this does not mean at all that the ant chooses the patch with the highest pheromone level .

Obviously, we would expect ants to perform FollowGradient on "best" patches, i.e. on patches where the amount of pheromone is higher that others, or where it is the highest.

IODA provides generic tools for refining the way interaction/target pairs are chosen. These tools are called Target Selection Policies (TSP). TSP are integrated in the IODA simulation engine, with a default policy: RANDOM, which ensures an equiprobable choice between all interaction/target pairs with the same priority level.

The IODA NetLogo extension provides several other Target Selection Policies, among those which are most often needed. For now, we introduce two frequent policies: BEST and PRORATA.

• BEST allows to select the target among agents that maximize a given reporter
• PRORATA allows to select the target with a probability that is proportional to a given reporter

In the case of pheromones following, we can compare those policies, using a reporter that gives the amount of pheromones on a patch.

Add the following reporter to your procedures:

to-report patches::pheromone
  report pheromone
end

Put the following lines in a text file called "matrix-PRORATA.txt":

ants 	Die		20	patches 0.5
ants	FollowGradient	10	patches 2	PRORATA:pheromone
ants 	MoveRandomly	0	patches	1

Put the following lines in a text file called "matrix-BEST.txt":

ants 	Die		20	patches 0.5
ants	FollowGradient	10	patches 2	BEST:pheromone
ants 	MoveRandomly	0	patches	1

Test your model with each of the new matrices. You should obtain different trails, as shown on figures b and c below.

The figures below come from simulations with respectively a RANDOM (a), a PRORATA (b) and a BEST (c) Target Selection Policy. You can clearly see that, in the area where pheromones are felt, the trails left by ants are more and more deterministic. Especially, in the BEST TSP, the ants go straight to the patch with the highest pheromone level.

Target Selection Policies are designed to help you to specify preferences in the way target are chosen in an assignation. Thus you can indicate one at the end of a line in the interaction matrix. Of course it does not make sense in a reflexive interaction

To use a Target Selection Policy, just add, at the end of the appropriate line, the keyword refering to the TSP (e.g. BEST or PRORATA) followed with ":" and the name of the abstract primitive which must be used to compare targets. That means that you have to write an additional concrete primitive, depending on the nature of the target agents. In the example above, the BEST:pheromone clause is used in the context where the target is a patch: hence you have to write a concrete reporter named patches::pheromone.

Other Target Selection Policies are presented in Tutorial #8.

Try to reproduce the classical "Ants" NetLogo model (Models Library → Biology → Ants) with IODA, using only agents. We suggest you start with the the following interaction and update matrices:

• First, look closely at the original NetLogo model and compare the actions of the turtles to find the appropriate matching with the IODA model.
• In the interaction and update matrices above, the following assumptions are made:
  • The path to the nest is not the problem, hence we can put the nest at (0,0) and go straight to it (ReturnToNest).
  • Pheromones are true agents instead of a patch variable: thus, diffusion and evaporation are handled through interactions (MoveRandomly and Evaporate respectively); pheromones can also merge (Take) since it does not make sense to have several pheromones agents at the same place. Finally, they Die when their value is too low.
  • Food pieces are true agents too.
• First, try to write the definition of the interactions. If you really encounter difficulties, or if you want to check your ideas, we propose a solution below.
• Be careful, some interactions must be exclusive, otherwise you might get inconsistent behaviors! Do not rely upon a clever ad hoc implementation of the primitives, use the meaning of the interaction instead, to decide whether it is exclusive or parallel.
• When writing the matrix file, use the appropriate Target Selection Policy for efficient pheromones following. We propose a solution below.
• Implement your model step by step (and test it!) : e.g. start with MoveRandomly, then add Take and ReturnToNest, and so on.
• Make use of the difference between abstract and concrete primitives, so as to define multi-purpose interactions that can support similar rules. (e.g. Take food vs. Take pheromones).

We propose the following interactions to reproduce the Ants simulation:

parallel interaction Follow
  trigger 	foraging?
  actions	follow-target  target:decrease-strength
end

exclusive interaction Take
  condition	can-take-load?
  actions	take-target  target:die
end

interaction MoveRandomly
  actions 	wiggle
end

interaction ReturnToNest
  trigger 	carrying-food?
  actions	drop-pheromone  move-to-home
end

interaction DropFood
  condition	carrying-food?
  actions	drop-load  turn-back
end

exclusive interaction Die 
  trigger  	too-weak?
  actions	die
end

interaction Evaporate
  actions decrease-strength
end

We propose the following matrix file to reproduce the Ants simulation:

; FILE FORMAT: 
; Source	Interaction  priority [UPDATE]
; or
; Source	Interaction  priority  Target  distance [<TARGET-SEL-METHOD>]

; interactions performed by ants
Ants	Take 	      30	Food        1	
Ants	DropFood      30	Nests       1
Ants	Follow        20	Food        5	
Ants	Follow 	      10	Pheromones  5	BEST:strength
Ants	ReturnToNest  10
Ants 	MoveRandomly  0

; interactions performed by pheromones
Pheromones	Die           20
Pheromones 	Take          10 	Pheromones  0.8
Pheromones	MoveRandomly  0
Pheromones	Evaporate     10	UPDATE

Your simulation will probably look like this little movie, which demonstrates several additional features:

• Food agents are created in three piles (coordinates-based areas) as in the original model.
• Food agents owns a quality attribute, and ants choose the best quality (among perceived food agents).
• The quantity of food droped on the nest is shown with a counter (updated through an interaction).

Please have a look at the "6-ants-and-food" folder in the tutorials directory for the details.

As mentioned before (details about the simulation step), each potential source agent has to indentify the potential targets of interactions. In other words, among all other agents, each active agent has to retain only those that are likely to undergo an interaction. The simulation engine retains those that fulfil the following criteria:

• first, they must be passive agents (non-empty column in the interaction matrix)
• among passive agents, only those which have non-empty cells on the row of the source agent in the interaction matrix can be retained

Yet, before each interaction is evaluated for those agents (using the triggers, conditions and limit distance), there is in general an intermediate step: in most individual-based models the perception is only local, thus each agent is endowed with a neighborhood function which defines what other agents are considered close enough to be perceived. In the IODA NetLogo extension, this user-defined function is <breed>::filter-neighbors. Since version 2.3, agent perception has been considerably improved. We show below several built-in primitives of the extension that allow to define and compose easily perception areas at a reasonable computational cost.

The first example, provided in the 6b-neighborhoods directory of the tutorials folder, is inspired by the "Vision Cone Example" model in the NetLogo library (Models Library → Code Examples → Vision Cone Example) with two breeds: wanderers and standers. Wanderers move around and "light" the standers in their neighborhood.

The neighborhood itself in this example can be built from the combination of several perception primitives. Basically, since v 2.3 there are four main set operations which can be associated with five geometric operations:

For instance, the following definition starts with agents within a radius of 10, adds those in cone of radius 30 and angle 30, then removes the agents within a radius of 5:

to wanderers::filter-neighbors
  ioda:filter-neighbors-in-radius 10
  ioda:add-neighbors-in-cone 30 30
  ioda:remove-neighbors-in-radius 5
end

which leads to the following perception shape:

The geometric operations mentioned above are metrics-dependent and able to cope automatically with x- or y-wrapping.

NetLogo links provide also a kind of neighborhood that can be useful for handling "social" networks i.e. acquaintances relations between agents. Such a model is demonstrated in the 6c-network directory of the tutorials folder, where all breeds can be bound by friendship relations (undirected link breed) on the one hand, while persons and banks may have an account in another bank (directed link breed).

IODA perception primitives based on the on-links geometric operations select the appropriate link neighbors to add to the list of potential interaction targets. For instance:

to persons::filter-neighbors
  ioda:filter-neighbors-on-links my-out-accounts  ; banks where I have an account
  ioda:add-neighbors-on-links my-friends    ; my friends (other persons or banks)
end

N.B.: In the matrix file of this example, please note the Infinity word used as a limit distance, so as to signify that the physical distance is not to be taken into account (the corresponding actions are not restricted by physical distance).

Custom perception tasks may also be used for defining more complex perception modes without changing the behaviors (interactions and matrix files) of the agents. For instance, in the 6d-termites-with-colored-chips directory of the tutorials folder demonstrates how to change the behavior of the termites so as specialize agents in a color. Wood chips are endowed with a specific color and so do the termites. We want each termite to focus only on the wood chips of the same color, without any modification of existing interactions.

Therefore, we can modify the perception of termites so as to make them discard any neighbors with a "wrong" color:

to termites::filter-neighbors
  ; first the usual in-radius filtering
  ioda:filter-neighbors-in-radius 1
  ; then we retain only the neighbors that fulfil the specified reporter
  ioda:retain-only-neighbors-custom "same-color?" []
end

; a reporter with two agents and a list of parameters (not used here)
to-report same-color? [ ag1 ag2 p ]
  report shade-of? [color] of ag1 [color] of ag2
end

Then due to this special filtering, the simulation runs as if several independent worlds were just sharing a common space without any relation between them, leading to the expected result:

The files provided in the folder 8-explosion of the tutorials directory aim at demonstrating several target selection policies available in IODA NetLogo. You are recommended to launch the corresponding model and to experiment while reading this section of the tutorial.

Below is the Blast interaction:

EXCLUSIVE INTERACTION Blast
  TRIGGER activated? countdown-finished?
  CONDITION target:no-shield?
  ACTIONS target:die die
END

As it has been explained above, the default process used for interaction and target selection retrieves all interaction/target pairs for which the trigger and condition are fulfilled, then selects one pair randomly (the target can be nobody). This process is suitable for most simulations.

Yet, suppose we have now the following interaction matrix:

When a mine performs the Defuse interaction, it does not explode at all. The priority for that interaction is the same than for Blast other soldiers, but since it is a reflexive interaction, the target is nobody. Thus, the probability that Defuse occurs is: 1/(N + 1), where N is the number of unprotected soldiers within the Blast radius (here, 4).

But, if the specifications of the simulation require that the Defuse and Blast interactions occur with the same probability, the default target selection policy is not suitable. Then, you can use the interaction-first selection policy: when several interactions have the same priority, a first random selection occurs (with equal probability) among those interactions (if they have potential targets), then for the interaction that was selected, the target is chosen randomly. In our case, the probability for each interaction is 1/2, though Blast has a large number of potential targets while Defuse has only 1 (as a reflexive interaction).

To use the interaction-first policy, you just have to use the keyword RANDOM-INT at the end of the matrix line.

In the tutorial model, compare the two experiments named "RANDOM" and "RANDOM-INT": in the latter, there is a probability 1/2 that the mine does not explode. Examine the corresponding matrix files to see the difference.

We have already introduced property-driven selection policies in the pheromones section of this tutorial. By using the keyword BEST: (resp. PRORATA:), followed by an abstract reporter, you ensure that the target is chosen with the highest value of the reporter (resp. with a probability which is proportional to the reporter). By using the keyword ALL-BEST: with a reporter, the target of the interaction is the list of all targets with the highest value for the reporter.

In the tutorial model, compare the three experiments named "BEST", "PRORATA" and "ALL-BEST". The reporter that is used there is weakness (the opposite of the strength of the soldier): thus, with "BEST" one of the weakest soldier is killed; with "ALL-BEST", all soldiers with the smallest strength are killed; and with "PRORATA", one soldier is killed, with a probability proportional to its weakness.

The three policies we present here allow a source to perform an interaction on a list of agents .

ALL

When this policy is used, the target of the interaction is made of all target agents that fulfill the trigger and condition, within the limit distance.

In the tutorial model, if you experiment "ALL", the mine will blast all soldiers which are not protected by a shield.

NUMBER:x-y, NUMBER:x-, NUMBER:-y, NUMBER:z

When this policy is used, the target of the interaction is made of N target agents that fulfill the trigger and condition, within the limit distance. The highest number of agents is taken, with x ≤ N ≤ y (respectively: x ≤ N, N ≤ y, N = z). If the number of targets is below x, the interaction cannot be performed.

In the tutorial model, you can compare experiments "NUMBER-10" (blast up to 10 soldiers), "NUMBER10-" (blast at least 10) and "NUMBER45-" (blast at least 45), which is not possible when too many soldiers wear a shield). In the latter, the Blast interaction cannot be performed on soldiers when too many of them wear a shield: then, only the reflexive occurrence of Blast (with a lower priority, see the interaction matrix above) is performed (the mine explodes without killing anyone).

FILTER:reporter

With this policy, the target of the interaction is first made of all target agents that fulfill the trigger and condition, within the limit distance. Then the source agent runs the specified reporter to filter the target (accessible with the ioda:my-target reporter) according to global considerations.

In the tutorial model, you can compare experiments "FILTER1" and "FILTER2". In the first one, a global damage budget is used to determine which soldiers are killed, depending on their proximity to the mine and their own strength (see procedure mines::distance-strength-tradeoff). In the second one, a random number of soldiers is killed (see mines::random-number).

• When using selection policies which allow to perform an interaction on multiple targets at the same time, do not forget when writing the concrete action primitives of the source that ioda:my-target reports a list . Trigger and condition are evaluated for each potential target individually, and actions performed by the target too (e.g. in the Blast interaction, target:die).
• When a source can perform several interactions at the same priority level with the same source, be very careful if you decide to use different target selection policies. You must be sure to write consistent lines in the matrix. For instance, if you have a Blast and a Hurt interactions realizable at the same time on soldiers, if one uses "RANDOM-INT" and the other nothing (or "RANDOM"), then "RANDOM-INT" overpowers "RANDOM" and is used for both.

As you can see in the interface tab of the provided model, you can change the metric used to compute distances between agents. This can be useful in several situations, especially when working with discretized space. By default, the ioda:setup procedure sets a variable (ioda:metric) to "Euclidean". You can change this value after the setup through the ioda:set-metric primitive. Valid parameters are the following:

• "Euclidean" (default value): the usual distance, or 2-norm distance, defined by:
  d(p₁, p₂) = ((x₁ - x₂)² +  (y₁ - y₂)²)^1/2
• "Moore" : also called ∞-norm distance or Chebyshev distance, defined by:
  d(p₁, p₂) = max(|x₁ - x-2|, |y₁ - y_2|)
• "Von Neumann" : also called the taxicab norm, or Manhattan distance, or 1-norm distance, defined by:
  d(p₁, p₂) = |x₁ - x_2| + |y₁ - y_2|

When a metric is chosen, it is used by neighbor perception primitives and by ioda:distance. All three metrics automatically deal with x- or y-wrapping.

Table 12: Initial configuration with a Moore metric (a) or a Von Neumann metric (b).

(a)	(b)