This section will get you up and running with SpeckSim, and introduce the main features.
SpeckSim can be started with the command
java -Djava.library.path=<natives> -jar SpeckSim.jar
where <natives> is the path to the directory that contains the native libraries for OpenGL access.
A screen should appear, looking something like this:
The visualisation canvas on the left displays the field in which the specks will do their thing. For future reference, it's a unit cube. The origin is displayed on the right purely because OpenGL uses a right-handed coordinate system.
The pane below the visualisation is the log terminal, we'll see how to direct logging messages there later on.
The large area on the right is the Configuration panel. All of the options for setting up the simulation and controlling the GUI will appear here.
The variables in the simulation are altered by the options available through the configuration pane. Right-click on the pane to reveal the most basic level of options available. Select the top option - SpeckSim
This displays the root of the Configuration tree for the simulator. We want to add some specks to the simulation, so click on Speck Populations
This frame allows us to specify the type and number of the specks in the simulation. Select Neighbourly Speck from the drop-down list and raise their population to 100. Note that when we add the Neighbourly Speck type, we gain access to the configuration options for that type.
The Neighbourly Speck has a very simple behaviour: it simply periodically broadcasts its own ID number, and keeps a list of those ID numbers that it has recently received, thus keeping track of its one-hop neighbourhood.
The movement model defines how specks move around in the simulation. For now, we'll stick to the simplest example available - the StaticMovementModel. This will simply distribute the specks at random around the field.
Click on the Movement Models button in the SpeckSim frame and set the simulation to use the Static model, like so:
The options for configuring the movement model are accessed through the button below the selection box.
Also, note how the configuration options are arranged in a tree structure. For brevity, I'll be referring to various configuration frames using pathnames, such as /SpeckSim/Movement Models/Static. You can either navigate manually through the tree by clicking on the buttons in the configuration frames, or directly by the sub-menus of the popup-menu we used earlier.
As of yet, there's nothing showing up in the visualisation canvas. This can be remedied by enabling some StateRenderers. Go to the /Interface/Visualisation frame and add the Speck and Neighbourhood renderers to the active renderers list. The visualisation system should look like this:
you can move the viewpoint around using the mouse and keyboard while the mouse pointer is over the visualisation frame:
Pretty pictures are all well and good, but you'll probably want to have more detailed information on how the specks are doing. To this end, use the "Statistics" button in /Interface to open the Statistics frame, and enable some statistics by opening those leaves of the tree.
The execution controls are located on the bottom right of the window.
Let 'er rip!
The data that that the simulator produces which is used in statistic calculation and visualisation is serialised and stored in a buffer. This allows convenient examination of past simulator behaviour.
To try this out, change the movement model to the Waypoint model, and set the motion speed in the model to 0.02. Run the simulator for 30 seconds to fill the state buffer.
When the simulation is not running, the gui can examine previous simulator states using the State Buffer component in the bottom-left of the interface. It operates similarly to a slider - clicking to the left of the toggle will examine the previous state, to the right will examine the next state. The toggle can also be dragged at will.
The current configuration of the simulator can be saved and loaded to and from xml files through the options in the popup menu, as can the current set of opened windows.
If you specify the option "-gui confFile.xml" on the command line when starting SpeckSim, that file will be loaded automatically. Similarly, saving the set of opened windows under the name "default" will mean that this set will be restored at startup.
SpeckSim can also be used to generate a file suitable for input to GNUplot or similar programs. Open the data generation panel from /Interface options.
Click on the "Variable name" panels to choose the variables that you want to plot on each axis, along with start and stop values.
The "Repetitions" variable will perform repeated runs of the same simulation and compute the average and standard deviation of the result for the final datafile. Clearly, simple repetitions of a predictably-repeatable experiment will not be helpful. To remedy this, you should enable the "Advance Seeds" option. When enabled, the SpeckSim will search through the configurator tree and increment any integer variables named "RNG seed offset" between each repetition, thus giving different results every run.
The "Time" variable simply controls how many seconds will pass in the simulator before a reading is taken from the statistic gatherers.
Once a run is started, the details cannot be changed. In addition, an interrupted run cannot be resumed, and all data generated thus far is lost.
The "Save run config" button will save the current configuration of the simulator, and of the data generation run, to a file. These files can then be used in SpeckSim's headless mode with the command line arguments "-dg <comma separated list of run files>". Each run file will then be processed in turn.