	Sinalgo - Simulator for Network Algorithms

Running Sinalgo

We have already seen that the toy release of Sinalgo only needs a double click to start. This section describes the more advanced possibilities to launch and configure Sinalgo.

To launch Sinalgo from within your IDE, execute the Run class, which is located in the folder sinalgo. Remember that your IDE needs to have the class paths set as described in the installation tutorial.
For Eclipse Users: In the Navigator or Package Explorer of Eclipse, open the folder src/sinalgo/. Right-click on Run.java and select Run As -> Java Application. (There are several alternatives to launch an application in Eclipse, please consult the documentation of Eclipse for more details.)
To launch the framework from the command line, change to the root directory of the Sinalgo installation and execute the following command
java -cp binaries/bin sinalgo.Run

Increase the VM Memory

With increasing size of the networks you simulate, Sinalgo requires more memory. By default, Java provides only around 128MB. In order to increase the amount of memory Java is allowed to use, modify the configuration file of your project and set the entry javaVMmaxMem to an appropriate value (in MB).

Note: Do not use the -Xmx flag for the virtual machine. This flag only affects the Run application, which starts the simulation in a separate process.

The Run Command

The Run command used to launch Sinalgo is a helper process to start the simulation process. I.e. when starting Sinalgo through java -cp binaries/bin Sinalgo.Run, the initial java process launches a second process, in which the simulation takes place. This allows the first process to read the configuration file of the selected project, set the maximum memory that may be used by the simulation process, and start the simulation process using the additional commands specified in the config file.

Depending on your OS and installed applications, you may have several tools at hand that may facilitate simulations with Sinalgo. Below is a brief list of how you may edit the javaCmd field in the config file:

java The default. Just start the simulation process.

nice -n XX java Start Sinalgo with modified priority XX.

time java Display the total running time of the simulation (after the simulation stopped).

Suggestions on how to modify javaCmd in the config file.

Command Line Configuration of Sinalgo

Calling Sinalgo without any arguments opens the project selection dialog. This dialog shows the available projects you may choose from, and gives you the possibility to alter the configuration of the projects. Refer to the Configuration section of the tutorial to learn more about how to configure your project.

By passing on arguments on the command line (or through your IDE), you can influence the execution of Sinalgo. The following list describes the recognized command line arguments.

-help	Prints the recognized command line arguments.
-gui	Starts the framework in GUI mode (default)
-batch	Starts the framework in batch mode, i.e. no windows. This mode is best suited to run long-lasting well-defined simulations.
-project XX	Indicates that Sinalgo should be started for project XX. If this argument is missing, the project selector dialog will be displayed.
-rounds XX	The framework performs XX simulation rounds immediately after startup. Defaults to zero.
-refreshRate XX	Sets that the GUI should be updated only every XX round. Defaults to 1.
-gen ...	This argument lets you automatically generate network nodes. It has the following form: -gen #n T D {(params)} {CIMR {(params)}}* The command generates #n nodes of node-type T and distributes them according to the distribution model D. (Optionally, the distribution model may take parameters in parentheses.) Optionally, you may specify in arbitrary order the connectivity, interference, mobility, and reliability models by appending the corresponding model name() to the -gen command. If a model is not specified, the default model (as specified in the project's configuration file) is used. (Again, any of the model names may be followed by model-specific arguments enclosed in parentheses.) () Model and Node Naming Convention: The name of models is composed of the project name in which the model is located and the name of the model itself: projectName:modelName. The same holds for the name of the node. Exception: Models and nodes stored in the defaultProject of the framework need not be prefixed with "defaultProject:". For disambiguation, the models may be prefixed with X=, where X={C\|I\|M\|R}. The mapping is as following: C - Connectivity Model I - Interference Model M - Mobility Model R - Reliability Model
-overwrite key=value (key=value)*	Overwrites the configuration entry named key to have the new value value. key may specify a framework configuration entry, or a custom configuration entry specified in the project's configuration file.

Command line parameters that may be used to configure a simulation.

Example 1

The following arguments open project sample1, and generate 1000 nodes of type S1Node from project sample1. The nodes are distributed according to the Random distribution model. After generating the nodes, the framework performs 10 rounds, but only draws the GUI every second round.

-project sample1 -gen 1000 sample1:S1Node Random -rounds 10 -refreshRate 2

Example 2

The following arguments open project sample2, and generate 10000 nodes of type S2Node from project sample2. The nodes are distributed according to the Random distribution model. Furthermore, the connectivity model is set to QUDG (which is in the default project), and the mobility model is set to LakeAvoid from project sample2.

-project sample2 -gen 10000 sample2:S2Node Random C=QUDG M=sample2:LakeAvoid

Note that in this case, the disambiguation is not necessary, and the following arguments result in the same behavior.

-project sample2 -gen 10000 sample2:S2Node Random QUDG sample2:LakeAvoid

Example 3

In order to enable mobility, disable interference, and set rMax of the GeometricNodeCollection to 50 you would add the following -overwrite argument:

-overwrite mobility=true interference=false GeometricNodeCollection/rMax=50

Example 4

You may place several -gen arguments to generate distinct sets of nodes:

-project sample1 -gen 100 sample1:S1Node Random UDG -gen 50 DummyNode Circle QUDG -gen 10 sample2:S2Node Random

Thus, it is possible to use nodes and models from several projects. But note that the configuration is loaded from the selected project.

True batch mode without windows

Running Sinalgo without any windows in true batch mode may require that you start the application with the flag

-Djava.awt.headless=true

If you launch Sinalgo via the Run class, you may need to specify this flag twice: once for calling Run, and once in the project configuration through the javaCmd property.
Thanks to Denis Rochat for pointing out this issue.

Running Sinalgo from Scripts

Instead of typing the basic java command for every run, you may make use of a script (batch) file that encapsulates the call to java with the necessary parameters described above. Two such scripts are included in the root directory of the regular release: sinalgo.bat for the Microsoft Windows cmd shell, and sinalgo for bash shells. Instead of typing

java -cp binaries/bin sinalgo.Run -project sample1

only write:

sinalgo -project sample1

Automating Sinalgo

A simulation often consists of several runs of Sinalgo, each time with slightly different parameters. The variation of the parameters is achieved easiest by using the -overwrite command line parameter, as described above. To call Sinalgo automatically several times with the distinct command line parameters, we propose to use a scripting language, the example below uses perl.

#!/usr/bin/perl

$numRounds = 100; # number of rounds to perform per simulation

for($numNodes=200; $numNodes<=500; $numNodes+=100) {

system("java -cp binaries/bin sinalgo.Run " .

"-project sample1 " .             # choose the project
"-gen $numNodes sample1:S1Node Random RandomDirection " . # generate nodes
"-overwrite " .                   # Overwrite configuration file parameters
"exitAfter=true exitAfter/Rounds=$numRounds " . # number of rounds to perform & stop
"exitOnTerminationInGUI=true " .  # Close GUI when hasTerminated() returns true
"AutoStart=true " .               # Automatically start communication protocol
"outputToConsole=false " .        # Create a framework log-file for each run
"extendedControl=false " .        # Don't show the extended control in the GUI
"-rounds $numRounds " .           # Number of rounds to start simulation
"-refreshRate 20");               # Don't draw GUI often

}

A sample perl script that demonstrates how Sinalgo may be called several times in sequence with modified command line arguments. In this example, project sample1 is started with 200, 300, 400, and 500 nodes, respectively.

The flags -project, -gen, -rounds, and -refreshRate are presented above. The remaining parameters overwrite the default entries in the project specific configuration file. Alternatively, we could add the flag -batch to run the simulation in batch mode. For huge simulations with many nodes, this may be preferable. But if memory is not a limiting factor, the GUI may provide a good interface to supervise the simulation. Setting the refresh rate to a fairly high value, the GUI does not use a significant amount of simulation time. Note that pressing the stop button, and then continuing a simulation is perfectly OK and does not change the simulation result.

Note: Project sample1 contains a more sophisticated run-script to demonstrate the possibilities of perl.

Remember: Depending on your platform, you may need to adjust the class path separator. In the example above, we used the semicolon. But for instance on Linux, the separator is a colon, and yet other separators may be used on other platforms.

Hint: Set the logToTimeDirectory such that log-files are not overwritten by a subsequent simulation. To collect simulation data from the different simulations, designate a log-file to which each simulation appends to. See Logging for more information.

Installing perl: You may obtain a copy of perl from www.perl.org. Alternatively, install Cygwin and include the perl package.

Debugging

The Run class launches Sinalgo in a separate process. This has immediate consequences for running a debugger, as the simulation itself does not run in launched application. In order to use the debugger of your IDE to analyze the implemented algorithms, you probably need to do one of the steps below.

a) Start Sinalgo directly using the following slightly modified command line.

java -Xmx800m -cp binaries/bin sinalgo.runtime.Main

This launches the simulation process directly, but does not allow to specify the maximum memory to be used through the config file. The -Xmx800m flag indicates that the JVM may use at most 800 MB of memory, adjust the value to your needs.

b) Use remote debugging: Some java debuggers can be attached to a remote process (even running on a different machine). Remote debugging requires two steps.

b.1) First, modify the run command for the simulation process s.t. it can communicate with the debugger. I.e. set the javaCmd entry of the config file to

java -agentlib:jdwp=transport=dt_socket,address=localhost:8000,suspend=n,server=y

This configures the JVM to receive connections. You are free to choose any (unused) port number in the address-flag.

b.2) After starting the simulation, launch the debugger and attach it to the application. In Eclipse, call Run -> Debug... and create a new configuration for a Remote Java Application. Select the Connection Type to be Standard (Socket Attach), and the Connection Properties to match the address specified in the javaCmd.

Hot Code Replace

The exchange of class files at runtime is called 'hot code replace' and can be performed by most IDEs, e.g. Eclipse. For that purpose, your IDE transfers the new class files over the debugging channel to the JVM running Sinalgo. Therefore, hot code replace requires Sinalgo to run in debugging mode.

Note: Hot code replace is only possible if the signature of the replaced class files remains the same. I.e. you may change the body of a method, but not the signature of the method. It is neither possible to add/remove methods or global variables.

GUI Description

This section summarizes the methods and helper-functions provided through the GUI of Sinalgo.

Menus

The Graph menu provides the following tasks:

Generate Nodes AddNodes Opens a dialog that adds new nodes to the simulation. You can specify the number of nodes to add, their initial distribution, as well as the node specific models.

Clear Graph ClearGraph Removes all nodes from the simulation.

Reevaluate Connections Loops over all nodes and determines for each node the set of neighbor nodes, according to the node's connectivity model. This function is especially useful in the asynchronous simulation mode, where the connections are not updated automatically.

Infos Prints some information about the current network graph, including the number of nodes and the number of (unidirectional) edges.

Export Creates a vector graphic image of the current view of the network graph and writes it to an EPS or PDF file.
To output the graphic in PDF format, your machine needs to provide a tool that can convert from EPS to PDF. By default, the framework calls the epstopdf application. Change the field epsToPdfCommand in the framework section of the configuration file to specify a different application.

Preferences Some preferences you are allowed to change at runtime. This includes the type of the edges and the message transmission model, which is the same for all nodes.

Methods provided in the Graph menu

The Global menu contains all global custom methods and the Settings dialog, which displays a list of all settings.

GUI Interaction

Perform a simulation step / execute the next event	Press the button. In synchronous simulation mode, this executes the number of rounds specified in the Rounds to Perform text field. In asynchronous simulation mode, this executes the number of events specified in the Events to Perform text field.
Abort a running simulation	Press the button. After pressing the button, the simulation will finish the currently executing round/event before it stops. Thus, this button is only useful if you set the Rounds to Perform or Events to Perform field to a value above 1. The framework finishes the current round/event to ensure integrity of the system, and that the simulation can be continued by pressing .
Add an edge from node A to node B.	Left-click on node A. Keep the mouse pressed, move it to node B and release it.
Move a node in in 2D	Right-click on the node and drag it to the new place. Alternatively, right-click on the node to obtain the popup menu for the node and select the 'Info' dialog to key in the new coordinates. The latter approach is also supported in 3D.
Zoom in / Zoom out	Position the mouse in the area containing the network and use the wheel to change the zoom factor. Alternatively, use the zoom-in / zoom-out buttons . This operation may also be performed in the 'View' panel of the extended control panel.
Zoom to Fit	Press the button to set the zoom factor such that the simulation area just fits on the screen. In 3D mode, press the button to reset the default view of the cube.
Translate the displayed simulation area	Press the right mouse-button on a free spot of the simulation area. Keep the mouse button pressed and move the mouse to translate the simulation area. This operation may also be performed in the 'View' panel of the extended control panel, with the difference that the network graph is only updated once the mouse button is released. This may be handy for huge networks graphs with a long drawing time.
Rotate the 3D cube	Press the left mouse-button on a free spot of the simulation area. Keep the mouse button pressed and move the mouse to rotate the simulation area. By default, the rotation keeps the Z-axis vertical. To turn off this feature, press the Ctrl button while pressing the left mouse-button. This operation may also be performed in the 'View' panel of the extended control panel, with the difference that the network graph is only updated once the mouse button is released. This may be handy for huge networks graphs with a long drawing time.

The view panel in the extended control shows the entire cube even though the main view of the network graph only shows a cut-out. The red rectangle indicates the portion of the simulation area currently displayed. The zoom, translate and rotate operations may also be performed in this area. 'View' panel of the GUI in 3D mode

Sinalgo - Simulator for Network Algorithms