SPARK-PL: Installation and User Interface (1.2)

Alexey Solovyev

Abstract: A quick description of the SPARK installation process and SPARK user interface.

Table of Contents
Installation of SPARK and SPARK-PL
SPARK GUI
Main Window
Simulation Control Panel
Main Menu
Data Layer Parameters
Batch Run Dialog
New Chart Dialog
Parameters Window
Chart Windows
View Windows
Data Window
Methods Window

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.

You do not need to get anything else except Java JDK 8.

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).

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

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

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.

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.

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.

Data layer properties. Opens the dialog for setting visualization properties of data layers.

Batch run. Opens the dialog for starting a batch run process.

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

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.

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.

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).

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

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.

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.

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.

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.

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

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).