This document aims at explaining how to implement an application with the MECSYCO framework. It focuses on a technical and implementation viewpoint (how to code), neither modelling, nor meta-modelling viewpoints (how to model, why these choices).
Some knowledge about multi-modelling, the
concepts, NetLogo modeling and the Java programming language could be helpful.
The environment used in this tutorial is Eclipse Luna 4.4.1 with the Java Development Kit 1.7.
Download the “getting started” eclipse project and import it in Eclipse through the import wizard (figure 1).
Random walk model
At first, you can take a look about the model’s behavior.
You can run the model located at My Models/Netlogo-Models/random_walk_1.nlogo via the NetLogo Editor (Figure 2). This editor is not shipped with the Getting Started project.
The model creates a pool of walkers – NetLogo turtles – positioned at the origin. For each step – NetLogo tick – the hidden walkers die and the other ones move in a random direction. When a walker overpasses the border of the world, in other words, is on a gray ground, it is hidden Therefore the count of walkers decreases over time.
The petri network in figure 3 represents a walker’s state.
Each place is a fulfilled condition and a transition is an event. Only one transition is playable by step.
The walkers out of the world scope are hidden and die at the next simulation step. Thus, after each step, the hidden walkers represent the walkers who leave the world. We use this characteristic for retrieving and exchanging the walkers.
A minimal example is the launching of a NetLogo model from a
model (Figure 4) only consists in a m-agent and a Model Artifact.
The m-agent is a generic component shipped with the
core. It intercepts each step of the simulation it is in charge of, and communicates via the model artifact.
A model artifact is a domain-specific component. However, it is possible to have a generic artifact simulator-dependent.
At this time, there is no generic version of a NetLogo model artifact. Thus, the model artifacts must be implemented by the user.
A model artifact is like the interface between the model instance under simulation and the m-agent. A NetLogo model artifact also adds output and input ports.
The model artifact created for the current example adds one output and one input ports. The output port provides the walkers which leave the world. The received walkers in the input port spawn at the world’s origin.
The figure 5 presents an intuitive scheme of the NetLogo model equipped with an output port and an input port.
launcher.MinimalExampleLauncher instantiates this model.
At line 2, the M-agent is created with the duration of the simulation (
maxSimulationTime). Here, the duration quantifies the number of NetLogo ticks to perform.
The model artifact is created at line 5 with the path to the model (
Model with loopback
We would like to retrieve the walkers which leave the world and spawn them at the world’s origin. The simpler way to do it is to create a loopback on the model connecting the output port to the input port (figure 6).
model, the connection between output and input ports is modeled with a coupling artifact. It is also a generic component shipped with the core.
It links two m-agents (or a m-agent with itself).
model is shown in the figure 7.
Only three extra lines of code are needed to establish this connection (Code 2 line 8 to 10).
The lines 9 and 10 specify respectively the destination – the model input - and the source – the model output – of the coupling artifact. In this example, the coupling artifact links the M-agent with itself.
Since there is only an input and an output, the chosen port names (“in” and “out”) are not relevant. When there exists several input ports and/or output ports, the port name enables a simple port discrimination in the model artifact.
At each tick, the M-agent gets the hidden walkers from the model artifact output and then sends them to the model artifact input. The model artifact creates as many new walkers as received. Freshly created walkers have the same color and the same size than the received ones.
Then, when you run the
model, you note that the count of walkers is constant over time.
Hum… I admit that the new walkers are hardly noticeable. Why not use another color for freshly created walkers?
It would be great to change the color of each exchanged walker before their transmission to the model artifact. In more generic terms, we would like to apply transformations on the exchanged data.
have such a feature. It’s named operation. There are no needs to introduce a new model artifact or modify the existing one.
An operation is symbolized by a point and it is placed on a coupling artifact (Figure 8). It is applied to the data which cross the coupling artifact.
The operation is shipped with the example (
operation.TurtleColorSetter). Only two lines are required for adding this operation (Code 3 lines 8 and 11).
Then you can observe in figure 9 that the newly created walkers appear at the model’s origin.
Great, isn’t it?
Well! You are ready to make two NetLogo models interact!
We would like to simply retrieve the walkers which leave a given world and then inject them in the other world (Figure 10).
Figure 11 exhibits the equivalent
The walker’s color depends on the world where it appears the first time. The walkers from the first world are green and the walkers from the second one are red.
Create a new launcher
InteractingRandomWalkLauncher based on
model.SingleRandomWalkLauncher (Code 4).
The result of the previous code is shown in figure 12.
Of course you can create more worlds and connect them together.
Any kind of transformations can be applied on the exchanged data. A
model allows the combination of operations.
For instance, we could combine a size setter operation with the color setter operation of the first example.
model is in the figure 13.
The size setter operation is not part of the getting started package. It is an opportunity for creating your first operation!
Create a new class named
mecsyco.core.operation.EventOperation. The apply method must be defined (Code 5).
The argument aEvent is the exchanged event. Typed as
mecsyco.core.type.SimulEvent, it consists of the time where an event occurs and the associated exchanged data, typed as
The SimulVector contains a set of walkers typed as
This last type embeds the NetLogo turtle’s characteristics, in particular their color and their size.
Add the operation into the coupling artifact (Code 6 and Figure 14).
Model artifact creation
Currently, the agents exchange walkers. However, the only useful information is the number of walkers with a specific color leaving a given world.
Instead of exchanging all the walkers, we could create another model artifact exchanging only the number of walker with a specific color. (Figure 15).
This change requires the creation of a new model artifact.
Create a class named
RandomWalkModelArtifact which copy the code of
getExternalOutputEvent is the method used by the m-agent for retrieving the events. It represents the output port while
processExternalInputEvent is used for introducing a new event into the model and then represents the input port.
Only these two methods must be modified.
getExternalOutputEvent must send the color counts, i.e. the number of occurrences of a given walker’s color.
common.type.Bag offers facilities to perform this counting.
processExternalInputEvent must retrieve the exchanged data and create the walkers with their attached color (Code 7).
At the line 8 we retrieve the received data – the color counts – typed as a bag of color. We use the NetLogo color coding and represent a color by a double.
The lines 14 to 20 process the bag of color and build the NetLogo command. In case of error we add a system of warning.
At line 23,
execCmd calls the NetLogo interpreter with the previously built command as argument.
At the line 43, we retrieve the hidden turtles thanks to the NetLogo interpreter.
The bag of color, instantiated at the 46-th line, is fulfilled at the line 49 with the turtle’s color.
RandomWalkModelArtifact in the
InteractingRandomWalkLauncher class. The result is identical, as expected but the data exchanged is optimized.
You can see the final results in the set of downloadable applications.
The other available examples follow the same principles.