Introduction

In the next sections we will provide a quick hands-on introduction on Simflowny for ABM on graph, based on the Voter model . For further details please refer to Simflowny user guide.

The Voter model is a simple model in which, essentially, the binary value of an agent is changed according to the consensus of its neighbours bare a random noise.

Model creation

Although the Voter model is already preloaded in the basic models library in Simflowny, we will recreate it here. Firstly, you need to open Simflowny in a browser. See the Getting started section for details.

Select any folder, or create a new one [1] (we are going to store the model there) and click on the plus button:

A new menu is open, select "Agent Based Model on graph":

Then the document editor will open with the basic skeleton for a model on a graph. It is represented on the left panel, as an editable tree. The right panel is a more readable (non-editable) view of the model. The page will look like this:

First, let’s fill in the general description of the model, contained in the Head element. By expanding the head, its children are shown, namely name, id, author, version, and date:

The elements where action is required are highlighted in red. In the case above, the highlighted elements are compulsory and haven’t been filled in yet. To set the value of each element, click on the empty space on the right of the label, down the Input column. The Id is not editable but will be filled automatically by the editor the first time the document is saved. Let’s fill in the head information:

The document is periodically saved when changes are detected, marked with small red triangles. Once the document has been saved, red marks disappear.

The next step consists in defining the Vertex Properties. In Simflowny a Vertex Property is a variable which has a specific value for each vertex in a graph. One Vertex Property is the minimum necessary to define a model:

Let’s define the first Vertex Property as state, and let’s add a second Vertex Property. To do so, right-click on the parent element, Vertex Properties. This will show the contextual menu, in this case containing the options Add Vertex Property and Clear Vertex Properties. Click on Add Vertex Property:

This will create a new child of the Vertex Properties, which now needs to be filled in:

Our second Vertex Property for the Voter model is acc, standing for accumulator. This is just an auxiliary variable to accumulate neighbour values:

With this, we are ready to proceed with the definition of the model rules, the algorithms that tell the model how to change its state from step n to step n+1. In Simflowny this is specified under the element Rules. The contextual menu for rules allows to add two children: Gather Rules and Update Rules:

Gather Rules are potentially non-local update operations on a vertex property which, for a certain agent, may involve information about its neighbours. On the other hand, Update Rules are local update operations, using only information from the same vertex. While you can write any algorithm by using only gather rules, parallel performance and optimization are improved if you carefully separate local operation rules from operations which may involve neighbours (no synchronization between CPU processors is needed for updates), and, as an added bonus, the model description becomes much clearer.

When creating a Gather Rules element, one child comes automatically with it: a Gather Rule operation. You may have as many as you wish, but at least you need one:

A Gather Rule is defined by Name (any mnemotechnic name will do), Vertex Property (the specific vertex property to update, taken from a drop-down list; you need a gather rule per each vertex property you want to update), and Algorithm, which contains the actual instructions to execute. This first Gather Rule is on the vertex property acc.

The Algorithm element uses a common rule language called Simml. This is a common language used across Simflowny (Simml stands for Simulation Markup Language). By displaying Algorithm contextual menu we find many options:

The different elements you can add as children using Simml constitute a full-blown rule specification language for models (technically speaking, the language is Turing-complete, meaning you can create any possible algorithm with it). For a complete reference to Simml please consult Simml reference.

Going back to the model construction, by using the contextual menu, we add an Iterate Over Edges element. This statement implies a loop over all the edges (connections) of a certain vertex [2]. We wish to indicate the direction of the connection, so from the drop-down menu in the Direction Att Input column we select in (incoming edge; notice in directed graphs you have both incoming and outgoing edges). After this, we add a Math child to Iterate Over Edges:

Editing its value opens a special editor

This editor gives some hits to the user when writing mathematical expressions, using the limited AsciiMath [3] from Simflowny (See asciiMath reference). Some special tags, part of Simml language, can be used in the expressions. The buttons below the editor show all the available Simml tags to use, the editor provides a contextual help for them. Nevertheless, they are explained in detail in Simml reference.

In the textbox input we type:

acc($cv) = acc($cv) + state($es($ce))

The syntax for mathematical expressions can be learned very easily (see Simflowny User Guide). In the line above,

• $cv stands for current vertex
• $ce stands for current edge

• $es means the “from” vertex, or “source” of the edge

  • This may need a deeper explanation: notice both the edges and the two vertices participating in the edge may harbour properties, (vertex properties for vertices and edge properties* for edges). In this case we are interested in the vertex property harboured by the source vertex of the edge, this is, the vertex pointing to the current vertex in a directed graph. This is why we use the expression state($es($ce)). If we were interested in the value of a state edge roperty harboured by the edge, providing it was defined previously, we would use state($ce).

The initialization of acc($cv) will be taken care of in an appropriate update rule. See update rules below.

The Simml reserved words, in this example $cv, $es and $ce, can be added through the buttons below or directly writen.

Alltogether, the expression updates the acc vertex property of each vertex by adding the value of the state vertex property from the vertices connected by the edge with the current vertex. This is, acc accumulates the values of state for all the (incoming) pairs of a certain vertex.

These instructions, plus a few more, is all you need to build any model you can conceive.

Once the expression is set, press Ok to confirm. The result is shown in the following figure:

Notice we have created a gather rule since the operation involves information from other external vertices than the current vertex.

Using the same mechanics we add a mathematical expression in an Update Rule for the property state:

tmp = acc($cv)/$lnoe_in($cv) - $rnd_uniform

In this case we have needed two additional Simflowny reserved words:

• $lnoe_in: local number of incoming edges (for the current vertex)
• $rnd_uniform: a random uniform variable (between 0 and 1)

Alltogether, this expression computes the average value of the incoming neighbour vertices and then subtracts a random value between 0 and 1. Notice tmp is a temporary variable not stored in vertices nor edges, consequently not needed to be used with $cv or $ce.

The result is:

We have not yet updated the value of state. To do so, we add an If-Then-Else instruction in the algorithm:

The input of the Math child of the If element will contain the condition, specifically:

tmp>=0

We add a Math child to the Then, and finally introduce the update for the state:

state($cv)=1

We also add an Else child to the If element, and there we add a Math child:

state($cv) = 0

Alltogether:

Using the same mechanics we add an Update Rule for the acc property to reset to zero at the beginning of each step:

acc($cv) = 0

We are almost done with the model definition. We just need to specify the order in which the different gather and update rules must be executed. To do so, we use the Rule Execution Order element:

The Rule input is a drop-down menu with all the Gather Rule and Update Rule names. We choose the desired instruction as the first rule, and then we add additional children of execution order to complete the sequence:

We have now finished the definition of the Voter model, which is visualized in the right frame:

Once the model is finished it is recommended to validate it. This process will firstly save the document and secondly it will check the structure and also the content of the document.

To validate the document, click on the validate button located in the bottom of the editor:

Then the document is validated by Simflowny and a successful validation message will be shown:

Now the model is stored in Simflowny database and the editor tab can be closed to return to the document manager.

Problem creation

The second stage is to create a problem that uses the Voter model we have created in the previous section. A problem on a graph domain is created by selecting the option "Agent Based Problem on graph" from the add document button:

As in the case of the model, this creates an empty template for the construction of a problem:

We fill in the Head details, as in the model, and then we add vertex properties: state and acc, as in the model (although we could have used different names):

Now, using the root's (Agent Based Problem Graph) contextual menu, we add a Parameters children to the root:

This wasn’t there as it is not compulsory to have parameters.

We fill in the parameter with the name time_steps and type INT (integer), taken from the drop-down menu. We also specify (this is optional, and therefore we add it through the Parameter's contextual menu) a default value: 1000:

Next, we specify the model to include. Problems are always based on models. In this way, we can recycle the model definition, particularly the rules, so they can be used in many problems.

To specify the model, we provide an arbitrary name (for referencing) and the model identifier in the database. When clicking to edit the Id, a new window opens with a reduced version of the document manager:

Then, navigate in the document tree to the folder where the model was created:

Once we have found the model, select it by double-clicking on it. Then the Id is set with the proper internal reference:

Notice that we are creating a graph-based problem. Graphs can take many forms, and Simflowny supports different options. To specify the kind of graph, a graph topology must be specified. There are two possibilities, relying on an external file or setting the topology in the problem:

In this tutorial, the last option is chosen. Add a Topology Specification. As a result, the Edge Directionality and Degree Distribution must be set. These elements are specified from drop-down lists. In this case, we choose directed for directionality (a directed graph) and random for degree distribution. Therefore we are requesting a directed random graph. For Evolution Step we choose AllVertices. This means all vertices are updated every evolution step (see the Simflowny User Guide for a reference):

Problems can be optionally endowed with initial conditions. External graph specification may already have initial values. For our example using topology specification, we must define initial conditions. To do so, we need to add a child Initial Conditions to the root element. Initial conditions are mathematical expressions which provide the values for the first step of the simulation. In our case, a simple mathematical expression suffices:

state($cv) = $rnd_int_1

We have specified that the initial value for state is a random integer (0 or 1). The accumulator is not needed to be initialized, since it is set to 0 at the begining of each time step (Acc update 1 rule):

Finally, we need to establish a finalization condition, that will specify when to stop the simulation. This is done through the Finalization Conditions element. Here we keep it simple and force the problem to stop after a number of time steps (by checking whether $in, the iteration number counter, surpasses the value of the time_steps parameter we created; notice $in is a reserved word and its value is automatically increased by one after each evolution step):

Once finished, click on validation to check the problem.

You have already created your first problem. Take the time to check all data is correct in the visual representation of the problem (right panel).

Then close the browser tab to return to the document manager.

Generating code

Once you are satisfied with the problem you have authored, the last stage is to translate this abstract formulation to specific code on a certain simulation platform. Simflowny is designed as an extensible framework on which plug-ins for different simulation platforms can be easily added. The current version provides support for the SAMRAI mesh management toolkit [4] for spatial-domain problems and the Boost Graph Library [5] for graph problems. These libraries provide parallelization capabilities, which allows the generated code to run in parallel over many processors.

To start the code generation process, click on the Voter problem we have just created. Then, the top toolbar changes:

The toolbar adapts to the document or documents currently selected, as there are operations that only can be applied to specific kind of documents. In this case, the code generation for Boost Graph Library. Click on the last button, Generate Boost Code button.

Then, Simflowny starts the code generation process:

Finally, the code is created, and can be downloaded clicking the proper button after selecting it:

The code is downloaded as a zip file containing all the files.

Running a simulation

Extract the downloaded file to a folder. This folder will be the location for the compilation and simulation. The source code files, a sample parameter file and a Makefile [6] to assist the compilation are uncompressed.

Open a terminal an cd to the code folder.

We want to simulate a random Voter Model for 10 timesteps, 500 vertices and 1000 edges. The vertex property that interests us is the state of the vertices.

Once we have established our requirements for the simulations the next step is to edit the input parameters file. Then with any text editor edit problem.input file.

First, we set the values:

• number_of_vertices = 500;
• vertex_properties=[“state”];
• time_steps = 10;

Save the file.

Next, compile the code using the Makefile system typing:

make

Once the compilation has completed, we are ready to perform a simulation. In the same terminal, run:

./Voterproblem problem.input

The command above executes the binary file recently created by the compilation and uses the parameter file previously set.

To review the results, use a DOT [7] compatible visualization software.

ABM on spatial domain Tutorial

For ABM on spatial domain, please check the ABM on spatial domain Tutorial.

Next step

For a more detailed approach to Simflowny, please check the User Guide.

Footnotes

[1]	Understood in a broad sense, which covers models on graphs or spatial domains where the elements are agents, particles, vertices or cells.

[2]	http://www.w3.org/Math/.

[3]	The document management is explained extensively in the Simflowny user guide, the aim of this tutorial is ABM generation. For document managment details, visit the user guide.

[4]	https://en.wikipedia.org/wiki/Graph_(discrete_mathematics).

[5]	http://asciimath.org/.

[6]	https://computation.llnl.gov/project/SAMRAI/

[7]	http://www.boost.org/doc/libs/1_58_0/libs/graph/doc/index.html

[8]	https://en.wikipedia.org/wiki/Makefile

[9]	https://en.wikipedia.org/wiki/DOT_(graph_description_language)