Package org.matsim.core.scoring

Scoring is responsible for calculating the (actual) utility/score of a plan.

Important Classes and Interfaces

A ScoringFunction is responsible for calculating the score of a plan based on information about how long an activity was executed or how much time an agent spent traveling. MATSim provides a default scoring function, CharyparNagelScoringFunctionFactory, which takes performing activities and traveling into account for the calculation of the score. Advanced scoring functions could be thought of where where the distance, people traveling along, people met at activities etc. have an influence on the score as well.
Because an instance of a ScoringFunction is usually specific for one person or for one plan only, a ScoringFunctionFactory is needed to create the needed instances of the ScoringFunction to be used.
The information, when an agent is traveling and when it is performing an activity, usually comes from MATSim-Events. EventsToScore feeds the information from the simulation to the agents' ScoringFunction-instance, which then calculates the effective score.

Typical Usage

If you are using the MATSim-Controler but want to use your own ScoringFunction, you can provide a factory for your ScoringFunction and set it with Controler.setScoringFunctionFactory(org.matsim.core.scoring.ScoringFunctionFactory). If you do not use the Controler, you can can use EventsToScore as events handler with your org.matsim.core.events.EventsManager-object to calculate the scores. Do not forget to call EventsToScore.finish() after processing all events.

Replacing / Extending the scoring function

There are two possibilities one can think of on how to change the scoring function: One can either want to use a complete different scoring algorithm, or one might plan to use an existing scoring function, but add additional utility-terms to it (e.g. tolls paid, money paid for parking lots, ...). For the first case (use a complete different scoring algorithm), write your own scoring function and scoring function factory, and add it to the Controler with Controler.setScoringFunctionFactory(org.matsim.core.scoring.ScoringFunctionFactory). But if you only plan to add or subtract some utility amounts from agents' score, you can generate PersonMoneyEvents. Scoring functions should listen for AgentUtilityEvents and just add the utility amount specified in the event to the agent's score. As an example, the roadpricing-package makes use of AgentMoneyEvents: An event-handler listens for agents entering and leaving links and thus calculates how much toll an agent pays. After the iteration, the event handler generates events itself: for each agent that must pay some toll, an AgentUtilityEvent is generated with the correct amount of toll. The scoring function receives those events and thus adds the paid tolls to the agents' score.
See Also:
playground.meisterk.org.matsim.run.westumfahrung.PlanAverageScore