Version: 2.2.2 (see changelog)
Download: (also see Examples).
Last Page Update: 2018-11-13 9:50PM
For use with the Eclipse IDE: see this optional tutorial.

How to use the simulator

This is a simulator for synchronous distributed systems. The simulator was written in Java and it was compiled with the Java compiler version 11.0.1. It should be compatible with Java versions 9 to 11 and Windows and Linux (likely Mac OS as well but this has not been officially tested).



First, ensure that you have installed the Java 11 JDK correctly and that the programs java and javac are in your environment PATH.
Download and unzip into the directory in which you will be creating and running your algorithms. All of the java files you create must be in this directory. If you are using a UNIX based system (Linux, etc.) give the scripts compile and runsim execute permissions (i.e. chmod +x compile runsim).

Back to Top


Your java file must contain your algorithm in a class that extends Algorithm and follows the template provided here. To compile the java file, run the provided compile script (compile.bat on Windows or just compile on Linux). Ensure that the script has execute permissions (+x) on UNIX based systems.


compile.bat filename

Where filename is the name of the java file containing your implementation of the distributed algorithm that you want to run on the simulator. If successful, this should produce a class file with the same name as your java file in the working directory.

Alternatively, you may use the Eclipse IDE to compile your algorithm by following this tutorial (this is optional).

Back to Top

Running the Simulator

Use the runsim.bat script (just runsim on Linux) to run the simulator. The last command line argument to the script must be the name of your network configuration file (see below).


runsim.bat networkconfigfile

Where networkconfigfile is the name of your network configuration file as described below. It must be located in the same directory as the runsim.bat script, Simulator.jar and your java class.

The simulator supports a number of other command line arguments to control how the simulation is run and help with debugging:

runsim.bat [-v] [-d] [-n] [-m maxrounds] [-r reportfilename] networkconfigfile Note that the networkconfigfile argument must come last, but options/flags can be in any order.

Alternatively, you may use the Eclipse IDE to run the simulator by following this tutorial (this is optional).

Back to Top

The Network Configuration File

The configuration file is a text file and each line contains one of the following commands:
Peer Mode Only Configuration Commands
More advanced configuration options exist that may be helpful to you. See the Advanced Configuration section for more details.

Back to Top

Network Modes

Network modes (set with the Mode command in the configuration file) restrict the network to better model problems you are trying to solve. The network mode must be set to one of the following:
Back to Top

The Algorithm

The distributed algorithm to be executed by the simulator must be a java class that extends the simulator's Algorithm class. The name of the java class containing the algorithm must be specified in the configuration file as described above. Look at the examples and the template java file to get an idea of how you must write your own distributed algorithms. The simulator's Algorithm class provides several methods that you can use to program your distributed algorithms:

Core Methods
Abstract Methods
Output Methods
Tree Methods (Only valid in TREE or BFS network modes)
Peer-to-Peer (P2P) Methods (Only valid in PEER network mode)
Helper Methods
Back to Top


By default, the GUI will try to layout the network graph using the "organic" layout mode and will attempt to draw the network graph using the simulated annealing technique by Davidson and Harel (1996). Users can manually reposition nodes by clicking and dragging them to a new location or give a different layout mode in the configuration file (see advanced configuration settings below).

If debug mode is enabled, users will be able to step through each round by clicking the button. Otherwise the simulation will continue to the next round automatically.


Symbol Description
An active node. Node ID is displayed in bold black text.
A root node as set by RootNode.
A node that has failed due to an error or fault is displayed in orange.
A node that has stopped running is shown in red. Messages printed with showMessage are shown above or below the node in small black text.
A node that has returned a solution/result will display the result in gold text at the bottom of the node.
An inactive link. By default, a link is shown for each direction a message can travel. A full duplex link is therefore represented by two links (one in each direction).
An active edge. That is a link over which a message was sent last round. The message text is shown to the right of the link.

Back to Top


Template Leader Election Leader Election 2 (O(nlogn) communication complexity) Broadcasting Sum Tree Breadth-First Search (BFS) Tree
Back to Top

Advanced Configuration

A number of advanced commands are available for the network configuration file that allow for random faults, automatic network generation and changing how the network is laid out in the GUI.

Random Faults
These commands allow a node to randomly fail during the execution of an algorithm. This can be useful when creating algorithms that must deal with nodes failing. Note that the commands CleanFailureRate and StoppingFailureRate only apply to nodes added (with AddNode) after the command, allowing you to set different failure rates for each node. Both clean failures and stopping failures may be used simultaneously.

Automatic Network Generation
Network Layout
Messaging Rules Back to Top


  2018-11-13      Version 2.2.2
  2018-10-29      Version 2.1.2
  2018-10-19      Version 2.1.1
  2018-10-12      Version 2.1.0
  2018-09-25      Version 2.0.0
Back to Top