Herdsim - a Distributed Systems Simulator written in Pony

This repo is reachable at https://github.com/mmirko/herdsim.git

herdsim

Herdsim is a distributed system simulator that allows users to simulate the behavior of homogeneous agents that follow a protocol to achieve a common goal. The simulator is inspired by the textbook “Design and Analysis of Distributed Algorithms” by Nicola Santoro. The simulator is written in Pony and is a major rewrite of the original simulator written in C/Lua/OpenCL.

The simulator is not meant to be used other than editing some part of the code to test new algorithms (it has no GUI or CLI). The editable parts are in a config.pony file and are:

  • The Protocol definition, which is a Pony primitive that defines the protocol that the agents will follow.
  • The configuration of the simulation, which is a Pony primitive that defines various parameters of the simulation.
  • The graph of the agents and the communication network, which is a Pony primitive that defines a deploy function that creates the agents and the communication network.
  • The initial state of the agents, which is a Pony primitive with a start function that calls the protocol’s initiators.

The code is organized as follows:

  • config.pony: Contains the configuration of the simulation. It is the only file that the user should edit. It is actually a symlink to the config.devel file.
  • herdsim.pony: Contains the main function that runs the simulation.
  • graph-*.pony: Contain the graph builders of the agent’s communication network.
  • proto-*.pony: Contain the protocol’s definitions.
  • example-*: Each directory contains a different example of the simulation main actor.

To run the simulator, you need to have Pony installed. You can install Pony by following the instructions on the Pony website. Once Pony is installed, you can first clone the repository:

git clone https://github.com/mmirko/herdsim.git
cd herdsim

Then you can run the simulator by running the following command:

make devel
make run

By default, the simulator runs the config in config.devel example, which is a simple example and can be used as a starting point to develop new algorithms. The main actor file is to the herdsim.pony file. To try a different example, you can change the config symlink to the desired example:

make example-[example name]
make run

The corresponding example will be executed. Related to the example chosen, a readme file named example-[example name]/README.md is provided to describe the example and the expected output.

to go back to the default example:

make devel

and to clean the build:

make clean

Some examples also generate a graph of the agents and the communication network. The graph is generated as GIF file or as AVI file using as rendering engine. To generate the graph, you need to have graphviz installed. You also need memcoder (mplayer) to generate the AVI file. Furthermore, the graph generation is not available in all examples. The example’s readme file will describe if the graph is generated in that particular example.

To generate the graph as a GIF file, you can run the following command:

make videoout.gif

or as an AVI file:

make videoout.avi