Repast Simphony Reference Manual

The Repast development team maintains an active mail list monitors Stack Overflow questions related to Repast and agent-based modeling. Please see the Support page for the most current help links.

Please see the online Repast Downloads page for current release information.

ReLogo project creation is nearly identical to creating a Repast project. The steps are outlined below.

Existing Repast projects starting with version 2.0 generally do not require any special steps to update the project or model components. Users may optionally update the Repast model installer builder files that are located in the project’s /installer folder by using an automated update feature. The Repast model installer builder is a bundled utility that packages a Repast model into a self-contained JAR installer that can be distributed to other systems even if they do not have Repast installed on them. Since some version-specific configuration details are contained in the project’s installation folder, it it sometime necessary to update these files after a new version of Repast is installed.

An existing Java project can be configured such that Repast and ReLogo models and components can be used. This involves adding the Repast Nature to the Eclipse project. Adding the Repast Nature requires a single step:

Users who have existing Repast projects or who have received a Repast project from someone else may import the project into a new version of Repast Simphony using the following steps:

Repast and ReLogo projects contain a number of folders and files that are required and contain essential model configuration data. Repast Java project developers typically modify these files to suit the model properties, however ReLogo project developers typically will not need to modify any of these files.

The following list of folders contain essential Repast project configuration files and should not be deleted or renamed:

After creating a new Repast project, the model meta-data XML files need to be updated according to the types of components that a user would like to include in the model. The only two files that need to be directly edited are the user_path.xml and the context.xml files. All other project configuration files are automatically updated by the Repast GUI, although they may be manually edited as well.

Repast Simphony provides multiple ways to distribute executable models to others without the need for them to separately download and configure Repast Simphony on their computer.

While Contexts create a container to hold your agents, Projections impose a structure upon those agents. Simply using Contexts, one could never write a model that provided more than a simple "soup" for the agents. The only way to reference other agents would be randomly. Projections allow the modeller to create a structure that defines relationships, whether they be spatial, network, or something else. A projection os attached to a particular Context and applies to all of the agents in that Context. This raises an important point:

Multiple projections can be addeded to the same context therefore it is possible, for example, for a context to contain a grid, a geography, and a network.

Agents may reference projections through their containing context by specifying the name of the projections, e.g. "mynetwork":

The returned Projection object will have limited value unless is is cast to the specific type (e.g. Network or Grid):

The Repast ContextUtils class provides a number of utility functions for finding Context instances from the model code.

To reference the current context of an agent:

The context’s parent context (if exists) can similarly be found using:

The Repast Context interface extends the standard Java Collection so that objects can be added or removed to or from contexts similar to how one would perform such operations with Java collections such as lists.

Starting with verion 2.8, queries on objects within contexts can be performed using Java streams filters. A stream filter processes the entire stream of objects returned by the context and passes only those objects that satisfy the conditions in the filter. Complex filter conditions can be used to find objects whose attributes meet a set of conditions. The use of stream filters is recommended over the legacy Property queries due to significant improvements in performance.

As an example of a stream filter, if an agent has a property "energy" and a getter method "getEnergy()" The following will generate a list of agents whose energy value is less than 4:

User models can implement their own custom Context implementations, either by creating a complete Context interface implementation from scratch, or by extending the Repast DefaultContext class. Extending DefaultContext is the recommended route since the default implementation contains all of the working implementations for the Context interface. User context imlplementations can be used in model code in exactly the same way as the default Repast Context.

Context loading is the process of populating the root model context with agents, projections, and sub-contexts and occurs when a model run is initialized, and may be thought of as the model’s "main" function that assembles the model components. The Repast ContextBuilder interface is used for model implementations that perform context loading:

Models should include a single ContextBuilder implementation. The context argument in the build() method is an instance of the Repast DefaultContext that can be populated and returned. A custom user-defined Context implementation could be created and returned instead of the default provided context.

The ContxtBuilder is called by the Repast runtime at initialization, but the implementing user model class (e.g. MyContextBuilder) is not specified in the scenario.xml file until it is set via the runtime menu option. To specify the user-defined ContextBuilder, see the section on Data Loaders.

There are a couple of approaches to perform model initialization/setup and appropriate method depends on specific modeling needs.

To initialize a model run without user input by say setting model parameters, reading input data, etc, then the ContextBuilder implementation is be the preferred approach since the build(…) method is called once every time the model is initialized or started via the GUI.

To perform any programmatic actions before init/run via the GUI, use a Model Initializer to perform the setup behavior by creating a class that implements repast.simphony.scenario.ModelInitializer. The initialize(…) method is called only once as the Repast GUI is created and before the model init/run button is pushed. The MouseTrap demo model provides an example of using the ModelInitializer.

The Eclipse new class wizard will create a template class with the initialize(…) method in which model initialization code may be included. The ModelInitializer implementation code will execute only once per runtime session, even if the model is reset/restarted and before the ContextBuilder code is executed. The ModelInitializer class needs to be specified in the scenario.xml as follows, assuming the class is named myModel.MyModelInitializer. The MouseTrap demo contains an example of this.

To provide user interaction with the model setup/init before pushing the init/run button, the ModelInitializer could be used to create an external JFrame/Panel that contains custom GUI elements. This approach could be used to store the user input information in a static singleton that is accessible by the model during the ContextBuilder.build().

A common model initialization design is to consider the GUI initialization at tick = 0, the model initialization at tick = 1, and then schedule all model behaviors at tick > 1. This allows the use of the GUI parameters and User Panel to set any model initialization information. A more detailed sequence of events is as follows:

This is similar to the way that actions have always been scheduled in repast with a slight twist. In this scenario, you get a schedule and tell it the when and what to run. An example of adding an item to the schedule this way is as follows:

The biggest change here is that instead of using one of the numerous methods to set up the parameters for the action like you would in repast 3, you just use an instance of ScheduleParameters. ScheduleParameters can be created using one of several convient factory methods if desired. A slight alteration of this is:

This example schedules the same action with the same parameters, but passes arguments to the method that is to be called. The "Forward" and 4 will be passed as arguments to the method move. The assumption is that the signature for move looks like this:

Java 5 introduced several new and exciting features (some of which are used above), but one of the most useful is Annotation support. Annotations, in java, are bits of metadata which can be attached to classes, methods or fields that are available at runtime to give the system more information. Notable uses outside repast includes the EJB3 spec which allows you to create ejbs using annotations without requiring such complex descriptors. For repast, we thought annotations were a perfect match for tying certain types of scheduling information to the methods that should be scheduled. The typical case where you would use annotations is where you have actions whose schedule is know at compile time. So for example, if you know that you want to have the paper delivered every morning, it would be logical to schedule the deliverPaper() method using annotations. Without going into extensive documentation about how annotations work (if you want that look at Java 5 Annotations), here is how you would schedule an action using annotations:

The arguments of the annotation are similar to the properties for the ScheduleParameters object. One particularly nice feature of using annotations for scheduling is that you get keep the schedule information right next to the method that is scheduled, so it is easy to keep track of what is executing when. Most of the time, objects with annotations will automatically be added to the schedule, however, if you create a new object while your simulation is running, this may not be the case. Fortunately, the schedule object makes it very easy to schedule objects with annoations.

The schedule will search the object for any methods which have annotations and add those methods to the schedule. This type of scheduling is not designed to handle dynamic scheduling, but only scheduling, where the actions are well defined at compile time.

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

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.

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

Scheduling using watchers is the most radical of the new scheduling approaches. Watchers are designed to be used for dynamic scheduling where a typical workflow is well understood by the model designer. Basically, a watcher allows an agent to be notified of a state change in another agent and schedule an event to occur as a result. The watcher is set up using an annotation (like above), but instead of using static times for the schedule parameters, the user specifies a query defining whom to watch and a query defining a trigger condition that must be met to execute the action. That’s a bit of a mouthfull, so let’s take a look at an example to hopefully clarify how this works. (this code is from the SimpleHappyAgent model which ships with Repast Simphony)

There is a fair amount going on in this, so we’ll parse it out piece by piece. First, note that there is a @Watch annotation before the method. This tells the Repast Simphony system that this is going to be watching other objects in order to schedule the friendChanged() method. The first parameter of the annotation is the watcheeClassName. This defines the type of agents that this object will be watching. The second argument, watcheeFieldName, defines what field we are interested in monitoring. This means that there is a variable in the class SimpleHappyAgent, that we want to monitor for changes. When it changes, this object will be notified. The query argument defines which instances of SimpleHappyAgent we want to monitor. In this case we are monitoring agents to whom we are linked. For more documentation on arguments for this query can be found at: Watcher Queries. The whenToTrigger argument specifies whether to execute the action immediately (before the other actions at this time are executed) or to wait until the next tick. The scheduleTriggerDelta defines how long to wait before scheduling the action (in ticks). Finally the scheduleTriggerPriority allows you to help define the order in which this action is executed at it’s scheduled time.

Let me give a practical example of how this would be used. Let’s say you are modelling electrical networks. You may want to say that if a transformer shuts down, at some time in the future a plant will shut down. So you make the plant a watcher of the transformer. The plant could watch a variable called status on the transformers to which it is connected, and when the transformer’s status changes to OFF, then the plant can schedule to shut down in the future. All done with a single annotation. It could look like this:

Obviously that is a simple example, but it should give you an idea of how to work with scheduling this way.

Watcher queries are boolean expressions that evaluate the watcher and the watchee with respect to each other and some projection or context. The context is the context where the watcher resides and the projections are those contained by that context. In the following "[arg]" indicates that the arg is optional.

The queries are tested in WatcherQueryTests and defined as annotations in MyWatcher.

The Repast schedule can be stopped or paused by model code, either scheduled at predetermined time, or immediately via some event. The following scheduling options are available:

Creating a grid in Repast Simphony is similar to creating the other projections. Your agents must exist in the context in order to exist in the grid, and you want to create the grid using a factory to make sure that it is initialized properly.

Pass the method a name (so that you can look up your grid later) and the context that will back the grid. But what is that last argument? The gridBuilderParameters. GridBuilderParameters are used to specify the properties of the grid itself, such as its dimensions, its border behavior, and how agents are initially added to the grid.

The GridBuilderParameters class contains a variety of static methods for creating specific types of GridBuilderParameters. For example,

will create parameters for a 10x10 torus where each cell can only have a single occupant. Other static methods (see the javadocs) allow you to create other types of grids. In general though, youwill always have to specify a GridAdder and perhaps a GridPointTranslator when creating GridBuilderParameters. You will also have to specify the dimensions. These will be the last arguments to the method.

An object doesn’t exist in the projection until it is added to the context, and once it is added to the context, it is automatically added to the projection. But where do we put it in the grid? That’s where the GridAdder interface comes in. The adder allows you to specify where to place an object once it has been added to the context. It has a simple method:

In this case, the destination is the type of projection to which we are adding our object (a grid). Object is the object we want to add to that projection. So, <U> is whatever we’re adding. Basically, to implement this interface, you just take in an object and do something with it in the supplied projection. Ok, let’s get a bit more concrete. Let’s say that we have a Grid and when an object is added to the grid, we want to locate it randomly. Here is the implementation for that:

The add method randomly generates locations and puts the objects into that location (assuming the grid allows the object to be there). This little bit of code sets up a random space for you as you add agents. Not surprisingly, this is the code for the RandomGridAdder which comes with Repast Simphony. This behaviour may not be what you want. The most basic Adder we provide is the SimpleAdder; This Adder doesn’t actually locate the object anywhere in the grid. It just allows the object to be used in the grid. The object won’t appear to have a location until you call

This is a very useful adder because you don’t have to know where the agent is supposed to be located in advance. Let’s look at one example of writing your own Adder. In this case, let’s assume that our agents have their grid coordinates stored. The adder just needs to use those coordinates to locate the agents properly. We’ll call the Interface Located:

Let’s write an adder that knows how to work with this:

This will add the object to the grid at the location specified by the agent itself. This doesn’t handle any errors or anything, but it should give you an idea of how to create your own adder.

A GridPointTranslator determines the border behavior of a grid. The border behavior is what happens when an agents moves past the border of a grid. Five kinds of border behavior classes are described below together with a description of how the behave in response to a Grid’s moveTo and moveBy (the moveBy methods are moveByDisplacement and moveByVector) methods.

Movement on the grid is accomplished with 3 methods.

This specifies the object to move and the new location to move to. It will return true if the move succeeds, for example, if the location is unoccupied an single occupancy grid and the new location doesn’t violate any border behaviors. This method can be used to introduce objects into the grid if they do not yet have a grid location. This will throw a SpatialException if the object is not already in the space, if the number of dimensions in the location does not agree with the number in the space, or if the object is moved outside the grid dimensions.

Moves the specified object from its current location by the specifiedamount. For example, moveByDisplacement(object, 3, -2, 1) will move the object by 3 along the x-axis, -2 along the y and 1 alongthe z. The displacement argument can be less than the number of dimensions in the space in which case the remaining argument will beset to 0. For example, moveByDisplacement(object, 3) will move the object 3 along the x-axis and 0 along the y and z axes, assuming a 3D grid. This will return the new location as a GridPoint if the move was successful, otherwise it will return null. Like moveTo it will throw a SpatialException if the object is not already in the space or if the number of dimensions in the displacement is greater than the number of grid dimensions.

Moves the specifed object the specified distance from its current position along the specified angle. For example, moveByVector(object, 1, Direction.NORTH) will move the object 1 unit "north" up the y-axis, assuming a 2D grid. Similarly, grid.moveByVector(object, 2, 0, Math.toRadians(90), 0) will rotate 90 egrees around the y-axis, thus moving the object 2 units along the z-axis. Note that the radians / degrees are incremented in a anti-clockwise fashion, such that 0 degrees is "east", 90 degrees is "north", 180 is "west" and 270 is "south." This will return the new location as a GridPoint if the move was successful, otherwise it will return null. Like moveTo it will throw a SpatialException if the object is not already in the space or if the number of dimensions in the displacement is greater than the number of grid dimensions.

Creating a continuous space in Repast Simphony is similar to creating the other projections. Your agents must exist in the context in order to exist in the continuous space, and you want to create the continuous spaceusing a factory to make sure that it is initialized properly.

Pass the method a name (so that you can look up your space later) and the context that will back the continuous space. Like the Grid, an Adder must be specified as well as a PointTranslator and the dimensions of the space.

Like most projections, an object doesn’t exist in the projection until it is added to the context, and once it is added to the context, it is automatically added to the projection. But where do we put it in the continuous space? That’s where the ContinuousSpaceAdder interface comes in. The adder allows you to specify where to place an object once it has been added to the context. It has a simple method:

n this case, the destination is the projection to which we are adding our object (ContinuousSpace). Object is the object we want to add to that projection. So, <U> is whatever we’re adding. Basically, to implement this interface, you just take in an object and do something with it in the supplied projection. Ok, let’s get a bit more concrete. Let’s say that we have a ContinuousSpace and when an object is added to the continuous space, we want to locate it randomly. Here is the implementation for that:

The add method randomly generates locations and puts the objects into that location (assuming the grid allows the object to be there). This little bit of code sets up a random space for you as you add agents. Not surprisingly, this is the code for the RandomCartesianAdder which comes with Repast Simphony. This behaviour may not be what you want. The most basic Adder we provide is the SimpleCartesianAdder. This Adder doesn’t actually locate the object anywhere in the grid. It just allows the object to be used in the grid. The object won’t appear to have a location until you call

This is a very useful adder because you don’t have to know where the agent is supposed to be located in advance.

Let’s look at one example of writing your own Adder. In this case, let’s assume that our agents have their continuous space coordinates stored. The adder just needs to use those coordinates to locate the agents properly. We’ll call the Interface Located:

Let’s write an adder that know how to work with this:

This will add the object to the grid at the location specified by the agent itself. This doesn’t handle any errors or anything, but it should give you an idea of how to create your own adder.

Just like the GridPointTranlator described on the Grid’s page, a PointTranslator determines the border behavior of a continuous space. The border behavior is what happens when an agents moves past the border of a continuous space. Five kinds of border behavior classes are described below together with a description of how they behave in response to a continuous space’s moveTo and moveBy_ (the moveBy_ methods are moveByDisplacement and moveByVector) methods.

Networks are created using a NetworkBuilder. The NetworkBuilder class allows the user to tune the network creation to create specific kinds of networks. This "tuning" is done by calling various methods on the builder. If none of these methods are called then a simple "plain vanilla" network is created. For example,

The first argument to the builder constructor is the name of the network, the second is the context which the network "projects" and the last is whether or not the network is directed. By default, the addEdge(source, target, …) methods of a network will create and use an instance of RepastEdge as the edge between the source and target.

Using the builder, you can customize this edge creation process by specifying an EdgeCreator on the NetworkBuilder. The EdgeCreator interface looks like:

The intention is that the user implement the createEdge method to customize the edge creation process. All edges created on the network via addEdge(source, target, …) will forward edge creation to this method. Specifying the edge creator on the builder looks like:

Any networks created using this builder will then use that EdgeCreator.

Networks can also be loaded from a file. Currently, the builder can load networks from UCINet’s dl format or from Excel. The relevant methods in the NetworkBuilder are:

The NodeCreator in the above is used to perform the actual node / agent creation based on the information in the network file. These nodes are added to the context and edges between them are created using the link data from the file. The NetworkFileFormat is either NetworkFileFormat.DL or NetworkFileFormat.EXCEL, although more formats may be added in the future. The Excel file format is described below.

An example of the network builder loading a file:

Lastly, a NetworkGenerator can be set on the NetworkBuilder. NetworkGenerators typically assume that the context already contains the nodes / agents and the generator arranges them in the appropriate topography (e.g. a Small World). For example,

The arguments to the generator are the probability of rewiring the network, the local neighborhood size, and whether or not generated edges will be created symmetrically. We then create a NetworkFactory and use that to create the network, passing it the network name, the context, the generator, and whether or not the resulting network will be directed. In this case, the generator creates a small world type network using the agents in the context as nodes.

See the repast.simphony.context.space.graph package for more information on NetworkGenerators and what is available.

Once you have a network, you can always add Relationships, but that’s not really that useful until you can query based on the relationships. The Network library provides all of the methods you would expect to have to access the objects and relationships in it. The particular methods in which you will be interested are:

In addition to these, there are also many other methods. See the javadoc for Network for more info.

Moving a Geography is typically accomplished using the following method

The first time this is called for an agent that agent is moved into the Geography and associated with the specific geometry. The specific geometry establishes the agent’s location in the geographical space and subsequent queries of the Geography will make use of that Geometry. If this is the first time an agent of this Class has been move in the Geography that type of agent will become associated with that Geometry type. For example, if the agent’s type is the Java class anl.model.Truck, and the Geometry is a Point, then all Trucks are considered to be Points and any Truck moved in the Geography must have a Point geometry.

An agent’s current Geometry (i.e. its location) can be retrieved with:

This returned Geometry can be used to move the agent without recreating a Geometry and passing that new Geometry to the move method. For example, where "this" refers to an agent,

In this case, we know the Geometry is a Point and so it has a single coordinate whose x and y values we can change. Note that its important to call move here to register the move with the Geography. Geography has additional move methods that can move by displacement etc.:

A Geography can also be queried spatially to return the objects within a particular envelope.

Additional queries are available for getting agents that intersect another agent or geometry, for getting the agents that touch another agent or geometry, and so on. See the classes in the repast.simphony.query.space.gis package for more information.

Agent geometry data can be loaded from standard ESRI shapefiles using the GeoToos API. An exmaple of creating a list of features from a shapefile filename string is provided below.

After the list of SimpleFeature objects is obtained, they can be assigned to the agent geometry in the Geography projection via:

Repast Geography projections support geolocated 2D grid coverage layers that provide storage and reference of integer and floating point data. Coverage layers can be stored in a Geography projection as a GeoTools GridCoverage2D via:

The Geography.addCoverage(…) method assigns the provided coverage and name to the Geography and can be later referenced using:

Repast Geography supports any valid GridCoverage2D as described by the GeoTools API.

Instances of GridCoverage2D usually created through the GeoTools API from various file loaders are typically read-only and cannot be modified in memory. The RepastCoverageFactory provides a number of static methods for creating writable coverages that can be both written to and read from using agent code. For example, to create a 2D coverage of size 10x10 grid cells with float data and data range of 0-10:

The env argument is a Geotools ReferenceEnevelope that defines the lat/lon coordinates of the grid coverage, for example:

The float and double-precision coverage layers support any continuous data values up to the maximum allowed by the respective data types. GIS raster data can also be (and is often) stored as discreete category type data using integer or byte data. The RepastCoverageFactory provides the ability to create writable indexed coverages with user-defined category data. For example:

Finally, writable coverage layers can be loaded from raster data files using:

Repast Network projections can be displayed on a GIS display just like any other Repast Display type using the runtime Display wizards. In this case no additional code is required since the GIS display will handle the layout of the network. However, there are scenarios where a modeller might want the Geography projection to be "aware" of Network projection data and events, say in the case of performing an intersection query between a network line and an agent geometry.

Repast provides a utility class GISNetworkListener that couples a Geography and Network and updates the Geography when Network events occur. The GISNetworkListener will create and move line geometries in a Geography Projection when changes occur in a Nework. GISNetworkListener is used as follows:

GISNetworkListener does not need to be storred locally as it assigns itself as a projection listener on both the network and the geograhy. GISNetworkListener should be called before any network or geography objects are added. When agents move in a geograhy, the GISNetworkListener will automatically update the location of the network edge line geometries in the geograhy. Additionaly, when network edges are created or destroyed, the GISNetworkListener will automatically create or destroy the associated line features in the geograhy.

Like many of the other registries in Simphony, the RandomRegistry is available through the current RunState (through its getRandomRegistry() method). This interface provides the capability for storing named random distributions and retrieving them. It also can set and retrieve the seed that a stream will use (or is using) for streams it creates through its addStream(String, Class, …) methods.

The RandomRegistry by itself is somewhat difficult to work with, to simplify using it the RandomHelper class was created. This provides methods for creating the random streams that will be used, and for retrieving the streams after they have been created, when you do not have a reference to the current RunState.

Through its getStream, getUniform and getNormal methods, you can retrieve distributions from the current RandomRegistry. Through its numerous createXXX methods, you can create the distributions and store them to the current RandomRegistry.

The RandomHelper also handles creating and maintaining a default Uniform number stream. This stream is the one used by Repast when it needs a random number, and is no different then the other Uniform number streams, except that it will always exist when requested from the RandomHelper (when the simulation is running). If you wish to use a Uniform distribution for your random numbers, you can avoid some of the extra work that comes with the named streams (meaning, specifying the name of the stream, and possibly casting the stream) by simply using RandomHelpers' getDefault, nextInt, and nextDouble methods. You also can retrieve and/or set the seed for the default stream through the RandomHelper’s getSeed and setSeed methods.

Generally there are going to be two types of usage of the random functionality. The first would be when you just need random numbers of some sort. In this case you would just want to use RandomHelper’s default methods, meaning the getDefault(), nextInt and nextDouble methods.

The other case is when you want numbers from a non-Uniform distribution, or you want multiple random streams functioning at once. In this case you can use RandomHelper’s default methods for any uniform numbers, but for producing multiple streams or a non-Uniform stream you have to use the methods that take in a stream name. Each of these separate cases will be walked through next.

When working with the default Uniform stream there is really only one thing you may want to look at manipulating, the default stream’s random seed. This is set through the RandomHelper’s setSeed(int) method. Setting the random seed should generally happen when the model is setting up. There are two ways you can do this. One way is in a ControllerAction, but if you wish to use the random numbers in setting up the model you will not have your seed set ahead of time. The other (correct) way is in a ParameterSetter.

In the ParameterSetter you are going to want to call RandomHelper’s setSeed method, as below:

The above code will set the default uniform distribution’s seed to be the current time. Now that the time is set, the agents or controller actions (in their runInitialize methods) can use the default distribution and will recieve numbers based off of that seed. For example if you had an agent that wanted to move based on some random condition, that could look like:

The above example compares the agent’s happiness to a random number between 0 and 1, in (0, 1), if the random number is greater than the agent’s happiness it will move.

Advanced applications that require multiple different random streams can use RandomHelper’s registerGenerator(String, int) method. This method will create a new random stream (a RandomEngine) with the specified name and seed.This stream can then be used to create distributions. See Simphony’s DefaultRandomRegistry implementation for examples of how to create distributions from the RandomEngine. RandomHelper’s registerDistribution(String, AbstractDistribution) and getDistribution(String) methods can be used to store and retrieve custom distributions in and from the RandomHelper.

For example,

The scenario tree in the Repast runtime GUI provides access to wizards and menus for creating and modifying runtime components like charts, displays, and data logging. The Repast runtime components reflect the state of the model simulation in various ways, like displaying the positions of the agents in space. The Repast runtime components do not actually have an effect on model behavior, except for when the parameters or custom user panel components are adjusted. In other words, creating a chart or a display, or an absence of these components, will not affect model behavior.

The scenario tree contains a fixed set of available runtime components including time series and histogram charts, data loaders, data sets, displays (2D, 3D, GIS), file (data) sinks, and User Panel options. Right clicking on any of the top-level component categories provides the option to create new entries for each. Double clicking on existing entries in each category will provide access to specific options.

The scenario tree is just one of the available runtime interfaces available in the left panel of the runtime window. Additional panels can be accessed by clicking on the named tabs in the left side panel for Run Options, Parameters, and User Panel.

The runtime run options panel provides access to options for controlling the model run state. These include:

The parameters panel shows the list of available model parameters and their values, and allows each parameter value to be changed before or during a model run. Model parameters will typically be represented in the GUI by an editable text box with the current value, or a check box that can be toggled for boolean true/false values, or a fixed list of allowed values, depending on how the parameters are defined. When a model is initialized or reset, the parameter values are set to their default values. Parameter values can be changed before or after a simulation is started, however the impact on model behavior id dependent on how the model parameters are accessed in the model code. In one model, the parameters might only be read during initialization in which case changing parameter values after the model has started will have no affect on behavior. In another model, the design could incorporate a check of model parameters at regular intervals and in this case changing parameter values after the model has started would affect behavior.

Repast Simphony records data from data sources of two types - Aggregate and Non-Aggregate. Aggregate data sources receive a collection of objects (agents, for example) and typically return an aggregate value derived from the set of all of the objects. For example, an aggregate data source might call a method on each object and return the maximum value or mean of all values. A non-aggregate data source takes a single object (e.g. a single agent) and returns a single value for each object. For example, a non-aggregate data source might call a method on an agent and return the result of that method call. Data sources are grouped into named data sets. A data set is a collection of data sources.

Once a data set is defined, the Repast runtime will record the data produced by the data set’s data sources. However, the recorded data will not be written to a file or displayed in a chart. For that to occur, a Text Sink must be defined. A text sink takes the data produced by data sources and writes them to a file or the console. Similarly, a Chart may be used to display the data set content in a time series or histogram. A single data set can be connected to multiple text sinks and charts.

Data sets allow the Repast runtime to record model data in memory, but data sets themselves do not provide access to the data in a human-readable format and their contents are lost when the Repast runtime is closed. Data set content can be directed to Text Sinks that will direct the data to either the Eclipse program console or to an output file. Console output will show up in Eclipse’s console tab and can be useful for debugging.

Repast allows you to create two different kinds of charts: time series and histograms.

Repast displays can be used to visually represent agent locations in 2D space, 3D space, and GIS projections. Additionally, continuous space, grid, and value layer projections, along with network projections can be combined together in displays to create visually rich representations of the agent world.

Creating displays involves the following common steps to specify:

Repast Simphony supports the creation of a parameter sweep through an xml file or through a scripted bsf file. Both define a sweep through the defintion of parameter setters. These setters may be constant setters such that the parameter value remains at its initial value, or the setters may define a list of values to sweep through, or lastly the setter may function as a numeric stepper that incrementally steps from an initial value through some ending value. These setters are organized in tree such that the sweep defined by a child is fully iterated through before the parent is incremented.

Individual parameters are identified as parameter elements and have two required attributes: name and type.

Currently 3 types of parameters are supported.

will start with a value of 1 and increment by 1 until 4 is reached. The type of number (long, double, float and integer) is inferred from the start, end and step values. If any of the values ends with f, for example

the parameter will be of the float type. Similarly, if any of the values end with L, the type will be a long. In the absence of a "f" suffix, if any of the numeric values contain a decimal point and one or more digits (e.g. 4.0) then the type will be a double. Otherwise, the type will be int.

The sweeper will iterate through the values in the list setting the parameter to that value.The value_type attribute defines the type of the list elements and can be one of string, boolean, double, int, long, float. Elements are delimited by a blank space. String elements can be surrounded by single quotes (') if they contain blank space. For example,

The sweeper will set the parameter to this constant value. The constant_type attribute defines the type of the constant value. A constant type of "number" works as its does above where the specified type of number (float and so forth) is derived from the value itself.

Parameters can be nested such that the space defined by the child or nested parameter will be swept before incrementing any values in the parent parameter at which point the child will be reset to its starting value. For example,

In this case, the sweeper will do set numAgents to 1000 and then sweep through each of the the wealth values. Then it will increment numAgents to 1010, and sweep through all the wealth values. It will continue in this fashion until numAgents reaches its end value. In this way, the simulation is run such that all the combinations of numAgents and wealth values are explored.

The default random seed (i.e. the seed for the default random stream) can be specified in a parameter file using a number type parameter with a name of "randomSeed". For example,

If no such parameter exists, the batch mechanism will set the random seed to the current time in milliseconds.

Controller actions can be added and integrated into the controller tree via plugin extension points. The repast.simphony.core plugin defines the following:

The repast.simphony.gui plugin extends these two extension points with:

These extend the above by adding gui related parameters. * composite.action adds a label parameter the value of which will be the label for the parent action as it is displayed in the controller action tree.

All the controller actions in repast simphony are added via this mechanism so examining their plugin.xml files and related code is a good place to learn more.

I’ve made a wizard framework that dynamically loads its options based on "options" specified in plugin.xmls. I’ve used it in enough places that I’ve gone ahead and generalized it. If you wish to use this setup I made it fairly straightforward. The classes used in this are in the repast.simphony.plugin.util plugin and in the repast.simphony.plugin.wizard package. These classes are WizardOption and WizardPluginUtil, DynamicWizard, and some related to the wizard’s model (DynamicWizardModel, WizardModelFactory).

WizardOption represents an option that will be taken in a wizard. It contains a SimplePath (the GUI steps the wizard will take) and some description methods (for grabbing the title and description of the option). Generally someone will subclass/subinterface this interface with their own type (say MyWizardOption) and add any extra methods to it. Implementations of WizardOption (or MyWizardOption) would generally specify their description (to be in tooltips or a description field in the wizard option selection) and a title (for the option’s title in a "Choose type" list), and then fill in the other methods as needed. The implementation would also build the steps it needs (say select file name or select agent class steps) in getWizardPath and return them.

The only method in WizardPluginUtil is the only one needed to dynamically load up the wizard options. This takes in the plugin id, the extension point id where wizard options would be registered, the specific WizardOption class the options should be an instance of, a PluginManager that the extension points would be grabbed from, and finally a boolean parameter that specifies whether or not to register the options with the DynamicWizard (this is important for using the DynamicWizard, and generally should be true). This assumes the extension point will have a class field specified in it, so it could look like so:

Or alternatively, you can just create a new extension point inherting its properties off the default one:

And extensions would then look like (assuming the plugin id is repast.simphony.data)

To load these options you have to call the WizardPluginUtil method from some point where you have access to the PluginManager. For now the best way to do this is from a menu or other item action creator. Hopefully at some point a more generic method will exist. You then can store the loaded options somewhere so that you can have direct access to them if you desire. So for instance this could look like

Finally, to actually display a wizard that uses these options you use DynamicWizard. There are a lot of arguments in the DynamicWizard as of now, so it is best to wrap the creation of the wizards in some other static method. So an example method could look like:

This will create a wizard that has its options stored with the key WIZARD_OPTIONS_ID, scenario and contextID (just general properties), the specified title for the wizard’s select an option step, and specified prompt for that same step, a final "wizard has completed" step, and a factory for generating the model used by the wizard (in this case a ChartWizardModel).

Each of these properties plays their own role in the wizard process. Explicitly, the important ones and their function (from this example):

When building a new Projection, some things should be done if it is to be integrated into the whole system. In particular, if it is to be freeze dryable, some special considerations may need to be made. Since the freeze dryer generally just writes out all the fields of an object, this may or may not function properly for a given Projection. For a projection to be properly freeze dryed one of the following has to happen:

All a ProjectionDryer does is store the settings from a custom Projection into a map, and later rebuild a projection from a map (with the same settings). Implementations store properties in the addProperties method, rebuild the projection in instantiate, and restore properties in the loadProperties methods.

The addProperties method should add implementation specific properties to the passed in Map. For instance, in a Network these properties could be a list of edges in the network. This would be something of the form "edges"→node1. So it would be implemented by:

The super call lets the class’s superclass (assuming it is not ProjectionDryer) add any neccessary properties. It then builds a list of the edges, storing the properties in an array. Finally it stores to the properties map the list of edges.

At some later point the context will be rehydrated and the projection will need to be rehydrated. First the projection will need to be instantiated, and accordingly, the instantiate method would be called. For our MyNetwork class this may be something like this:

This simply fetches the projection’s name (which will be stored in ProjectionDryer’s loadProperties method - another reason why it’s important to call the super’s method!) and then creates the network with that name. Next the network’s properties need to be loaded, which, according to our addProperties method will be like so:

In this method we first are calling the super’s load properties method (so that things like listeners and any other settings will be loaded), then we fetch the edge information from the properties map (the ArrayList… = line), and finally we add the edges into the given network. Note that we may have to cast the properties if the network requires specific types in its methods (for instance if the weight is a Double or double as in this example). Now the Projection will be added into the context and the rehydration process will continue on.

The different kind of dryers need to be registered in different kinds of ways. If you create a custom FreezeDryer, you must register that dryer to any FreezeDryer instance you create. If you have created a custom ProjectionDryer, you must register it to the ProjectionDryer class by calling its addProjectionDryer method.