Installation of SPARK and SPARK-PL

A SPARK distribution contains the SPARK library for developing agent based models
in Java, SPARK-PL, and a runtime environment with a user interface for running simulations.
SPARK-PL is a special programming language
which greatly facilitates the model developing process.

First of all, you need to obtain a distribution of SPARK.
It can be downloaded from the official SPARK site at
http://www.pitt.edu/~cirm/spark
in the Download section. There you need to select the latest version of
a SPARK-PL distribution for your operation system. Also
you can download a universal distribution which works
on any platform. This universal distribution does not support
advanced graphical features of SPARK which are not essential
for model developing.

The installation process of SPARK/SPARK-PL is very simple.
Extract the distribution archive into any folder on your computer
and everything is done. To start SPARK, open
'SPARK Manager.jar' in Explorer, Finder, or another
file manager.

SPARK GUI

Before creating your own model, it is a good idea
to look at sample models. After running 'SPARK Manager.jar',
click 'Open project...' in the 'File' menu. Go to the 'samples'
folder, select any folder there, and open an xml file inside
the selected folder. Now click the 'Start' button and the SPARK
user interface will appear with the selected model (here a screenshot
of Worms model is shown).

Figure 1. SPARK GUI

The SPARK user interface consists of several windows. The main window with
simulation control elements is always shown. Other windows are
parameters, charts, additional views, model methods, and model data.
Some types of windows (charts, additional views) can be created directly
from the user interface. Other windows (parameters, methods, data) only appear if the
corresponding model has special elements.

You can move and resize windows. Closing any window except the main window will hide
the corresponding window. It can later be shown again by selecting its name in the
Window menu. Closing the main window will stop the simulation and exit the user
interface. Positions, sizes, and visibility of all windows are saved automatically when
the interface is closed. Next time the same model is run, all windows will be restored
to their saved positions.

Main Window

Figure 2. Main Window

The main window contains the following elements: the main menu bar, the simulation control panel,
a graphical view control panel, a graphical view panel.

Simulation Control Panel

Figure 3. Simulation Control Panel

The left most label shows the number of simulation ticks. In SPARK, simulation time
is measured in simulation steps, ticks. Next is 'Start' button which starts a simulation.
When this button is clicked, then it will become 'Pause' button which
can pause an active simulation process.
The button 'Setup' stops a simulation and reinitializes a loaded model.
Also it resets all information gathered during the previous
simulation process. The center slider controls the simulation
speed. This slider specifies the amount of skipped frames and simulation delays.
The right most slider also controls the simulation speed in terms of
simulation frequency. The precise meaning of the simulation speed and these sliders is
given below.

In SPARK, simulation and visualization processes are parallel. When the simulation speed is at the Normal position,
then the simulation process runs as fast as possible meanwhile visualization process tries
to visualize as much as it can. If the simulation process is faster than visualization, then
some frames will be skipped automatically. If the simulation speed is set to faster values
(on the left from the Normal position), then several frames will be always skipped (the label Fast
corresponds to 100 skipped frames). Slower values of the simulation speed affect the simulation process
by inserting a short delay after each simulation step. The length of this delay is constant.

The frequency slider (the right most one) can be only used to slow down the simulation process.
The purpose of this control is to fix the simulation frequency rate. The labels on the slider
correspond to desired frequency rates. 0 means that the frequency rate is not fixed. The frequency
rate is not guaranteed for slow simulations.

Main Menu

File

Open. Opens a SPARK model directly form the SPARK user interface.
Warning: if you want to open a SPARK model directly from the user interface,
then do not confuse a SPARK project description file and a SPARK model descriptioin
file which both have the xml extension. Usually, a SPARK project description file
is located in the root folder of a SPARK project, meanwhile a SPARK model description
file is located in project's output folder (which is usually called 'output').

Close. Closes a loaded model. Not really useful.

Exit. Closes the SPARK user interface. All interface information is
automatically saved for the currently open model.

Below the 'Exit' item, names of recently open models are shown. Choosing one of them
will close the loaded model and open the selected one.

Preferences. Opens the SPARK preferences dialog.

Figure 4. Preferences Dialog

In the first tab, the visualization engine can be selected.
Note that JOGL can be selected only if you are using a version
of SPARK specific for your operation system (not a universal version).

In the second tab, the number of remembered recently open models can be specified.

The third tab specifies a directory where bitmap fonts can be found.
This is used in JOGL rendering mode and is a subject of another tutorial.

Model

Model properties. Opens the model properties dialog.

Figure 5. Model Properties Dialog

The check box and the next number field set the random generator seed
for the next simulation. If the check box is not selected, then
the seed in the number field is used for initializing the random number
generator for the next simulation. Different simulation processes with
the same simulation seed will give the same outcome.

Last two parameters (Observer name and Execution mode) are experimental. It is not
recommended to change them from the default values.

Window

New View. Creates a new view window.

New Chart... Opens a chart creation dialog.

Tile Windows. Tiles windows on the screen in a non-overlapping way.
Only visible windows are rearranged.

Windows... Opens a dialog where a selected window can be killed (removed).
This dialog could be useful if there is a window without content in the interface.
Such windows could appear as a result of some model modification, especially
when a global variable used for a chart is renamed or removed. Note: it is possible to kill
even Parameters and other system windows. These windows will be recreated next time
the model is loaded.

A list of interface windows. Unchecked windows are invisible.

Data Layer Parameters

Figure 6. Data layer parameters

The dialog for changing data layer parameters can be opened from the main menu:
Model -> Data Layer Properties. This dialog is used for setting visualization properties
of data layers. It is possible to change two values and colors
associated with these values. The first value corresponds to
the minimum value of a data layer and the second value corresponds
to the maximum value of a data layer. These values can be arbitrary:
they do not affect the behavior of data layers and only used for their visualization.
If you want to get exact current minimum and maximum values for a data layer,
then click 'Normalize' button.

The button 'Colors' opens a new dialog for adding more colors for visualization of a data layer.

Figure 7. Data layers parameters

The button 'Add' creates a new element for a color. Each element has two properties:
a value (in percents) and a color. The button 'Remove' removes the corresponding element.

Batch Run Dialog

If it is required to run a model several times and save the
results after each run, then the batch run feature of SPARK is useful
Go to 'Model' menu and click 'Batch run' to open the batch run dialog.

Figure 8. Batch Run Dialog

The first line in the batch run dialog is the number of steps (ticks)
in each run. The second line is the number of repetitions of each run.
The third line specifies the prefix of output file names. The fourth line
specifies how often data is sampled. The default value is 1, so data for
all ticks is saved by default.

The next flags control what kind of output is saved. If the 'Save data' flag is on,
then the simulation data is saved in comma separated (csv) files. The 'Save final snapshots'
flag indicates whether the final snapshot for all views will be saved or not.
If the 'Save snapshot' flag is activated, then snapshots will be saved for all views
at time points controlled by the 'Snapshot interval' parameter.

All batch run data is saved in the project output folder. Each batch run will create
a unique folder inside the output folder with the name corresponding to the
time when the batch run process has been started. The output data file names have the
following structure: [prefix][number of run]-[number of repetition].csv. One run
corresponds to a model run with some fixed values of parameters. Different runs
correspond to different values of parameters. Each output data file contains all
values of parameters for the corresponding run and collected data.

All snapshots are saved as png files. The names of these png files have the following
structure: [number of run]-[number of repetition]-[view name]-[tick number].png.

The middle section of the batch run dialog is used for setting parameters
during batch runs. If a parameter is checked, then its value will be
changed from 'Start' to 'End' with the given 'Step'. If several parameters
are checked, then all possible values for all checked parameters are tried.
If a parameter is not selected, then its current value is used during
a batch run process.

Note: due to round off errors, it is preferrable to make the 'End' value a
little higher than a required value. For example, if you want to change
some parameter from 1 to 2 with step 0.1, then it is better to set the end value
2.01.

The last section of the batch run dialog can be used to set up automatic data
analysis process. Data analysis feature is not fully implemented in SPARK yet, so
all parameters in this section must be ignored now.

New Chart Dialog

Charts can be created in the New Chart dialog (Window -> New Chart).

Figure 9. New Chart Dialog

The left column contains all available variables. Selecting variables in this column and then
pressing 'Select' will add selected variables to the right column. Variables in the right
column can be selected and then removed by pressing 'Remove'. The button 'Reset' removes
all variables from the right column. The button 'Create' creates a new chart window for
all variables in the right column. If 'Pie chart' check box is selected, then a pie chart
window is created. Otherwise a standard line plot is created. The upper part of the dialog
contains a text box for entering simple mathematical expressions involving model variables.
Any expression entered in this text box can be added to the right column and then
it will be plotted in a chart window.

The last variables in the left column have special name 'count$[agent name]'. These variables
are generated automatically for any SPARK model and they represent the number of
corresponding agents in the model.

Parameters window

Figure 10. Parameters window

It contains all parameters of the running model.
Parameters are model variables that can be changed
during a simulation process. You can change them before
starting a simulation or when a simulation runs in real time.
Some parameters are represented by sliders (numerical parameters).
Other parameters are represented by check boxes (boolean parameters).

Each numerical parameter is characterized by 3 options: its minimal and maximal values,
and its step size. There are two ways to set these options. One way is to do
it inside the model code using attributes (see the corresponding tutorial).
Another way is to edit parameter options inside the user interface. The 'Edit'
button opens a dialog for changing parameter options. Three options for
each parameter can be edited. To activate changes, it is required to select
the check box at the 'Overwrite default' column. Default options are options
defined in the model code.

The upper section of the Parameters window contains controls for saving and
loading values of parameters. The button 'New' creates a new named set of parameter values.
When a new set is created, it can be selected in the combo box. To save the current
values of parameters it is required to select any valid set of values (not 'none')
and click the 'Save' button. If the 'Auto save' check box is activated, then
the current values of parameters will be saved in the selected set
when the SPARK user interface is closed (or when the model is closed).

Chart windows

There could be several chart windows in the user interface.

Figure 11. A chart

Each chart window shows a plot of one or several model variables.
If you click the 'Clear' button, then
the plot area will be cleared. If you click the 'Save'
button, then you can select a file in which to save
the numerical data of the plot. The 'Remove' button destroys the
chart window.

View windows

There is always one view located inside the main window. Additional
view windows can be created from Window -> New view.

Figure 12. A view window

The upper part of each view window contains several control elements.
The first three controls specify how a view window reacts on user input.

If the 'select' mode is chosen, then left clicks inside the view will open
an inspector dialog for viewing internal variables of agents which are at
the position of the mouse cursor. The inspector dialog contains two columns:
the left column lists all agents at the position of the mouse cursor, the right column
shows variables and their values for a selected agent. In the 'select' mode it is also
possible to zoom in/out the view with mouse wheel or with '+' and '-' buttons.
Arrow keys can be used for moving the content of the view left/right and up/down.
'Enter' resets the original zoom and position of the view. Note: to make keyboard input
active for a view, it is required to left click inside it first. The right mouse button
opens a context menu when clicked inside the view (in the 'select' mode). This context
menu duplicates the functions of other view control elements.

The 'move' mode allows to move the content of a view with a mouse. To move the context
with a mouse, it is required to press and hold the left button inside the view and move a mouse.
Also the same keyboard control as in the 'select' mode is available. If the view works
in a 3d mode, then the right button can be used to rotate the view.

In the 'control' mode all user input inside a view window is processed by a running
model itself. This mode allows to run models which support an interactive control.

The button 'reset' sets the default zoom and position of the view content (the same
effect as 'Enter' key in 'select' and 'move' modes). 'snapshot' saves a snapshot of the view.
'rename' opens a dialog for renaming the view (note: even the main window can be renamed).
'props' opens a view properties dialog. 'remove' kills the corresponding view window (note:
the main window cannot be removed).

Each view can be customized. Press 'props' and the visualization properties dialog
will appear.

Figure 13. Visualization Properties dialog

The main visualization properties of agents are visibility, a border flag,
transparency, a label flag. The visibility controls whether agents of the selected
class are rendered or not. Rendered agents could be with or without border (a border flag).
Rendered agents can be transparent. The label flag specifies if the label is printed
for the selected class of agents. The order in which agents are arranged in the table
is important. The top most agents appear on the top during the visualization process.
The buttons to the right from the visualization properties table can be used to
change the order of agents in the table. Select a line in the table and then click
'Up' or 'Down' to move the selected agent up or down. 'Advanced' opens a dialog for
setting advanced visualization properties of a selected class of agents. These advanced
properties are not described in this tutorial.

In the 'Spaces' section, it is possible to select which space is visualized in the corresponding
view. SPARK models support multiple spaces and each view can visualize only one selected
space. The 'Rotate' flag can be used to rotate the visualization by 90 degrees.
If the 'Auto size' flag is turned off, then it is possible to specify how many pixels correspond
to a unit of the selected space in x and y directions. If 'Auto size' is active, then
these numbers are automatically computed such that the space completely fills up
the corresponding view.

Visualization properties of data layers can be set in the 'Data Layers' section.
It is possible to set which data layers should be visualized in the corresponding view.
No data layers can be selected ((none) option), one particular data layer can be selected
(option with the name of the corresponding data layer), several data layers can be selected
((special) option). If the (special) option is selected, then multiple data layers are rendered
inside the view window. Colors of all rendered data layers are mixed together. It is possible
to control the weight coefficients for mixing data layer colors. Only data layers with
positive weight coefficients are rendered in this mode. It is also possible to visualize
data layers as height maps. In order to do so, it is required to enter a positive number
for the corresponding height weight. This will work only when JOGL visualization is turned on.

Data Window

It is possible to save the data collected during a simulation. Just
click the 'Save' button in the Data window.

Figure 14. Data window

A standard dialog will appear where you can specify a name of a
data file. All data will be saved as a plain text CSV file which can be
easily opened by any text editor or Microsoft Excel. Note that the saved data
will also contain the current values of all parameters.

Note: only the variables which appear in the Data window can be used
for collecting data during a batch run process. These data variables can
be only created inside the model code by adding a special attribute to
global variables (see the tutotial on attributes in SPARK-PL).

Methods Window

Figure 15. Methods window

Some model functions can be manually called from the user interface.
All available functions are listed inside the Methods window.
These special external functions are created inside the model code by
setting a special attribute for functions (see the tutorial on attributes
in SPARK-PL).