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.