Repast Simphony : Frequently Asked Questions
This page last changed on Mar 18, 2009 by etatara.

Frequently Asked Questions About Repast Simphony.

General Questions

Programming with Repast Simphony

Problems

General Questions

How can I create an agent-based model in my domain of interest?

Agent-based models are not necessarily complicated or hard to make, but there is no single modeling approach that works for all domains. To get a better understanding of agent-based modeling and simulation (ABMS) and ABMS toolkits, take a look at the proceedings from the Agent 200X conference http://agent2007.anl.gov/proceedings/index.html.

Additionally, a new book is available on how to do agent-based modeling and simulation. The book is titled Managing Business Complexity: Discovering Strategic Solutions with Agent-Based Modeling and Simulation. The book teaches readers:

  1. how to think about agent-based modeling, that is, about agents and their interactions;
  2. how to explain the features and advantages of agent-based modeling to other people; and
  3. how to actually implement agent-based simulations.

The new book is intended to be a complete agent-based modeling resource, accessible to readers who haven't had any previous experience in building agent-based simulations, or any other kinds of models, for that matter.

The book's details are as follows:

Title: Managing Business Complexity: Discovering Strategic Solutions with Agent-Based Modeling and Simulation
Authors: Michael J. North and Charles M. Macal
Publisher: Oxford University Press
Publication Date: March 2007
ISBN: 0-19-517211-6

The book's table of contents is as follows:

  1. The Challenge
  2. The ABMS Paradigm
  3. Agents Up Close
  4. The Roots of ABMS
  5. The Role of ABMS
  6. Discovering Agents and Agent Behaviors
  7. Office ABMS
  8. How to Do Desktop ABMS
  9. How to Do Participatory ABMS
  10. How to Do Large-Scale ABMS
  11. ABMS Verification and Validation
  12. A Visual Approach to Data Collection and Cleaning
  13. Understanding and Presenting ABMS Results
  14. ABMS Project Management
  15. Rising to the Challenge

Further information on the book can be found at the following address:

http://tinyurl.com/2sgtlc

What is the difference between Repast J and Repast Simphony?

Repast Simphony is a free and open source agent-based modeling toolkit that offers users a rich variety of features including the following:

  1. An optional point-and-click model development environment that generates Java classes and seamlessly integrates with hand written Java and Groovy components.
  2. A pure Java point-and-click model execution environment that includes built-in results logging and graphing tools as well as automated connections to a variety of optional external tools including R, VisAD, Weka, popular spreadsheets, MATLAB, and iReport.
  3. An extremely flexible hierarchically nested definition of space including the ability to do point-and-click and modeling and visualization of 2D environments, 3D environments, networks including full integration with the JUNG network modeling library, and geographical spaces including full Geographical Information Systems
    (GIS) support.
  4. A range of data storage "freeze dryers" for model check pointing and restoration including text file and database storage.
  5. A fully concurrent multithreaded discrete event scheduler.
  6. Libraries for genetic algorithms, neural networks, regression, random number generation, and specialized mathematics.
  7. Automated Monte Carlo simulation framework which supports multiple modes of model results optimization.
  8. Built-in tools for integrating external models.
  9. Fully object-orientation.
  10. Availability on virtually all modern computing platforms including Windows, Mac OS, and Linux.

More information on Repast Simphony can be found on the main web site:

http://repast.sourceforge.net

You might look at the following papers in the Agent 2006 proceedings at http://agent2007.anl.gov/proceedings/proc2006.html

Howe, T.R., N.T. Collier, M.J. North, M.T. Parker, and J.R. Vos, "Containing Agents: Contexts, Projections, and Agents," Proceedings of the Agent 2006 Conference on Social Agents: Results and Prospects, Argonne National Laboratory, Argonne, IL USA (September 2006).

North, M.J., P. Sydelko, J.R. Vos, T.R. Howe, and N.T. Collier, "Legacy Model Integration with Repast Simphony," Proceedings of the Agent 2006 Conference on Social Agents: Results and Prospects, Argonne National Laboratory, Argonne, IL USA (September 2006).

Parker, M.T., T.R. Howe, M.J. North, N.T. Collier, and J.R. Vos, "Agent-Based Meta-Models," Proceedings of the Agent 2006 Conference on Social Agents: Results and Prospects, Argonne National Laboratory, Argonne, IL USA (September 2006).

Tatara, E., M.J. North, T.R. Howe, N.T. Collier, and J.R. Vos, "An Introduction to Repast Modeling by Using a Simple Predator-Prey Example," Proceedings of the Agent 2006 Conference on Social Agents: Results and Prospects, Argonne National Laboratory, Argonne, IL USA (September 2006).

Are training courses available for Repast Simphony?

We typically offer three days of training in Chicago, IL USA at the Agent 20XY (http://agent2007.anl.gov/) conference. We also run an intensive business-oriented ABMS course in Chicago, IL USA which includes two and a half days of Repast training (http://www.dis.anl.gov/conferences/abms/info.html). Other short courses are scheduled periodically in other areas.

Programming with Repast Simphony

Where can I find example models for Repast Simphony?

The source code for demo models is available in the project repast.simphony.demos from the Sourceforge SVN. A workspace containing the demos as a project is available for download separately from the Sourceforge download site, and is included with the Repast Simphony installer.

How do I schedule a "global" behavior, a behavior above the individual agent level?

There's at least two ways to do this. Both assume that you create your model in your own ContextBuilder.

The first way requires that you have your ContextBuilder extend DefaultContext. Once you've done this you can add @ScheduledMethods to this ContextBuilder to perform some global action.

public class MyContextBuilder extends DefaultContext implements ContextBuilder {

	/**
	 * Builds and returns a context. Building a context consists of filling it with
	 * agents, adding projects and so forth. The returned context does not necessarily
	 * have to be the passed in context.
	 *
	 * @param context
	 * @return the built context.
	 */
public Context build(Context<T> context) {
	...
}

@ScheduledMethod(start = 1)
 public void step() {
   	// my "global" behavior
 }
}

The second way uses the RunEnvironment object to get a reference to the current Schedule with which can add your behavior. For example,

public class MyContextBuilder implements ContextBuilder {

	public Context build(Context<T> context) {
		...
		ISchedule schedule = RunEnviroment.getCurrentSchedule();
		ScheduleParameters params = ScheduleParameters.createOneTime(1);
		schedule.schedule(params, this, "step");
	}

 	public void step() {
   		// my global behavior
 	}
}

 Note that while the above schedules the execution of MyContextBuilder.step, any of the options provided by ISchedule are available.

How do I create a custom display?

All simphony displays implement IDisplay. CustomDisplay.java is an example that displays a panel with a simple label in it. Note that most of the methods are empty or return null.  The important methods are render, update and getPanel. When update is called the display should update its internal state to reflect the latest state of whatever its displaying. When render is called, the display should draw those updates. getPanel is called during initialization to put a panel into a display tab.

The next step then is telling simphony to load this display during initialization. You do that with a ModelInitializer. The model initializer is run once just after your scenario is loaded. It can be used to add additional items to the scenario tree that's displayed on the left hand side of simphony. Its not immediately obvious but this is actually a tree of actions that simphony executes when it initializes a model prior to a run. A model initializer then can add a custom action that initializes a custom display. TrapInitializer.java  does just that. The second added controller action is what sets up the custom display. Lastly, you need tell Simphony to run your ModelInitializer and you do that in the scenario.xml file located in your scenario directory (e.g. mousetrap.rs) by adding a model.initializer entry. For example,

<model.initializer class="repast.simphony.demo.mousetrap.TrapInitializer" />

Do I have to use the agent editor and Groovy for my agents?

No. Repast Simphony accepts both user defined POJOs (Plain Old Java Objects) as well as POGOs (Plain Old Groovy Objects) as agents (or for defining other model components), making the use of Groovy completely optional. The graphical agent behavior editor generates Groovy agent classes. For those interested in learning more about Groovy, a dynamically typed programming language very well integrated with Java, there is the Groovy home page <http://groovy.codehaus.org/> and the very informative book "Groovy in Action" by Dierk Koenig.

How can I convert my Repast J model to run in Repast Simphony?

A quick summary of the process of converting to Repast J to Repast S:

  1. Create a new Repast Simphony project or add the Repast nature to your existing project(see tutorial).
  2. Strip out all of the Repast J-specific visualization code from your agents (ie extends DefaultDrawableNode).
  3. Pick out the relative information such as scheduling and model parameters from the Repast J main class (ie SimpleModelImpl) and put this in the Repast S ContextBuilder or agent class constructors (where ever you see fit).
  4. Create a scenario/score model.
  5. Create displays, loggers, etc via the Repast S runtime interface.

Several of the demos (sugarscape and regression) included with Repast S are direct ports from the Repast J models, so comparing these will provide some additional help on porting models.

How can I run Repast Simphony from another Java application?

Repast may be launched programmatically by directly calling the repast.simphony.runtime.RepastMain class. RepastMain takes two arguments, the first is the location of the model scenario directory and the second is an optional location of the repast runtime location.

Note that you need to have repast.simphony.runtime/bin and the jars in repast.simphony.runtime/lib on your classpath since the runtime needs these to start.

Also, you can put the repast runtime folders anywhere you like if you are calling the RepastMain from your own code. As long as you have repast.simphony.runtime/bin to your classpath, RepastMain will be able to find the runtime and start properly.

Here's a simple class that will do this:

public class UserMain {

public UserMain(){};

  public void start(){

    String[] args = new String[]{"C:/myModel/scenario.rs"};

    repast.simphony.runtime.RepastMain.main(args);
  }

  public static void main(String[] args) {

    UserMain um = new UserMain();
    um.start();
  }
}

How can I control the Repast Simphony schedule from another Java application?

To run a simulation purely programmatically with fine control, you need to create a class that extends repast.simphony.engine.environment.AbstractRunner and modify to suit your needs. The runner class can then be used to initialize, step, run, pause, stop and reset the model. This approach uses components from the GUI which is totally user driven and the Batch run which is completely self-contained with no user-interaction.

Attached are a sample runner TestRunner_2.java and main class TestMain_2.java. In this case you won't use either the RepastMain (GUI) or the BatchMain (batch mode), but use the runner class directly. Note that you will need to include the classes from repast.simphony.runtime and repast.simphony.Batch in your classpath to run.

How can I implement regression in Repast Simphony?

Please see http://repast.sourceforge.net/docs/reference/SIM/index.html

How can I implement neural networks in Repast Simphony?

Please see http://repast.sourceforge.net/docs/reference/SIM/index.html

How can I implement genetic algorithms in Repast Simphony?

Please see http://repast.sourceforge.net/docs/reference/SIM/index.html

How can I implement Systems Dynamics in Repast Simphony?

Please see http://repast.sourceforge.net/docs/reference/SIM/index.html

How can I link Matlab to Repast Simphony?

To startup Matlab, the JMatlink.dll file needs to be in your path and the Matlab program bin dir needs to be in the path as well, although Matlab should set this for you at installation. You can copy the JMatlink.dll from the repast.simphony.matlab/lib folder to your Matlab bin directory, which should solve the problem if your Matlab bin is already in your path. For more information, please see http://jmatlink.sourceforge.net/

Do I need to define all contexts, projections and agents in the model.score?

It depends. The score file serves several purposes, including parsing of annotations, context building, and providing information to the runtime GUI. Agents and contexts do not need to be defined, but if you leave them out, the simulation runtime won't pick up annotations for scheduling and watching, and you won't be able to see omitted objects in the runtime wizards. You can technically omit everything but the root context builder in the model.score and still run a simulation, provided that you do all of the scheduling of actions and watches programmatically and you create custom displays if desired.

Where can I find 3D models to use in displays?

The website http://www.turbosquid.com/ has many 3D models available. There are many free models, although most of them are sold for a fee. I have used several of the free models and they turned out pretty well. The licensing agreement on the site indicates that you may publicly show reproductions (such as presentations and papers), but the free models may not be re-distributed electronically. The fee-based models have various licensing agreements depending on the author.

The models available online generally are of one of the more popular formats such as Lightwave, Wavefront OBJ or AutoDesk 3DS. To display one of these models in a Repast S 3D display, the file needs to be loaded as a com.sun.j3d.loaders.Scene object. The Scene object is then used to define the TaggedBranchGroup object that is provided by the user-defined 3D style class. See repast.simphony.demo.predatorprey.WolfNodeStyle.java as an example.

The J3D group provides an interface com.sun.j3d.loaders.Loader which returns the Scene object provided the model file. The default J3D Loader implentations handle models of type Wavefront OBJ, and Lightwave files. We have additionally included a Loader implentation that handles MilkShape (.ms3d) files. Milkshape (http://chumbalum.swissquake.ch/) is a shareware 3D modeling tool that has the ability to import and convert many different types of 3D model files. Generally, if I find a 3D model online that I like, I would open with Milkshape and save it in the MS3D format such that it can be loaded as in the WolfNodeStyle class.

There are also many other Loader implentations for other file types available online, although none of the ones I found were compatible with Repast's licensing scheme, and thus we did not include them. See http://java3d.j3d.org/utilities/loaders.html for more information on freely availble Loader implentations.

Problems

Where is step 4c in the flowchart editor in Repast Simphony version 1.0?

In version 1.0, step 4c is missing from the agent flowchart editor, even though the tutorial documentation references 4c. Step 4d should be used instead.

How come I can't enter data into combo boxes in the flowchart editor in Repast Simphony version 1.0?

Only one Enter key on some keyboards works for entering the data in the combo boxes. My full size keyboard has an Enter key just right of the letters (three spaces right of the L key) and another Enter key as part of the numeric keypad at the far right of the keyboard. The Enter key that is part of the numeric keybad does NOT work. Only the "central" Enter key (aka Return key) will enter the values into the combo boxes.

Unable to find class(es) to watch: [] classpath:

This error will generally by accompanied by the exception "java.lang.RuntimeException: Couldn't find classes using supplied class loader:" The Base Path entry in the model.score file tells the runtime where to find the agent .class files. Make sure that the compiled agent class files are located in the path specified in the model.score.

I press the run button but nothing happens or the tick reads -1

Most likely the tick counter does not increment because no behaviors have been scheduled. The tutorial infrastructure demo is an event-based model, and requires user-interaction to start things in motion (think dominoes). If you read Section 2-08 "Constant Scheduled Behavior" of the tutorial, it will show you how to create a constant repeating behavior that will let you run the simulation without any user interaction.

log4j:WARN No appenders could be found for logger (MessageCenter.INTERNAL.repast.simphony.ui.RSUIPlugin)

Several people have reported errors when trying to start a Repast Simphony model such as

log4j:WARN No appenders could be found for logger (MessageCenter.INTERNAL.repast.simphony.ui.RSApplication ).
log4j:WARN Please initialize the log4j system properly.

with some variability in the (MessageCenter....) part. In almost all cases, this warning is NOT actually related to logging configuration errors, and more likely it is related to problems in the model.score file like incorrect paths, or missing agent class files.

When you start a Repast model and you get the log4j message in the Eclipse console, you can usually find more information from the Repast runtime error log. The error log is available when the icon in the lower right corner of the Repast runtime is flashing.

Java out of memory

If your simulation contains many agents and/or graphical components, you may need to increase the memory available to the Java runtime. Use the VM argument -Xmx<maximum heap size> to set the maximum heap (memory) size from the command line or from the VM arguments section in the Eclipse launch configuration. For example, to set the maximum heap size to 500 Megabytes, use -Xmx500M.

How come I can't use methods that return Amounts to style agents in the runtime wizards in Repast Simphony version 1.0?

In version 1.0, icon style wizards can only use methods that return a java.lang.Number. In version 1.1 we have added the ability to use Amounts for scaling that just returns a double value using the Amount's units, assuming that the user accounts for different units (ie trying to scale an icon size by 25.seconds or 8.35.kilograms).

The good news is that the stylers have access to all public methods in a class that return a java.lang.Number. For a workaround in version 1.0, you could define a method for an Amount (say time) called

public double getTimeAmountInSeconds(){

  return timeAmount.doubleValue(SI.SECOND);

}

This approach is also useful for people who want to use a rule-based approach for styling since a custom method can check any number of criteria and return discrete values to the styler, rather than just scaling on a continuous variable.

My version of R doesn't work with Repast Simphony.

Version 2.4.1 and later of R has been tested to work with Repast and is suggested for use. R Commander is required to run R as plugin with Repast. See the R Commander documentation on how to install http://socserv.mcmaster.ca/jfox/Misc/Rcmdr/.

How come I can't copy/paste into some fields in the visual agent flowchart?

The inputs for certain table fields (i.e., SWT CCombo's) do not enable the clipboard (i.e., copy, cut, and paste) system edit menu and shortcuts. This is a Elcipse bug. A few of the inputs in the visual editor will have this problem. As a work around, please note that right clicking on the problematic fields brings up a popup menu that has working clipboard functions.


Attachments:
CustomDisplay.java (text/plain)
TrapInitializer.java (text/plain)
TestMain_2.java (application/octet-stream)
TestRunner_2.java (application/octet-stream)
info.png (image/png)
Document generated by Confluence on Mar 18, 2009 16:17