Repast Simphony Tutorial

Nick Malleson
May 7, 2008
1 Introduction
This is a short tutorial which looks at some of the major differences between Repast 3 and Repast
Simphony and goes over how to start building a simple model in Simphony. Im still learning how to
use repast myself so I make no promises that the information here is correct! I hope that my experiences
will help you overcome Simphonys steep learning curve. By the end of you should understand:
1. What Repast Simphony is / what it does.
2. How to build a simple model without using the new GUI interface,
3. How to use contexts and projections to organise agents,
4. How to make some agents move around a geographical environment.
2 So what is Repast S?
2.1 A bit of history
Repast is a free and open-source set of tools which was originally based Swarm. Initially Repast was
implemented exclusively in Java, although Repast version 3 is now fully object-oriented and consists
of three core implementations: Repast for Java (Repast J); Repast for the Microsoft .Net framework
(Repast.Net); and Repast for Python Scripting (Repast Py). However, Repast 3 has recently been
superseded by a signicant development named Repast Simphony (Repast S).
1
2.2 Repast Simphony
The main improvements that Simphony has made over Repast3 are:
Adding a new GUI for developing models (see Figure 1(a)). The ofcial Simphony tutorial
(http://repast.sourceforge.net/docs/tutorial/SIM/index.html) uses this
GUI but, as far as I can tell, it is only suitable for fairly simple models. Fortunately it is still pos-
sible to build models the good old fashioned way!
Improving the runtime GUI (see Figure 1(b)). Now you use the GUI to build displays or charts,
output data, interrogate agents, and interface with other programs (like R for stats or Weka for
data mining). This means that these tasks are done after the model has been built and compiled,
they dont feature in the underlying code at all. This seems quite unusual at rst but is actually
quite useful.
(a) The GUI for developing models (b) The runtime GUI
Figure 1:
3 Contexts and Projections
Before we get coding, its worth quickly describing the biggest change to the underbelly of Repast: the
addition of contexts and projections.
A context is basically a bucket which we can use to hold agents. Its like a soup: it holds a
population of agents but doesnt give agents any concept of space or relationships (Howe et al., 2006).
Contexts are arranged hierarchically and can contain sub-contexts. Agents who exist in a sub-context
2
also exist in the parent context, but the reverse is not necessarily true. For example, contexts which hold
People agents could be used to represent villages and subcontexts could be used to represent families.
Then agents could move between family and village contexts if they marry, move away, divorce etc.
Figure 2 illustrates this. Contexts are also useful for separating different types of agents, such as Houses
and People.
Figure 2: Contexts and sub-contexts
Once we have agents in a context, projections can give the agents a space and can dene their
relationships. For example, GIS projections gives each agent an (x, y) spatial location and Network
projections allow relationships between agents to be dened (e.g. a social network). Projections are
created for specic contexts and will automatically contain every agent within the context (so if you add
an agent to a context it is also added to any projections which have been created in that context)
1
.
4 An Example: SimTutorial
Ok, enough reading, lets start! Simphony has been integrated with Eclipse so were pretty-much forced
to use this development environment. If you like Eclipse then this is ne and if you dont you can edit
your model code using a different text editor later anyway.
Step 1: Start Eclipse
This one is fairly straightforward.
Step 2: Build a new Simphony Project
1. Go to File -> New -> Other
1
Dont worry about this too much, it will become clear later
3
2. Select Repast Simphony -> Repast Simphony Project fromthe box which appears.
3. Give the project a name (well call it SimTutorial).
4. Press next a few times and then finish, the default values should all be ok.
When Eclipse has nished creating the project you should see something a bit like this:
The model.score will be open automatically. This is an xml le (displayed nicely in Eclipse)
which describes the model components (agents, contexts, projections and attributes)
2
. The runtime GUI
reads this le so it knows what the model contains. So, if we create a newtype of agent/context/projection
we add it to the model.score le and then write the Java code for it.
3
This is what well do next.
Step 3: Creating our rst context
We could just add agents to our root context (called SimTutorial), but its better to organise different
types of agent into their own sub-contexts. Well create a sub-context to hold People agents:
1. How to create a context in model.score le:
2
If you need to re-open the model.score le it is in the simtutorial.rs folder.
3
This isnt strictly true, particularly if you use your own ContextCreator (see Section 4.2) but will do for now.
4
(a) Right-click on SimTutorial and then Create Member -> Context. This will create
a new context called SimTutorialContext. We can now congure this new context:
(b) Right-click on SimTutorialContext and go to Show Properties. The box at the bottom
of Eclipse should now show all the properties of our context.
(c) To change the name of the context to something more suitable, click on Label and type
PeopleContext. If you scroll down a bit youll notice that there is a property called File
Name for Source Code, this is where we implement the Java code for the context.
4
2. Implement the Java class for the context. Weve told Repast that we want to create a new context,
but at the moment it doesnt do anything (later we want to get the context to create some People).
Heres how to create Java code which will make the context do what we want:
(a) The box on the left of the Eclipse workspace shows all the different components of the
project. Click on the (+) to expand the SimTutorial folder and then expand the src folder
(this is where all our source code is kept).
(b) Right-click on the default package (called simtutorial) and go to New -> Class.
(c) We need the class to have the same name as the context so type PeopleContext in the
Name box.
(d) Finally, we can dene parent classes or interfaces here. As were creating a context we need
to extend DefaultContext. Click on Browse next to the Superclass box and type
DefaultContext into the box which appears. After a few seconds Eclipse should nd the
DefaultContext class (in the repast.simphony.context package). After clicking on OK you
should have something that looks like Figure 3.
(e) Click on OK and then Finish.
4
There is also a Package property, if youre arranging your code into different packages this is how to tell repast which
package the source code is in.
5
Figure 3: Creating a new class for the PeopleContext
Now we have created a new context and a Java class for it. Eclipse will have brought up an editor
for this new class. We havent made any agents yet so well ignore the implementation of the context
for now. Dont worry about the yellow line underneath DefaultContext, this is Eclipses way of telling
us there will be a compile-time warning (if you hold your mouse over the yellow line youll see what
the warning is). Ignore this for now.
Step 4: Creating the rst agent type
Weve told repast about our main context, now lets tell it what agents we want to be part of the context
(this is very similar to creating a new context).
1. Create the agent in the model.score.
(a) Click on the model.score tab (near the top of the Eclipse window) to show the model.score
le.
(b) Right click on PeopleContext and then Create member -> Agent.
(c) Change the label to Person.
2. Implement the Java classes.
6
(a) Right click on the simtutorial package and then New -> Class.
(b) Call the class Person. Then nish.
Again, Eclipse will bring up an editor window for our Person class. Now weve created a new
context and a new type of agent who will exist in the context. Lets check everythings OK by running
Simphony. To do this click on the little arrow next to the green button and then Run SimTutorial
Model (see Figure 4). This might take a while on the geography machines (much quicker on my
computer at home for some reason).
Figure 4: How to run the model
After a few seconds the Simphony GUI should pop up (on the left near the bottom you should see
our PeopleContext subcontext). This is the GUI that we can use to create charts, show displays, output
data and so on. You can save the conguration by clicking on the little disk icon so you dont need to
re-create everything each time you re-run the model (afraid I dont know how repast remembers the
conguration, but trust me it does!). If everything worked OK just close Simphony for now.
7
Step 5: Create a projection for the agents
Weve created a context and told repast that we might create some people to exist in the context, but so
far we havent said anything about the space which the agents will inhabit. Repast uses projections to
specify relationships between agents and their environment. The types of projection we can use include:
GIS Projections - agents have an (x, y) location and can move around a geographic environment.
Grid Projections - traditional, CA-type, grid.
Network Projections - specify relationships between agents, i.e. social networks.
In this tutorial well create a GIS projection. Heres how:
1. Tell the model.score about the projection.
(a) In the model.score le, right click on PeopleContext and then Create Member -> Projection
- Geography.
(b) Right click on the new projection and choose Show Properties.
(c) Change the label to PeopleGeography.
We dont do anything with our projection yet, weve just told repast that we want to use one.
Because the projection is part of our PeopleContext well write the code for the projection in this
class so that when Repast creates the PeopleContext, it will also create our PeopleGeography.
2. Implement the projection
(a) Open up PeopleContext.java (should still be open as a tab in Eclipse).
(b) Add the following default constructor to the class:
8
public PeopleContext() {
super("PeopleContext"); // must match name in model.score
GeographyParameters<Person> geoParams =
new GeographyParameters<Person>();
// These lines actually create our Geography.
// Tell Repast to create a new geography projection
// called "PeopleGeography" in this context.
Geography<Person> peopleGeography =
GeographyFactoryFinder.createGeographyFactory(null).
createGeography("PeopleGeography", this, geoParams);
System.out.println("Created PeopleGeography");
}
The PeopleContext() constructor will be called when our model is initialised, so all the code
inside it will be executed.
(c) The indentation is probably horrible, if you highlight all the code and press Control + I
Eclipse will indent everything nicely.
(d) Youll notice that lots of the code is underlined in red. This is Eclipse telling us that there
will be compile errors, this is because we need to add some import lines at the top. Eclipse
has a nice way of looking for the classes we might want to import, if you click on the tiny red
x on the left of the line with an error you should get an option to import a class le. Figure 5
illustrates this. Import all the required class les until all the errors have been corrected
(check that you are importing classes from a repast simphony package, not a class with the
same name from a different package).
Step 6: Add some agents to the context
Ok were almost there, we have a context to hold our agents and a projection which will give them all a
spatial location. Now all thats left to do is create our agents and give them some simple actions.
9
Figure 5: Eclipse can automatically import classes.
10
Step 7: Create some agents
1. The rst thing we need to do is add a bit more code to our Person class. Open up the class and
copy all this lot in (between the open/close curly brackets of the class):
private String name;
private String age;
public Person() {
super();
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getAge() {
return age;
}
public void setAge(String age) {
this.age = age;
}
2. Now we could just put a for-loop in our PeopleContext class which creates some agents, adds
them to the context and gives them an (x, y) location in our projection, something like:
for (int i=0; i<10; i++) {
Person p = new Person();
this.add(p); // this refers to PeopleContext
peopleGeography.move(p, new GeometryFactory().
createPoint(new Coordinate(i,i+1)));
}
11
But this isnt very useful so instead well make use of a fantastic feature of Simphony: reading in
a shapele.
3. Loading agents from a shapele.
(a) Ive already created a little shapele with some people in it. Copy the entire People folder
from my transfer directory:
N:/Earth&Environment/Geography /TransferArea/NickMalleson
into the root directory of the SimTutorial project which is probably here:
C:/RepastS/workspace/SimTutorial.
(b) Then add this code after creating the geography in PeopleContext.java:
// Create some people from a shapefile:
File shapefile = null; // NOTE: import java.io, not the sun package!
ShapefileLoader<Person> personLoader = null;
try {
shapefile = new File("People/people.shp");
personLoader = new ShapefileLoader<Person>(
Person.class, shapefile.toURL(),
peopleGeography, this);
}
catch (java.net.MalformedURLException e) {
e.printStackTrace();
}
while (personLoader.hasNext()) {
personLoader.next();
}
The amazing, magical thing about the shapefileLoader is that if you have an attribute in the
shapele and corresponding get/set methods in your agent, it will automatically create agents with
the same values as the shapele. For example, the people shapele has name and age elds
and our Person agent has get and set methods for name and age variables, so each Person is
12
created with the correct name and age. Amazing!
5
.
The shapele loader will have loaded every Person from the shapele into the PeopleContext and
given them an appropriate spatial location in the PeopleGeography. We can test this by running
through all the agents in the geography and printing their location. If you want to do this youll
need to add these lines after the people have been loaded in PeopleContext.java (not compulsory):
// Get all agents in the geography and print their location:
for (Person p:peopleGeography.getAllObjects()) {
Geometry geom = peopleGeography.getGeometry(p);
Coordinate coord = geom.getCoordinate();
System.out.println(p.getName()+" is at: ("+
coord.x+","+coord.y+")");
}
Note: make sure you import the com.vividsolutions.jts.geometry package for the Geom-
etry object.
Step 8: Get the agents moving
Now that we have loaded our agents into the context and given them a spatial location in the projection
we can get them to move around. For now well just have them move in a random direction. Firstly, we
need to create and schedule a method which will be called every iteration to control the agents:
1. Create and schedule a step method for the agents which will control their behaviour.
(a) There are a few ways to schedule things in Simphony, have a look at the Working with the
scheduler section in the Simphony reference docs if you want more info.
6
For now well
use annotations, these take advantage of a nice new feature of Java and are good if we know,
at compile-time, when we would like a method to be executed.
(b) Put the following code after the setAge method in Person:
5
Does anyone else nd this really exciting?
6
http://repast.sourceforge.net/docs/reference/SIM/index.html
13
// Tell repast to run this function at every iteration
@ScheduledMethod(start = 1, interval = 1, priority = 0)
public void step() {
System.out.println(name+" has called step method");
}
(c) The step() method will now be called at every iteration. If you open the project now and
run it (the little green arrow) you should see text telling us that the step() method is being
called for each Person. This isnt particularly useful though as the agents dont actually do
anything.
2. To make the agents move around the geography add the following code (put it after the System.out
line in the step() method):
// Find the context this person exists in.
Context<Person> context = ContextUtils.getContext (this);
// Get the GIS projection associated with the context
Geography<Person> projection = (Geography<Person>)context.
getProjection("PeopleGeography");
// Move the agents a small distance in a random direction
projection.moveByVector(this, 0.01,
RandomHelper.nextDoubleFromTo(0, (2
*
Math.PI)));
Its worth noting that in Simphony all the geographical information about each agent is stored in the
projection, not in the agent (the Person class has no (x, y) variables). This allows our agents to be more
generic, you dont have to specically give them any information about their relationship with each
other or the environment. We could, for example, control our agents from another class and then the
Person class wouldnt even need know about Repast Simphony!
Step 9: Create a Display
Weve pretty-much nished now. You can run Simphony and the agents will move around their geogra-
phy. To actually see this happen, however, we need to create a display:
14
1. Run the model. Remember that all displays, charts etc are created separately from the underlying
model source code, we do this using the runtime GUI.
2. On the list on the left look for the Displays icon underneath the PeopleContext folder. Right
click on it and choose Add Display.
3. In the new window which pops up you can congure the display.
(a) Leave the default name (A Display) for now, anything will do.
(b) The type of projection should be GIS. Repast has detected that the only projection we
have created in the PeopleContext is a GIS geography, this could be Network or Grid if we
had created these types of projections as well.
(c) Tell repast that we would like the display to show our PeopleGeography by clicking on it
and then clicking on the right arrow to move it accross into the box on the right. You should
have something that looks like Figure 6
(d) Click Next.
4. Now we can congure how we would like the agents to be displayed. We can also add other
shapeles to be displayed (like roads, houses etc) by clicking on the + button. For now, just
change the ll colour of our People agents (click on Edit) then click next.
5. The nal box lets us congure how often the display will be updated. Click nish.
6. Finally, save the new model conguration by clicking on the oppy disk at the top. Im not sure
how repast remembers the conguration but it does!
7
Now if we re-compile and/or re-run the
model Repast will have remembered this display.
7
Therell be some xml le in the project somewhere...
15
Figure 6: Creating a display
Press the play button and were off!
You should see some agents wandering around aimlessly, like in Figure 7. Ive also put a video on
my transfer drive, see if you can work out how to save your own video (its really easy, just press one
button).
So far weve created a context, added some agents into the context and created a GIS projection so
the agents can have a location in a geographical space. Now we could create a Network projection to
create a social network for the agents or create another context to hold House objects and give the agents
a home.
Thats the end of the main tutorial. For the remainder Ill just outline a few other features which
might be useful that you can look at if you ever need/want to: model parameters, saving the model
state, outputting data and drawing charts. Then, as an appendix, Ill look at a couple of the unanswered
questions, like why are there yellow lines all over the Java code? (Havent nished the rest yet...)
16
Figure 7: Running the SimTutorial Model
Step 10: Saving a model state: Freeze Drying
Step 11: Output some information
The runtime GUI has made the task of outputting information pretty simple. Firstly we create a new
data set, then tell Repast how we would like to output the data. Here are some instructions to output the
name and age of each person every iteration and also the average age (this isnt particularly interesting
because the name and age dont change but it will do for now).
1. Run the model.
2. Under PeopleContext, right click on Data Sets and the Add Data Set.
3. In the new box: any name will do but the Data Set ID will be used when we tell Repast how
wed like to output the data. Select Person under Agent Class. Then press next.
4. Press Add three times to add three simple variables. Change the source of the second two variables
to print the output from the getAge() and getName() functions.
5. Click on the little arrow just to the right of the Add button and select Add Aggregate Mapping.
Select getAge() and Mean.
6. Press OK, then next, then nish.
17
No weve created the data set we need to tell Repast how we would like to output it:
1. Right-click on Outputters under PeopleContext and the Add File Outputter.
2. Give the outputter any name and select the ID of the data set we just created.
3. Move all the variables from the box on the left to the right-hand box. If you change the order of
the variables this will change the order of the columns in the output le. Press next.
4. Click on browse to say where you would like the le to be stored and also give it a name, it is
handy to give the le a .csv extension so that silly programs like Excel will know how to read
it. Press Finish.
5. Save the changes by clicking on the oppy disk (otherwise youll have to redo these steps each
time you re-run the model).
6. Press Run.
Step 12: Draw a chart
Step 13: Using Parameters
Parameters are variables, held by repast, which can be changed during a simulation run. Theyre quite
useful because it gives you a central place to store important model variables but theyre especially useful
because you can get repast to automatically test the sensitivity of your model by running a parameter
sweep.
18
4.1 Extras: Why all the yellow lines?
XXXX
4.2 Extras: Implementing your own Context Creator
When you run Simphony, note that under the Data Loaders section is something called Score Context
Builder. This means that Simphony will read the model.score le to build the contexts. If you want
to, you can change this to A specic Java class and implement your own context creator (which
must implement ContextBuilder). This is very useful because it gives you ner control over what
contexts/agents are created. For example, our PeopleContext might require a HouseContext to give
each Person a home once they have been created. Using a ContextCreator which you implement yourself
means you can ensure that the HouseContext is created before the PeopleContext.
19
4.3 Extras: Complete Code
Person.java
package simtutorial;
import repast.simphony.context.Context;
import repast.simphony.engine.schedule.ScheduledMethod;
import repast.simphony.random.RandomHelper;
import repast.simphony.space.gis.Geography;
import repast.simphony.util.ContextUtils;
public class Person {
private String name;
private int age;
public Person() {
super();
System.out.println("Created a new Person");
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public int getAge() {
return age;
}
public void setAge(int age) {
this.age = age;
20
}
// Tell repast to run this function every iteration
@ScheduledMethod(start = 1, interval = 1, priority = 0)
public void step() {
System.out.println(name+" stepping");
// Find the context this person exists in.
Context<Person> context = ContextUtils.getContext (this);
// Get the GIS projection associated with the context
Geography<Person> projection =
(Geography<Person>)context.getProjection("PeopleGeography");
// Move the agents a small distance in a random direction
projection.moveByVector(this, 5,
RandomHelper.nextDoubleFromTo(0, (2
*
Math.PI)));
}
}
21
PeopleContext.java
package simtutorial;
import java.io.File;
import com.vividsolutions.jts.geom.Coordinate;
import com.vividsolutions.jts.geom.Geometry;
import com.vividsolutions.jts.geom.GeometryFactory;
import repast.simphony.context.DefaultContext;
import repast.simphony.context.space.gis.GeographyFactoryFinder;
import repast.simphony.space.gis.Geography;
import repast.simphony.space.gis.GeographyParameters;
import repast.simphony.space.gis.ShapefileLoader;
public class PeopleContext extends DefaultContext {
public PeopleContext() {
super("PeopleContext");
GeographyParameters<Person> geoParams =
new GeographyParameters<Person>();
// These lines actually create our Geography.
// Tell Repast to create a new geography projection
// called "PeopleGeography" in this context.
Geography<Person> peopleGeography =
GeographyFactoryFinder.createGeographyFactory(null).
createGeography("PeopleGeography", this, geoParams);
System.out.println("Created PeopleGeography");
// for (int i=0; i<10; i++) {
// Person p = new Person();
22
// this.add(p);
// peopleGeography.move(p,
// new GeometryFactory().
// createPoint(new Coordinate(i,i+1)));
// }
// Create some people from a shapefile:
File shapefile = null;
ShapefileLoader<Person> personLoader = null;
try {
shapefile = new File("People/people.shp");
personLoader = new ShapefileLoader<Person>(
Person.class, shapefile.toURL(),
peopleGeography, this);
}
catch (java.net.MalformedURLException e) {
e.printStackTrace();
}
while (personLoader.hasNext()) {
personLoader.next();
}
// // Get all the agents in the geography and print their location:
// for (Person p:peopleGeography.getAllObjects()) {
// Geometry geom = peopleGeography.getGeometry(p);
// Coordinate coord = geom.getCoordinate();
// System.out.println(p.getName()+" is at: ("+coord.x+","+coord.y+")");
// }
}
}
23
References
Nick Collier. RePast: An extensible framework for agent simulation. Available on-line
at www.econ.iastate.edu/tesfatsi/RepastTutorial.Collier.pdf [accessed -
March 2008], 2003.
T.R. Howe, N.T. Collier, M.J. North, M.T. Parker, and J.R. Vos. Containing agents: Contexts, pro-
jections, and agents. In Proceedings of the Agent 2006 Conference on Social Agents: Results and
Prospects, Argonne National Laboratory, Argonne, IL USA, September 2006.
M.J. North, T.R. Howe, N.T. Collier, and R.J. Vos. The repast simphony runtime system. In Agent 2005
Conference on Generative Social Processes, Models, and Mechanisms, Argonne National Laboratory,
Argonne, IL, USA, October 2005a.
M.J. North, T.R. Howe, N.T. Collier, and R.J. Vos. The repast simphony development environment. In
Agent 2005 Conference on Generative Social Processes, Models, and Mechanisms, Argonne National
Laboratory, Argonne, IL, USA, October 2005b.
Recursive Porus Agent Simulation Toolkit. Repast simphohy.
http://repast.sourceforge.net/, 2008.
24