A quick description of the SPARK installation process and SPARK user interface.
Table of Contents
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 don't need to get anything else except Java runtime of version 1.5 or higher. You can test whether you have Java or not by visiting the Web page http://java.com/en/download/help/testvm.xml
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.
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).
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.
The main window contains the following elements: the main menu bar, the simulation control panel, a graphical view control panel, a graphical view 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.
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 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 properties. Opens the model properties dialog.
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.
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.
The button 'Colors' opens a new dialog for adding more colors for visualization of a data layer.
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 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.
Charts can be created in the New Chart dialog (Window -> New Chart).
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.
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).
There could be several chart windows in the user interface.
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.
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.
It is possible to save the data collected during a simulation. Just click the 'Save' button in the Data window.
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).