RinSim

RinSim is an extensible MAS (Multi-Agent System) simulator. It supports pluggable models which allow to extend the scope of the simulator. Out of the box, RinSim currently focusses on MAS for PDP (Pickup and Delivery Problems). You can easily extend RinSim by introducing your own custom models.

Getting Started

Prerequisites

To use RinSim, you need the following:

Note: if you install the latest Eclipse IDE for Java Developers, the m2e and eGit plugins are preinstalled, but not PDE. If you install Eclipse IDE for Java EE Developers or Eclipse Classic, PDE will be preinstalled, but not m2e or eGit.

• eclipse
• m2e Maven plugin for eclipse.
  • Update site:

http://download.eclipse.org/technology/m2e/releases

• eGit Git plugin for eclipse (or another git client)
  • Update site:

http://download.eclipse.org/egit/updates

• PDE (Eclipse Plug-In Development Environment)

To install m2e and eGit:

• Go to Help -> Install New Software...
• Click Add...
• Enter the update site in location and enter any local name for the update site.
• Select the desired packages and install.

To install PDE

• Go to Help -> Install New Software....
• In Work with, click the drop down and select Indigo - http://download.eclipse.org/releases/indigo (or the update site for your eclipse release).
• Search for plug-in.
• Install the Eclipse Plug-In Development Environment.

Getting RinSim

RinSim is hosted on gitHub. You can get it using eGit (the eclipse plugin) or git.

(If you are using a pc from the lab and cannot install eclipse plugins, you can find a zipped workspace here. You should open this workspace as a workspace in eclipse File -> Switch Workspace -> Other... Using this zipped workspace is not the recommended method, since you cannot update RinSim.)

Using eGit

• Go to File -> Import...
• Select Git -> Projects from Git and click next.
• Select URI and click next.
• Enter

git@github.com:rinde/RinSim.git

in the URI field, select https as protocol, and click next.

• Select the v2 branch and click next.
• Choose a local directory for your project and click next.
• Wait for eGit to download the project.
• Make sure Import existing projects is selected and click next.
• Click finish.

You will now have one project in eclipse. See Importing the Maven projects in eclipse on how to actually use it.

To update the simulator later on, right-click on the top-level project, go to Team and select and select Pull.

Using Git

• Open a terminal.

• Navigate to the directory where you want to store the RinSim project.

• Execute the following git command

   git clone git@github.com:rinde/RinSim.git -b v2
  

  This will download all the source files of the RinSim project to you local directory.

To update the simulator later on, you can use the pull command:

git pull origin v2

Note that git might require you to first commit your own changes.

Importing the Maven projects in eclipse

RinSim relies on Maven to load all required dependencies. To make use of Maven in eclipse you have to execute the following steps:

• In eclipse go to File -> Import... -> Maven -> Existing Maven Projects.
• Browse to your local RinSim directory.
• You will now see a list of .pom files.
• Select the .pom files for core, example, and ui.
• Click Finish.

After finishing the import, you should see the following three projects in your workspace:

• core: the heart of the simulator and the models.
• ui: everything related to visualizing stuff for the simulator.
• example: some simple examples of how to use the simulator.

Running the example

Execute one of the examples in the example project.

• Right-click on Example.java or RandomWalkExample.java and select Run As -> Java Application
• You should now see a map of Leuven. Agents and other objects on the map are represented by dots.
• Use the menu or keyboard shortcuts to start, stop, speedup or slowdown the simulation.

Simulator Architecture

This section gives a brief overview of the most important elements of the simulator. For a deeper understanding you should have a look at the examples, the source code, and the tests. A simplified class diagram of the key elements can be found here.

Simulator

The Simulator class is the heart of RinSim. Its main concern is to simulate time. This is done in a discrete manner. Time is divided in ticks of a certain length, which is chosen upon initializing the simulator (see examples and code).

Of course time on its own is not so useful, so we can register objects in the simulator, such as objects implementing the TickListener interface. These objects will listen to the internal clock of the simulator. You can also register other objects, as we will see in a moment.

Once started, the simulator will start to tick, and with each tick it will call all registered tickListeners, in turn, to perform some actions within the length of the time step (as illustrated here).

As you can see there is also an afterTick, but we'll ignore this for now.

Apart from simulating time, the simulator has little functionality on its own. All additional functionality (such as movement, communication, etc.) that is required by your simulation, should be delegated to models. These models can be easily plugged (or registered) in the simulator.

Models

Out of the box, RinSim comes with two basic models: RoadModel and CommunicationModel. Further on, you will see how you can implement your own models.

• RoadModel: simulates a physical road on top of a Graph object. A Graph object represents the structure of the roads. The RoadModel allows to place and move objects (RoadUsers) on the roads. The RoadModel can, for example, be used to simulate physical trucks and packages.

• CommunicationModel: simulates simple message-based communication between objects implementing the CommunicationUser interface. It supports both direct messaging and broadcasting. It can also take distance, communication radius, and communication reliability into account. Messages between agents are send asynchronously (as illustrated here).

GUI

The GUI is realized by the SimulationViewer, which relies on a set of Renderers.

• SimulationViewer: is responsible for rendering the simulator. By default, if a RoadModel is registered in the simulator, it renders the road of the loaded graph. Additional rendering is done by application specific renderers that are passed on creation of the GUI (see examples and code).

• Renderer: is responsible for rendering one model (or more). Examples are the ObjectRenderer to do basic rendering of objects in the RoadModel, or MessagingLayerRenderer to visualize messages between agents. When introducing new models you can create new custom renderers for these models.

Simulation Entities

Simulation entities are entities that are the actual objects in our simulation, such as agents, trucks, and packages. They can implement the TickListener interface and/or other interfaces to use additional models. Once registered in the simulator, the simulator will make sure they receive ticks (if required) and are registered in all required models (see the example below).

A simple example

The following code illustrates how a simulator can be created. A sequence diagram can be found here.

//create a new random number generator
MersenneTwister rand = new MersenneTwister(123);

//create a new simulator
Simulator simulator = new Simulator(rand, 1000);

//load graph of Leuven
Graph<MultiAttributeEdgeData> graph = DotGraphSerializer.getMultiAttributeGraphSerializer(new SelfCycleFilter()).read(MAP_DIR + "leuven-simple.dot");

//create a new road model for Leuven and register it in the simulator
RoadModel roadModel = new RoadModel(graph);
simulator.register(roadModel);

//create a new communication model and register it in the simulator
CommunicationModel communicationModel = new CommunicationModel(rand);
simulator.register(communicationModel);

//configure the simulator
//after this call, no more models be registered in the simulator
//before this call, no simulation entities can be registered in the simulator
simulator.configure();
		
//create some agent and register it in the simulator
SomeAgent agent = new SomeAgent();
simulator.register(agent);
				
//create a ui schema used by object renderer
UiSchema schema = new UiSchema();
//some agents will be red
schema.add(SomeAgent.class, new RGB(255,0,0));
		
//start the GUI with a simple object renderer
View.startGui(simulator, 5, new ObjectRenderer(roadModel, schema, false));

How to create a model

available soon

Additional guidelines

Maps

On this page a number of maps are made available.

Using gitHub's issues to report changes

You can use gitHub's issue feature to report problems, bugs, or useful features for RinSim.

Remember:

• The issue system should only be used for stuff directly related to RinSim, not for questions about the MAS course or for questions on how to do stuff with RinSim. You can use Toledo/lab sessions/fellow students for this.
• Check if your issue has already been reported.
• Be precise in the description of your issue.
• When reporting a bug, give sufficient information on how to reproduce the bug.
• Think twice before creating a new issue.

more guidelines available soon

Making pull requests for RinSim

available soon