Repast Simphony Frequently Asked Questions

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

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

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.

Please see the Repast Quick Start guide.

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.

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.

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:

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:

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

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:

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.

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

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

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

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

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

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:

Please see the Repast Model Testing Guide.

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

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

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

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

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

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

See the Repast Reference manual section Creating a New 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.

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

See the Repast Reference manual section Distributing Your Model.

See the Repast Reference manual section Importing a 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.

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

To upgrade scenarios simply do the following:

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.

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

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.

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.

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:

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.

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.

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

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:

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.

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 Menu → Run 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.

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:

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:

https://adoptopenjdk.net/installation.html#linux-pkg ,

where the last line would be:

apt-get install adoptopenjdk-11-hotspot

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.

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.

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

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.

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.

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

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

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.

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.

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:

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

/System/Library/Java/Extensions

/Library/Java/Extensions

or

<User Home>/Library/Java/Extensions

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