Skip to content

Home

Jump to bottom Edit New page
tjiagoM edited this page May 6, 2016 · 12 revisions

trasmapi

TraSMAPI is a generic API used as bridge for microscopic traffic simulators (what is a microscopic simulator?) that allows real-time communication between agents in the urban traffic context (such as vehicles, traffic lights and pedestrians) and the environment created by various simulators. This tool was developed at LIACC (Artificial Intelligence and Computer Science Laboratory), University of Porto.

This API offers a higher level of abstraction than most microscopic traffic simulators, in such a way that the solution is independent from the simulator in use.

Table of contents

Supported Simulators

Currently, TraSMAPI only works with three microscopic simulators: SUMO, AIMSUN and ITSUMO. To learn how to run the TraSMAPI API for the available simulators please have a look at their respective repository:

Usage

TraSMAPI is written in Java. To use it in your project, create a trasmapi folder/package and clone the genAPI folder into there. After that simply implement the methods specified in the API according to the simulator you are using. As previously mentioned, this specialisation already exists for some simulators.

Basics and Ad-hoc Systems

As TraSMAPI was developed with object oriented design at its core, both the simulation objects and the simulator itself are objects of the language.

Initialisation and Configuration

Any system developed based on this tool will have an instance of the class TraSMAPI. Inside the application, it represents the simulator and any communication with the simulator in general will be made through this instance. A typical setup of the system would be the following code:

TraSMAPI api = new TraSMAPI(simulatorParam); 
List<String> params = new ArrayList<String>();
params.add(stringParam);
api.launch(params);
api.connect("localhost", 8820);

In this example, simulatorParam is used to specify the simulator TraSMAPI will use. Subsequently, the simulator is executed with parameters corresponding to a given stringParam. The parameters in particular change from simulator to simulator. In reality, the launch method is optional, as the simulator might be executed independently of TraSMAPI. After being executed, we request TraSMAPI to connect via sockets to the simulator using the method connect.

Basic Simulation Controls

The basic operation in simulation control is the request to execute a new simulation step. That is achieved though the simulationStep method. A typical execution cycle would look like this:

while(true)
{
   if(!api.simulationStep(0))
      break;
}
api.close();

The close method is called with the objective of closing the connection to the simulator. If the simulator was launched though the framework, then it will also be closed

Interaction with simulation elements

The majority of the simulation elements can be manipulated by associating them with objects of the language. Please look into the documentation of each supported simulator in order to understand how to achieve this.

Multi-Agent System Support

The importance of a multi-agent system (MAS) in this domain has been extensively covered in the literature. You can use TraSMAPI's MAS module for developing these systems.

Initialisation of a Multi-Agent System

The multi-agent system is composed of a main controller (an instance of the Mas class) and a series of agents registered in it. (through the addAgent method) During the configuration of the system we need to instantiate several controlling elements, being the main cycle of the system similar to the one presented below:

Mas mas = new Mas();
mas.addAgent(new TrafficLightAgent());
mas.start();

while(true)
{
   if(!api.simulationStep(0))
      break;
   mas.step(1);
}
        
mas.close();
api.close();

Agent Specification

In the previous excerpt, please pay special attention to the use of the agent TrafficLightAgent. System agents correspond to classes derived of the superclass Agent and implement a set of specific methods. This would be a typical agent declaration:

public class TrafficLightAgent extends Agent
{
   public void init()
   {
      (...)
   }
    
   public void action()
   {
      (...)
   }
    
   public void newMessage()
   {
      (...)
   }
    
   public void close()
   {
      (...)
   }
}

There are four methods that must be implemented:

  • init() is executed when Mas.start() is called. At this time, the developer must be declare the variables which correspond to simulation elements (traffic lights, lanes, induction loops, etc.). This is also where the agent should interacts with agents already in the simulation, exchanging messages relative to the strategy to be applied.
  • action() is called at each simulation step; the agent usually queries the simulator and acts upon it.
  • newMessage(). Although the agent might read his own inbox at the execution of the action() method, this method is called whenever a new message is delivered; urgent messages that need to be processed in this simulation step shall be treated here.
  • close(): this method is executed at the end of the simulation, when Mas.close() is called. The agent must save any persistent information required for the next execution.

Messages between Agents

Agents may exchange objects of the type Message (or subclasses) between them, through the methods broadcast(Message) or sendMessage(Message, AgentId).

New messages may be read through the method getMessage(); a typical reading cycle will look like this:

public void newMessage()
{
   while (getNumMessages() > 0)
   {
      Message m = getMessage();
      (...)
   }
}

An agent may obtain the sender through the getFrom() method. As the messages may be subclasses of the class Message, there is no need to parse them. The sender agent encapsulates the information in variables to be read by the receiver.

Integrating TraSMAPI with JADE

We are still working in this part of the documentation

Statistics Module

We are still working in this part of the documentation

Contributing

We appreciate any help you could give by improving our code, documention, or by simpling creating an issue. If you wish you can contact us at [email protected]

Supporting a New Simulator

We don't have any instructions for this. For the understanding of how you could do a new extension to TraSMAPI, have a look in the supported simulators.

Submitting a Pull Request

  1. Fork it.
  2. Create a branch (git checkout -b my_trasmapi)
  3. Commit your changes (git commit -am "Added message type")
  4. Push to the branch (git push origin my_trasmapi)
  5. Open a Pull Request
  6. Enjoy a refreshing Diet Coke and wait

Published papers

License

Copyright 2016 STEMS-group

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Add a custom footer
Add a custom sidebar
Clone this wiki locally