Controler Structure

The figure shows the main structure of the MATSim Controler. Easily recognizable is the iteration loop consisting of plans-execution, scoring and replanning. At each one of the eight marked points, modules can easily add additional functionality to MATSim.

Counts

'package org.matsim.counts:'

• Using xml-schema: 

  <counts xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="[SOME URL]/counts_v1.xsd"
  name="[SOME NAME]" desc="[SOME DESC]" year="[SOME YEAR]" layer="[SOME LAYER]">

• Automated graph creation is available using the LGPL library JFreeChart (+ the LGPL library jCommon), the MPL and LGPL library  iText (for pdf output), overlib.js (for tooltips) (licence conditions to check) and stylesheets:
  
  • To create our own graphs you can derive them from the abstract class CountsGraph and plug them into CountsGraphWriter (in the run method).

  • The simulation values can be scaled with a user supplied scaling factor.

  • CountsGraphWriter creates either pdf files or linked html output (formated with css).

  • The html output provides tooltips (using overlib.js) and links on the graphs.

  • All needed helper files (e.g. stylesheets etc.) are automatically copied into the folder div of the iteration output folder, that is, the graph output folder can be used standing alone.

   Contact:

  In case of questions or comments, please contact: horni(at)ivt.baug.ethz.ch

Emissions

Emissions

Monetarizing car or HDV emissions can be done quite straightforward using the MATSim simulation results. This includes the following steps:

• Modeling air pollution emissions on a micro scale for every link in the network (such as PM10, PM2,5, NOx, NO2, NMVOC and CO2).
• Modeling noise emissions on a micro scale for every link in the network.
• Modeling the resulting immissions based on land use data.
• Calculating the marginal social costs of transport for every link in the network.
• Proposing second-best pricing schemes in order to internalize the calculated external effects.

Making this operational is planned within the context of the "detailed evaluation" project (DFG).

Hybrid Electric Vehicles and Smart Grid

Overview

One of the main goals of the project is to model the electric demand of Plug-in Hybrid Electric Vehicles (PHEVs) and Electric Vehicles (EVs) and to find out, if the underlying electricity network can support such demand.

For doing this, MATSim has been coupled with a simulation model of the electricity network, which is called PHEV Management and Power System Simulation (PMPSS) [1]. Furthermore a charging module was added to MATSim, which decides the policy, when and how charging is performed by the vehicles. After relaxation of the MATSim Iterations, the charging information is given to PMPSS which finds out, if certain grid constraints have been violated (e.g. transformer capacities). This information is given back to MATSim and the charging module. As such, MATSim and PMPSS form an outer loop around the original MATSim loop.

Three type of charging schemes have been implemented in [1]: Dumb Charging, Dual Tariff Charging and Smart Charging. They are shortly described in the PDF poster, here.

Developer Infos

• The energy consumption of vehicles is calculated based on the average speed they drive along a link. Event handlers are used to capture this information.
• Controller listeners are used to implement the charging module and the scoring, which happens after the simulation.
• As PMPSS is implemented in MATLAB, it is invoked from Java after a specified number of iterations, where the MATSim demand is assumed to be relaxed (e.g. 100 iterations).

 Reference

 [1] Waraich, R.A., M.D. Galus, C. Dobler, M. Balmer, G. Andersson and K.W. Axhausen (2009) Plug-in Hybrid Electric Vehicles and Smart Grid: Investigations Based on a Micro-Simulation, paper presented at the 12th International Conference on Travel Behaviour Research (IATBR), Jaipur, December 2009.
(http://www.ivt.ethz.ch/vpl/publications/reports/ab592.pdf)

Matrices

Maintenance and Questions:

Marcel Rieser and Michael Balmer, senozon AG ({rieser, balmer}_at_senozon.com)

Javadoc:

http://www.matsim.org/javadoc/org/matsim/matrices/package-summary.html

In Brief:

This was used to store things like OD matrices inside matsim. Since we prefer to disaggregate such things right away into individual trips, this module was not maintained. It is not clear if maybe it should be re-surrected.

[mrieser] I recently cleaned the package up a bit, in that it no longer requires Locations (from the deprecated World concept) but just Ids, and that they work more stand-alone. Matrices are used mostly in demand modelling. As such, they are useful, but would probably need more cleanup to come up to standards.

 - think about interface Matrix to have different implementations, also backed by matrix-package (e.g. Jama, ...).
 - mostly used in initial demand modeling. MATSim needs *some* kind of matrix support for idm.
 - probably rename matrices/Matrix to odmatrices/ODMatrix to make clear it's not a general matrix impl?

Micro-simulation

Documentations for the following micro-simulations currently available:

JDQSim: I moved this to the user part of the documentation since I think it can be used from the config file only.  kai, apr'11

Modeling collective taxis in MATSim

Main concepts/features

Large Scale

The service is available 24h per day, 7 days a week.

The vehicles are ranging from minivans to minibuses (approximately 6 to 12 passengers)

The service works without fixed stations

Taxis can be taken on the fly (smart phones)

Modeling Hypothesis

Price and utility parameters based on those of other modes in MATSim-T

Available to all agents at every point in time and space

No capacity restrictions (unlimited capacity)

Bibliographic reference:

Ciari, F., M. Balmer and K.W. Axhausen (2009) Large scale use of collective taxis: a multi-agent approach, paper presented at the 12th International Conference on Travel Behaviour Research, Jaipur, December 2009.

Possible future developments

Michal Maciejewski is looking into using MATSim to generate realistic instances of the dynamic vehicle routing problem (DVRP). If one wants to avoid that the DVRP program can "cheat", requests for service should not come out of MATSim before their time.  There seem to be the following types of requests:

1. Get me a taxi/courier as soon as possible.
2. Get me a taxi/courier for a specified departure time.
3. Get me a taxi/courier for a specified arrival time.

Let me first look at taxis (i.e. persons make requests for themselves).

The first seems to be relatively easy to model: The leg mode would be "taxi"; the person would end its activity, go into the corresponding departure handler, which would request a taxi and then put the person into the departure queue (presumably, the same as there is for pt, although I am not sure if there is one per link or just one per pt stop).

The second is more difficult.  Sending out the request when the activity starts is too early, and the DVRP may use that to its advantage.  Possibilities that come to my (kn's) mind:

1. We add something like "prescheduled event" to matsim.  Then, an agent starting an activity at time t, could pre-schedule an event for time t + tau.
2. Sending a request during an activity will only be implemented together with within-day replanning.
3. The agent ends its activity when it makes the request, and then just sits in the departure queue.

Option 1. seems plausible at first glance.  Yet, it looks like it will cause additional headaches if this is ever combined with within-day replanning (because matsim would need to check which pre-scheduled events an agent has left around when it changes its plan).  Given our past experiences with such "quick fixes", this does not sound like a great idea.

Option 2. seems plausible (to me).  Within-day agents might be contacted, say once a minute, and asked if they want to call taxi for a pre-scheduled time in the future.

Option 3. seems a plausible fix for the meantime (to me).  It will produce wrong results with respect to agent scoring, but at least it will generate correct taxi requests.

Now courier service. 

Seems to me that I don't know enough about this.  Freight, at this point, is planned to be plugged into matsim by using "truck drivers".  I.e. from the point of view of matsim, the transportation of goods will just be a side effect of a driver moving a vehicle from A to B, and that vehicle being loaded with certain goods.

Clearly, we can still make up courier requests without following the goods.  For this, once more the within-day agents seems like the most consistent option.

Taxis in MATSim

Once there are requests, there need to be taxis.  Personally, I would start with a single taxicab.  In terms of implementation, this would probably inherit from what is currently (may'11) called ExperimentalBasicWithindayAgent.

(Using delegation/composition instead of inheritance is difficult with matsim agents, since "this" inside some delegated logic points to the delegate, not to the composing object.  Yet, the "this" is used to remove the agent from data structures, and insert it into others (e.g. at-activity data structure, wait data structure, in-vehicle data structure).)

As a first step, I would make the taxi agent, every time it arrives somewhere, generate a next activity location and then drive there.

As a second step, I would try to make that taxi agent pick up a waiting passenger and deliver it.

After some thinking, my intuition is that I would stay away from the pt code.  Picking up passengers can as well be done with regular arrival, I would think, and that would be much less intrusive.

Update (jul'11): There is an "AdapterAgent" in Michael Z.'s playground, and Michal M. has started using that for his taxicab prototype.

Router

There are now 3 least-cost path algorithms in package org.matsim.router:
- Dijkstra
- AStarEuclidean
- AStarLandmarks

For every router, there exists a class which computes some preprocessing data and is passed to the router class constructor in order to accelerate the routing procedure. The preprocessing classes are located in org.matsim.demandmodeling.router.util:
- PreProcessDijkstra
- PreProcessEuclidean
- PreProcessLandmarks

Dijkstra:
Condition: The link cost must be non-negative, otherwise Dijkstra does not work.

The new version is much faster on short routes than the former version (50 times as fast, if the start and end node of the route are ~1km away from each other) and diminutively faster on long routes (~1.5 times faster with preprocessing). Dijkstra can be used with or without preprocessing data (the preprocessing just marks all nodes that are in dead ends). Preprocessing does not take long (2 seconds on a network with 400'000 nodes on our computer leibnitz) and does not require much additional memory (~ 1 pointer per node) either, therefore it should be used where possible. Invoking Dijkstra may then look like this:

PreProcessDijkstra preProcessData = new PreProcessDijkstra();
preProcessData.run(network);
TravelCostI costFunction = ...
LeastCostPathCalculator routingAlgo = new Dijkstra(network, costFunction, preProcessData);
routingAlgo.calcLeastCostPath(fromNode, toNode, startTime);

If you don't want to preprocess the network, you can invoke Dijkstra as follows:

LeastCostPathCalculator routingAlgo = new Dijkstra(network, costFunction);

AStarEuclidean:
Is about 3 times faster than the above Dijkstra.
Conditions:
    - The same as  for Dijkstra: The link cost must be non-negative, otherwise Dijkstra does not work.
    - The length stored in the links must be greater or equal to the euclidean distance of the link's start and end node, otherwise the algorithm is not guaranteed to deliver least-cost paths. In this case PreProcessEuclidean gives out a warning message.
    - The CostCalculator which calculates the cost for each link must implement the TravelMinCostI interface, i.e. it must implement the function getLinkMinimumTravelCost(Link link). The TravelTimeCalculator class does implement it.

PreProcessEuclidean.run() is very fast and needs (almost) no additional memory.
Example invocation:
TravelMinCostI costFunction = ...
PreProcessEuclidean preProcessData = new PreProcessEuclidean(costFunction);
preProcessData.run(network);
...
LeastCostPathCalculator routingAlgo = new AStarEuclidean(network, preProcessData);
...

A note about the so-called overdo factor: You can drastically accelerate the routing of AStarEuclidean by providing an overdo factor > 1 (e.g. 1.5, 2 or 3). In this case, AStarEuclidean does not calculate least-cost paths anymore but tends to deliver distance-minimal paths. The greater the overdo factor, the faster the algorithm but the more the calculated routes diverge from the least-cost ones.
A typical invocation then looks like this: LeastCostPathCalculator routingAlgo = new AStarEuclidean(network, preProcessData, 2);

AStarLandmarks:
About double as fast as AStarEuclidean. PreProcessLandmarks.run() takes about 1 minute on 400'000 nodes on leibnitz and requires 2*X double values per node, where X is the number of landmarks. Currently, it is set to 16 (but can be set to another value, as 12 or 8 for example), so with 400'000 nodes we would need 2*8*16*400'000 bytes = about 100MB of additional memory.
Conditions: The same as for AStarEuclidean.
Example invocation:

TravelMinCostI costFunction = ...
PreProcessLandmarks preProcessData = new PreProcessLandmarks(costFunction);
preProcessData.run(network);
...
LeastCostPathCalculator routingAlgo = new AStarLandmarks(network, preProcessData);
...

Scoring

Currently the following documentation for scoring is available:

• For some conceptual material see here (not a "child" page): Explanations concerning the so-called Charypar-Nagel scoring function

Trip structure analysis of activity plans

For a description of the algorithms see the respective child pages.

Configuring location type for trip structure analysis

The algorithms can use different location attributes of activities as the basis for the trip structure analysis.

An activity can be located at a facility, a link or another type of location. By default, the algorithms described use the facility information as the location information. Sometimes it might be useful to use the link as the location information, e.g. if facilities are not part if the scenario. This can be configured as follows.

<module name="planomat">
    <param name="tripStructureAnalysisLayer" value="link"  />
</module>

Plan plan = ...;
// generate instance of the plan algorithm
MeisterkConfigGroup meisterk = new MeisterkConfigGroup();
PlanAnalyzeTourModeChoiceSet patmcs = new PlanAnalyzeTourModeChoiceSet(meisterk);
// specify and set set of modes available to the agent
EnumSet<BasicLeg.Mode> possibleModes =
EnumSet.of(BasicLeg.Mode.walk, BasicLeg.Mode.bike, BasicLeg.Mode.pt, BasicLeg.Mode.car);
patmcs.setModeSet(possibleModes);
// run algorithm
patmcs.run(plan);
// obtain result: choice set of feasible mode combinations
ArrayList<BasicLeg.Mode[]> actual = patmcs.getResult();

Plan plan = ...;
PlanAnalyzeSubtours past = new PlanAnalyzeSubtours();
testee.run(plan);
...
int numSubtours = past.getNumSubtours(); // get the number of subtours
int[] subtourIndexation = past.getSubtourIndexation(); // get the subtour indexation array

Within-day replanning. Status: experimental

For general conceptual material see here (javadoc) and here (code).

For a working example implementation see here (javadoc) and here (code).

If any of these links are not working, check for packages with "withinDay" in their name in the tutorial section of the matsim javadoc. or the matsim code.

Reference: Dobler, C. (2009) Implementations of Within Day Replanning in MATSim-T, Arbeitsberichte Verkehrs- und Raumplanung, 598, IVT, ETH Zurich, Zurich.