Events are a central concept in MATSim, as they are the only way for feedback from the mobility simulation to the behavioral modules.
The following types of events must be generated by a mobility simulation:
| id | name | data |
| 0 | arrival | time, agent-id, link-id, leg-id |
| 2 | left link | time, agent-id, link-id |
| 3 | stuckAndAbort | time, agent-id |
| 4 | wait2link | time, agent-id |
| 5 | entered link | time, agent-id, link-id |
| 6 | departure | time, agent-id, link-id, leg-id |
Counting of leg-ids begins at 0 (zero).
The following types of events are currently optional:
| id | name | data |
| 7 | actstart | time, agent-id, link-id, act-type |
| 8 | actend | time, agent-id, link-id, act-type |
| 9 | agentUtility | time, agent-id, utility |
leg-id should not be an obligatory data field, but it is currently requested by planomat.exe. Additionally, planomat.exe requires the events to be stored in a text-file (not XML!) and that the description is the same as the aforementioned name.
open questions
please comment to these questions with "add comment" (see below).
Die korrekte zeitliche Reihenfolge von Events muss lediglich pro Agent eingehalten werden. Ein Event mit Zeit t1 eines Agenten a1 darf also nicht nach einem Event mit Zeit t2 des selben Agenten a1 ausgelöst werden, wenn t1 < t2. Zwischen unterschiedlichen Agenten muss diese Reihenfolge aber nicht eingehalten werden.
Dies geht davon aus, dass das Event-Handling zentralisiert ausgeführt wird und bei dieser zentralen Stelle die Events in der entsprechenden Reihenfolge eintreffen müssen.
All events, that were issued in a simulation-run, should be passed along to an instance of the class org.matsim.evens.Events. This is done by creating a new event and then calling computeEvent() method of your instance of Events.
Example:
Events myEventManager = new Events(); EventLinkEnter test = new EventLinkEnter(time, agentId, linkId); Events.computeEvent(test);
The Events instance will then take the event and forward it to every EventHandler, that wants to receive events of this kind.
To receive events out of the simulation, you have to write your own event-handler as described below.
Building a new eventhandler that uses already existing events
If you just want to receive any of the already defined events, it is an easy task:
EventHandler...I interface that you want to get to know about.Events.addHandler(EventHandlerI handler).Hazard: Be aware, that if you overload some special EventHandler ...I interfaces and the BasicEventHandlerI than the special interfaces will receive the appropriate events and the handleEvent(BasicEvent event) receives the SAME event a second time. This will get optionally in a later verion.
Remark: Instead of overloading several EventHandler...I interfaces it sometimes might be easier just to overload BasicEventHandlerI and to check the events in an if clause like this:
if(event.getClass() == EventAgentNoRoute.class) {
...
} else if(event.getClass() == EventAgentArrival.class) {
...
} else if(event.getClass() == EventLinkLeft.class) {
...
}
Example:
class CountLinkTravelTimes implements
EventLinkEnterHandlerI,
EventHandlerLinkLeft {
public void handleEvent (EventLinkEnter event) {
...
id = event.linkId; // do something with it
...
}
public void handleEvent (EventLinkLeft event) {
...
id = event.linkId; // do something with it
...
}
}
...
Events myevent = new Events();
CountLinkTravelTimes myhandler = new CountLinkTravelTimes();
myevents.addHandler(myhandler);
EventLinkEnter test = new EventLinkEnter(time, agentId, linkId);
Events.computeEvent(test);
Building your own specialized event based on an existing event:
Now we have to additionally define a specialized event class, let's say
class EventAgentStuckAndReplanning extends EventAgentStuck {
private double replanning_probability;
// some other special things...
}
Now we are ready to receive this Event from all EventHandlerAgentStuckI! We can check for this special event by the means of
if(event.getClass() == EventAgentStuckAndReplanning.class) {...}
If for some reasons we want to write a handler that only receives this special Event StuckAndReplanning, we would have to add a new interface that extends EventHandlerI
e.g.
public interface EventHandlerAgentSuckAndReplanningI extends EventHandlerI {
handleEvent(EventAgentSutckAndReplanning event);
}
and ready you are... just implement that interface in your Handler and the handler will start receiveing only the appropriate events!
Building your own specialized event based on nothing at all:
It is simply as above, only that you inherit from BasicEvent. All Events should inherit from BasicEvent, which only defines, that there has to be a time and an agentId. One might think of events that don't even have an agentId, maybe you would leave this field blank (e.g. Integer.MIN_VALUE) or whatever. We included agentId into BasicEvent as the wast majority of events will need an agentID.
This article is work-in-progress!
The current event types are less and less suited for describing the simulation output. Especially when activities take place in facilities (instead of links as now) and when public transport is included in the simulation, new event types have to be introduced. This page proposes a new set of events that should be suitable for the future development of MATSim.
One of the main concepts are the differentiation between Persons and Vehicles. Persons are part of the population/scenario, specified in the plans/population-file. Vehicles are created (at the moment) within the simulation. The simulation only moves vehicles, never persons. Pedestrians should thus to be enclosed into a "Pedestrian-Vehicle".
| Event Name | Attributes | Notes |
| EndActivity | person, facility, actType | |
| EnterVehicle | person, vehicle, facility | |
| DepartureAtFacility | vehicle, facitlity | |
| FacilityToLink | vehicle, link | |
| LinkToIntersection | vehicle, link | |
| IntersectionToLink | vehicle, link | |
| LinkToFacility | vehicle, link | |
| ArrivalAtFacility | vehicle, facility | |
| LeaveVehicle | person, vehicle, facility | |
| StartActivity | person, facility, actType | |
| VehicleStuck | vehicle, link |
Description of the data-format to write (and read) Matsim-Events
Events should be stored in XML-Files.
There is no DTD for Events because each event could use other attributes as needed. As long as it is not possible to defined something like "free additional attributes" for tags in DTD, there will be no DTD for events.xml. Therefore, the events-fileformat ist very simple to reduce the possibility of errors.
The following attributes are required:
Most events will also have the following attributes:
Additional event-types may define additional attributes.
<?xml version="1.0" encoding="utf-8"?>
<events xml:lang="de-CH">
<event time="21600" type="departure" agent="759062" link="47" /> <!-- time: 06:00, in seconds -->
<event time="22980" type="arrival" agent="759062" link="122" /> <!-- time: 06:23 -->
<event time="21720" type="departure" agent="966916" link="25" />
<event time="22865" type="arrival" agent="966916" link="312" />
</events>