Pamela Toman

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.

Sometimes, although the model installs successfully from the standalone installer setup.jar file, the displays refuse to behave correctly. We observed the following odd behaviors in standalone runtime models on some Windows machines:

• Charts (data visualizations) and Displays (geography objects) did not initially render upon model initialization (“initialize” or “play” seemed to work, but nothing was displayed in the main panel).
• Charts were only displayed when the model was paused and then restarted.
• When paused and restarted, the model would display two charts — one chart completely blank, and the other showing the expected data.  Every single chart would be doubled.
• No matter what, the GIS display would not render.

To a large extent, this behavior seemed to be determined by whether the machine running the standalone model also already had the Repast development environment installed.  If the machine had the development environment installed, the displays almost always showed up properly; if the machine had only a Java JRE and not Repast, the displays were missing or repeated (and the GIS map wouldn’t appear at all).

We asked at the Repast-interest listserv in case someone knew of a solution (or if not, to alert the developers of a potentially new bug).  Nick Collier suggested on the basis of the missing GIS map display that the problem may be that Repast requires the Java Advanced Imaging libraries to be installed. He linked the Sun website’s 1.1.2 release, but the installer didn’t play well with the first test machine.  Instructions for installing Java Advanced Imaging libraries from elsewhere on the internet resulted in total success, however!  And that was that, problem solved.

Two Repast lessons here:

1. Make sure to test standalone installations on machines without the Repast development environment installed.
2. If you have odd display issues using Repast, make sure that Java Advanced Imaging (JAI) is installed, with .jars to jre/lib/ext and .dlls to jre/bin.

NOTE: The model would produce the error below, but only after the model was paused and then restarted (without pausing and restarting, no charts were created that could even generate an error):

2010/08/16 11:19:55,510: Error while creating displays
java.lang.IllegalArgumentException: Duplicate AttributeTypes DefaultAttributeType [name=__sele_cted__ , type=class java.lang.Boolean , nillable=true, min=1, max=1]
at org.geotools.feature.FeatureTypeBuilder.check(FeatureTypeBuilder.java:600)
at org.geotools.feature.FeatureTypeBuilder.addType(FeatureTypeBuilder.java:347)
at org.geotools.feature.FeatureTypeBuilder.addTypes(FeatureTypeBuilder.java:327)
at repast.simphony.space.gis.FeatureAgentFactory.getFeatureType(FeatureAgentFactory.java:169)
...

(This problem and its solution are also documented in the Repast-interest thread; they are repeated here for more recorded detail in the hope that more Googleable buzzwords might bring you to a solution faster….)

The skeleton version called batch_params.xml in the batch folder of the Repast project folder is not a good example of what the final format should look like. Similarly, the batch parameters tutorial, while very good and offering plenty of line-by-line examples, does not give a complete example of what a batch_params.xml file should look like, either.

In writing my batch_params.xml file, the file available here helped:

C:\Program Files\RepastSimphony-1.2.0\eclipse\plugins\repast.simphony.batch_1.2.0\models\test_batch_params2.xml

So you don’t have to go searching for it yourself, the content is:

<?xml version="1.0" ?>
<sweep runs="2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="batch_params.xsd">
    <parameter name="double_const" type="constant" constant_type="number" value="4.0" />
    <parameter name="long_const" type="constant" constant_type="number" value="11L" />
    <parameter name="string_const" type="constant" constant_type="string" value="hello cormac" />
    <parameter name="boolean_const" type="constant" constant_type="boolean" value="false" />
    <parameter name="long_param" type="number" start="1L" end="3" step="1">
       <parameter name="float_param" type="number" start=".8f" end="1.0f" step=".1f">
          <parameter name="string_param" type="list" value_type="String" values="foo bar">
              <parameter name="randomSeed" type="list" value_type="int" values="1 2" />
          </parameter>
       </parameter>
    </parameter>
</sweep>

Christof Zellweger, a postgraduate student at the University of Melbourne, also notes that the batch parameters XSD describing the schema of the batch_params.xml is in the plugins folder of the core Repast module. The schema file is likely to be located here: /path/to/repast/installation/eclipse/plugins/repast.simphony.batch_/models/batch_params.xsd.

—
Updated 2012.07.28.