Simflowny 2: An upgraded platform for scientific modeling and simulation

Simflowny 2: An upgraded platform for scientific modeling and simulation

A. Arbona Corresponding Author: IAC, Universitat de les Illes Balears, Cra. de Valldemossa km 7.5, 07122, Palma, Spain B. Miñano IAC, Universitat de les Illes Balears, Cra. de Valldemossa km 7.5, 07122, Palma, Spain A. Rigo IAC, Universitat de les Illes Balears, Cra. de Valldemossa km 7.5, 07122, Palma, Spain C. Bona IAC, Universitat de les Illes Balears, Cra. de Valldemossa km 7.5, 07122, Palma, Spain C. Palenzuela A. Artigues IAC, Universitat de les Illes Balears, Cra. de Valldemossa km 7.5, 07122, Palma, Spain C. Bona-Casas IAC, Universitat de les Illes Balears, Cra. de Valldemossa km 7.5, 07122, Palma, Spain J. Massó

Simflowny is an open platform which automatically generates parallel code of scientific dynamical models for different simulation frameworks. Here we present major upgrades on this software to support an extended set of families of models, in particular: i) a new generic family for partial differential equations, which can include spatial derivatives of any order, ii) a new family for agent based models to study complex phenomena –either on a spatial domain or on a graph–. Additionally we introduce a flexible graphical user interface (GUI) to accommodate these and future families of equations. This paper describes the new GUI architecture and summarizes the formal representation and implementation of these new families, providing several validation results.


Program Title: Simflowny
Licensing provisions: Apache License, 2.0
Programming language: Java, C++ and JavaScript
Journal Reference of previous version: Comput. Phys. Comm. 184 (2013) 2321–2331
Does the new version supersede the previous version?: Yes
Reasons for the new version: Additional features
Summary of revisions:
Expanded support for Partial Differential Equations.
Support for Agent Based Models.
New Graphical User Interface.
Simflowny runs in any computer with Docker [1], installation details can be checked in the documentation of Simflowny [2]. It can also be compiled from scratch in any Linux system, provided the requirements are properly installed following documentation indications.
The generated code runs on any Linux platform ranging from personal workstations to clusters and parallel supercomputers.
Nature of problem:
Simflowny generates code for numerical simulation for a wide range of models
Solution method:
Any discretization scheme based on either Finite Volume Methods, Finite Difference Methods, or meshless methods for Partial Differential Equations.
Agent Based Model simulations execute their own algorithm as set in their models.
Additional comments:
The software architecture is easily extensible for future additional model families and simulation frameworks.
Full documentation is available in the wiki home of the Simflowny project [2].


Appendix A Introduction

We present a significantly upgraded version 2 of Simflowny [3], an open platform for scientific dynamical models, composed by a Domain Specific Language (DSL) and a web based Integrated Development Environment (IDE), which automatically generates efficient parallel code for simulation frameworks.

Originally, Simflowny was built to address the fact that efforts towards a formalization of mathematical equations in simulation, at a more abstract level than the mere program source code, are still rare. Usually, the process that goes from an idea reflected in a set of equations to the final code is pure art, in the sense that it lacks formalization and general tools to ease it.

In version 2 we have extended this formalization of mathematical equations to a more general family of scientific model paradigms (for example, Agent Base Models). Simflowny is aimed to create a community contributed platform where some elements of the simulation flow for Initial Value Problems are formalized. This formalization allows the reuse and exchange of such elements, even outside the platform itself.

Simflowny has a simple yet ambitious goal: a complete split of the physics (by introducing the concept of models and their associated problems) from the numerical methods necessary for a simulation (the discretization schemes), and the automatic generation of the final simulation code (where the parallel features of the chosen framework will be optimally leveraged, as well as other provided capabilities).

The DSL is based on an XML Schema Definition (XSD) representation. The XSD schemas prescribe the structure of the XML documents for models, problems, and discretization schemes. Where algorithms are to be included in either of these XML documents, this is done through a specific markup language developed for Simflowny, called SimML (Simulation Markup Language). SimML constitutes a full-blown rule specification language (technically speaking, the language is Turing-complete, meaning you can create any possible algorithm with it). To insert mathematical expressions in the algorithms and documents, Simflowny prescribes MathML, the standard markup language for representing mathematical expressions.

In version 2 the DSL has been expanded and currently supports the following scientific model paradigms, or families:

  • Partial Differential Equations (PDE) written in balance-law form. This family was the only one supported in version 1 of Simflowny. The PDEs are written as an evolution system containing only first order derivatives both in time and space, which allow users to use numerical schemes based on Finite Volume Methods to deal with shocks and discontinuities. Some examples of balance law systems include the wave equation, Maxwell equations, Einstein equations,… This family also allows parabolic terms like the ones appearing, for instance, in the Navier-Stokes equations.

  • Generic PDE, a new family of models that allows almost arbitrary forms of PDE evolution equations, including spatial derivatives of any order. The only restriction is that the system must be still first order in time. One could write in this form all the examples in balance-law form but directly as second order system (in space). Additionally, it also includes many other equations like the heat equation, the Navier-Stokes-Korteweg equation (third order in space), the Cahn-Hilliard equation (fourth order in space) and the Phase-Field-Crystal equation (sixth order in space).

  • Agent-Based Models (ABM), another new family of models which simulate the evolution of a system of multiple interacting agents. These models are often built in order to study the emergence of complex phenomena. Agents might live either on a spatial domain (Spatial ABM) or on a graph (ABM on a Graph). Additionally, Spatial ABM contain two subfamilies: Cellular Automata, i.e. agents statically bound to a cell in a mesh, and kinematic ABM, where agents roam freely in a meshless domain. Some well-known examples are the Ising and Collective Motion (flocking) models for the Spatial ABM, and the Voter model and Cash and Goods [4] for ABM on a Graph.

From the computer science point of view, Simflowny is built on the well-known three-tier architecture:

  • A presentation tier, implemented as a web browser based graphical user interface (GUI).

  • A logic tier, based on an application server.

  • A data tier, combining native XML databases with bulk data storage.

In Simflowny 2, the original Graphical User Interface (GUI) of version 1, written ad hoc for the original PDE family, has been completely redone to make it flexible enough to automatically accommodate new families of equations, both of PDE nature or otherwise (such as ABM).

The current procedure to generate code is similar to the previous version, although new features have been introduced to allow for more flexibility with the new families. Although the details vary among the families, the process to convert a mathematical model into a numerical code can be split in four stages (see fig. 1):

Figure 1: Workflow diagram, containing the following stages: 1) the mathematical model containing either the evolution equations for PDEs, or a description of the interactions among the multiple agents in ABM. 2) the problem, which mainly includes the model, the domain of the simulation and the initial and boundary conditions. 3) the discrete scheme, which converts the continuous problem into a discrete one. Notice that ABM models are already discrete. 4) the code generation, converting the discrete problem to code for the final framework.
  • The representation of the mathematical model, which contains either the evolution equations to be evolved in the case of PDEs, or a description of the interactions among the multiple agents in ABM.

  • The representation of the problem, which includes the mathematical model, the domain of the simulation, the analysis quantities and the initial and boundary conditions to be applied, either to the evolution fields (in PDEs) or to agent properties (in ABM).

  • The representation of the discrete scheme, which converts the continuous problem into a discrete one by defining the space and time discretization operators (for PDEs). This stage does not apply to the ABM families since the original models are already discrete.

  • The generation of the code from the discrete problem to the final framework. These frameworks will essentially play the role of a mesh/memory manager by setting the domain, distributing the usage of memory of the fields and parallelizing the workload among the different processors.

While Simflowny 1 supported the Balance Law PDE family through the Cactus toolkit [5, 6], Simflowny 2 provides support for SAMRAI mesh management toolkit [7] for spatial-domain problems and the Boost Graph Library [8] for graph problems.

Through SAMRAI, Simflowny 2 supports mesh-based discretization schemes for PDEs, specifically Finite Difference Methods (FDM) and Finite Volume Methods (FVM). It also supports particle-based mesh-free Lagrangian methods (e.g.: Smooth Particle Hydrodynamics, SPH), as well as spatial agent models and Cellular Automata. Notice that SAMRAI only allows models with spatial dimensions .

Simflowny 2 reflects the parallelization capabilities of both SAMRAI and Boost, and therefore any model developed on Simflowny can generate optimized parallel code for these frameworks. For efficiency reasons, code responsible for communication is only generated in the parts of the model which are not local: in PDEs this amounts to communicate only the fluxes and spatial derivatives while keeping source terms local; in ABM such split is reflected through the gather / update paradigm: gathers are operations involving neighbours, and are communicated, while updates do not involve neighbours and are consequently performed locally to each processor.

Futhermore, the powerful capabilities of Adaptive Mesh Refinement are available in Simflowny by leveraging its excellent implementation in SAMRAI.

Notice that Simflowny’s four stage structure allows us to achieve our stated main goal: a complete split of the physics (the model and the problem) from the numerical methods (the discretization schemes) and from the parallelization/distribution issues, which are hidden in the framework (mesh manager or graph manager). Therefore, we can use the same representation of the discrete problem (which involves the three first stages) in different simulation frameworks, which might allow for higher scalability and efficiency.

Regarding user roles, in Simflowny 2 we consider final users, who are interested in using the platform to build and numerically solve a simulation problem (the user C pictured in fig. 1), and developer users, who are interested in creating new physical models (user A) and discretization schemes (user B). The latter should not be confused with the developers of Simflowny, who are interested in adding new functionality to the platform itself.

Simflowny 2 includes example databases for typical physical models and discretization schemes. However, in complex simulation scenarios the development or tailoring of both physical models and discretization schemes by the corresponding experts (A, B) becomes necessary. These elements are the starting point for the simulation workflow driven by the final user (C).

Simflowny 2 is open source, and it is available in the form of compilable source code and also as a Docker [9] container. See Simflowny’s wiki for further details 111

The paper is organized as follows. The new GUI architecture is described in Section II. Section III is devoted to the generic PDEs, while Section IV focuses on ABM on spatial domain and on graphs. We finish with some final remarks.

Appendix B New GUI architecture

In Simflowny, problems, models, and discretization schemes are represented as XML files. In the former GUI, the edition of these files was done with many ad hoc non-reusable GUI components, specifically developed for such documents.

As the families of models supported by Simflowny grew, this approach became unsustainable due to the following issues:

  • It did not take advantage of already existing structure embedded in the XML documents, rather creating a new data structure specifically for the GUI.

  • It suffered of a lack of coherence, since there was no guarantee –when the GUI components were developed manually– that similar components were designed in a similar way. In fact, it was possible, specially when the work was done by several developers, that the GUI components differed substantially even if they corresponded to similar information.

  • It was becoming rather inefficient, with significant development costs due to such heterogeneous designs.

These drawbacks led us to completely redesign the GUI to convert it into a specialized XML editor. Each XML document, accompanied by its schema (XSD) provides all the necessary information to automatically generate a GUI for editing such document on the fly.

Simflowny’s web GUI is composed by two elements: a document manager, which is also the GUI’s main page, and a document editor.

b.1 Document manager

The document manager consists of three areas (see figure 2) : i) a toolbar, located at the top, and containing contextual actions for the selected document; ii) a document tree on the left area; and iii) a document list from the selected tree folder on the right area.

Figure 2: Document manager screen. Notice the tree area on the left. The area on the right shows the available documents in the selected folder.

The specific buttons appearing in the toolbar depend on the document actively selected in the document manager. For instance, with no document selected, the only actions are Create new and Import, as shown in figure 2.

When selecting a document, other buttons appear in the toolbar. For instance in the case of a document describing an ABM simulation problem, the buttons are those shown in figure 3. The five actions on the left are common to any kind of document; from left to right: Create new, Import, Edit, Download, Delete. The remaining three ones are contextual actions, in this case specific for the ABM simulation problem; from left to right: XML to LaTeX, XML to PDF, and Generate Boost Code.

Figure 3: Action bar on the document manager when a problem is selected. The five actions on the left Create new, Import, Edit, Download, Delete are common to all documents. The remaining three ones XML to LaTeX, XML to PDF, Generate Boost Code are contextual actions, in this case specific to the ABM simulation problem.

The Create new button is used to create new documents, whose type is selected on the fly in the button submenu. When clicked, a document editor tab opens with a template document of the selected type. Document edition is explained in detail in the following subsection. The document will be stored in the folder selected in the document tree. The Import button allows uploading documents to the current database. Every document previously exported from Simflowny can be imported. The Edit button opens the document editor with the selected document loaded. All the documents in Simflowny can be exported. When using the Export button the selected documents will be downloaded in a zip, which will contain the selected document and any documents it references. Clicking on the Delete button will delete the selected documents.

The XML to LaTeX and XML to PDF actions generate and download, respectively, LaTeXand PDF versions of the selected document. The last action generates parallel Boost code for an ABM on a graph (see section D.1.3).

The document tree on the left area is a customizable hierarchical structure. Each element in the tree can be seen as folder where to place the documents. It is possible to reorganize the tree. Right-clicking on any folder opens a contextual menu to Add a new folder, or Rename or Delete an existing folder. It is also possible to move a folder (including subfolders and documents) or documents into another by drag and drop.

The third area in the document manager, at the right of the tree is a document list from the selected tree folder. A double-click on any document will open it in the document editor. The documents can be ordered and filtered using the header columns.

b.2 Document editor

The Document Editor is a specialised XML editor. Underneath, all documents in Simflowny are XML files, which have a tree structure. The Document Editor presents such tree structure in the left panel, which is editable, while a presentation panel is available on the right, offering a more readable view of the document being edited. See figures in sections C and D.

The functionalities available for editing documents include:

  • Those addressed to manage the XML elements, among them:

    • Decorated versions of the XML tags, to improve readability. For instance, the XML tag addPartialDerivatives is shown as Add Partial Derivatives.

    • Expanding and collapsing nodes.

    • Preemptive creation of compulsory elements.

    • Adding and removing children elements to a parent node. When adding children only those allowed by the XSD are shown in contextual menus.

    • Reordering (moving upwards or downwards) certain elements in a list.

    • Copy/paste capabilities for SimML elements.

  • Those addressed to manage the content of each XML element, among them:

    • Typing the text content. To enable the edition of an element value, the empty input area next to its label must be clicked.

    • Support for unicode characters, for instance Greek letters. A graphical tool is provided to facilitate the introduction of such characters. The user may copy a symbol from the pop-up and use it in the editor.

    • Dropdown lists when the elements can only be chosen from a closed list, either defined in the XSD or corresponding to previously defined content in the same XML document.

    • A specialised editor for SimML instructions.

    • A specialised math editor for MathML expressions using the AsciiMath standard (see figure 4 for an example) 222

    • Document cross-reference (hyperlink) graphical tool, used for instance to reference a specific model from a problem.

    • Highlighting missing content to avoid errors.

Figure 4: MathML editor. An example of an algebraic expression introduced using the MathML editor. This editor hints the user when writing mathematical expressions, which are entered in the AsciiMath standard in Simflowny. Some SimML instructions can be used in the expressions. The buttons below the editor show all the possible SimML tags available and provide a contextual help for them.

The document is auto-saved when changes are detected and when the browser tab is closed. At the bottom of the document there is a button to validate the structure and, as far as possible, the content of the document. In the same toolbar area there are two buttons to Expand or Collapse all the nodes in the tree.

Appendix C Models based on PDEs

In this section it is discussed in detail one of the new families incorporated into Simflowny 2, namely a generic PDE with finite difference discretization. In order to stress the differences with respect to the previous version, we first briefly summarize the previous model for PDEs in Balance Law form. Next we describe the generic PDE family and present an example with the wave equation.

Notice that both families are restricted to systems with first order derivatives in time, a requirement that can always be satisfied by introducing new evolution fields. This condition allow us to use the Method of Lines (MoL) to ensure stability of the system when converting continuum equations into discrete ones.

c.1 Pre-existent functionality: PDEs in Balance Law form

The pre-existent family consists of balance law PDE, namely


where is an array with all the evolved fields, are the fluxes, the sources, and and are the algebraic expressions conforming the parabolic terms. Since fluxes and sources depend only algebraically on the fields, the evolution system is restricted to be first order both in time and space, except for the parabolic terms. The advantage of this model is that both Finite Difference and Finite Volume methods can be applied on this form of the equations.

c.2 New functionality: Generic PDEs

As it was explained previously, before the generation of the numerical code we must define the model, the problem and the discretization schemes. This family can explicitly solve any PDE written as


where is an array with all the evolved fields and is any operator depending on the fields and its spatial derivatives (of any order). Therefore, the only restriction here is that the system can only involve first time derivatives of the fields.

Arbitrary operators can be constructed by using recursive rules, which can be written formally as


where are arbitrary functions depending on but not on its derivatives, and is a generic matrix which in practice will have only one non-trivial component. Notice that this new family can also be expressed in a logical abstract language as


where, similarly to the former definition, are arbitrary algebraic functions on , and is recursive term allowing for a complex set of expressions using differential calculation. Both the algebraic and the recursive terms are optional at every level of the recursion.

Once the model is well defined, we need to set up the problem, namely, the domain of the simulation, the initial and the boundary conditions for the evolved fields, the finalization condition, and the analysis quantities to be computed.

Before the code generation we must define the discretization rules. As we mentioned before, we will take advantage of the theoretical background developed for PDEs by using the Method of Lines. We have implemented, as a basic set available in the database provided with Simflowny, some discretization operators which ensure stability of the discrete problem (i.e., a third-order Runge-Kutta for the time integration and fourth order centered space discretization), although any other scheme can be defined. By default, it is assumed a recursive rule such that the -order discrete derivative of a field is obtained by applying the discretization operator to the derivative of that field. This procedure provides a straightforward way to compute space derivatives of any order. Notice however that all these schemes –for the time and space discretization– can be modified freely by setting a different discretization policy.

c.3 Generic PDE example : the wave equation

The use of Simflowny for Generic PDEs is illustrated using the widely known wave equation. The wave equation for a scalar field in 2D can be written as a system of equations with only first order time derivative, namely


The recursive rules are straightforward here, with


To construct the problem we need to set the domain, the initial data and the boundary conditions. For this simple example we will set a square domain with an initial parametrized Gaussian profile for the scalar field and periodic boundary conditions.

We will use third order Runge-Kutta for the time integration together with fourth order accurate centered difference operators satisfying the Summation By Parts rule), which ensures stability and convergence of the discrete problem. The second order space derivatives are calculated by using a 5 point stencil.

c.4 Model creation

In the document manager, the user should select a folder, or create a new one, to store the model. Next, the user clicks the plus button, expanding a new menu where the option Generic PDE Model should be selected. The document editor will open the basic skeleton to define a generic PDE model, as shown in figure 5. We will now describe the different parts of this skeleton.

Figure 5: Editor showing the basic skeleton for a generic PDE model

The head element contains the general description of the model, which might be filled by the user. By expanding this head, its children are shown (i.e., name, id, author, version, and date).

The first step is to set the spatial dimensions and the names of all the coordinates (i.e., space and time) in Spatial Coordinates. By default there is only one Spatial Coordinate element. New spatial coordinates can be added by the user from the Spatial Coordinates element through its contextual menu. In our particular example, there are two spatial coordinates and a time coordinate .

The second step consists in defining the fields, that is, the variables which are going to be evolved in Simflowny. One field is the minimum required to define a model. For the wave equation, the user must define two fields .

The core of a PDE model relies on the last mandatory section, where the evolution equation (i.e., the operators) associated to every field must be set with a descriptive name. The generic PDEs have a structure, described by eqs. 3-5, in which the last (n)-recursive step consists on a summation of terms –defined as Term elements–, each one with many combinations of derivatives. The terms which are going to be discretized in the same way are grouped by elements called Operator. It is possible to use different discretization schemes for each Operator. As it is shown in figure 6, the user can introduce both algebraic expressions (Math) or derivative ones (Partial Derivatives) in the contextual menu of Term.

In the example with the wave equation, the simplest choice is to use only one operator for both equations, that it will be referred as default from now on. For the equation  8 (i.e., the time derivative of the scalar field ), the default operator has only one algebraic expression, , to be added as a Math element. The mathematical expressions are introduced through the editor explained in section B. The time evolution of , given by eq. 9, contains two terms . These terms, which must be introduced as Partial Derivatives elements, are calculated by using the recursive rules given in eq. 10-12 from the top to the bottom level. For the first term , the user defines first the most external derivative and sets the coordinate in Partial Derivative. At the second iteration the next level is defined following a similar procedure. Finally, at the bottom level the user adds a Math element to define the algebraic function . This procedure is displayed in Figure 7. The process to add the second term is similar to the one explained above. Figure 8 shows the model, completed at this point.

Figure 6: Construction of the wave equation model. In the left panel the contextual menu to add mathematical term for the scalar field equation term is shown.
Figure 7: Construction of the wave equation model. Second derivative term introduced.
Figure 8: Detail of the right frame of the editor showing the completed wave equation model.

Once the model is finished one can validate it as seen in section B.

c.5 Problem creation

The next stage is to create a problem containing the model, the domain and the initial and boundary conditions. The problem can be created from the document manager by adding a new document Generic PDE Problem. After setting the header information, the coordinates and fields must be added.

Two parameters are added for the Gaussian profile of the initial data by using the contextual menu.

The user may now select the model. This selection is performed through a small document manager pop-up, as seen in Figure 9.

Figure 9: Construction of the wave equation problem. Selection of the wave equation model.

In general, a given problem might include an arbitrary number of models. This is useful, for instance, if these models are going to be applied to different regions of the simulation domain, since Simflowny provides a multi-region capability. By default, the user must define a region covering the full simulation domain. Optionally, one can also define subregions, each one employing different models.

In our example, the wave problem has a single region. The user must select the wave model as an Interior Model in this region. The spatial domain is set to by assigning a Coordinate Min of and Coordinate Max of for coordinate . The same process is repeated for coordinate .

The last compulsory element to set in a region is the Initial Condition, which might contain mathematical formulas (Math Expressions) and logical conditions (Apply If). In this test case, the initial conditions are:

see figure 10.

Figure 10: Construction of the wave equation problem. Initial conditions created.

The next step consists in adding the domain Boundary Conditions. In this element the user sets first the Boundary Policy, which is a mapping of the regions, in this case the region main, to a specific Boundary Condition. Periodic boundary conditions are applied to all the edges and fields by setting the Boundary Condition Type as Periodical and the the side and axis properties to all for all fields, meaning that periodic boundary conditions are applied to all coordinates (i.e., and ) and to both sides (i.e., lower and upper).

The last setting regarding the boundaries is the Boundary Precedence, which indicates in what order overlapping boundary conditions are applied. All the boundary conditions must be added to the Boundary Precedence list. In this case it does not matter the order as it does not alter the result.

The last piece of information needed in a problem is the Finalization Conditions element. These conditions have to be logical expressions depending on evolution fields, parameters or variables (i.e., including the coordinates). In this test case, the simulation stops when the evolution time reaches a certain value provided by the user. Therefore, a new parameter t_end is to be added. Then, the finalization condition Math is . See figure 11, where the complete problem is shown.

Figure 11: Detail of the right frame of the editor showing the completed wave problem.

c.6 Problem discretization

The following stage, after the problem definition, is the discretization. Although the users can create their own, Simflowny provides a set of discretization schemas.

Discretization schemas can be applied to multiple problems and vice versa. Additionally, a schema might be parametrized, so it is possible to use the same schema with different parameter choices to generate different discretized problems. As a consequence, it is necessary a mapping between discretization schemas and a given problem. This mapping is known as Discretization Policy in Simflowny and it is common to all the PDE families. Although this policy can be created from scratch, it is easier to generate it from an existing Generic PDE Problem: by selecting the problem in the document manager the toolbar shows a button to generate the Generic PDE Discretization Policy.

The new document automatically incorporates the problem information. Therefore, the only required actions are selecting the space and time discretization schema (i.e., Operator Discretization and Time Integration Schema respectively) for every region in the problem. In the wave model example, the spatial Operator Policy applied in the only region is the 4th Order Operators schema. The time integration chosen is RK3 with dissipation, also available in the database. At this point, the policy is completed, as seen in Fig. 12.

Figure 12: Discretization policy completed.

Once the discretization policy is defined the user must explicitly discretize the problem. This step is performed in the document manager, after selecting the newly created policy, with the toolbar operation Discretize Problem.

c.6.1 Generating code

By using the toolbar, the Discretized Problem abstract formulation can be translated into an specific code to be run on a certain simulation platform. Then, Simflowny starts the code generation process, which finishes with the creation of the Generated Code. The code can be downloaded in a zip file format, see figure 3 and section B.

c.6.2 Running a simulation

The code compressed in the zip file can be compiled and executed in any machine with an installed version of SAMRAI. The unzipped folder will be the location for the compilation and simulation and contains the source code files, a sample parameter file and a Makefile.

The wave problem example consists on running a simulation up to using a mesh of cells. This can be achieved by modifying the following values in the problem.input file:

  tend = 1
  dt = 0.005

The user can compile and launch the simulation by running in a terminal the following commands:

  ./Waveproblem problem.input

The results are saved by default in the outputDir directory and can be visualized with Visit [10]. The figure 13 shows a snapshot of the results for the scalar field at .

Figure 13: Scalar field results from wave problem simulation.

Appendix D New functionality: Agent Based Models

This section is comprised of two subsections. First we introduce Agent Based Models on a graph, and then ABM on a spatial domain.

The difference between ABM on a spatial domain and ABM on a graph is only the topology of the domain: in the former case agents have spatial positions and neighbours of an agent are determined by a distance, while in the latter agents are the vertices of a graph, and neighbours are determined by the graph topology. Within the ABM on a spatial domain we distinguish two subcategories, related to agent motion: fixed agents (i.e. Cellular Automata) or moving agents.

The ABM models allowed in Simflowny are of the form:


where is a discrete arbitrary algorithm using the properties of an agent, the properties of its neighbours, parameters, and coordinates or, in the case of ABM on a graph, characteristics of the graph local topology. Such algorithm is structured around two types of rules:

  • Collection of neighbour information (gather).

  • Local information processing and updating the local state (update).

d.1 Agent Based Models on a graph

In this section we validate the new capabilities in Simflowny 2 by building an ABM on a graph model and running a simulation with it. We will implement the voter model, a simple model in which essentially the binary value of an agent is changed according to the consensus of its neighbours together with a random noise.

d.1.1 Model creation

In the document manager, the user should select any folder, or create a new one in order to store the model there. Next, the user clicks the plus button. This expands a new menu, where the option Agent Based Model on graph should be selected. Then the document editor will open the basic skeleton for a model on a graph, as shown in figure 14.

Figure 14: Editor showing the basic skeleton for a model

Now, the user fills in the general description of the model, contained in the head tag. By expanding the head, its children tags are shown, namely name, id, author, version, and date.

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.

To build the voter model, the user defines two Vertex Properties called state and acc. state stands for the voter model state, which can take two values. acc is just an auxiliary variable to accumulate neighbour values.

With this, the user is ready to proceed with the definition of , which, as stated before, is composed of the rules that tell the model how to change its Vertex Properties from step n to step n+1. In Simflowny this is specified under the element rules, whose contextual menu 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 vertex, may involve information about its neighbours. On the other hand, Update Rules are local update operations, using only information from the same vertex. While the user can write any algorithm by using only gather rules, parallel performance and optimization are improved by carefully distilling local operation rules from operations which may involve neighbours. This is because no communication between different processors is needed for update rules, and, as an added bonus, the model description becomes much clearer when update rules are used wherever possible.

When creating a Gather Rules element, one child comes automatically with it: a Gather Rule operation. A model may contain as many as needed, one being the minimum.

A Gather Rule operation is defined by name, Vertex Property, and algorithm, which contains the actual update rule. In the voter model, this first Gather Rule, called here Acc gather 1, corresponds to the Vertex Property acc.

The algorithm is defined using SimML and MathML. The algorithm contextual menu allows the user to select the needed SimML element. See figure 15.

Figure 15: Construction of the voter model. In the left panel the contextual menu to add SimML elements is shown.

To continue with the building of the voter model, the user adds an Iterate Over Edges element under the algorithm element. This is a loop over all the edges of a certain vertex.

Iterate Over Edges has a child called Direction Att to indicate the edge direction, in in our case. After this, the user adds a math child to Iterate Over Edges with the following content:

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

where $cv stands for current vertex, $ce stands for current edge, and $es($ce) stands for the neighbour vertex at the other end of the edge (edge source).

All together, the expression updates the acc Vertex Property of each vertex by adding the value of the state Vertex Property of the vertices participating in the edge with the current vertex (i.e., its neighbours). This is, acc accumulates the values of state for all the (incoming) pairs of a certain vertex.

In a similar fashion, the user adds a mathematical expression in an update rule (State update 1) for the Vertex Property state:

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

In this case we have needed two additional functions: $lnoe_in for the local number of incoming edges (for the current vertex) and $rnd_uniform to generate a random uniform variable (between 0 and 1). Therefore, 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.

At this point, the value of state is not yet updated. To do so, the user should add an if-then-else instruction as a child of Algorithm, the If condition being , the Then statement , and the Else statement . Notice that mathematical conditions and statements are introduced as a math element. See figure 16.

Figure 16: Detail of the If-Then-Else structure while building an update rule.

In a similar fashion, the user initializes the acc Vertex Property by adding an Update Rule called Acc update 1 and containing the statement .

Finally, the user just needs to specify the order in which the different Gather Rule and Update Rule instructions must be executed by using the Rule Execution Order element. A Rule element, child of Rule Execution Order, is added referencing either a Gather Rule or an Update Rule. The user chooses the desired element as the first rule, and then follows on with additional rules to complete the sequence, in this case: Acc update 1, Acc gather 1, and State update 1

Now the definition of the voter model is complete, it can be validated, and it is displayed in the right frame of the editor, as shown in figure 17.

Figure 17: Detail of the right frame of the editor showing the completed voter model.

d.1.2 Problem creation

The next stage is the creation of the problem based on the voter model defined in the previous subsection.

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.

The user fills in the Head details and then the vertex properties: state and acc, as in the model (although different names may be used).

As seen in figure 18, the Parameters and Parameter elements are used to define the time_steps integer parameter.

The following step is referencing a model, using the cross reference graphical tool as explained in section B. In this example, the user selects the voter model as shown in figure 18.

Figure 18: Building the voter problem: head, fields, parameters and model reference.

Now, using the contextual menus provided by the GUI, the user adds a time_steps parameter of integer type INT and default value 1000. See figure 18.

Simflowny supports either loading a graph from a file or defining it through properties. Such properties allow the user to define the graph as either directed or undirected (Edge Directionality) and either random, scale-free or circular (Degree Distribution). Our problem is based on a directed random graph. See figure 19.

The user can choose to evolve one vertex per time step, or all of them as in this example (Evolution Step). See figure 19.

Figure 19: Detail of the right frame of the editor showing the completed voter problem.

Problems can be optionally endowed with initial conditions, which provide the values for the first step of the simulation. In this case, a simple mathematical expression suffices:


which sets the initial value for state as a random integer (0 or 1). There is not need to initialize the accumulator, since in the model it is set to 0 at the beginning of each time step.

Finally, the user needs to establish a finalization condition, that will specify when to stop the simulation, in this case after a fixed number of time steps. Notice $in, the iteration number counter, is a reserved word and its value is automatically increased by one after each evolution step. See figure 19.

Once finished, the user may click on the button Validate to assess the problem integrity.

d.1.3 Generating code

The button to launch the code generation is located on the action bar on the document manager. The user should select the voter problem in the document manager, and click on this button. Then, Simflowny starts the code generation process. After a few seconds, the code generation finishes and a new document of type Generated Code appears in the document manager. By selecting such document and clicking on the Download button the code is obtained in a zip file, see figure 3 and section B.

d.1.4 Running a simulation

The user may download the file to any computer where Simflowny 2 has been properly installed and configured, and unzip it into a folder. This folder will be the location for the compilation and simulation and contains the source code files, a sample parameter file and a makefile.

The use case consists in simulating a random voter model for 10 timesteps, 500 vertices and 1000 edges. To do so one should set the following values in the problem.input file.

  number_of_vertices = 500;
  time_steps = 10;

The code compiles using make. Next, the simulation may be launch by running:

./Voterproblem problem.input

The results are saved by default in outputDir directory which can be visualized with any DOT [11] viewer. The figure 20 shows a snapshot of the results.

Figure 20: Voter model results.

d.2 Agent Based Models on a spatial domain

In the previous subsection, we have detailed how to create an ABM on a graph, how to create an associated problem, how to generate its code and how to run it. Simflowny 2 also includes the new family of ABM on a spatial domain, which we validate in this section. As many features are common with the ABM on a graph family, we will directly present an example without detailing the process of building the model and the problem

In this example, a two-dimensional flocking model is implemented into Simflowny. We use the vectorial noise model of Gregoire and Chaté [12]. The model is a variation of the Original Vicsek Model [13] (OVM), devised to reproduce the collective motion - or flocking - we find in many biological and non-biological systems (see, for instance, references [14],[15], and [16]and [17] for reviews). In these systems long-range orientation order emerges after spontaneous symmetry breaking.

In the OVM, point-like agents move synchronously in discrete time steps, with a fixed common speed . In 2D the orientation of agent is an angle . The evolution rule provides the new angles at each time step, based on the angles of the agent’s neighbours (agents within a certain influence radius) in the previous time step. Essentially, the agent tries to align itself with its neighbours. This alignment is perturbed by a white noise.

The Gregoire and Chaté model is based on the OVM, but modifies the manner in which noise is incorporated into the model. They define vectorial noise as generated by errors when estimating interactions, in comparison with the angular noise in the OVM, related to errors in trying to follow the newly computed direction. Altogether, the update rule for the Gregoire and Chaté model is:


where is a delta-correlated white noise, represents noise-strength, and is the number of neighbours. The sum is made over all the neighbours () of agent .

The solution of this system ranges from nearly complete orientation order for low noise intensity to random orientation for high noise intensity. These phases are separated by a novel phase transition. The solutions near the transition point are characterized, for a wide spectrum of parameters, by ordered moving structures (bands) separated by disordered interband regions.

d.2.1 Generating code

Assuming we already have the model and problem introduced in Simflowny, rather similarly as in the voter model case, the code generation can be launched using the button from the action bar appearing when the problem is selected. The user should select the Collective Motion problem in the document manager, and click on this button. Then, Simflowny starts the code generation process. After a few seconds, a new document representing the generated code appears in the document manager. It can be downloaded by selecting such document and clicking on the Download button.

d.2.2 Running a simulation

After downloading the code, the user may unzip it and run a simulation. The unzipped folder will be the location for the compilation and simulation and contains the source code files, a sample parameter file and a makefile.

The use case consists in simulating a Collective Motion for 10 timesteps in a domain. To do so one should modify the following values in the problem.input file.

  time_steps = 10
  dt = 1
  x_up = 100.0, 100.0

The code compiles using make. Next, the simulation may be launch by running:

./Collectivemotionproblem problem.input

The results are saved by default in outputDir directory and can be visualized with Visit [10]. The figure 21 shows a snapshot of the results.

Figure 21: Collective motion results.

See [18] and [19] for the use of Simflowny’s flocking model in more complex scenarios.

Appendix E Conclusions and future work

We have presented version 2 of Simflowny, a platform for scientific modelling and simulation on parallel frameworks. Alongside the description of a new GUI architecture to allow for a more agile inclusion of new paradigms of scientific models, we have presented two newly available families: generic PDE (PDE written in free-style form, in contrast with the Balance Law form), and ABM, either on a spatial domain or on a graph. We have illustrated the new families with simple models, but there are a number of more advanced models available, either to use directly or as a starting point to more tailored models. These include Navier-Stokes Equations (Hydrodynamics), Maxwell Equations (Electromagnetism), Einstein Equations (General Relativity), Brusselator, or Ising models. All of them are included in the basic model library of Simflowny.

In the future, we will continue expanding the database of available models and include new families. We are also working towards supporting unstructured meshes and allowing for discretization schemes on such meshes (such as Finite Element Methods).

Appendix F Acknowledgements

The research leading to these results has received funding from the European Union Seventh Framework Programme (FP7/2007-2013) under grant agreement no 317534 (the Sophocles project).


  • [3] A. Arbona, A. Artigues, C. Bona-Casas, J. Massó, B. Miñano, A. Rigo, M. Trias, and C. Bona. Simflowny: A general-purpose platform for the management of physical models and simulation problems. Computer Physics Communications, 184(10):2321 – 2331, 2013.
  • [4] Ranaivo Mahaleo Razakanirina and Bastien Chopard. Using Cellular Automata on a Graph to Model the Exchanges of Cash and Goods, pages 163–172. Springer Berlin Heidelberg, Berlin, Heidelberg, 2010.
  • [5] T. Goodale, G. Allen, G. Lanfermann, J. Massó, T. Radke, E. Seidel, and J. Shalf. The Cactus framework and toolkit: design and applications. In Proceedings of the 5th international conference on High performance computing for computational science, VECPAR’02, pages 197–227, Berlin, Heidelberg, 2003. Springer-Verlag.
  • [6], 2013.
  • [7] A. M. Wissink, R. D. Hornung, S. R. Kohn, S. S. Smith, and N. Elliott. Large scale parallel structured AMR calculations using the SAMRAI framework. In Supercomputing ’01: Proceedings of the 2001 ACM/IEEE conference on Supercomputing (CDROM), pages 6–6, New York, NY, USA, 2001. ACM.
  • [8] Jeremy G Siek, Lie-Quan Lee, and Andrew Lumsdaine. Boost Graph Library: User Guide and Reference Manual, The. Pearson Education, 2001.
  • [9] Dirk Merkel. Docker: Lightweight linux containers for consistent development and deployment. Linux J., 2014(239), March 2014.
  • [10] Hank Childs, Eric Brugger, Brad Whitlock, Jeremy Meredith, Sean Ahern, David Pugmire, Kathleen Biagas, Mark Miller, Cyrus Harrison, Gunther H. Weber, Hari Krishnan, Thomas Fogal, Allen Sanderson, Christoph Garth, E. Wes Bethel, David Camp, Oliver Rübel, Marc Durant, Jean M. Favre, and Paul Navrátil. VisIt: An End-User Tool For Visualizing and Analyzing Very Large Data. In High Performance Visualization–Enabling Extreme-Scale Scientific Insight, pages 357–372. Oct 2012.
  • [11] Emden R Gansner and Stephen C North. An open graph visualization system and its applications to software engineering. Software Practice and Experience, 30(11):1203–1233, 2000.
  • [12] Guillaume Grégoire and Hugues Chaté. Onset of collective and cohesive motion. Phys. Rev. Lett., 92:025702, Jan 2004.
  • [13] Tamás Vicsek, András Czirók, Eshel Ben-Jacob, Inon Cohen, and Ofer Shochet. Novel type of phase transition in a system of self-driven particles. Physical Review Letters, 75(6):1226, 1995.
  • [14] John Toner and Yuhai Tu. Long-range order in a two-dimensional dynamical XY model: how birds fly together. Physical Review Letters, 75(23):4326, 1995.
  • [15] Hugues Chaté, Francesco Ginelli, Guillaume Grégoire, and Franck Raynaud. Collective motion of self-propelled particles interacting without cohesion. Physical Review E, 77(4):046113, 2008.
  • [16] Andreas Deutsch, Guy Theraulaz, and Tamas Vicsek. Collective motion in biological systems. Interface Focus, 2(6):689–692, 2012.
  • [17] Tamas Vicsek and Anna Zafeiris. Collective motion. Physics Reports, 517(3–4):71 – 140, 2012.
  • [18] A Arbona, C Bona, B Miñano, and A Plastino. Statistical complexity measures as telltale of relevant scales in emergent dynamics of spatial systems. Physica A: Statistical Mechanics and its Applications, 410:1–8, 2014.
  • [19] A Arbona, C Bona, J Massó, B Miñano, and A Plastino. A fisher-gradient complexity in systems with spatio-temporal dynamics. Physica A: Statistical Mechanics and its Applications, 2015.

Appendix G SimML sample set

SimML is Simflowny’s Simulation Markup Language, a tag-based specification that allows the creation of complete algorithms to manage PDE and ABM models. Its tags can be mixed with MathML notation to conform the algorithm. SimML tags can provide the functionality to manage the algorithm flow, use model elements, change the context of instructions, and use specific values of the problem. Some tags can be expressed in infix notation to allow for its inclusion into MathML expressions.

For instance, two typical tags are if and while. The first introduces a conditional in the algorithm flow based on a logical expression, introduced by the user using MathML. The second creates a loop, which repeats its internal instructions until a logical condition is accomplished.

PDE problems commonly use boundary to invoke the boundary conditions (whatever they are), while balance-law PDEs use flux and sources to call the evolution equation fluxes and sources respectively. They can use current cell, increment coordinate or decrement coordinate to access variables in specific cells.

ABM most common tags are current agent and current vertex to acces variables in the agent and vertex, or edge source and edge target to access variables from vertices connected to the current one.

The tags iterate over cells, iterate over agents and iterate over vertices are used to sweep over all the cells (PDE), agents (ABM on spatial domain) and vertices (ABM on graphs) respectively and execute the instructions within the tag. To iterate over neighbour agents or vertices, the tags iterate over interactions and iterate over edges are appropriate.

There are also tags to get values of field, spatial coordinate, time coordinate or iteration number among others. Nondeterministic behaviour can be introduced through a random number generator when random number tag is set.

Some global accounting information can be obtained using the self-explanatory tags global number of vertices, global number of agents, global number of edges and local number of edges.

In ABM on spatial domain, the tag neighbour agent is used to access variables of neighbour agents (i.e. those which are in the vicinity of the current agent and which are listed through the iterate over interactions tag).

Some of these tags appear in the examples presented in the paper. See for instance figure 16.

For a full reference see Simflowny SimML documentation333

Comments 0
Request Comment
You are adding the first comment!
How to quickly get a good reply:
  • Give credit where it’s due by listing out the positive aspects of a paper before getting into which changes should be made.
  • Be specific in your critique, and provide supporting evidence with appropriate references to substantiate general statements.
  • Your comment should inspire ideas to flow and help the author improves the paper.

The better we are at sharing our knowledge with each other, the faster we move forward.
The feedback must be of minimum 40 characters and the title a minimum of 5 characters
Add comment
Loading ...
This is a comment super asjknd jkasnjk adsnkj
The feedback must be of minumum 40 characters
The feedback must be of minumum 40 characters

You are asking your first question!
How to quickly get a good answer:
  • Keep your question short and to the point
  • Check for grammar or spelling errors.
  • Phrase it like a question
Test description