Package org.opentrafficsim.road.gtu.strategical.od

Class ODMatrix

  • All Implemented Interfaces:
    Serializable, org.opentrafficsim.base.Identifiable
    public class ODMatrix
extends Object
implements Serializable, org.opentrafficsim.base.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-2022 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 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 org.opentrafficsim.base.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,
                                  double fraction)
        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
        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)
        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

      • 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