Herdsim - a Distributed Systems Simulator written in Pony

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

Herdsim is a distributed system simulator that allows users to simulate the behavior of homogeneous agents following a protocol to achieve a common goal. The simulator is inspired by the textbook “Design and Analysis of Distributed Algorithms” by Nicola Santoro. It 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 without editing parts of the code to test new algorithms (it has no GUI or CLI). The editable parts are in a config.pony file and include:

  • The Protocol definition, which is a Pony primitive that defines the protocol the agents will follow.
  • The configuration of the simulation, which is a Pony primitive that defines various simulation parameters.
  • The graph of the agents and the communication network, which is a Pony primitive that defines a deploy function to create 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 simulation configuration. This is the only file 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 for the agent’s communication network.
  • proto-*.pony: Contain the protocol definitions.
  • example-*: Each directory contains a different simulation example.

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 that can be used as a starting point to develop new algorithms. 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. For each example, 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 a GIF file or as an AVI file. To generate the graph, you need to have graphviz installed. You also need mencoder (mplayer) to generate the AVI file. Furthermore, graph generation is not available in all examples. The example’s readme file will describe if the graph is generated for 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