IODA NetLogo Frequently Asked Questions

"IODA" stands for "Interaction-Oriented Design of Agent simulations".

• The IODA methodology and simulation algorithms (i.e. what is actually in use in this NetLogo extension):
  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.
• The key ideas of the IODA methodology:
  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).
• Do not forget to cite also NetLogo itself when you refer to the IODA NetLogo extension:
  U. WILENSKY (1999), NetLogo. http://ccl.northwestern.edu/netlogo Center for Connected Learning and Computer-Based Modeling, Northwestern University. Evanston, IL.

This methodology was born in the MultiAgent Research Team of the Centre de Recherche en Informatique, Signal et Automatique de Lille (CRIStAL), UMR CNRS 9189 at the Université de Lille (Sciences et Technologies), France. For more information on IODA please consult the IODA webpage and the SMAC Research Team webpage.

• The IODA NetLogo extension is composed of a JAR file written in Java (ioda.jar) for the definition of new data types and file parsing, and an include file written in the NetLogo language (IODA_2_3.nls) for the simulation engine.
• This extension is derived from a research platform in Java, called "JEDI" (for: "Java Environment for the Design of agent Interactions"), which is the exact implementation of all concepts and algorithms proposed in the IODA approach. A subset of this engine was used for the implementation of a Serious Game (see the Format-Store project).
• An experimental IODA version for the Unity 3 game engine has also been implemented, mostly in C# (see the Galaxian project).

The IODA NetLogo extension is released under the GNU General Public License, version 3 (see http://www.gnu.org/licenses). It is free and open source. The Java source code is available in the ioda/src folder, and the simulation engine is in file IODA_2_3.nls. We encourage users to report bugs or any suggestion for enhancing this extension, and share their IODA-based models with the NetLogo user community.

The IODA NetLogo extension version 2.3 is fully compatible with NetLogo version 5.x. If you are using NetLogo 4.1.3, please use the 2.0 instead. The 2.3 version incorporates API changes from NetLogo 4.1.3 to NetLogo 5.1, but does not use the new features (such as tasks) yet.

Not yet. Especially, the simulation engine (nls include file) has been designed to cope with 2D patches only. However, it should work with little code modification, both in Java classes and NetLogo include file.

Indeed a simulation with the IODA extension of NetLogo is still a bit slower than a simulation using only NetLogo, because the IODA simulation engine defines its own scheduler, and the interaction selection process is not that simple. However, we the think that for simulations involving complex relations between several kinds of entities, the loss of performance (compared with pure NetLogo) is widely counterbalanced by the facility to design and change models.

Yet, since version 2.3 considerable enhancements in the performances have been made possible through the use of Netlogo tasks. In version 2.3, tasks are used 1° for computing the neighbors of each agent, and 2° for handling the concrete primitives. The figures below show the the time required for three versions of the IODA engine for running a fixed number of ticks in two very differerent models from the tutorials directory: model #3 ("Termites with Chips") and model #14 ("Age of Crisis"). In the first one, using tasks only for handling the perception of neighbors (engine "2.2+" — development release) is quite enough to get a considerable increase of the efficiency. Yet, in more complex simulations involving much more agents families and interactions (model 14), the use of tasks to handle also the concrete primitives used by the interactions (engine 2.3) provides a substantial additional enhancement.

The name you want, since you can load any (syntactically correct) interactions file with the command ioda:load-interactions. Still, a name like "interactions.txt" is quite relevant.

No. You can write keywords, interaction names and primitive names in uppercase or lowercase.

The syntax is the following (as mentioned in the file interactions.txt in the tutorials/0-template folder):

[EXCLUSIVE|PARALLEL] INTERACTION <name>
[TRIGGER <tr_1> ... <tr_n>]
[...]
[TRIGGER <tr'_1> ... <tr'_n>]
[CONDITION <cond_1> ... <cond_n>]
[...]
[CONDITION <cond'_1> ... <cond'_n>]
[ACTIONS <act_1> ... <act_n>]
END

What is absolutely required is the interaction name. All other elements are optional.
The basics of interactions are described in the "particles" section of the tutorial. The difference between exclusive and parallel interactions is explained in there.
When you specify triggers and conditions, one trigger line (at least) and one condition line (at least) must be fulfilled so as to allow the interaction to occur. A trigger (or condition) line is fulfilled if and only if all primitives of the line report true. Thus, if you need to define alternative conditions or triggers, e.g. a year is a leap year if it is divisible either by 400, or by 4 but not by 100 (cf. tutorials, folder 4b-leap years), you can express this logical disjunction by using two CONDITION clauses.
Actions are performed in the specified sequence.

Yes, you can. You can achieve this through two methods:

• New or modified interactions can be written in separate files that you load with the ioda:load-interactions command.
• You can define an interaction "manually" using the ioda:interaction-make command.

In order to modify an existing interaction, you just need to build an interaction with the same name and the new definition.

Be sure that all concrete primitives required by all changes are already written in your code!

If needed, the set of all interactions (including the new or modified ones) canbe stored in a text file using the ioda:save-interactions command.

The name you want, since you can load any (syntactically correct) matrix file with the command ioda:load-matrices. Still, a name like "matrix.txt" is quite relevant.

No. You can write breed names, interaction names and other keywords in uppercase or lowercase.

The syntax is the following (as mentioned in the file matrix.txt in the tutorials/0-template folder):

<source> <interaction> <priority> UPDATE
OR: <source> <interaction> <priority>
OR: <source> <interaction> <priority> <target> <distance> [<target-selection-policy>]

Three items are required:

1. the name of the source breed
2. the name of the interaction
3. the priority of this interaction from the point of view of the source

With those three elements only, a reflexive interaction (i.e. an interaction performed on the source as target) is added to the interaction matrix. In order to add this line to the update matrix you only need to add the UPDATE keyword. Otherwise, to add a regular interaction to the interaction matrix, you need to specify at least two additional items:

1. the name of the target breed
2. the limit distance between source and target to allow the interaction to occur (if not relevant, this distance can be set to Infinity)

The last optional item (the target selection policy) specifies how the target of the interactions has to be chosen (default is random). For more information on target selection policies, please refer to the corresponding sections of the tutorial (Pheromones and Explosion).

Last remarks:

• This file is read as a CSV file, thus you can use any field separator char since you put it in the second argument of the ioda:load-matrices command.
• Any non-letter, non-digit, non '+'/'-' character at the beginning of the line introduces a comment line. Empty lines are ignored.

By default, matrix lines are simply added to the appropriate matrix (interaction matrix or update matrix). Yet, since v 2.3 you are provided with the ability to remove lines from the matrices.

Matrices modification can be achieved through two methods:

• You can specify an initial matrix together with predefined changes in separate files, and then use the ioda:load-matrices command to load each file when needed. This is demonstrated in the directory 8b-dynamic matrices of the tutorials folder. In that case, any line starting with the - character are removed from the appropriate matrix, while other lines (or starting with the optional + character) are added.
• You can use directly the appropriate commands (see the Dictionary): ioda:add-assignation and ioda:remove-assignation.

Be sure that all concrete primitives required by all changes are already written in your code!

If needed, the new interaction and update matrices can be stored in a text file using the ioda:save-matrices command.

Applets are now a deprecated feature in NetLogo. Yet, if you still want to export your model as an applet, you need to put the following files in the same directory:

• NetLogoLite.jar and NetLogoLite.jar.pack.gz (copy them from your NetLogo installation directory)
• IODA_2_3.nls
• a directory named ioda containing ioda.jar and ioda.jar.pack.gz
• your NetLogo model (e.g. model.nlogo) with the correct relative path to IODA_2_3.nls (i.e. __includes [ "IODA_2_3.nls" ])
• all additional text files describing your interactions and matrices (e.g. interaction.txt and matrix.txt)
• the HTML file generated when you "Save as applet" your model from the File menu (eg. model.html)