Spatial Awareness

This tutorial will provide a beginner’s introduction to running Repast Simphony simulation models through its graphical user interface (GUI). It will cover only the most basic functionality needed to run a published Repast model, explore its behavior, and share observations with an audience.

To learn how to use the Repast GUI for your own models, I would alternatively recommend the official Repast Java Getting Started Guide available on their documentation page.

The GUI is used for manually executing individual simulation runs. This stands in contrast to executing multiple, automated simulation runs through other means. The benefit to using the GUI is that one can visually observe what the simulation is doing in real-time through various graphical displays. Time can also be slowed down or paused to focus on specific moments in time, and parameters can be easily adjusted for individual runs.

For this tutorial I use the Schelling model featured in the tutorial about Repast installers. You can download it here. I describe things as if you are running this same model. However, it would be easy enough to follow along using a different model or even none at all.

A Repast model’s GUI is launched from the directory to which it was installed (using a Repast installer). You can run an installed model by clicking on the “start_model.bat” or “start_model.command” file depending on whether you are running Windows or Unix, respectively.

A screen should pop up appearing as above. This is the Repast GUI. It can be subdivided into three main parts: toolbar, control panel, and display panel. The toolbar provides buttons for controlling the simulation’s basic temporal behavior (start, pause, etc.). The control panel lets you adjust everything else about the model. The display panel shows a visual representation of the simulation as well as any charts.

You can adjust this layout by clicking and dragging the various tabs presented on the control and display panel, but this isn’t currently necessary nor recommended.

Toolbar

First, note that each icon on the toolbar has a tooltip to help you understand its function. The three leftmost buttons on the toolbar relate to saving the changes you’ve made to a model using the GUI. The only one important to immediately learn is “save.” After making any changes through this interface, such as adding a chart or parameter, click save, and the next time you open this Repast model those changes will be preserved. Repast will prompt you to save if you try to exit, but it is still recommended to save any significant changes in case the program crashes, power is lost, etc. Know that nothing taught through this tutorial really requires saving, but its still good to know going forward.

The purpose of this software is to execute a series of simulation “runs”. A run is a single execution of a model using a given random seed and set of parameter values.

The next five buttons control the flow of time with respect to said runs. The first of these buttons is initialize run. This, naturally, reads a provided random seed and set of parameters. It then builds the foundation of the simulation (creating the environment, populating it with objects/agents, etc.) without moving forward in time. Click on initialize run now. After a short period you will see many red, blue, and green dots forming a square shape in the display panel to the right. These three colors are intended to represent household ethnicities in an urban setting.

The next two buttons, start run and step run, both progress time. Start run lets the simulation progress as quickly as it is able to execute, while step run advances only a single time step. The start run button becomes a pause button once it is clicked. Click on start run now. You will see the colored dots organize into relatively homogeneous blobs.

Pause run allows the simulation to be temporarily frozen in time until it is started again. Hitting the stop run button, on the other hand, ends the simulation run irreversibly. Stop run also exports any prior scheduled video or tabular output. The reset run button clears all knowledge (in RAM) of the presently loaded run, such as any displays or charts, resets parameters to their default values, and provides a new random seed to be used in the next run. Try pausing, stopping, and then resetting the model.

The next button to the right is configure and launch batch runs. This creates a new window that allows one to schedule a queued series of simulation runs having varying parameter values. This is a more advanced topic and will be covered in future tutorials. Next to it are nine buttons that provide likewise advanced functionality, and they will each be covered on an individual basis, if at all, in future tutorials.

Control Panel

The control panel provides a variety of options for controlling and understanding a Repast simulation model. There are four tabs that can be selected from the bottom of the control panel: run options, parameters, scenario tree, and user panel.

Run options provides means to further control the flow of time in conjunction with the relevant buttons on the toolbar. Pause at and stop at are self explanatory. Schedule tick delay slows down the simulation’s execution so that it can be better observed. Click start run on the toolbar. Doing this before clicking initialize run will do the initialization step automatically. Try slowing down the simulation’s operation by scheduling a tick delay of 100. Now, the dots will move much more slowly. Speed them back up by getting rid of the tick delay. Click stop run and then reset run to clear this run.

The parameters tab allows users to manually set values for the model’s parameters. Doing multiple model runs using different parameter combinations and analyzing potential differences in each run’s behavior is one of the main appeals of simulation modeling. In an accurately realistic simulation model, changing parameter values allows one to ask “what would happen if we implement this design, policy, strategy, etc.?” and predict the result. With more abstract simulation models, it can be useful to observe the general relationship between a parameter and the model’s behavior.

The Schelling model, which is decidedly on the abstract end of the spectrum, includes parameters that govern the initial setup of the simulation as well as the behavior of its agents. For example, the parameter percent like neighbors determines what degree of local homogeneity an agent requires in order to remain stationary. It is by default set at .5. Change this to .1, and click start run. You will notice that the landscape of agents is much patchier than before. There are still areas of relative homogeneity, but they are much smaller. Click stop and refresh to clear this run. You will see percent like neighbors return to its default value of .5.

Now, change world width to 100 and click start run. The simulated plane for this run is twice as wide as a result. There is more empty space this run because, while there is twice as much total space, the initial number of agents parameter has remained the same. Click stop run and reset run to clear this run.

It is important to realize that Repast does not provide a built-in way to determine whether an entered parameter value is a valid entry. For example, if you initialize a run where world height is set to zero, the simulation will have an error and fail to start. If you initialize a run where percent like neighbors is set to 999, the run will initialize but not progress past time-step 0. These are easy enough to catch. An even worse situation would be where a model successfully runs despite an invalid parameter value, generating seemingly legitimate results that are in fact bogus. For this reason, it is important to read a Repast model’s documentation and any relevant publications in order to understand the effects of different parameter values.

The scenario tree tab allows you to configure how to visually render the simulation as well as produce output data. There should always be an entry under data loaders and probably at least one entry under charts or displays. The Schelling model contains 2 such displays: a two dimensional one and a three dimensional one.

Charts, if not included by the model’s author, can be added manually. This will be covered in a future tutorial in more depth. They are used to generalize quantitative characteristics of a model. Charts can be of the histogram or time-series variety, and will update themselves as the simulation proceeds. Displays show the model’s components, e.g. agents or their environment, within a two or three dimensional space.

Display Panel

You’ve had some interaction with the display panel already through running the Schelling Model, but there are a few more features that should be introduced. Click initialize run but do not progress time further.

The display panel features tabs similarly to the control panel. For this specific model, there are two such tabs: Schelling Model: 2D Display and Schelling Model: 3D Display. By default, the 2D display is presented. To interact with a 2D display, the mousewheel can be used to zoom in and out, and the right mouse button can be used to pan the display.

Click on the other tab to switch to the 3D display. This features the same controls as the 2D display, with the addition that clicking and holding the left mouse button rotates the display. Click on the other tab to return to the 2D display.

One doesn’t have to program a model in order to leverage simulation in their current project. Analyzing and/or interpreting published models in a different manner than originally presented can be a productive endeavor. Existing models can also be compared to new sets of data that were not available at the time of their formulation. Finally, simulation models can help communicate something that would be otherwise difficult for a target audience to understand.

For all of these uses and more, presenting visual media becomes essential towards leveraging simulation models. On the display panel, there are two buttons that help you do this: export to an image and export to a movie. They are both in the top left corner of the display panel.

Export to an image‘s icon shows a small camera. When you click it, a dialog will appear asking where you want to save the image and under what name. You can choose from 4 different file formats to export. The exported image will represent whatever occupies the display tab. There is no way to change the resolution of the exported image. It will be the same size and resolution as it appears on your screen, as if you had taken a screen shot and cropped it to the extent of the display tab. So, if you want a high resolution image, be sure to increase the size of the display panel by maximizing the Repast window and decreasing the size of the control panel.

Export to a movie’s icon shows a small camcorder. When you click it, a dialog will appear, requiring you to provide both a file name and frame capture rate. The resolution of the output file is determined in the same manner as before, so make sure the display panel is sufficiently sized.

A lower frame capture rate (entering, in the bottom-left, a larger value of ticks between captures) will create a video where things move much more quickly, shortening the length of the exported video and possibly missing certain details of the model’s behavior.

A higher frame capture rate (entering, in the bottom-left, a smaller value of ticks between captures) will create a slower moving movie with a longer duration. Lowering this value past 1 (the default value) will not change the exported movie; it will record as if you had entered 1. If you still desire a slower moving product, scheduling a tick delay in the run options tab of the control panel can achieve this. Alternatively, video editing software such as Openshot can be used to add a slow motion effect, among other things.

The default frame capture rate affects the model’s execution time in addition to the speed of the exported video. For a simulation that ordinarily executes very quickly, such as the Schelling model, a frame capture rate value at the default value of 1 will significantly slow down the model’s execution, and could render your computer unresponsive. If this becomes a serious issue, setting a lower frame capture rate (more ticks between captures) will solve the issue.

That wraps up this introduction. You now have the knowledge required to interactively execute Repast Simphony simulation models and migrate your observations into whatever report, slideshow, website, etc. you happen to be working on.