Evoplex: A platform for agent-based modeling on networks

Evoplex: A platform for agent-based modeling on networks

Marcos Cardinot marcos.cardinot@nuigalway.ie Colm O’Riordan Josephine Griffith Matjaž Perc Discipline of Information Technology, National University of Ireland, Galway, Ireland Faculty of Natural Sciences and Mathematics, University of Maribor, Koroška cesta 160, SI-2000 Maribor, Slovenia CAMTP – Center for Applied Mathematics and Theoretical Physics, University of Maribor, Mladinska 3, SI-2000 Maribor, Slovenia Complexity Science Hub Vienna, Josefstädterstraße 39, A-1080 Vienna, Austria

Evoplex is a fast, robust and extensible platform for developing agent-based models and multi-agent systems on networks. Each agent is represented as a node and interacts with its neighbors, as defined by the network structure. Evoplex is ideal for modeling complex systems, for example in evolutionary game theory and computational social science. In Evoplex, the models are not coupled to the execution parameters or the visualization tools, and there is a user-friendly graphical user interface which makes it easy for all users, ranging from newcomers to experienced, to create, analyze, replicate and reproduce the experiments.

multi-agent system, complex adaptive systems, network science, evolutionary game theory
journal: SoftwareX

1 Motivation and significance

Agent-based modeling (ABM) has been used as a framework to simulate complex adaptive systems (CAS) in a wide range of domains such as life sciences, ecology and social sciences cardinot2018a (); filatova2013 (); grimm2005 (); bonabeau2002 (). Those systems are composed of a number of interacting agents each of whom have a defined set of attributes and can exhibit specific behaviors based on their interactions with the environment and the other agents miller2009 (). Research in this field usually aims to explore how small changes in individual behavior can both affect and promote collective behavior throughout the system sun2016 (); macal2010 (); gotts2003 ().

Given the flexibility of the ABM approach and the increasing computing power of cheap personal computers, efforts to develop reusable, flexible, multi-threaded, scalable and user-friendly software are more than ever required by the scientific community. However, despite the high number of existing ABM toolkits and platforms available nikolai2009 (), due to the heterogeneity and diversity of the areas of research and application domains, most researchers still prefer to implement individual and domain-specific, specialised software from scratch, which is usually not publicly released. Many researchers write MATLAB or Mathematica based scripts which, although being complete and well-known scientific platforms, are neither free nor open-source, which therefore reduces the transparency and re-usability of the developed models perkel2018 ().

In fact, implementing a highly specialized solution from scratch is time-consuming, complex and error-prone. Many projects try to overcome this by implementing a toolkit or platform for a general purpose problem domain. For instance, some projects such as NetLogo netlogo () and GAMA gama () succeed in providing generic and reusable software; however, they require the user to learn their specific programming language. A wide range of the ABM solutions including MASON mason18 () and Repast repast () are written in Java tobias2004 (), which make them cross-platform and usually faster than some Python or JavaScript alternatives like Mesa mesa () and AgentBase agentBase (). However, they usually require modellers to be highly proficient in the language or they have critical scalability issues. Overall, the main issues with some existing software include the use of old/deprecated technologies, not following state of the art in software engineering, developing single-threaded applications and not being community-friendly.

Furthermore, despite being a common strategy in the field, many ABM projects start with the promising and challenging intention of developing powerful software to meet any requirement in the field, from simple cellular automaton models to complex and realistic geographical information science (GIS) models. Unfortunately, this promising approach usually results in making the code base very complex and hard to both optimise and maintain. In reality, given the small size of the development teams, there is no best strategy for all scenarios, and the user choice is usually guided by their familiarity with the languages or technologies used in the software. In this way, defining a clear and focused scope can help solve those issues.

Thus, in this paper we present Evoplex, a cross-platform, free and open-source software which aims to mitigate the issues outlined by providing a fast and fully modular ABM platform for implementing and analysing models which impose an explicit graph-theoretical approach, i.e., the agents are represented as nodes (or vertices) and edges (or links) represent connections between agents.

2 Software description

Evoplex is a fast, robust and extensible platform for developing agent-based models and multi-agent systems on networks. Here, each agent is represented as a node in the network and is constrained to interact only with its neighbors, which are linked by edges in the network. Although not limited to a particular domain, Evoplex is ideal for tackling problems associated with evolutionary computation, complex adaptive systems, evolutionary game theory and cellular automata.

As shown in Figure 1, the Evoplex workflow is very straightforward and intuitive. The engine processes projects as inputs. A project is a plain table (csv file) where the experiments are listed along the rows, and the inputs to each experiment are placed along the columns. An experiment is defined by a set of parameter settings (inputs) necessary to perform one trial (simulation) and (optionally) the required data outputs, which can be the result of some statistical function and/or the state of the set of nodes/edges for each time step. Each experiment can run for one or more trials, i.e., repeat the same experiment using different pseudo-random generator seeds. The strategy of having the projects defined in plain text files aims to make it easier for users to replicate and reproduce their results. Furthermore, it allows newcomers to interact with with the models without requiring any programming skills.

Figure 1: Simplified overview of the user workflow.

We provide a user-friendly and interactive graphical user interface (GUI) to allow for creating, opening, running and saving projects. Also, the GUI provides many useful tools including interactive graph and grid views. Moreover, Evoplex allows several experiments to run at the same time. These are automatically distributed in parallel across multiple threads.

2.1 Software Architecture

Evoplex is simple, user-friendly and was built with performance in mind from the start. It is cross-platform and runs on every major platform, i.e., Linux, Microsoft Windows, and MacOS. Evoplex is developed in modern C++ 14, based on Qt, which is one of the most popular and successful C++ frameworks available to date. Moreover, Evoplex includes CMake scripts to ease the compilation and setup from its source code.

The Evoplex application bundles three main open-source components: the EvoplexCore library, the EvoplexGUI library and a collection of plugins (example models and graph generators). The EvoplexCore library is available under the Apache 2.0 License, which is permissive, free and commercially friendly. The EvoplexGUI library is available under the GNU GPLv3 license, which is also free but is conditioned on making the source code of licensed works and modifications available.

Following a common practice in software engineering, the Evoplex architecture is guided by a fully modular approach. The core component, EvoplexCore, splits its implementation into both private and public Application Programming Interfaces (APIs). The private API is intended for internal use only and is where the simulations will actually occur; it is responsible for managing the I/O operation, parsing inputs, handling the CPU threads and memory, loading and creating instances of plugins and others. The public API exposes all the tools and services needed to develop a plugin, which can be either a model or a graph generator.

Figure 2 shows a simplified overview of the overall software architecture, which is composed of four major layers: the kernel (i.e., EvoplexCore library), the plugins, the data and the applications layers. The current version of the Evoplex application layer includes EvoplexGUI, which implements a graphical user interface on top of EvoplexCore (kernel) to provide a number of interactive and user-friendly tools. Note that as the kernel is completely independent of the applications layer, Evoplex can be distributed with different user-interfaces but share the same engine (kernel). For instance, one may want to implement an EvoplexCLI application to perform simulations via command-line, or an EvoplexWeb application to provide visualization tools on a web browser.

Figure 2: Simplified illustration of the software architecture.

In Evoplex, every model or graph is a plugin and is compiled independently from the main application. The creation of plugins is very straightforward and requires a very basic knowledge of C++. Given the Evoplex approach of not coupling the visualization tools nor inputs/outputs to the model, the models’ code is usually very simple and short. We provide a few examples of plugins of easy reuse and customization111https://evoplex.org/docs/example-plugins. In summary, a plugin comprises four files: CMakeLists.txt which does not need to be changed by the modeller and is just a CMake script to ease the compilation process and make it portable across different compilers and IDEs, the plugin.cpp (source) and plugin.h (header) files where the modeller implements the model’s algorithm, and metadata.json which holds the definition of all the attributes of the model.

Moreover, Evoplex uses automated Continuous Integration (CI) to make sure that the code base works as expected and to allow early detection of problems. After every new commit, the CI system automatically builds Evoplex from the source code, executes regression tests, unit-tests and static code analysis across a range of different versions/distributions of the supported platforms, i.e., Linux, Microsoft Windows, and MacOS.

2.2 Software Functionalities

The Evoplex application comes with a user-friendly and intuitive GUI that allows loading and unloading of plugins at runtime and provides a bunch of widgets and tools to allow for the creation and running of experiments and analysing (or visualizing) their outputs. The main tools and widgets are described below:

  • Project View: As shown in Figure 3, when opening a project, all experiments are listed in a table which is dynamic and customizable and allows running, pausing and queuing multiple experiments at the same time. When running the experiments, Evoplex automatically manages the available resources to run them as fast as possible (in parallel) and use as little memory as possible.

  • Experiment Designer: This widget is displayed beside the Project View in Figure 3 and allows creating, removing and editing of experiments.

  • Nodes Generator: This tool can be accessed in the Experiment Designer and provides handy functions to ease the generation of the initial set of nodes.

  • Experiment View: This widget is opened when the user double-clicks on an experiment in the Project View. It allows for the opening of multiple visualization tools at the same time, which can be set to show different trials of the same experiment. For instance, given an experiment with a stochastic model which runs for trials; the user may want to visualize the behavior of the trials side by side to investigate the effects of randomness over time.

  • Graph/Grid View: Evoplex provides both graph (nodes and edges — Figure 4) and grid (cells) views. Those views allow zooming in and out, exporting nodes/edges as a text file, taking screenshots, selecting a node to inspect and change the state of its attributes and others. Also, it allows changing the nodes/edges size and choosing which attribute and colormap will be represented in the nodes/edges.

Figure 3: Screenshot of Evoplex 0.2.1 showing the Project View and the Experiment Designer tools.
Figure 4: Screenshot of Evoplex 0.2.1 showing the Experiment View docking two instances of the Graph View at different positions.

Differing from most of the other ABM solutions, in Evoplex, the widgets are not statically coupled to the model plugin. That is, the model plugin only defines the entities’ attributes and implements the algorithm to describe the nodes’ (agents) behavior for each time step. Then, at runtime and not requiring any programming skill, the users have the freedom to decide which widgets they want to open and where they want to place them. Also, all widgets can be detached from the main window, enabling users to open different views in multiple monitors or attach them at different positions and sizes in the screen.

3 Illustrative Examples

In order to illustrate the use of Evoplex, we consider an implementation of the widely known model of a spatial prisoner’s dilemma (PD) game proposed by Nowak & May in 1992 nowak1992 (). In the PD game, agents can be either cooperators or defectors, and receive a fixed payoff based on a pairwise interaction. That is, given two agents, if both are cooperators, both get a reward ; if both are defectors, both get a punishment ; if a cooperator plays with a defector, the cooperator receives , and the defector receives (temptation to defect) nowak2004 ().

In this model, agents (nodes) are placed in a square grid, where, in each round: every node accumulates the payoff obtained by playing the PD game with all its immediate neighbors and itself; then, each agent copies the strategy of the best performing agent in its neighborhood, including itself.

Figure 5 shows a screenshot of an experiment with an implementation of this model running in Evoplex. The experiment is created using the Experiment Designer tool. Using the Experiment View, we run the experiment for one step, opened the Grid View and placed a defector in the middle of the grid. Then, when running the experiment for more steps, it is possible to observe the emergence of chaotically changing spatial patterns.

Figure 5: In this experiment, the model (prisonersDilemma) is set with a temptation to defect equal to ; the graph is set for population of 9801 cooperators, distributed in a squareGrid with periodic boundary conditions, undirected edges and von Neumann neighborhood; the simulation is fed with a pseudo-random generator seed equal to (which does not make any difference in this fully deterministic model), and is set to run for a maximum of time steps for only one trial; finally, it also stores the frequency of each type of strategy over time. In the Grid View, the colors blue, red, green and yellow corresponds to cooperators, defectors, new cooperators and new defectors respectively.

4 Impact

Evoplex is intended to address research whose methodology comprises a simulation-based approach to evolve outcomes of populations of autonomous and interacting agents. It has been used to support research in a number of areas, including spatial game theory and evolutionary game theory cardinot2018c (); cardinot2018a (); cardinot2018b (). In those scenarios, agents are described in terms of graph theory, i.e., a graph (network) consisting of a set of nodes (agents) and edges (agents’ connections).

Despite having a few options of agent-based modeling (ABM) software available, none of them are really suitable for this area of research. Beyond the issues mentioned in Section 1, most of the existing simulators have very limited performance and are unable to handle the complexity of the models which are investigated at present, e.g., coevolutionary models with a large number of agents.

Moreover, another recurring issue with existing ABM software is that they are designed to run and analyze one experiment at a time. However, research in the field usually needs to explore the outcomes of large populations for a wide range of parameter settings, which in many cases require many Monte Carlo steps to converge. In this case, the user needs to modify the model’s source code or write a script on top of it to automate the execution of the experiments, which will usually run in a single thread, one at a time. Some projects like FLAME flame () and OpenMOLE openmole () succeeded in allowing efficient parallel processing, but their use and configuration are not straightforward. Thus, in those cases, we observed that for any small interaction with the model, the user ends up having to change the code/script back and forth very often, which is both error prone and difficult for non-experienced users.

Evoplex changes the paradigm of ABM for graphs by allowing nodes and edges to be independent entities. Thus, given a set of nodes (agents), the user can easily investigate how changes in the topology may affect the population’s behavior (vice versa) without touching the source code nor changing the model. Also, the robust and multi-threaded engine combined with the user-friendly GUI makes it easier for users to share, reproduce, replicate and analyze the experiments. Evoplex is free, non-profit and is fully open-source with a permissive license, allowing for both commercial and academic use.

5 Conclusions

We have presented Evoplex, a flexible, fast and multi-threaded platform for agent-based modeling imposing an explicit graph-theoretical approach. We discussed that, different from other software, in Evoplex, the models are not coupled to the execution parameters nor the visualization tools. Also, it provides a user-friendly GUI which makes it easy for all users, ranging from newcomers to experienced, to create, analyze, replicate and reproduce experiments. As an open-source project, we encourage users to provide feedback, share models and contribute to improving the software. Evoplex is an ever-evolving project, and future work will involve adding support for multilayer networks, as well as implementing more plugins, and developing more visualization widgets for the GUI.


This work was supported by the National Council for Scientific and Technological Development (CNPq-Brazil) (Grant 234913/2014-2), and by the Slovenian Research Agency (Grants J1-7009, J4-9302, J1-9112 and P5-0027).


  • (1) M. Cardinot, J. Griffith, C. O’Riordan, A further analysis of the role of heterogeneity in coevolutionary spatial games, Physica A: Statistical Mechanics and its Applications 493 (2018) 116–124.
  • (2) T. Filatova, P. H. Verburg, D. C. Parker, C. A. Stannard, Spatial agent-based models for socio-ecological systems: Challenges and prospects, Environmental Modelling & Software 45 (2013) 1–7, thematic Issue on Spatial Agent-Based Models for Socio-Ecological Systems. doi:doi.org/10.1016/j.envsoft.2013.03.017.
  • (3) V. Grimm, E. Revilla, U. Berger, F. Jeltsch, W. M. Mooij, S. F. Railsback, H.-H. Thulke, J. Weiner, T. Wiegand, D. L. DeAngelis, Pattern-oriented modeling of agent-based complex systems: Lessons from ecology, Science 310 (5750) (2005) 987–991. doi:10.1126/science.1116681.
  • (4) E. Bonabeau, Agent-based modeling: Methods and techniques for simulating human systems, Proceedings of the National Academy of Sciences 99 (suppl 3) (2002) 7280–7287.
  • (5) J. H. Miller, S. E. Page, Complex adaptive systems: An introduction to computational models of social life, Vol. 17, Princeton university press, 2009.
  • (6) Z. Sun, I. Lorscheid, J. D. Millington, S. Lauf, N. R. Magliocca, J. Groeneveld, S. Balbi, H. Nolzen, B. Müller, J. Schulze, C. M. Buchmann, Simple or complicated agent-based models? a complicated issue, Environmental Modelling & Software 86 (2016) 56–67. doi:10.1016/j.envsoft.2016.09.006.
  • (7) C. M. Macal, M. J. North, Tutorial on agent-based modelling and simulation, Journal of Simulation 4 (3) (2010) 151–162. doi:10.1057/jos.2010.3.
  • (8) N. Gotts, J. Polhill, A. Law, Agent-based simulation in the study of social dilemmas, Artificial Intelligence Review 19 (1) (2003) 3–92. doi:10.1023/A:1022120928602.
  • (9) C. Nikolai, G. Madey, Tools of the trade: A survey of various agent based modeling platforms, Journal of Artificial Societies and Social Simulation 12 (2) (2009) 2.
  • (10) J. M. Perkel, A toolkit for data transparency takes shape, Nature 560 (7719) (2018) 513–515.
  • (11) S. Tisue, U. Wilensky, Netlogo: A simple environment for modeling complexity, in: International conference on complex systems, Vol. 21, Boston, MA, 2004, pp. 16–21.
  • (12) A. Grignard, P. Taillandier, B. Gaudou, D. A. Vo, N. Q. Huynh, A. Drogoul, Gama 1.6: Advancing the art of complex agent-based modeling and simulation, in: G. Boella, E. Elkind, B. T. R. Savarimuthu, F. Dignum, M. K. Purvis (Eds.), PRIMA 2013: Principles and Practice of Multi-Agent Systems, Springer Berlin Heidelberg, Berlin, Heidelberg, 2013, pp. 117–131.
  • (13) S. Luke, R. Simon, A. Crooks, H. Wang, E. Wei, D. Freelan, C. Spagnuolo, V. Scarano, G. Cordasco, C. Cioffi-Revilla, The mason simulation toolkit: Past, present, and future, in: Multiagent-based Simulation Workshop (MABS) at AAMAS, 2018, pp. 1–12.
  • (14) M. J. North, N. T. Collier, J. Ozik, E. R. Tatara, C. M. Macal, M. Bragen, P. Sydelko, Complex adaptive systems modeling with repast simphony, Complex Adaptive Systems Modeling 1 (1) (2013) 3. doi:10.1186/2194-3206-1-3.
  • (15) R. Tobias, C. Hofmann, Evaluation of free java-libraries for social-scientific agent based simulation, Journal of Artificial Societies and Social Simulation 7 (1).
  • (16) D. Masad, J. Kazil, Mesa: an agent-based modeling framework, in: Proceedings of the 14th Python in Science Conference (SCIPY 2015), 2015, pp. 53–60.
  • (17) W. Wiersma, Agentbase: Agent based modeling in the browser, in: W. Jager, R. Verbrugge, A. Flache, G. de Roo, L. Hoogduin, C. Hemelrijk (Eds.), Advances in Social Simulation 2015, Springer International Publishing, Cham, 2017, pp. 451–455.
  • (18) M. A. Nowak, R. M. May, Evolutionary games and spatial chaos, Nature 359 (6398) (1992) 826–829.
  • (19) M. A. Nowak, K. Sigmund, Evolutionary dynamics of biological games, Science 303 (5659) (2004) 793–799. doi:10.1126/science.1093411.
  • (20) M. Cardinot, J. Griffith, C. O’Riordan, M. Perc, Cooperation in the spatial prisoner’s dilemma game with probabilistic abstention, Scientific Reports 8 (1) (2018) 14531. doi:10.1038/s41598-018-32933-x.
  • (21) M. Cardinot, C. O’Riordan, J. Griffith, The Impact of Coevolution and Abstention on the Emergence of Cooperation, Springer International Publishing, Cham, 2019, pp. 105–122.
  • (22) M. Kiran, P. Richmond, M. Holcombe, L. S. Chin, D. Worth, C. Greenough, Flame: simulating large populations of agents on parallel hardware architectures, in: Proceedings of the 9th International Conference on Autonomous Agents and Multiagent Systems, International Foundation for Autonomous Agents and Multiagent Systems, 2010, pp. 1633–1636.
  • (23) R. Reuillon, M. Leclaire, S. Rey-Coyrehourcq, Openmole, a workflow engine specifically tailored for the distributed exploration of simulation models, Future Generation Computer Systems 29 (8) (2013) 1981–1990.

Required Metadata

Current code version

Nr. Code metadata description Please fill in this column
C1 Current code version v0.2.1
C2 Permanent link to code/repository used for this code version \(https://github.com/evoplex/evoplex\)
C3 Legal Code License Apache 2.0 (EvoplexCore) and GPLv3 (EvoplexGUI)
C4 Code versioning system used Git
C5 Software code languages, tools, and services used C++, OpenGL, Qt and CMake.
C6 Compilation requirements, operating environments & dependencies C++ compiler (e.g., GCC, Clang or MSVC), Qt Framework and CMake.
C7 If available Link to developer documentation/manual \(https://evoplex.org/api\)
C8 Support email for questions evoplex@googlegroups.com
Table 1: Code metadata (mandatory)

Current executable software version

Nr. (Executable) software metadata description Please fill in this column
S1 Current software version v0.2.1
S2 Permanent link to executables of this version \(https://github.com/evoplex/evoplex/releases\)
S3 Legal Software License GPLv3
S4 Computing platforms/Operating Systems Linux, OS X, Microsoft Windows and Unix-like
S5 Installation requirements OpenGL 2.0+
S6 If available, link to user manual - if formally published include a reference to the publication in the reference list \(https://evoplex.org/docs\)
S7 Support email for questions evoplex@googlegroups.com
Table 2: Software metadata (optional)
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