IODA NetLogo Documentation

IODA NetLogo 2.3 User Manual 

Direct links to other parts of the IODA NetLogo Manual:TutorialFAQDictionary


The IODA NetLogo extension provides users of NetLogo (Wilensky, 1999) with many features of the IODA Methodology – "IODA" stands for "Interaction-Oriented Design of Agent simulations" (Kubera et al., 2008, 2011).

The IODA approach aims at simplifying the design and reusability of individual-based simulations. It relies upon three key ideas:

  • The declarative parts of the model should be separated from the procedural parts as far as possible.
    • declarative parts include the nature of the agents and how they can interact
    • procedural parts include essentially the simulation engine (scheduling, action selection algorithms…)
  • Thus, any relevant entity of a model is represented by an agent (Kubera et al., 2010).
  • Any behavior is encoded through a generic rule called an interaction. Basically, an interaction is a condition/action rule involving two agents: a source that performs the interaction and a target which undergoes it. Interactions must be designed independently from the specificities of agents (and vice-versa).
  • The matching between agents and interactions is ensured through:
    • an interaction matrix which indicates what interactions an agent may perform or undergo, and with what other agents
    • a generic simulation engine which asks potential source agents to select and perform an interaction and a target agent.

Thus the design of an individual-based model is split into three main tasks, through a top-down process:

  1. write the interaction matrix: who can do what with whom ?
  2. describe the interactions i.e. each behavioral rule
  3. write the elementary capabilities of the agents i.e. small code primitives

The goal of this extension is to allow NetLogo users to get familiar with the IODA approach, and use it within their models, for research or educational purpose. For more information on the IODA approach, please consult the IODA NetLogo Tutorials, the IODA webpage and the research papers mentioned below.


The IODA NetLogo package can be downloaded from this page.

Application examples

On-line examples from the tutorial files

You can have a look at a few examples on-line (without downloading the extension itself) through NetLogo applets on the IODA NetLogo webpage.

Other projects

The IODA NetLogo extension has been used for the realization of several applicative projects, among them:

  • MInOTAUR, a tactile platform for mixing software agents with tangible artifacts and humans
  • TrafficGen, a multi-purpose traffic simulator based on open cartographic data.

Other projects based on the IODA methodology have been developed using different programming languages or environments, for instance:

  • Galaxian, a space battle simulation written in C# within the professional game engine Unity3d (aimed at running for hours on a 6m-wide immersive screen)
  • FormatStore, a serious game dedicated to vendor training, written in Java, Javascript and VRML

What's New?

Version 2.3

  • New features
    • New primitives for the composition of different capabilities in neighbors perception: several predefined methods can be used (in-radius, in-cone, on-patches, on-links…) as well as set operations (union, intersection, difference)
    • New keyword NOT: added for simplifying the definition of interactions
    • Interactions can now be added or modified through a string, during runtime
    • Interaction and update matrices can be modified by adding/removing items, either by loading additional files or by changing elements manually
    • Interaction and update matrices, as well as new or modified interactions, can be saved into text files.
  • General changes
    • Considerable increase of efficiency (through the use of NetLogo tasks for handling perception and primitives) — see FAQ page for details
    • Tutorial #5 (pheromones): perception of ants changed to patch-here + neighbors
    • Tutorial #12 (colors): modified to provide a custom simulation generator with the ability to generate random interaction matrix, add or remove interactions on-the-fly, and save interesting matrices into a text file
    • Tutorial #14 (age of crisis): updated to use the new perception methods
    • Tutorial examples updated to use the NOT: keyword in the definition of interactions
  • New tutorial models added:
    • #6b (neighborhood) which demonstrates how to compose neighbors perception capabilities
    • #6c (network) which demonstrates how to use link neighbors in the perception capabilities
    • #6d (colored chips) which provides an example of custom reporter-based perception
    • #8b (dynamic matrices) which shows how to change dynamically the content of the interaction or update matrices
    • #16 (lactose operon) which demonstrates a model of genetic regulation
  • Bugs fixed
    • all predefined metrics ("Euclidean", "Von Neumann" and "Moore") are now able to cope automatically with X/Y world wrapping
    • Minor corrections in tutorial pages

Version 2.2

  • New features
    • Ordering Policies can now be set up for both update step and interaction selection step (random by default)
    • Alternatives can be easily specified both in triggers and conditions
    • New tutorial model added: #4b (leap years) which demonstrates the new features
    • New tutorial model added: #15 (rescue the princess) – see description here
  • General changes
    • Tutorial page: all code examples now use the NetLogo 5 clear-all…=reset-ticks= scheme
    • Tutorial page: updated image of the runtime error in tutorial #1
    • Tutorial #2 (termites): modification of the model so as to be closer to the original NetLogo model (code and tutorial page)
    • Tutorial #3 (termites with chips): correction of an error in the interaction matrix (code and tutorial page)
    • Added a plot in Tutorial model #11 (primes)
  • Bugs fixed
    • Extension primitives ioda:primitives-to-write and ioda:check-consistency do not raise exceptions any more
    • Models saved as applets are able now to read the interaction and matrix files

Version 2.1

  • General
    • Modification of the source code so as to comply with the NetLogo 5.0 API

Version 2.0

  • General
    • Refactoring of the previous (non-public) IODA NetLogo extension from pure include file to Java extension + include file


The ioda folder is provided with the following items:

  • ioda.jar: the JAR file that contains the IODA NetLogo extension itself, which defines three data types (interaction, assignation and matrix) with their own commands and reporters
  • ioda.jar.pack.gz: a compressed version of the JAR file (used e.g. for applets)
  • IODA_2_3.nls: the NetLogo include file which contains the standard IODA simulation engine
  • a src folder with the Java source code of the extension
  • a doc folder with the documentation of the extension, i.e.:
  • a tutorials folder with several examples
  • gpl.txt, a copy of the GNU General Public License (version 3) – see "Terms of Use" below.

How to install

The IODA NetLogo extension 2.3 has been developed for NetLogo 5.1 (and should work for NetLogo 5.0). If you are still using NetLogo 4.1.3, please use IODA NetLogo 2.0 instead.

To install the IODA NetLogo extension for use by any model, place IODA's folder either in the extensions directory in the NetLogo directory, or in the same folder as the model that uses it. For more information about other ways of installing an extension refer to the NetLogo Extensions Guide.

In order to use the IODA simulation engine, your NetLogo code must include the file named IODA_2_3.nls. Thus, if the IODA folder is installed in the NetLogo directory, it could be useful to put a copy of this file (or a symbolic link) next to your own NetLogo model, in order to use a relative path instead of an absolute path.

Getting started

See the Tutorial for a comprehensive, step-by-step guide of using the IODA methodology within NetLogo simulations.

The main usage pattern of IODA in NetLogo models is as follows: The user creates a model for the problem to study, according to the IODA methodology (Kubera et al. 2011). A IODA model is composed of the following elements:

  • A list of agents: those agents are supported by NetLogo turtles (or user-defined breeds) and patches; they can be endowed with their own variables and reporters/commands</li>
  • A list of interactions: an interaction is a condition/actions rule, which captures the abstract features of a behavior; it involves a source agent (which performs the interaction) and one (or more) target agents (which undergo the interaction). The definition of interactions can be done manually in the NetLogo program, but you are recommended to describe them in a text file, like in the tutorial examples.
  • An interaction matrix and an update matrix which specify how interactions are assigned to agents. The update matrix contains interactions that each agent tries to perform in the beginning of a simulation step. The interaction matrix specifies what interactions an agent X may perform over an agent Y. Here again, you are recommended to write those matrices in a text file (CSV format), like in the examples.
  • A list of agent primitives: these primitives are reporters and commands that will be evaluated or run by the agents when trying to perform or undergo interactions. Interactions are written using abstract primitives: thus, agents must implement concrete primitives according to the interactions they can perform or undergo. For instance, if agents of the breed wolves can perform (i.e. be the source) of an interaction that contains the abstract primitives hungry? (in trigger/condition) and follow (in actions), then two concrete primitives must be written: a reporter named wolves::hungry?, and a command named wolves::follow.

The IODA NetLogo extension provides tools for checking the consistency of a model, i.e. to ensure that all concrete primitives have been written with respect to the definition of interactions, the interaction matrix and the update matrix.

After defining those items, you have to write a setup procedure to initialize your simulation and a go procedure to run it. If you simply want to make use of the predefined IODA simulation engine, just put ioda:setup at the end of your setup procedure, and ioda:go at the beginning of your go procedure. That's all!


Y. KUBERA, P. MATHIEU and S. PICAULT (2011), "IODA: an interaction-oriented approach for multi-agent based simulations", in: Journal of Autonomous Agents and Multi-Agent Systems (JAAMAS), vol. 23 (3), p. 303-343, Springer DOI: 10.1007/s10458-010-9164-z.

Y. KUBERA, P. MATHIEU and S. PICAULT (2010), "Everything can be Agent!", in: van der Hoek et al. (eds.), Proceedings of the 9th International Joint Conference on Autonomous Agents and Multi-Agent Systems (AAMAS 2010), Toronto, p. 1547-1548.

Y. KUBERA, P. MATHIEU and S. PICAULT (2008), "Interaction-Oriented Agent Simulations: From Theory to Implementation", in: M. Ghallab, C.D. Spyropoulos, N. Fakotakis, M. Avouris (eds.), 18th European Conference on Artificial Intelligence (ECAI'08), Frontiers in Artificial Intelligence Applications, IOS Press, p. 383-387, ISBN 978-1-58603-891-5.

P. MATHIEU and S. PICAULT (2005), "Towards an interaction-based design of behaviors", in: M.-P. Gleizes (ed.), Proceedings of the The Third European Workshop on Multi-Agent Systems (EUMAS'2005).

U. WILENSKY (1999), NetLogo. Center for Connected Learning and Computer-Based Modeling, Northwestern University. Evanston, IL.

Contact Information

Authors: Sébastien PICAULT and Philippe MATHIEU

Email: ioda (at)

Team Web Site:

Terms of Use

Valid HTML
  4.01 Strict

All contents © 2008-2015 Sébastien PICAULT and Philippe MATHIEU – SMAC Research Team
Centre de Recherche en Informatique, Signal et Automatique de Lille (CRIStAL), UMR CNRS 9189
Université de Lille (Sciences et Technologies) – Cité Scientifique, F-59655 Villeneuve d'Ascq Cedex, FRANCE.

The IODA NetLogo extension is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The IODA NetLogo extension is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with IODA NetLogo extension. If not, see     SMAC logo     CRIStAL logo     CNRS logo     University of Lille logo

Created with Emacs Org-mode