1. General

1.1. What is 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:

  • Repast Simphony models can be developed in several different forms including the ReLogo dialect of Logo, point-and-click statecharts, Groovy, or Java, all of which can be fluidly interleaved.

  • 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 such as R Studio.

  • 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.

  • A range of data storage "freeze dryers" for model check pointing and restoration including text file and database storage.

  • A fully concurrent multi-threaded discrete event scheduler.

  • Integrate support for random number generation, statistical distributions, and specialized mathematics.

1.2. How do I install Repast Simphony?

Please see the current download and installation instructions here: https://repast.github.io/download.html

1.3. Can I install different versions of Repast Simphony at the same time?

Yes, as long as each version is installed to a different folder, each installed copy of Repast Simphony is fully self-contained and will not interfere with other versions of the software.

1.4. How do I get started using Repast Simphony?

Please see the Repast Quick Start guide.

1.5. What software platforms work with Repast Simphony?

Repast Simphony is a Java application that is compatible with Windows, macOS, and most linux variants. As of Repast version 2.6, only 64-bit platforms are supported.

1.6. What version of Java is required to run Repast Simphony.

Repast Simphony version 2.6 requires Java 8 or later, and is interchangeably compatible with Java 8 LTS or Java 11 LTS versions. Please see the Java Requirements page for more details.

1.7. Which version of Repast should I use?

There are two editions of Repast and several ways to write models in each edition because there are many different kinds of users, each of whom has unique needs:

  • New users are strongly encouraged to begin by using ReLogo within Repast Simphony.

  • Users with limited programming backgrounds are strongly encouraged to use ReLogo within Repast Simphony.

  • Users desiring rapid prototyping are encouraged to use ReLogo within Repast Simphony.

  • Users seeking visual model construction are encouraged to use ReLogo and Statecharts within Repast Simphony.

  • Users with a workable knowledge of a Java-generating language such as Groovy and who want to use the features of that language should to use their chosen language along with the Java approach within Repast Simphony.

  • Users with a workable knowledge of Java who want highly customized models should to use the Java approach within Repast Simphony.

  • Users with a basic knowledge of C++ who need models that run on supercomputers should use the Logo-style C++ approach within Repast HPC.

  • Users with a strong knowledge of C++ who need highly customized models that run on supercomputers should to use the standard C++ approach within Repast HPC.

1.8. What is the difference between Repast Simphony and RepastJ?

Repast Simphony is the current version of the Repast ABM toolkit and is actively maintained with regular release cycles. RepastJ is the original version of Repast that was released in 1999, and is no longer maintained, although archive builds are available at https://sourceforge.net/projects/repast/files/Repast/. Users wishing to develop ABMs should use Repast Simphony, and legacy RepastJ models can be easily updated to work with Repast Simphony.

ReLogo is an agent-based modeling (ABM) domain specific language (DSL) for developing agent-based models in the free and open source Repast Suite of ABM tools; the Java based Repast Simphony ABM toolkit and the C++ high performance computing Repast HPC toolkit both incorporate ReLogo. ReLogo is geared towards a wide range of modeling and programming expertise, combining the sophisticated and powerful ABM infrastructure and capabilities in the Repast Suite with the ease of use of the Logo programming language and its associated programming idioms. Repast projects may optionally include ReLogo language components that seamlessly integrate with Java and Groovy agents.

For more information, please see:

  • The ReLogo agent-based modeling language, J Ozik, NT Collier, JT Murphy, and MJ North, 2013 Winter Simulations Conference (WSC), Washington, DC, 2013, pp. 1560-1568. http://doi.org/10.1109/WSC.2013.6721539

1.10. What is Groovy?

Repast Simphony ReLogo is based on the Groovy dynamic language. Groovy itself is a widely used, free, and open source Java Virtual Machine (JVM) language that both compiles to Java bytecode and tightly integrates with Java. Thanks to its Groovy foundations, ReLogo freely interoperates with Groovy and Java. A Repast model developer can use Groovy classes in both Repast and ReLogo projects and can use any Java or Groovy library without special syntax. They can also write Groovy and most Java code fluidly at any point in a ReLogo file to gain access to the advanced features of either language.

For those interested in learning more about Groovy, please see the Groovy home page http://groovy-lang.org/ and particularly the Learn section of the site http://groovy-lang.org/learn.html

1.11. What are Statecharts?

Statecharts are a software engineering design methodology and an explicit visual and logical representation of the states of system components and the transitions between those states. Used in ABMS, they can clarify a model’s logic and allow for efficient software engineering of complex state-based models. In addition to agent state and behavioral logic representation, visual statecharts can also be useful for monitoring agent status during a simulation, quickly conveying the underlying dynamics of complex models as a simulation evolves over time.

The new statecharts framework in Repast Simphony, a subset of Harel’s statecharts (Harel 1987), introduces software engineering practices through the use of statecharts that directly translate visual representations of agent states and behaviors into software implementations. By integrating an agent statecharts framework into Repast Simphony, we have made it easier for users at all levels to take advantage of this important modeling paradigm. Through the visual programming that statecharts afford, users can effectively create the software underlying agents and agent-based models.

For more information, please see:

1.12. What is the difference between Eclipse and Repast Simphony?

Eclipse is a free and open-source integrated development environment (IDE) that supports software development in many different programming languages. Eclipse provides a workspace in which users can create, edit, and run source code, and develop software of varying levels of complexity. Repast Simphony is an Eclipse plug-in that provides agent-based software development tools that seamless integrate into the Eclipse IDE and allows modelers to develop agent-based models using the full capability of Eclipse. Repast software installers for Windows and macOS include Eclipse that has already been configured with Repast Simphony.

1.13. Is Repast Simphony available for Android or iOS?

Repast Simphony is typically used with an IDE like Eclipse to build and run models on computer workstations or clusters. However, applications developed for platforms like Android may use some of the core Repast libraries as they are distributed as Java JAR files and can separately be compiled from source code. Advanced users

1.14. Where can I find the Repast Simphony source code?

All Repast source code is available on the public Git repository https://github.com/repast.

1.15. Is Repast Simphony really free? And how is it licensed?

Repast Simphony is free and open source software licensed under the "New BSD" license, which means you are free to use, modify, and redistribute Repast and Repast models. All third-party libraries used by Repast have been rigorously checked for license compatibility with the BSD license, and these third party libraries may also be freely re-distributed. The current Repast Simphony license is located here: https://repast.github.io/license.html

1.16. How can I get help with using Repast Simphony?

Support information is available here: https://repast.github.io/support.html

1.17. How can I report a problem or bug with Repast Simphony?

The Repast team maintains a public issue tracker on Github and welcomes all comments and suggestions on how to improve the software: https://github.com/Repast/repast.simphony/issues

1.18. 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 we suggest the following references:

  • Everything you need to know about agent-based modelling and simulation, CM Macal, Journal of Simulation, 10:2, 144-156, 2016. https://doi.org/10.1057/jos.2016.7

  • Hammer or Tongs: How Best to Build Agent-Based Models?, North M.J., In Advances in Practical Applications of Agents, Multi-Agent Systems, and Complexity: The PAAMS Collection. PAAMS 2018. Lecture Notes in Computer Science, vol 10978. Springer. https://doi.org/10.1007/978-3-319-94580-4_1

  • Complex adaptive systems modeling with Repast Simphony, MJ North, NT Collier, J Ozik, E Tatara, CM Macal, M Bragen, P Sydelko, Complex adaptive systems modeling 1 (1), 2013. https://doi.org/10.1186/2194-3206-1-3

1.19. How do I perform verification and validation of my model?

The following reference provides a review of ABM validation and verification literature:

  • Hammer or Tongs: How Best to Build Agent-Based Models?, North M.J., In Advances in Practical Applications of Agents, Multi-Agent Systems, and Complexity: The PAAMS Collection. PAAMS 2018. Lecture Notes in Computer Science, vol 10978. Springer. https://doi.org/10.1007/978-3-319-94580-4_1

1.20. How do I cite Repast in scientific publications?

If you publish a Repast Simphony-related paper, please considering citing the following paper:

  • North, MJ, NT Collier, J Ozik, E Tatara, M Altaweel, CM Macal, M Bragen, and P Sydelko, "Complex Adaptive Systems Modeling with Repast Simphony", Complex Adaptive Systems Modeling, Springer, Heidelberg, FRG (2013). https://doi.org/10.1186/2194-3206-1-3

If you publish a Repast HPC-related paper, please considering citing the following paper:

2. Programming with Repast Simphony

2.1. Where can I find example models?

A library of example Repast models is included with Repast. Please see the Repast Quick Start guide for instructions on using the example models.

2.2. Do I have to use Java or Groovy for my agents?

Repast Simphony accepts both user-defned 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. For those interested in learning more about Groovy, a dynamically typed programming language very well integrated with Java, please see the Groovy home page http://groovy-lang.org/ and the very informative book "Groovy in Action" by Dierk Koenig. https://www.manning.com/books/groovy-in-action

2.3. How do I create a new Repast project?

See the Repast Reference manual section Creating a New Repast Project.

2.4. How do I create a new ReLogo project?

See the Repast Reference manual section Creating a New ReLogo Project.

2.5. How do I update an existing Repast or ReLogo Project?

If you created a Repast or ReLogo project using a previous version of Repast Simphony and would like to update the project files to a newer version of Repast, see the Repast Reference manual section Updating an Existing Repast Project.

2.6. How can I load a network from an Excel file?

See the Repast Reference manual section Loading Networks from input files.

2.7. Scheduling

2.7.1. How can I initialize my model?

See the Repast Reference manual section Using the Model Initializer.

2.7.2. How can I schedule an agent behavior to execute at a regular tick interval?

See the Repast Reference manual section Schedule with Annotations.

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

See the Repast Reference manual section Scheduling Global Behaviors.

2.7.4. How can I dynamically schedule actions based on events?

See the Repast Reference manual section Directly Schedule an Action.

2.7.5. How can I stop or pause the simulation at a specific time or event?

See the Repast Reference manual section Stopping and Pausing the Model Using the Schedule.

2.8. Displays and GUI

2.8.1. 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 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 the Repast runtime GUI. 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"

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

There are many online sources for 3D model files that can be used in Repast 3D displays. 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 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.

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 implementation that handles MilkShape (.ms3d) files. Milkshape http://www.milkshape3d.com/ a shareware 3D modeling tool that has the ability to import and convert many different types of 3D model files. Generally, if a 3D model is available online it may be opened with Milkshape and saved in the MS3D format.

2.9. Geographic GIS Modeling

2.9.1. Does Repast support geographic projections (GIS)?

Yes. See the Repast Reference manual section GIS Projections.

2.9.2. How can I import a GIS shapefile or raster into a Repast model?

See the Repast Reference manual section Loading Agent Data from Shapefiles.

2.9.3. Can I load or create GIS raster layers in Repast model?

See the Repast Reference manual section Coverage Raster Layers.

2.9.4. Can GIS and Network projections be combined?

Yes. See the Repast Reference manual section Network Projections in GIS.

2.9.5. What is the difference between the GIS and GIS 3D displays?

The GIS (legacy) displays are the original GIS displays from Repast version 1.0. These displays provide basic GIS functionality in a 2D projection with limited styles for polygon, line, and point features. Current releases of Repast Simphony still support the original GIS displays. The GIS 3D displays provide more advanced GIS display functionality and are based on NASA WorldWind Java. GIS 3D displays can produce shapes for polygon, line, and points, along with raster layers, and online GIS image data such as background satellite imagery and OpenStreetMap layers. It is recommended to use the newer GIS 3D displays for Geography projections since the displays provide a much higher degree of customization over the legacy 2D diaplays.

2.10. Running Models

2.10.1. 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"};


  public static void main(String[] args) {

    UserMain um = new UserMain();

2.10.2. 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 it 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.

The example Java runner class TestRunner_2.java and main class TestMain_2.java provide examples. 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.

2.11. Model Configuration

2.12. How can I give my Repast model to someone else?

See the Repast Reference manual section Distributing Your Model.

2.13. How do I open a Repast model that someone else gave me?

See the Repast Reference manual section Importing a Model.

2.14. How do I include a third-party library in my model?

Simply place the .jar files in the project /lib folder and the Repast runtime will automatically load them. See the Repast Reference manual section user_path for more details.

3. Upgrading Repast Simphony Models

3.1. Updating from version 2.9.x to 2.10.0

Several third party libraries were updated and require minor changes to user models code. These include:

3.1.1. User models that use GeoTools and JTS classes

Reorganize java imports to reflect new package names by changing any import of:

  • com.vividsolutions.jts.* to org.locationtech.jts.*

3.1.2. Java Units API 2.0

The Java Units API has been updated to version 2.0. User model code that use the JScience org.jscience.physics.amount.Amount will need to be updated to use the new javax.measure.Quantity.

For example, using the JScience Units API:

import org.jscience.physics.amount.Amount;
import static javax.measure.unit.SI.*;

Amount x = Amount.valueOf(150, METRE);
double y = x.doubleValue();

would need to be updated to the new Units 2.0 API:

import tech.units.indriya.quantity.Quantities;
import javax.measure.Quantity;
import static tech.units.indriya.unit.Units.METRE;

Quantity x = Quantities.getQuantity(150, METRE);
double y = x.getValue().doubleValue();

3.2. Updating from version 1.0, 1.1 or 1.2 model to run in Repast Simphony 2.0 and later

To upgrade scenarios simply do the following:

  • Right click on the scenario folder (usually "yourmodelname.rs").

  • Choose "Convert Scenario" from the popup menu.

This will create a user\_path.xml and a context.xml from your old Score file. It will also make backup copy of the scenario.xml file and then remove any displays from the scenario file. Removing the displays is necessary because old Piccolo 2D displays will no longer load in version 2.0.

3.3. 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:

  • Create a new Repast Simphony project or add the Repast nature to your existing project(see tutorial).

  • Strip out all of the Repast J-specific visualization code from your agents (ie extends DefaultDrawableNode).

  • 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).

  • Create a scenario/score model.

  • Create displays, loggers, etc via the Repast S runtime interface.

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

4. Problems

4.1. My project does not show up on Eclipse’s run (launch) button

The project launch configuration has simply become hidden and needs to be manually added to the list of available programs to run. Follow these steps: 1. Choose "Organize Favorites" from the bottom of the Run menu 2. Press the "Add" button on the upper left of the resulting "Organize Run Favorites" window. 3. Select all of the items in the "Add Run Favorites" window.

4.2. WARNING: An illegal reflective access operation has occurred

The following warning message occurs when using Java 9 or later, and has no impact on the model code, performance, or reliability, and can be safely ignored:

WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by ...
WARNING: Please consider reporting this to the maintainers of ...
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release

4.3. FATAL: java.lang.UnsupportedClassVersionError

This can occur when Elipse’s compiler compliance level is greater than the current JRE. For exammple, the following will occur when the compiler compliance is 16 and the JRE is 11.

FATAL [AWT-EventQueue-0] 13:46:13,958 repast.simphony.ui.RSUIPlugin - Fatal error starting Repast
java.lang.UnsupportedClassVersionError: jzombies/Human has been compiled by a more recent version of the Java Runtime (class file version 60.0),
this version of the Java Runtime only recognizes class file versions up to 55.0

This can be fixed by setting the compiler compliance level to our recommended 1.8. In Eclipse, Preferences → Java → Compiler and set the compiler compliance level to 1.8.

4.4. FATAL java.lang.ExceptionInInitializerError (caused by java.lang.reflect.InaccessibleObjectException)

This will occur when using a JRE > 11. For example,

FATAL [AWT-EventQueue-0] 13:55:14,856 repast.simphony.ui.RSUIPlugin - Fatal error starting Repast
    at com.thoughtworks.xstream.XStream.setupConverters(XStream.java:807)
    at com.thoughtworks.xstream.XStream.<init>(XStream.java:574)
    at com.thoughtworks.xstream.XStream.<init>(XStream.java:496)
Caused by: java.lang.reflect.InaccessibleObjectException: Unable to make field private final java.util.Comparator java.util.TreeMap.comparator accessible: module java.base does not "opens java.util" to unnamed module @371ef662
    at java.base/java.lang.reflect.AccessibleObject.checkCanSetAccessible(AccessibleObject.java:357)

We recommend using Java/JRE 11 which will avoid this issue, but if you must use a JRE > 11 then these errors can be fixed by using the --add-opens VM argument. The format is --add-opens <module>/<package>=ALL-UNNAMED. For example, if the error specifies module java.base does not "opens java.util" to unnamed module @371ef662, then the module is java.base and the package is java.util, and the VM argument is --add-opens java.base/java.util=ALL-UNNAMED.

There are likely to be more than one of these arguments required. For example, the JZombies demo needs:

--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/java.util=ALL-UNNAMED
--add-opens java.base/java.lang.reflect=ALL-UNNAMED
--add-opens java.base/java.text=ALL-UNNAMED
--add-opens java.desktop/java.awt.font=ALL-UNNAMED

VM arguments for a particular model can be added in that model’s run configuration. Run → Run Configurations → Select the Model, and add the VM arguments in the VM arguments text panel in the Arguments tab.

4.5. "Port Already in Use" Error when running Repast Simphony Web Server

When attempting to start the Repast Simphony Web Server to run a model in a browser, the network port used by the server may be already in use, and the following exception will appear.

Exception in thread "main" java.lang.RuntimeException: Port already in use. Make sure no other process is using port 5000 and try again. at io.javalin.Javalin.start(Javalin.java:158)

The error can be avoided by changing the port number in the launch configuration. The server port can be configured in the server’s launch configuration.

+ a. Go to the Run MenuRun Configurations (at the bottom of the menu) b. Click on the Server launcher you want to edit. c. Click on the Arguments tab d. Edit the program arguments. The first argument (e.g., 5000) specifies the server port, the second the scenario folder of the model to run, and the third argument determines whether or not to auto-launch a browser where true means auto-launch.

Figure 1. Server Launcher Configuration Dialog

4.6. WARNING: NSWindow drag regions should only be invalidated on the Main Thread!

The following warning message occurs when using macOS Mojave, and has no impact on the model code, performance, or reliability, and can be safely ignored:

WARNING: NSWindow drag regions should only be invalidated on the Main Thread! ...

4.7. "Inconsistency detected by ld.so …"

There are reported issues with the standard Java 11 install on Ubuntu 18.04 that result in this error being generated when a model is initialized. The issue can be avoided by either downgrading to Java 8 or by installing the Adopt OpenJDK version of Java 11:

where the last line would be:

apt-get install adoptopenjdk-11-hotspot

4.8. Eclipse: An out of memory error has occurred.

Eclipse may exceed the specified maximum memory it can use when building large projects. The memory allocated to Eclipse is specified in the eclipse.ini file in the /eclipse folder and can be directly edited with a text editor. The arguments -Xms and -Xmx may be updated to allocate more memory, for example


will allocate 2GB maximum to Eclipse. The default values for -Xmx is usually much smaller. As of Repast version 2.6, the eclipse.ini included with the Repast installer omits the -Xms and -Xmx entirely, as the JVM is able to automatically re-allocate memory up to the system available maximum. For users who download their own copy of Eclipse, or for Repast versions prior to 2.6, the -Xms and -Xmx values can be removed or updated as needed.

4.9. SEVERE: Retrieval returned no content for https://worldwind20.arc.nasa.gov/…

This is a benign warning that sometimes occurs in GIS displays because the online server for layers like satellite imagery is unreachable or offline. The only impact of this error is that some GIS display imagery data may be unavailable. Model behavior is not affected.

4.10. WARN "Empty or non-existent path"

When launching a Repast model, the following errors may occur in the console:

WARN  ... Warning while parsing classpath: Empty or non-existent path 'mypath'.
WARN  ... While initializing watchers: Empty or non-existent path 'mypath'.
WARN  ....While initializing classpath: Empty or non-existent path 'mypath'.

indicating that the model classpath has not been configured, or is empty. Check that the user_path.xml agents entry points to the correct path for the model agents, usually by default this is "../bin". This warning will also occur if no agent classes are defined within the "mypath" location.

4.11. When I run my model I see the error "java.lang.ClassNotFoundException: somepackage.someclass at …"

This is caused by a Java classpath configuration error such that the model cannot find the specified class "somepackage.someclass". If the specified class refers to a user-created model file, please make sure that the user_path.xml agents path is pointing to the project "../bin" folder. If the specified class is not a user-defined class, it is probably referenced from a third party library. Make sure the library is included in the project /lib folder and that the user_path.xml specifies the /lib folder as a classpath entry.

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

The tick counter will not increment if no behaviors have been scheduled. Schedule agent behaviors in the agent classes using the @ScheduledMethod annotation.

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

An issue sometimes occurs with the Repast message logging system that results in error messages like

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 user_path.xml 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.

4.14. Exception in thread "main" java.lang.OutOfMemoryError: Java heap space

Java has attempted to use more memory that is available to the model. With version of Java prior to version 9, it was usually necessary to specify the amount of memory needed by an application, because the default amount or "heap space" was very small. Java 9 and later generally have better memory management, however it is still possible to experience an OutOfMemoryError if a model uses an unusually large amount of memory.

To increase the amount of system memory available to Java, a "VM" argument may be specified in the Eclipse launch configuration for the model. To increase the available memory (up to the physical system limit) use the -Xmx argument and provide a numerical value for the memory using the M or G qualifier to specify megabytes or gigabytes. For example -Xmx4000M and -Xmx4G both specify a memory limit of 4 GB.

Figure 2. Eclipse launch configuration dialog showing VM arguments options.

4.15. When I run the model I get the runtime error javax.media.opengl.GLException

When running a Repast model with displays an error similar to that shown below is seen and the displays do not show correctly in the Repast runtime GUI:

javax.media.opengl.GLException: WindowsWGLDrawableFactory - Could not initialize shared resources...
ERROR [AWT-EventQueue-0] 12:13:10,314 repast.simphony.visualizationOGL2D.DisplayOGL2D - Error initializing OGL 2D display. JOGL must be installed and computer must support open gl rendering
javax.media.opengl.GLException: Profile GL2 is not available on null, but: [GLProfile[GL2ES2/GL4.hw], GLProfile[GL4/GL4.hw], GLProfile[GL3/GL3.hw], GLProfile[GL4/GL4.hw], GLProfile[GL2GL3/GL4.hw]]
    at javax.media.opengl.GLProfile.get(GLProfile.java:806)

This is caused by the system’s graphics card drivers being out of date, or the system graphics hardware not supporting OpenGL. The most common cause of this error is out of date graphics drivers. The graphics drivers should be updated and are generally available from the computer manufaturer or directly from the GPU support sites of NVidia or ATI.

Under OSX, Apple has installed older obsolete versions of the vecmath and Java3D libraries. These may be located in a variety of locations such as




<User Home>/Library/Java/Extensions

Remove all the vecmath, java3d and jogl related jars and vecmath, java3d, jogl, and jnilib files from those directories.

4.17. Problems with updating older Repast models

4.17.1. I imported a previous workspace into a new version and now I get an error like "java.lang.UnsupportedClassVersionError….unsupported major.minor version 51.0"

Older workspaces that previously worked with Simphony may be setup to use Java 1.6. The workspace preferences must be updated to use Java 1.8 or later. Go to the Preferences menu then select Java → Installed JREs and choose a Java JRE 8 or later that installed on your system.

4.17.2. I tried the batch model launcher in Eclipse and I get class not found errors for the apache CLI classes.

The current version of the batch GUI require a different classpath and older versions of the .launch file do not have the correct classpath. To fix this, open the .launch file as text and replace the line:

<listEntry value="&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;
path=&quot;3&quot; type=&quot;3&quot;/&gt;&#10;"/>


<listEntry value="&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;
path=&quot;3&quot; type=&quot;4&quot;/&gt;&#10;"/>

4.17.3. When building the model installer I get an exception "[java] com.izforge.izpack.compiler.CompilerException"

Models created with previous version of Repast should have their installer configuration files updated. This can be done automatically. If you created a Repast or ReLogo project using a previous version of Repast Simphony and would like to update the project files to a newer version of Repast, see the Repast Reference manual section Updating an Existing Repast Project.

4.17.4. My Repast project includes JUnit unit tests but the tests won’t compile (e.g. the imported packages won’t import etc.).

Eclipse included with Repast Simphony changed the name of its JUnit library plugin. The project build path needs to be updated to this new JUnit library. To do this, right click on the project name in the package explorer then Build Path → Add Libraries. Choose JUnit from the list, then Next, then Finish. That will add Eclipse’s current JUnit to the project.

4.17.5. I imported an existing 2.0 project into 2.1 / 2.2 and created a statechart. The statechart code in my agent won’t compile.

By default a 2.0 project is not set up to generate and compile code from a statechart. To enable this, the project must be upgraded to a new verison of Repast Simphony. To do that, right click on the project name, then choose Repast Simphony from the menu and then Update Repast Simphony Nature. Now when you save the statechart you should see a src-gen directory in into which the statechart code is generated.

4.17.6. Batch run GUI NullPointerException

When running the Repast batch run GUI with a model created with an older version of Repast, you may see an error like:

Exception in thread "AWT-EventQueue-0" java.lang.NullPointerException
at repast.simphony.batch.gui.BatchConfigMediator.<init>(BatchConfigMediator.java:80)
at repast.simphony.batch.gui.BatchConfigMediator.<init>(BatchConfigMediator.java:72)
at repast.simphony.batch.gui.MainPanel.<init>(MainPanel.java:27)

The MessageCenter.log4j.properties file in the model root folder is out of date and needs to be updated. Replace the current contents of that file with:

log4j.rootLogger = error
log4j.logger.org.java.plugin = warn, stdout
log4j.logger.org.apache.commons= warn, stdout
log4j.logger.repast.simphony.plugin = warn, stdout

log4j.logger.MessageCenter.INTERNAL.repast = info, stdout, R
log4j.logger.MessageCenter.INTERNAL.saf = info, stdout, R

log4j.logger.repast.simphony.batch = info, stdout, R
log4j.logger.repast.simphony.batch.ssh.SSHSessionFactory = warn, stdout, R

log4j.appender.stdout = org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout = simphony.util.messages.MessageCenterLayout
log4j.appender.stdout.layout.conversionPattern =%-5p [%t] %d{HH:mm:ss,SSS} %c - %m%n

log4j.appender.R.layout.ConversionPattern=%-5p [%t] %d{ISO8601} %c - %m%n