Repast demo and tutorial

I have gotten to the point in the current version of my model where sending a both run of simulations of to IRIDIS the southampton uni supercomputer is becoming more and ore necessary. I'm struggling to get a run of 20 years in my simulation at the moment to check for stability of population and territories etc and its taking ages.
One run, depending on the number of agents and amount of reproduction (hence new agents), can take anywhere from half an hour to about 2 hours. I'm also having problems with memory where the simulation breakdown at that start of a new run due to being out of memory. Am currently trying to fix this problem.

Anyway, on my way to discovering if its possible to export a repast batch and pass it to IRIDIS I have come across a nice Repast demo that I wish had been around two years ago when I was starting to think about potential agent based simulation software and 18 months ago when i was struggling with my first attempts with repast.

Demo is based on a population of 'bugs' that move around and eat food from the landscape. Coincidentally amazingly relevant to my own model. I might try the demo and see if I can steal any ideas for better coding/construction of the model/GUI.

Demo can be found here: http://code.google.com/p/repast-demos/wiki/StupidModel
and an output of the GUI:

batch update

Ok, so i did say i was going to post the relevant files that enabled my model to run in batch mode.
I've just come back to this after a few months and have had to re-learn how to do batch runs, so... heres the relevant information:

Batch mode depends mainly on 2 files
1. batch_params.xml - located within the batch folder
2. parameters.xml - located within the JaguarMovementValidation.rs folder

The parameters file must include those parameters that have been set as requiring user input in the ContextCreator file
Batch_params.xml must then include reference to any parameters that are included within the parameters.xml file

Batch mode does not seem to work properly if you try to by-pass these parameters. For instance, I just want to do multiple runs with the same parameters and tried to by-pass the numberOfJaguars parameter by keeping it the same and removing the end and step variables. Batch mode then reports an error and won't run.

For a simple test of running a single simulation, but increasing the jaguar numbers from 50 to 300 in steps of 50, the batch_params.xml file looks like this:


<?xml version="1.0"?>
<sweep runs="10">
<parameter name = "NumberOfJaguars" type="number" start="50" end="300" step="50">
</parameter>
</sweep>

when viewed from the Repast GUI it looks like this:

The parameters.xml file, when viewed within the Repast GUI looks like this:

What I now want is to simply run my simulation 30 times using the same parameters.. I do this by removing the parameters from the ContextCreator file and removing all links to this parameter from both the parameters.xml file and the batch.xml file.

This works, but I'm now having the problem that the output is being generated once per tick for the first 50 ticks only, whereas I want the output once at the final tick count of 5000 (or 2000, depending on my criteria).... shall update once I have this issue resolved.

Other people using ABMS for spatially explicit ecological modelling

I recently went to a talk by Lael Parrot who was visiting Southampton University for the week. Not a name I had heard of before but I'm quite surprised at this now considering she is involved in very similar work to me!

The most relevant paper I found from her was the one she talked about at the seminar she gave:

Anwar, S.M., Jeanneret, C.A., Parrot, L. & Marceau, D.J. (2007) Conceptualization and implementation of a multi agent model to simulate whale-wathcing tours in the St. Lawrence Estuary in Quebec, Canada. Environmental Modelling and Software 22 1775-1787.

Not only was this paper spatially explicit and employed agent-based modelling, but it was done using the Repast Simphony toolkit!! Finally, an ecological example of someone doing a peer-reviewed and published piece of research using Repast.

I've not yet management to dive into the paper in depth but some of the simulations Lael showed during her talk have me very impressed - linking the repast output with GIS data and creating some pretty good looking 3D models of the system. They also re-integrated the model output with the original GIS data to do some spatial analysis and statistics, so I wonder whether this might also be my best option... definitely something to look into in more detail.

Its a much bigger model than mine will be so I have no doubt that I'll be able to pick up some interesting tips from Lael and the paper. I'll report back with any useful bits of information.

Repast Batch runs

Ok, so I have successfully got my model to work in batch mode ! :)

Am VERY happy!

The key things seems to be that you can only access parameters from the batch_params.xml file that have been explicitly set up within the model to be controlled by the user (i.e. included within the parameters.xml file in the 'projectName'.rs folder of the project.

Also, if there are any parameters set up in this way that are not included in the batch_params.xml file, the model will not run in batch mode. This only seems to apply to parameters included in the contextCreator file, not those set up within other classes of the model.

Some information seems to be misleading.... in the previous batch post I alluded to a webpage that might be useful from the repast.sourceforge website. This information relates to running a model in batch mode but goes through a quite complicated scenario of installing GridGain and using this to run the model.
This is NOT required to run a simple batch run within eclipse on the local computer. It appears to be most useful for distributing the model to other sources, and using grid computing to run batches...

I doubt I'll need anything quite this complicated as of yet....

Today is a good repast day!

Repast Development and Batch Runs

So its back to the grindstone following a not-long-enough christmas and new year break. This month its all about finalising my model and getting it to a state where I can send off a batch run of the model to Southampton University's super computer. Not only will this mean I get my model to work much more efficiently but that I also won't have to sit around for ages watching the GUI display and waiting... and waiting.... and waiting... whilst tediously repeating... repeating... and repeating runs whilst manually changing parameters.
Excellent.

Only problem is, Repast, once again, seems to be letting me down on documentation! This has to be THE major disadvantage of using this software over others such as MASON (whom several people have suggested I use, but I'm loathe to, considering the time and effort I've spent in learning Repast and the fact that MASON seems to be heavily social simulation focused).

However, there are some other kind people out there who, also noticing the severe lack of Repast documentation, have been amazingly generous by recording and allowing public access to their findings. Pamela Toman, I am very grateful to you for this post about doing batch runs in Repast. Some other useful pages exist including one of Repast Simphony's own online pages found here that outlines the format of how to amend the batch_params.xml file, even if it doesn't go into detail about how to get this to work, or what the file should look like once its been constructed.

Basically, its all a bit more complicated that it needs to be. Repast has an option of a Batch run from the run menu in Eclipse. This requires you to show it where it can find the batch parameters run file (batch_params.xml located in the batch folder within the model architecture in eclipse). I've yet to get to the point of trying this out but it seems that if you just want to run a batch run within eclipse, this MAY be all you need to do.

Exporting the model to run in batch via an external source (i.e. a super-computer) seems much more complicated and there are several files that need amending in order for this to work. So far, I've done the amending, but not been able to test if the export works. Thats next on my list of jobs to do.

Pamela Tomans post outlines all of this, but in brief:

1. The main amendments involved the start_model.bat or start_model.command files (.bat in Windows, .command in Mac/Linux). The model needs to know explicitly where to look for all necessary files, which need to be manually added (running in GUI doesn't require this step). The repast.simphony.repast.RepastMain command also needs to be changed to repast.simphony.batch.BatchMain so it knows to run in batch mode (see Pamela Tomans post for more details on how to amend this file).

2. Actually, what you need to do is create a new start_model.command/bat file. You can call it whatever you want, but if you want the model to be able to run in both GUI and batch, you can't amend the original start_model.command file. If you do, it will no longer run in GUI mode.

3. Now you have added a new file for batch, you need to add this to two other files, so the model knows to look at this file. Here you need the find the installation_coordinator.xml and installation_components.xml files (both within the installer folder of the model architecture in eclipse). Again, more info on Pamela Tomans post.
I have a slight issue with this step however. My installation_coordinator.xml file has a slightly different format to that suggested by Pamela (and others when I googled online). Im still trying to work out where to add the necessary information..... The install_components.xml file was straightforward to amend.

4. Ok, now you should be ready to update the batch_params.xml file. Again, Pamela has a good example on her page. Im currently working through this to get ready to test with a simple one-parameter change and only 5 runs. I'll update once I know more and post my final .xml file.

5. Now comes the tricky bit as far as I can tell. If the batch is to run within repast then you should just be able to choose the batch model run and show it the batch_params.xml file. Again I should be testing this soon.... if the batch is to export and go to a super-computer, then the batch file itself needs to be amended. Not sure where to find this or how to run the batch file outside of repast. Should have some answers here within the month. Fingers crossed.

Useful webpages
Pamela Toman - http://www.pamelatoman.net/blog/tag/batch-runs/
Repast Simphony batch runs - http://repast.sourceforge.net/docs/reference/SIM/Batch%20Runs.html
Repast Simphony batch parameters - http://repast.sourceforge.net/docs/reference/SIM/Batch%20Parameters.html
Repast Parameter Sweeps Getting Started - http://repast.sourceforge.net/docs/RepastParameterSweepsGettingStarted.pdf

Some useful technical information

If the eclipse.ini file needs editing, (to increase memory or 'Java heap space') this can be found easily by going through the eclipse directory in Windows. In Mac OSX, go to eclipse.app, right-click, open package contents, contents, Mac OS, then open the eclipse.ini file in text edit.

JDK and JRE are needed for model development. The Java Runtime Environment is needed to run the java applications, the Java Development Kit is needed to develop java applications.

Subversion needs to use the SVNKit rather than the JavaHL in eclipse. This is true for Windows and Mac OS.
Subversion also brings problems when trying to save the scenario in repast. The projectName.rs folder and the styles sub folders both need to be un-checked as read-only. I've found this problem with both Windows and MacOS. In Windows, a secondary projectName.rs.bak folder is created if saving the scenario encounters this problem. In this case the subfolders and files need to be moved back into the projectName.rs folder and the projectName.rs.bak folder deleted. This doesn't seem to occur in Mac OS.

JOGL and Java3D jar files can be downloaded and installed directly from the repast homepage; http://repast.sourceforge.net/download-extras.html, again this is true for Windows and Mac OS.
Java3D files allow applications with 3D displays to run.
JOGL is Java OpenGL which is a wrapper that allows OpenGL to be used, necessary for repast models to run successfully.

Python plugin for eclipse - need to also download ActiveTcl (currently version 8.5.10 as of Sept 11) to allow use of TKinter.

GeoTools seems to be a set of java open source code library classes which provide standard compliant methods for manipulation of geospatial data. Should allow use of raster files, without converting to .pgm files. Currently testing this as of Sept 11.
There is a website dedicated to the open source files - http://geotools.org/
My current version of eclipse seems to have access to these class files without the need to download anything extra. The geoTools website seems to indicate you need to download and install the GeoTools code into both eclipse and netBeans. Will update when I know more.

Demo models for repast

After struggling to remember how to get access to the repast demo models, which are EXTREMELY helpful when trying to figure out how repast works, they can be downloaded from http://repast.sourceforge.net/models.zip

After extracting the files, get the models into Eclipse easily by:

1. Select File -> Import Repast Examples from the Eclipse main menu

2. Check Select root directory: /home/rlr/Repast/Repast-Models/models (not: Select archive file)

3. Check the boxes for the example projects you would like to import select all copy projects into workspace

4. Click Finish

Now they all appear in the packages panel

On a Mac eveything should work fine, if working on Windows there may now be problems running some of the example models due to JOGL and Java3D errors.

Meghan Hutchins provides an excellent outline of how to fix these errors, please see the link on the left to her blog, or else click here for the specfici pages related to demo models and how to fix errors that may occur. (User guide to Eclipse/Repast)
http://meghanhutchins.com/pmwiki.php/Main/InstallJava3DLibraries