org.opentrafficsim.road.gtu.strategical.od

Class ODMatrix

java.lang.Object

org.opentrafficsim.road.gtu.strategical.od.ODMatrix

All Implemented Interfaces:

Serializable, Identifiable

public class ODMatrix
extends Object
implements Serializable, Identifiable

The minimal OD matrix has 1 origin, 1 destination and 1 time period. More of each can be used. Further categorization of data is possible, i.e. for origin O to destination D, for lane L, for route R and for vehicle class C, the demand at time T is D. The further categorization is defined by an array of Class's that define the categorization.

Copyright (c) 2013-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See OpenTrafficSim License.

Version:

$Revision$, $LastChangedDate$, by $Author$, initial version Sep 15, 2016

Author:

Alexander Verbraeck, Peter Knoppers, Wouter Schakel

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
ODMatrix(String id, List<? extends Node> origins, List<? extends Node> destinations, Categorization categorization, TimeVector globalTimeVector, Interpolation globalInterpolation) Constructs an OD matrix.

Method Summary

Modifier and Type	Method and Description
boolean	contains(Node origin, Node destination, Category category)
int	destinationTotal(Node destination) Calculates total number of trips over time for given destination.
boolean	equals(Object obj)
Set<Category>	getCategories(Node origin, Node destination) Returns the categories specified for given origin-destination combination.
Categorization	getCategorization()
Frequency	getDemand(Node origin, Node destination, Category category, Time time, boolean sliceStart) Returns the demand at given time.
DemandPattern	getDemandPattern(Node origin, Node destination, Category category)
FrequencyVector	getDemandVector(Node origin, Node destination, Category category)
List<Node>	getDestinations()
Interpolation	getGlobalInterpolation()
TimeVector	getGlobalTimeVector()
String	getId()
Interpolation	getInterpolation(Node origin, Node destination, Category category)
List<Node>	getOrigins()
TimeVector	getTimeVector(Node origin, Node destination, Category category)
int	getTrips(Node origin, Node destination, Category category, int periodIndex) Returns the number of trips in the given time period.
int[]	getTripsVector(Node origin, Node destination, Category category)
int	hashCode()
void	increaseTrips(Node origin, Node destination, Category category, int periodIndex, int trips) Adds a number of trips to given origin-destination combination, category and time period.
int	matrixTotal() Calculates total number of trips over time for the complete matrix.
int	originDestinationTotal(Node origin, Node destination) Calculates total number of trips over time for given origin-destination combination.
int	originTotal(Node origin) Calculates total number of trips over time for given origin.
void	print() Prints the complete OD matrix with each demand data on a single line.
void	putDemandVector(Node origin, Node destination, Category category, FrequencyVector demand) Add a demand vector to OD.
void	putDemandVector(Node origin, Node destination, Category category, FrequencyVector demand, TimeVector timeVector, Interpolation interpolation) Add a demand vector to OD.
void	putDemandVector(Node origin, Node destination, Category category, FrequencyVector demand, TimeVector timeVector, Interpolation interpolation, double fraction) Add a demand vector to OD, by a fraction of total demand.
void	putDemandVector(Node origin, Node destination, Category category, FrequencyVector demand, TimeVector timeVector, Interpolation interpolation, double[] fraction) Add a demand vector to OD, by a fraction per time period of total demand.
void	putTripsVector(Node origin, Node destination, Category category, int[] trips)
void	putTripsVector(Node origin, Node destination, Category category, int[] trips, TimeVector timeVector) Sets demand data by number of trips.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ODMatrix

public ODMatrix(String id,
                List<? extends Node> origins,
                List<? extends Node> destinations,
                Categorization categorization,
                TimeVector globalTimeVector,
                Interpolation globalInterpolation)

Constructs an OD matrix.

Parameters:

id - String; id

origins - List<? extends Node>; origin nodes

destinations - List<? extends Node>; destination nodes

categorization - Categorization; categorization of data

globalTimeVector - TimeVector; default time

globalInterpolation - Interpolation; interpolation of demand data

Throws:

NullPointerException - if any input is null

Method Detail

getId

public final String getId()

Specified by:

getId in interface Identifiable

Returns:

id.

getOrigins

public final List<Node> getOrigins()

Returns:

origins.

getDestinations

public final List<Node> getDestinations()

Returns:

destinations.

getCategorization

public final Categorization getCategorization()

Returns:

categorization.

getGlobalTimeVector

public final TimeVector getGlobalTimeVector()

Returns:

globalTimeVector.

getGlobalInterpolation

public final Interpolation getGlobalInterpolation()

Returns:

globalInterpolation.

putDemandVector

public final void putDemandVector(Node origin,
                                  Node destination,
                                  Category category,
                                  FrequencyVector demand)

Add a demand vector to OD.

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

demand - FrequencyVector; demand data, length has to be equal to the global time vector

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

IllegalArgumentException - if the demand data has a different length than time data, or is less than 2

IllegalArgumentException - if demand is negative or time not strictly increasing

IllegalArgumentException - if the route (if in the category) is not from the origin to the destination

NullPointerException - if an input is null

putDemandVector

public final void putDemandVector(Node origin,
                                  Node destination,
                                  Category category,
                                  FrequencyVector demand,
                                  TimeVector timeVector,
                                  Interpolation interpolation)

Add a demand vector to OD. In this method, which all other methods that add or put demand indirectly refer to, many consistency and validity checks are performed. These do not include checks on network connectivity, since the network may be subject to change during simulation.

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

demand - FrequencyVector; demand data, length has to be equal to the time vector

timeVector - TimeVector; time vector

interpolation - Interpolation; interpolation

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

IllegalArgumentException - if the demand data has a different length than time data, or is less than 2

IllegalArgumentException - if demand is negative or time not strictly increasing

IllegalArgumentException - if the route (if in the category) is not from the origin to the destination

NullPointerException - if an input is null

putDemandVector

public final void putDemandVector(Node origin,
                                  Node destination,
                                  Category category,
                                  FrequencyVector demand,
                                  TimeVector timeVector,
                                  Interpolation interpolation,
                                  double fraction)

Add a demand vector to OD, by a fraction of total demand.

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

demand - FrequencyVector; demand data, length has to be equal to the time vector

timeVector - TimeVector; time vector

interpolation - Interpolation; interpolation

fraction - double; fraction of demand for this category

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

IllegalArgumentException - if the demand data has a different length than time data, or is less than 2

IllegalArgumentException - if demand is negative or time not strictly increasing

IllegalArgumentException - if the route (if in the category) is not from the origin to the destination

NullPointerException - if an input is null

putDemandVector

public final void putDemandVector(Node origin,
                                  Node destination,
                                  Category category,
                                  FrequencyVector demand,
                                  TimeVector timeVector,
                                  Interpolation interpolation,
                                  double[] fraction)

Add a demand vector to OD, by a fraction per time period of total demand.

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

demand - FrequencyVector; demand data, length has to be equal to the time vector

timeVector - TimeVector; time vector

interpolation - Interpolation; interpolation

fraction - double[]; fraction of demand for this category

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

IllegalArgumentException - if the demand data has a different length than time data, or is less than 2

IllegalArgumentException - if demand is negative or time not strictly increasing

IllegalArgumentException - if the route (if in the category) is not from the origin to the destination

NullPointerException - if an input is null

getDemandVector

public final FrequencyVector getDemandVector(Node origin,
                                             Node destination,
                                             Category category)

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

Returns:

demand data for given origin, destination and categorization, null if no data is given

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

NullPointerException - if an input is null

getTimeVector

public final TimeVector getTimeVector(Node origin,
                                      Node destination,
                                      Category category)

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

Returns:

interpolation for given origin, destination and categorization, null if no data is given

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

NullPointerException - if an input is null

getInterpolation

public final Interpolation getInterpolation(Node origin,
                                            Node destination,
                                            Category category)

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

Returns:

interpolation for given origin, destination and categorization, null if no data is given

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

NullPointerException - if an input is null

getDemand

public final Frequency getDemand(Node origin,
                                 Node destination,
                                 Category category,
                                 Time time,
                                 boolean sliceStart)

Returns the demand at given time. If given time is before the first time slice or after the last time slice, 0 demand is returned.

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

time - Time; time

sliceStart - boolean; whether the time is at the start of an arbitrary time slice

Returns:

demand for given origin, destination and categorization, at given time

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

NullPointerException - if an input is null

getDemandPattern

public DemandPattern getDemandPattern(Node origin,
                                      Node destination,
                                      Category category)

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

Returns:

OD entry for given origin, destination and categorization.

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

NullPointerException - if an input is null

contains

public final boolean contains(Node origin,
                              Node destination,
                              Category category)

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

Returns:

whether there is data for the specified origin, destination and category

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

NullPointerException - if an input is null

getCategories

public final Set<Category> getCategories(Node origin,
                                         Node destination)

Returns the categories specified for given origin-destination combination.

Parameters:

origin - Node; origin

destination - Node; destination

Returns:

categories specified for given origin-destination combination

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

NullPointerException - if an input is null

putTripsVector

public final void putTripsVector(Node origin,
                                 Node destination,
                                 Category category,
                                 int[] trips)

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

trips - int[]; trip data, length has to be equal to the global time vector - 1, each value is the number of trips during a period

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

IllegalArgumentException - if the demand data has a different length than time data, or is less than 2

IllegalArgumentException - if demand is negative or time not strictly increasing

IllegalArgumentException - if the route (if in the category) is not from the origin to the destination

NullPointerException - if an input is null

putTripsVector

public final void putTripsVector(Node origin,
                                 Node destination,
                                 Category category,
                                 int[] trips,
                                 TimeVector timeVector)

Sets demand data by number of trips. Interpolation over time is stepwise.

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

trips - int[]; trip data, length has to be equal to the time vector - 1, each value is the number of trips during a period

timeVector - TimeVector; time vector

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

IllegalArgumentException - if the demand data has a different length than time data, or is less than 2

IllegalArgumentException - if demand is negative or time not strictly increasing

IllegalArgumentException - if the route (if in the category) is not from the origin to the destination

NullPointerException - if an input is null

getTripsVector

public final int[] getTripsVector(Node origin,
                                  Node destination,
                                  Category category)

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

Returns:

trip data for given origin, destination and categorization, null if no data is given

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

NullPointerException - if an input is null

getTrips

public final int getTrips(Node origin,
                          Node destination,
                          Category category,
                          int periodIndex)

Returns the number of trips in the given time period.

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

periodIndex - int; index of time period

Returns:

demand for given origin, destination and categorization, at given time

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

IndexOutOfBoundsException - if the period is outside of the specified range

NullPointerException - if an input is null

increaseTrips

public final void increaseTrips(Node origin,
                                Node destination,
                                Category category,
                                int periodIndex,
                                int trips)

Adds a number of trips to given origin-destination combination, category and time period. This can only be done for data with stepwise interpolation.

Parameters:

origin - Node; origin

destination - Node; destination

category - Category; category

periodIndex - int; index of time period

trips - int; trips to add (may be negative)

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

IllegalArgumentException - if the category does not belong to the categorization

IndexOutOfBoundsException - if the period is outside of the specified range

UnsupportedOperationException - if the interpolation of the data is not stepwise, or demand becomes negtive

NullPointerException - if an input is null

originTotal

public final int originTotal(Node origin)

Calculates total number of trips over time for given origin.

Parameters:

origin - Node; origin

Returns:

total number of trips over time for given origin

Throws:

IllegalArgumentException - if origin is not part of the OD matrix

NullPointerException - if origin is null

destinationTotal

public final int destinationTotal(Node destination)

Calculates total number of trips over time for given destination.

Parameters:

destination - Node; destination

Returns:

total number of trips over time for given destination

Throws:

IllegalArgumentException - if destination is not part of the OD matrix

NullPointerException - if destination is null

matrixTotal

public final int matrixTotal()

Calculates total number of trips over time for the complete matrix.

Returns:

total number of trips over time for the complete matrix

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

NullPointerException - if an input is null

originDestinationTotal

public final int originDestinationTotal(Node origin,
                                        Node destination)

Calculates total number of trips over time for given origin-destination combination.

Parameters:

origin - Node; origin

destination - Node; destination

Returns:

total number of trips over time for given origin-destination combination

Throws:

IllegalArgumentException - if origin or destination is not part of the OD matrix

NullPointerException - if an input is null

toString

public String toString()

Overrides:

toString in class Object

print

public final void print()

Prints the complete OD matrix with each demand data on a single line.

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

equals

public final boolean equals(Object obj)

Overrides:

equals in class Object