When running a MATSim simulation, unused cores can be utilized to make the simulation faster. The event handler which is used by default, is running in the same thread as the simulation. For this reason, the presented 'parallelEventHandling' module can make your simulation much faster.

How to use the 'parallelEventHandling' Module

Parallel event handling can be turned on by inserting the follwing module into the config XML file of MATSim:

<module name="parallelEventHandling">
    <param name="numberOfThreads" value="1" />
</module>

The only required parameter in this module is 'numberOfThreads'. The value of this parameter specifies, how many threads (cores) should be assigned to handling events.

There is an additional optional parameter 'estimatedNumberOfEvents', which can be optimized to your simulation resulting in slightly faster runs. But its usage requires an estimate of the number of events which will occur in one iteration.

<param name="estimatedNumberOfEvents" value="5000000" />

Hints and Pitfalls

• Don't make any  assumptions on the order, in which the handlers are executed (as they are executed in parallel).
• Don't write the data in one handler and read that data in a different handler. Although this is possible, special care is required as synchronization between threads is needed for this. Furthermore this could lead to a degradation of the speed up.
• There is no point in using parallel event handling, if you have just one core available on your machine.
• Always make sure, that one thread is needed for the single cpu simulation. This means, if you have 4 cores, you can set the parameter 'numberOfThreads' to maximum 3.
• If 2 handlers have been added to the simulation, then there is no point in assigning 3 threads to parameter ''numberOfThreads', because it won't make the simulation faster (but rather could slow it down in some cases).
• The number of handlers can be bigger than 'numberOfThreads'. In this case automatically if possible, each thread is assigned the same number of handlers. 
• If the simulation is quite slow (compared to event handling), you won't be able to make full use of parallel event handling.

The actual speed up you get depends on many factors, especially on those mentioned in 'hints and pitfalls'. Experiments on a 16 core machine with different numbers of handlers have shown that the parallel event handler can reduce the simulation time with a very low overhead.

Further Reading

Some Java specific implementation aspects of JDEQSim and parallelEventHandling are described in the following paper:

Waraich, R.,  D. Charypar, M. Balmer and K.W. Axhausen (2009) Performance improvements for large scale traffic simulation in MATSim, paper presented at the 9^th Swiss Transport Research Conference, Ascona, September 2009. Download from here.