Spatial Awareness

This tutorial will walk you through both building and using “installers” for simulation models made using the Repast Simphony agent-based modeling platform. Installers are the primary way that developers of Repast models can distribute their work so that others can run, analyze, and evaluate their simulations. The software installed by these installers can be executed either directly to interact with the simulation via Repast’s GUI interface or indirectly, for example through an R script.

The only prerequisite for executing these installers is to have a Java Runtime Environment (JRE) installed. The version needs to be at least that used to compile the simulation. It is my perception that, at least among my peers, a user is far from guaranteed to have JRE on their computer. However, it is much easier to install JRE and  a Repast installer than the alternative of installing Repast Simphony for this sole purpose.

Installing a Repast Model

If don’t have a model to work with, you can download the Schelling model included as part of Repast’s example models here.

Now, you have this .jar file that was either retrieved from the internet or built yourself. In many cases, you can simply double click this file to start the installer. If this does not work, you will have to run “java -jar /directory/setup.jar” in unix or “java -jar [drive]:\\directory\setup.jar” in Windows. Use the installer’s interface to install the model wherever you want.

The newly created model directory contains everything besides Java needed to run the simulation. It can be started by double clicking one of the two “start_model” files. The one with a “.command” extension is for Unix users, and the “.bat” one is for Windows. A window should appear looking like this:

That’s it! To introduce yourself to using the basic features of Repast’s GUI to run simulations, see that tutorial.

Creating an Installer for your Model

This section covers how to build an installer for a model using Repast Simphony.

In Eclipse, open the drop down menu next to the green “run” button, and select “build installer for [model name]”. In this example I build the same installer for the Schelling model that was used in the prior example . Next, you select the directory to put the installer in, and it will create here the file “setup.jar”, overwriting such a file if it already exists.

Eclipse will print a bunch of log text, ending with “BUILD SUCCESSFUL” if everything worked correctly. It is recommended that you rename this file to something more descriptive, such as “SchellingInstall.jar”, for example.

This is all you need to create an installer. However, there are further customization options that are important to know. Repast let’s you change the version number, model description, and license description that are displayed during the installation process. All of these changes are made to the eclipse project directory and will require the installer to be rebuilt.

The version number is displayed during the second screen of the installation process. You can change this by editing the file “installation_coordinator.xml” located in the installer folder of a Repast project folder. It can be done with any text editor. Near the top of this file is a field “appversion”. The following number is the version number. Change this to the relevant version.

The third and fourth screens in the installer contain the model description and license, respectively. They are both changed by editing the relevant text files located in your model’s Eclipse project directory titled “model_description.txt” and “license.txt”. You do not have to find any special fields like before; simply change the text to whatever you want the relevant installer screen to display.