Pamela Toman

As discussed in Exporting standalone batch runs, Stefan König and Axel Pürkhauer developed a .command file for Repast that will run in “batch mode” on non-development Mac and *nix machines. That file appears below. (I’ve also posted a sample .bat file and a sample .sh file, both contributed by others. You may get some benefit from looking at those as well.)

start_model.command, modified by Stefan König and Axel Pürkhauer in 2010 to use BatchMain

#!/bin/bash
# Repast Simphony Model Starter
# By Michael J. North and Jonathan Ozik
# 11/12/2007
# Edited by Stefan König for use with batch files
# Note the Repast Simphony Directories.

PWD="${0%/*}"
cd $PWD

REPAST_VERSION=1.2.0
REPAST_BASE=$PWD/repast.simphony
REPAST_SIMPHONY_ROOT=$REPAST_BASE/repast.simphony.runtime_$REPAST_VERSION
REPAST_SIMPHONY_LIB=$REPAST_SIMPHONY_ROOT/lib

# Define the Core Repast Simphony Directories and JARs
CP=$CP:$REPAST_BASE/repast.simphony.batch_$REPAST_VERSION/bin
CP=$CP:$REPAST_BASE/repast.simphony.runtime_$REPAST_VERSION/lib/*
CP=$CP:$REPAST_BASE/repast.simphony.core_$REPAST_VERSION/lib/*
CP=$CP:$REPAST_BASE/repast.simphony.core_$REPAST_VERSION/bin
CP=$CP:$REPAST_SIMPHONY_ROOT/bin
CP=$CP:$REPAST_SIMPHONY_ROOT/bin-groovy
CP=$CP:$REPAST_BASE/repast.simphony.score.runtime_$REPAST_VERSION/lib/*
CP=$CP:$REPAST_BASE/repast.simphony.score.runtime_$REPAST_VERSION/bin
CP=$CP:$REPAST_BASE/repast.simphony.dataLoader_$REPAST_VERSION/bin
CP=$CP:$REPAST_BASE/repast.simphony.data_$REPAST_VERSION/bin
CP=$CP:$REPAST_BASE/repast.simphony.score_$REPAST_VERSION/bin
CP=$CP:$PWD/yourModelDirectory/bin #### NOTE: yourModelDirectory
CP=$CP:$REPAST_SIMPHONY_LIB/saf.core.runtime.jar
CP=$CP:$REPAST_SIMPHONY_LIB/commons-logging-1.0.4.jar
CP=$CP:$REPAST_SIMPHONY_LIB/groovy-all-1.5.7.jar
CP=$CP:$REPAST_SIMPHONY_LIB/javassist-3.7.0.GA.jar
CP=$CP:$REPAST_SIMPHONY_LIB/jpf.jar
CP=$CP:$REPAST_SIMPHONY_LIB/jpf-boot.jar
CP=$CP:$REPAST_SIMPHONY_LIB/log4j-1.2.13.jar
CP=$CP:$REPAST_SIMPHONY_LIB/xpp3_min-1.1.4c.jar
CP=$CP:$REPAST_SIMPHONY_LIB/xstream-1.3.jar
CP=$CP:$REPAST_BASE/repast.simphony.data_$REPAST_VERSION/lib/*

# Change to the Default Repast Simphony Directory
cd yourModelDirectory #### NOTE: yourModelDirectory

# Start the Model
/path/to/bin/java -Xss10M -Xmx400M -cp $CP repast.simphony.batch.BatchMain -params $PWD/batch/params.xml yourModel .rs

As discussed in Exporting standalone batch runs, I developed a .bat file for Repast that will run in “batch mode” on non-development Windows machines. That file appears below. (I’ve also posted a sample .sh file and a sample .command file, both contributed by others. You may get some benefit from looking at those as well.)

start_model.bat, modified by Pamela Toman in 2010 to use BatchMain

@ECHO OFF
TITLE yourModelNameHere
REM Repast Simphony Batch Run Model Starter
REM By Michael J. North and Jonathan Ozik,
REM edited for batch runs by Pamela Toman,
REM on basis of .command file from Stefan König
REM
REM Please note that the paths given below use
REM a unusual Linux-like notation. This is a
REM unfortunate requirement of the Java Plugin
REM framework application loader.

REM fill out the below information so it is true for your installation
set REPAST_VERSION=1.2.0
set REPAST_SIMPHONY=../repast.simphony
set REPAST_SIMPHONY_ROOT=%REPAST_SIMPHONY%/repast.simphony.runtime_1.2.0
set REPAST_SIMPHONY_LIB=%REPAST_SIMPHONY_ROOT%/lib

REM Define the Core Repast Simphony Directories and JARs
REM You may not need the line below. I had to reset the classpath (as in the next line)
REM to avoid the character length limit on classpaths (I was getting an "input line is too
REM long" error upon running this file).
set CP=
SET CP=%CP%;%REPAST_SIMPHONY%/repast.simphony.batch_%REPAST_VERSION%/bin
SET CP=%CP%;%REPAST_SIMPHONY%/repast.simphony.runtime_%REPAST_VERSION%/lib/*
SET CP=%CP%;%REPAST_SIMPHONY%/repast.simphony.core_%REPAST_VERSION%/lib/*
SET CP=%CP%;%REPAST_SIMPHONY%/repast.simphony.core_%REPAST_VERSION%/bin
SET CP=%CP%;%REPAST_SIMPHONY_ROOT%/bin/
SET CP=%CP%;%REPAST_SIMPHONY_ROOT%/bin-groovy
SET CP=%CP%;%REPAST_SIMPHONY%/repast.simphony.score.runtime_%REPAST_VERSION%/lib/*
SET CP=%CP%;%REPAST_SIMPHONY%/repast.simphony.score.runtime_%REPAST_VERSION%/bin
SET CP=%CP%;%REPAST_SIMPHONY%/repast.simphony.dataLoader_%REPAST_VERSION%/bin
SET CP=%CP%;%REPAST_SIMPHONY%/repast.simphony.data_%REPAST_VERSION%/bin
SET CP=%CP%;%REPAST_SIMPHONY%/repast.simphony.score_%REPAST_VERSION%/bin
SET CP=%CP%;%REPAST_SIMPHONY_LIB%/saf.core.runtime.jar
SET CP=%CP%;%REPAST_SIMPHONY_LIB%/commons-logging-1.0.4.jar
SET CP=%CP%;%REPAST_SIMPHONY_LIB%/groovy-all-1.5.7.jar
SET CP=%CP%;%REPAST_SIMPHONY_LIB%/javassist-3.7.0.GA.jar
SET CP=%CP%;%REPAST_SIMPHONY_LIB%/jpf.jar
SET CP=%CP%;%REPAST_SIMPHONY_LIB%/jpf-boot.jar
SET CP=%CP%;%REPAST_SIMPHONY_LIB%/log4j-1.2.13.jar
SET CP=%CP%;%REPAST_SIMPHONY_LIB%/xpp3_min-1.1.4c.jar
SET CP=%CP%;%REPAST_SIMPHONY_LIB%/xstream-1.3.jar
SET CP=%CP%;%REPAST_SIMPHONY%/repast.simphony.data_%REPAST_VERSION%/lib/*
SET CP=%CP%;./bin
REM adding the bin to the classpath (above) is important!

REM Change to the Default Repast Simphony Directory
cd yourModelDirectory
REM directory change is needed so that local links don't break when running the
REM program -- e.g. when pulling in data from a folder

REM Start the Model. In the batch version you must include the path to
REM the batch file parameters in addition to the XXX.rs folder containing the model.score file.
java -Xss10M -Xmx400M -cp %CP% repast.simphony.batch.BatchMain -params batch/batch_params.xml yourModel.rs

REM move back up a level, to where you started
cd ..

For running your model, the Repast development environment offers three options out of the box:

• run the model once, using the GUI you’ve developed, within the development environment
• export the model, such that you can install it in a production version on other computers (on those computers, it also runs under the GUI in single-run mode)
• run the model in “batch mode” from the development environment (in batch mode, the model runs multiple iterations as defined in the batch_params.xml file, without the involvement of the GUI)

It is missing the fourth option: export the model in a version that can run in “batch mode” in a production environment.  The logical hole is palpable.

To create a standalone model that runs in batch mode, you’ll need to change the default batch (Windows) and/or command (Linux, Unix, Mac) file in your project.  You need to change the classpath of the .bat/.command/.sh so that it includes all the files that are required for batch runs.  You also need to change the invocation command from repast.simphony.runtime.RepastMain into repast.simphony.batch.BatchMain, and add the location of your batch parameters as a parameter to the command.

Stefan König and Axel Pürkhauer at the University of Bayreuth wrote a .command file with the appropriate modifications.  I used this file as the basis for a batch file, after Mr. König and I corresponded based on an email he sent to the Repast-interest listserv.  In 2012, Christof Zellweger, a postgraduate student at University of Melbourne, reached out with a further modified .sh shell script, which he kindly provided for posting here. Each script is provided in full on its own page:

• start_model.command for Mac and *nix, modified by Stefan König and Axel Pürkhauer in 2010 to use BatchMain
• start_model.bat for Windows, modified by Pamela Toman in 2010 to use BatchMain
• start_model.sh for Mac and *nix, modified by Christof Zellweger in 2012 to use BatchMain

So that’s all well and good. However, if you modify the original batch run file, you will lose the ability to run your model in a one-run-at-a-time-in-GUI-mode manner within standalone installs.   So, if you would rather create a new .batch or .command file to handle BatchMain runs vs. RepastMain runs, you will also want to alter the files used by the installer to build the standalone installer package.  Unless you alter those files, Repast will not know to include your new .batch file in the standalone installer package it builds.

If the new .batch or .command has a different name….

=> installer/installation_coordinator.xml

Add the third line below to the file at the appropriate place (around line 34):

<include name="installer/start_model.bat" />
<include name="installer/start_model.command" />
<include name="installer/yourNewBatchRunFile.fileType" />

=> installer/installation_components.xml

Add the sixth line below at the appropriate place in the file (around line 87):

<packs>
<pack name="Model" required="yes">
<description>The core model files</description>
<file src="repast.simphony.bin_and_src_$REPAST_VERSION/temp/installer/start_model.bat" 
 targetdir="$INSTALL_PATH"/>
<file src="repast.simphony.bin_and_src_$REPAST_VERSION/temp/installer/start_model.command" 
 targetdir="$INSTALL_PATH"/>
<file src="repast.simphony.bin_and_src_$REPAST_VERSION/temp/installer/yourNewBatchRunFile.fileType" 
 targetdir="$INSTALL_PATH"/>

With those two files modified, any future exports of the model will include your new .batch or .command file as well.

—
Updated 2012-07-28.

I wanted to configure the runtime environment to get rid of the extraneous tool buttons near the top, since I’m not launching those tools from within Repast (and they aren’t much use anyway).

With thanks again to Nick Collier for the suggestion, the right way to hide most of the tool buttons along the top of screen near the reset button is to rename the file plugin_jpf.xml to something else in the each of the directories that you want the tool button to disappear for:

• JUNG: repast.simphony\repast.simphony.jung_1.2.0
• MATLAB: repast.simphony\repast.simphony.matlab_1.2.0
• VisAD: repast.simphony\repast.simphony.visad_1.2.0
• Weka: repast.simphony\repast.simphony.weka_1.2.0
• R: repast.simphony\repast.simphony.R_1.2.0
• Spreadsheet: repast.simphony\repast.simphony.spreadsheet_1.2.0
• iReport: repast.simphony\repast.simphony.iReport_1.2.0

The leaves you with the “Export geography layers to a shapefile” button.  That one’s a bit harder — you have to actually edit one of the plugin_jpf.xml files.  To remove that last button, open up repast.simphony\repast.simphony.gui\_1.2.0\plugin\_jpf.xml in an editor.

Near the bottom, replace the following lines:

<parameter id="actionSpec">

<parameter id="actionID" value="repast.simphony.ui.gis.ShowExportDialog"/>
<parameter id="label" value="&amp;Export Geography Layers"/>
<parameter id="class" value="repast.simphony.ui.gis.ShowExportDialog"/>
<parameter id="icon" value="nfs_mount.png"/>
<parameter id="menuID" value="repast.simphony.ui.tools_menu"/>
<parameter id="groupID" value="runTools"/>
<parameter id="tooltip" value="Export geography layers to a shapefile"/>

</parameter>

with:

<parameter id="actionSpec">

<!-- ORIGINAL
<parameter id="actionID" value="repast.simphony.ui.gis.ShowExportDialog"/>
<parameter id="label" value="&amp;Export Geography Layers"/>
<parameter id="class" value="repast.simphony.ui.gis.ShowExportDialog"/>
<parameter id="icon" value="nfs_mount.png"/>
<parameter id="menuID" value="repast.simphony.ui.tools_menu"/>
<parameter id="groupID" value="runTools"/>
<parameter id="tooltip" value="Export geography layers to a shapefile"/>
-->
<!-- to avoid displaying the Export to Shapefile button -->
<parameter id="actionID" value=""/>
<parameter id="class" value="repast.simphony.ui.gis.ShowExportDialog"/>
<parameter id="menuID" value="repast.simphony.ui.tools_menu"/>
<parameter id="groupID" value="runTools"/>

</parameter>

If you remove the entire parent entry actionSpec, your model won’t run at all. Removing too many parameters from the inside that the actionSpec parameter makes Repast complain. If you get rid of the user-assistance items like button images and tooltips, the text set as the actionID will still form a working (ugly) button. The above approach removes the least amount you can remove to get rid of the visual cues.

During standalone model installation, one user received an error that read “This directory cannot be written!” upon attempting to install the model into C:/Program Files/modelName.  Creating the modelName directory directly in Explorer didn’t help, and neither did giving TrustedInstaller.exe (which is built into Vista) full permissions.

It seems like this may be an IzPack compatibility with Vista/Windows 7 issue (no guarantee, as I haven’t yet personally experienced or fixed this issue).   (Repast uses IzPack to create the standalone .jar for model installation.)  I haven’t been able to verify this myself yet, but am hoping the clue may be useful to others.  It may be possible to overcome this error through settings within IzPack, a solution that I am only guessing is possible on the basis of a non-Repast thread at Stack Overflow — in that thread, the user solved the problem by making the installer ask for appropriate privilege escalation.

Drawing on that thread, apparently the issue here is a change in how post-Windows XP versions of Windows do administrator privileges.  In Visa and Windows 7, you can be logged in “as an administrator”, but that doesn’t actually mean anything unless the UI/UAC confirms it (in reality on those OSs, running “as an admin” means you are actually running as a privileged user who can elevate to admin under appropriate circumstances).  As a result, during install, the installer needs to know to pop up the UAC dialogue that queries the user whether s/he is okay with elevating for this task.  The default Repast installer doesn’t allow for this.

You can also avoid this issue on Vista/Windows 7 by installing the model into a subdirectory of My Documents, should that be a possibility.