RepastCity - A demo virtual city

Author: Nick Malleson

Background
I've written a small Repast Simphony program which demonstrates how to create a virtual city and move some agents around a road network. I'm using this type of model for my PhD (an agent-based model of crime/burglar) and hopefully this program will be useful for anyone who needs to be able to move agents around a city.

If you're new to Repast Simphony you should do some tutorials first otherwise the code won't mean anything to you. You could try my tutorial or do some of the ones on the Repast website. Repast Simphony has quite a steep learning curve but is well worth learning if you need to build agent-based models, it's an excellent tool.

There is some background information about how the program works on my research blog. I'm also writing a working paper which should explain it better but haven't finished that yet.

Referencing and Editing
The code is released under the GNU General Public Licence so you're welcome to use the code however you would like to but please put a reference to me ( Nick Malleson) or to this page somewhere. When I finish my working paper you could use that instead.

If you improve or extend the code please let me know and I'll update it on this site. This is my first attempt at building a virtual city and so there will be lots of places where it can be improved (particularly with regards to efficiency, I think the routing algorithm is very slow).

The Program
The program is available as a single compressed file which contains the entire Eclipse project: Repast City Project. Download this file and extract it to a temporary directory.

To run the program you need to download Repast Simphony version 1.1 (it comes bundled with the Eclipse development environment) and then follow these instructions:

Start Repast (Eclipse)
Go to File -> Import
Then under 'General' select 'Existing Projects Into Workspace'.
Next to 'Select root directory' click on browse and select the extracted project.
Then click on 'Finish'. If you left the 'copy projects into workspace' box ticked you can now delete the zip file and the extracted directory because all the code will be copied into your Eclipse workspace.
Finally click on the 'Run' button (green) at the top of Eclipse and select 'Run RepastCity Model'. (If there is not option to run the model try closing the project and then re-opening it).
The only other thing you need to do is create a display so you can see the agents and the city (if you're not sure how to create displays do a tutorial first). Here's briefly how to create one:

When you have started the model scroll down in the scenario tree box until you can see the 'PersonContext' entry. Under that there should be a 'Displays' menu and a 'Person Display' under that.
Delete the person display and create a new one.
When you get to change how the SimplePerson agents are displayed click on the '+' button. Now you can add the shapefiles which represent the city (houses.shp and roads.shp, they are stored in the eclipse_workspace/RepastCity/repast_city_data/shape directory).
Finally, when I add agents or shapefiles to a display I always edit their style (maybe just change their colour slightly) because otherwise Simphony sometimes throws an exception.
That's it! There is a picture below which shows what the program should look like. I''ve also made a video of the simulation running.

I hope the code is useful. If you have any questions my email address is on my School of Geography webpage or even better try the Repast mailing list .



Changes (updated versions of the program)
These updated versions are not necessarily easier to understand so they might not be appropriate for people who just want to get an idea about how to build this sort of program themselves. Have a look at the comments to see if it's better for you to download one of these versions rather than the original.

RepastCity1.1.
I have made the routing algorithm more efficient by caching certain things like the closest road coordinate to each house. It runs much faster and has fixed an occasional bug where agents get stuck on one of the houses but the code is probably harder to understand.