button. Otherwise the simulation will continue to the next round automatically.
java and javac are in your environment PATH.compile and runsim execute permissions (i.e. chmod +x compile runsim).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 filenamefilename 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.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 networkconfigfilenetworkconfigfile 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.runsim.bat [-v] [-d] [-n] [-m maxrounds] [-r reportfilename] networkconfigfile
-v OR --verbose Set the console output to verbose. Increasing the amount of output given by the simulator. Can be helpful for debugging.-d OR --debug Turns on debug mode. In debug mode, the simulator pauses between each round and waits for user input (either a key press or button click) before advancing to the next round.-n OR --nogui Disables the GUI interface and only provides console output. Can be useful when running on a system without a GUI (e.g. a server).-m R OR --maxrounds R Limits the maximum number of rounds the simulator will run to R, where R is a nonzero positive integer. A space must be between -m or --maxrounds and the number R.-V OR --version Prints the simulator's version number and exits (you do not have to give an configuration file name with this option).-x OR --exit Simulator will exit as soon as all nodes have stopped. GUI will close automatically in GUI mode.-r FILE OR --report FILE Creates a report containing debugging information and the results of the simulation in the given file FILE. A space must be between -r or --report and the file name FILE.networkconfigfile argument must come last, but options/flags can be in any order.Mode networkmode Set the mode the network will operate in. Must be set before nodes are added using AddNode. Valid modes are identical (or ident for short), root, bfs, peer, or tree. Network modes place restrictions on what commands can be used in your java algorithm. See below for details on each mode.AddNode x: x1 x2 ... xk Adds a node with id = x and neighbours x1, x2, ... xk. Nodes with an id of 0 are considered special placeholders. They are not shown in the GUI and can not be sent messages but they are returned by the neighbours() method. When in tree mode, x1, x2, ... xk are children of node x and a parent link is created automatically.LoadAlgorithm Alg Specifies the java class containing the distributed algorithm
to be executed. This means that the algorithm must be defined in a java file called Alg.java. You must compile this java class before running the simulator using compile.bat and Alg.class should be in the same directory as the simulator.RootNode z Marks node z as a special node (root node). You might find this useful, for
example, when broadcasting information from a particular node to the rest of the
system. This command is only valid in root, bfs and tree modes. The node z must already be added with AddNode and the network mode set with Mode. Nodes can determine if they are the root node using the isRoot() method in your java code.RoundTime t Specifies the duration of each round in milliseconds. Must be larger than 299. You have to choose
a sufficiently large number that allows the simulator to complete a round for each node
before the next round starts.Successor x: s Marks node s as node x's successor. Both x and s must be valid IDs of nodes added to the network (e.g. using AddNode) before the Successor command is issued. The successor of a node can be access via the successor() method.DataKeys k1 k2 ... kn Adds keys k1 to kn to the peer-to-peer (P2P) system. All keys must be integers and unique. The keys in a P2P system can be accessed via the getKeys() method.Find x: k1 k2 ... kn The keys that node x will look for, where x is a node ID that has already been added to the network (e.g. using AddNode) and k1 to kn are integer keys already added to the P2P system using DataKeys. Each node can access the keys they need to find via the keysToFind() method.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:
identical OR ident All nodes are identical other than their ID (obtained via the getID() method). No root nodes are allowed. Calls to isRoot() will result in an error.root The network may have one special (root) node that is unique. Your code can determine if it is the root node by using the isRoot() method. Calls to the tree methods (getParent(), etc.) will result in an error.bfs The simulator will create a breadth-first spanning tree of the network and make this tree available via the tree methods (getParent(), etc.). A root node must be set using RootNode in the configuration file.tree Allows you to manually specify a tree network. The AddNode command in the configuration file will be changed such that the list of given nodes are the node's children in the tree. All nodes will have bidirectional links to their parent and children and have access to the tree methods. A root node must be set using RootNode in the configuration file. It is assumed that there are no cycles in the network when using this mode.peer The network is configured in peer-to-peer (P2P) mode, enabling the configuration commands Successor, DataKeys, and Find. The Algorithm methods getKeys, successor, keysToFind, etc. are also enabled in this mode.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:String getID() Returns the node's id as a String (as set in the configuration file with AddNode).Vector<String> neighbours() Returns a java Vector containing the id's of this node's neighbours.
Each id is stored as a java String.int numNeighbours() Returns the number of neighbours this node has in the network.Message makeMessage(String destination, String data) Creates a new Message, with the current node listed as the sender, that may be sent with the send method. Each message
contains 3 values:
the id of the destination node (given in makeMessage), the id of the sending node (added automatically by makeMessage), and the message's
data (provided by you to makeMessage). You can access these values using the String source(), String data() and String destination() methods provided by the Message class.Message makeMessage(Vector<String> destinations, String data) Creates a new Message with multiple destinations. You can access the Vector of destinations using the Vector<String> toList() method of the Message class.boolean waitForNextRound() Makes the current node wait until the beginning of the following
synchronous round. This must be called once per iteration of your main loop. waitForNextRound() returns true if your algorithm can keep running or false if it should stop (e.g. network is trying to shutdown this node, an error occurred, etc.).void send(Message mssg) Sends the specified message to the destination specified in the
message. Note that a node can only send one message down each link per round.Message receive() Waits for messages from the neighbours. If no messages arrive in the current
round, null is returned. If several messages are sent to the node in a round, then
multiple invocations to the receive method will be needed to read them all.boolean isRoot() Returns true if this node is the root node (as set the configuration file with RootNode). If the network mode does not allow a root node, this method will throw a SimulatorException.Object run() You must implement this method (see examples). This method should return your solution (the result of your algorithm) or null. The solution must be a String, primitive type (int, double, etc.) or null.void printMessage(String message) Prints the string message in the console.void showMessage(String message) Displays the string message above the node in the GUI.void showMessage(String message, int location) Displays the string message above or below the node in the GUI. location must be one of Algorithm.LOCATION_ABOVE or Algorithm.LOCATION_BELOW. You may display a message both above and below a node at the same time.int numChildren() Returns the number of children this node has in the tree.Vector<String> getChildren() Returns a java Vector containing the id's of this node's children in the tree.String getParent() Returns this node's parent in the tree or null if the node does not have a parent.String successor() Returns the ID of the node marked as a successor of the current node.Vector<Integer> getKeys() Returns a java Vector containing all of the keys in the P2P system.Vector<Integer> keysToFind() Returns a java Vector containing all of the keys this node should find. An empty Vector will be returned if no keys are set for this node using the Find command.int numKeys()Returns the number of keys in the P2P system.int numKeysToFind()Returns the number of keys the current node must find.boolean hasKey(int key)Checks if the given key (key) is present in the P2P system. Returns true if the key was set with the DataKeys command and false otherwise.boolean tryingToFindKey(int key)Checks if the given key (key) needs to be found by the current node. Returns true if the key was set for this node using the Find command and false otherwise.boolean equal(String s, String t) Returns true if strings s and t are the same; returns
false otherwise.boolean larger(String s, String t) Returns true if s is larger than t; returns false
otherwise. If s and t contain only characters '0' to '9', then these strings are
first converted to integer numbers and then compared. Otherwise a lexicographic comparison
is made to determine which string is larger.
int compare(String s, String t) Interprets s and t as integers and returns 1 if s is larger than t, 0 if s equals t and -1 if s is less than t.int randomInt(int max) Returns a random integer between 0 (inclusive) and n (exclusive).double randomDouble(double max) Returns a random double between 0 (inclusive) and n (exclusive).int stringToInteger(String str) Returns an integer based on the value of the given string str. For example, stringToInteger("10") returns the integer value 10.String integerToString(int number) Converts the integer, number, into a string value. For example, integerToString(10) returns the string value "10".boolean contains(String str, String word) Returns true if the string str contains the substring word, otherwise returns false.String pack(Object value1, Object value2, ...., Object valueN) Packs 1 or more values into a String delimited by commas. String values should not contain a comma (as it is used as the delimiter). Most value types are supported (int, long, double, float, string, boolean, etc.). Can be useful for sending multiple values in one message. Values can also be passed as an array of Objects.String pack(Vector values) Same as the normal pack method but takes a Vector of values to pack rather than an array or list of arguments.String[] unpack(String message) Returns a String array containing one element for each value packed into the message using the pack method. Array elements will be in the order they were packed into the string. All values will be of type String and may need to be converted before use.Vector unpackVect(String message) Same as unpack but the result is a Vector rather than a String array.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. |
network1 but uses RandRing and GUILayout to make the ring.network1c but uses RandRing and a ring of size 7.CleanFailureRate r Before every round, a node has a r% chance of failing. The node will fail cleanly, sending all messages before failing. 0 ≤ r ≤ 100MaxCleanFailures m The maximum number of clean failures that can happen in one simulation. m ≥ 0StoppingFailureRate r Every time a node sends a message, it has a r% chance of failing. The node may or may not send all messages before failing. 0 ≤ r ≤ 100MaxStoppingFailures m The maximum number of stopping failures that can happen in one simulation. m ≥ 0CleanFailureRate 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.RandRing s Creates a random ring network of size s. Nodes are given IDs from 1 to s in random order. This command can not be used with AddNode.OrdRing s Creates an ordered ring network of size s. Nodes are given IDs from 1 to s in order. This command can not be used with AddNode.RandLine s Creates a random line network of size s. Nodes are given IDs from 1 to s in random order. This command can not be used with AddNode.OrdLine s Creates an ordered line network of size s. Nodes are given IDs from 1 to s in order. This command can not be used with AddNode.RandStar s Creates a random star network of size s. Nodes are given IDs from 1 to s in random order. This command can not be used with AddNode.OrdStar s Creates an ordered star network of size s. Nodes are given IDs from 1 to s in order. This command can not be used with AddNode.RandComplete s Creates a random network of size s in which all nodes are connected to each other. Nodes are given IDs from 1 to s in random order. This command can not be used with AddNode.OrdComplete s Creates an ordered network of size sin which all nodes are connected to each other. Nodes are given IDs from 1 to s in order. This command can not be used with AddNode.RandMesh w h Creates an mesh network of width w and height h (of size w * h). Nodes are given IDs from 1 to s in random order. This command can not be used with AddNode. Note that the GUI may not layout nodes optimally for a mesh network (some manual rearrangement is required). OrdMesh w h Creates an mesh network of width w and height h (of size w * h). Nodes are given IDs from 1 to s in order. This command can not be used with AddNode. Note that the GUI may not layout nodes optimally for a mesh network (some manual rearrangement is required). PlaceNode n: x y Sets the location of the node n in the GUI where x and y are the coordinates. Only affects how nodes are displayed and not the simulation. Can not be used with GUILayout.GUILayout name Changes the layout mode from the default of organic to one of organic, ring, line, or fast. Can not be used with the PlaceNode command. The organic layout uses the simulated annealing technique by Davidson and Harel (1996) to attempt to layout the graph automatically (this layout method may cause a long start up time when a large number of processors are used). The ring layout positions the processors in a circle. The line layout will position processors in a line that wraps down to the next line when it reaches the end of the screen. The fast layout is a faster version of the organic layout (as implemented by JGraphX) that works for a larger number of nodes but results in a layout of reduced quality.
MultiMessage x Allows or disallows the sending on multiple messages the same direction on the same link per round. If x is ON, any number of messages can be sent in any direction each round. If x is OFF, only one message can be sent in each direction per round. The default setting as of version 2.2.1 is ON, in pervious versions the default was OFF and immutable.Successor, DataKeys, and Find. Adds Algorithm methods successor(), getKeys(), keysToFind, etc.
MultiMessage Off configuration command to change back to the old rules (not necessary for assignment 4).-V and --version command line options to print the simulator version number and exit.pack helper method can now take a Vector of values in addition to an array or list of arguments.tree and bfs modes.send() before entering a round (i.e. before calling waitForNextRound()) or after starting the receive phase (i.e. after calling receive()) will result in an exception.PlaceNode command for network configuration file. Allows you to place a node at a set location in the GUI.pack and unpack helper methods for packing and unpacking multiple values into a string (can be used to make sending multiple values in one message easier).contains helper method for checking if a string contains another string (wrapper method for String.contains).RandMesh and OrdMesh putting nodes in wrong order (not in left, up, right, down order given in assignment and examples).0 node placeholder to mark the ends of a line network or the borders of a mesh network. These placeholder nodes do not show up in the GUI and can not be sent a message, but are included in the vector returned by the neighbours() method. They are also not included in the count returned by numNeighbours().RandLine and OrdLine updated to add 0 node placeholders as the rightmost and leftmost nodes in the line.RandMesh and OrdMesh configuration file commands to automatically create mesh networks.stringToInteger and integerToString.