Package org.opentrafficsim.road.od

Class OdMatrix

java.lang.Object
org.opentrafficsim.road.od.OdMatrix
All Implemented Interfaces:
Identifiable
public class OdMatrix extends Object implements 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-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See OpenTrafficSim License.

Author:
Alexander Verbraeck, Peter Knoppers, Wouter Schakel

  • Constructor Details

    • OdMatrix

      public OdMatrix(String id, List<? extends Node> origins, List<? extends Node> destinations, Categorization categorization, DurationVector globalDurationVector, Interpolation globalInterpolation)
      Constructs an OD matrix.
      Parameters:
      id - id
      origins - origin nodes
      destinations - destination nodes
      categorization - categorization of data
      globalDurationVector - default time
      globalInterpolation - interpolation of demand data
      Throws:
      NullPointerException - if any input is null

  • Method Details

    • getId

      public final String getId()
      Specified by:
      getId in interface Identifiable

    • getOrigins

      public final List<Node> getOrigins()
      Returns origins.
      Returns:
      origins

    • getDestinations

      public final List<Node> getDestinations()
      Returns destinations.
      Returns:
      destinations

    • getCategorization

      public final Categorization getCategorization()
      Returns categorization.
      Returns:
      categorization

    • getGlobalTimeVector

      public final DurationVector getGlobalTimeVector()
      Returns global time vector.
      Returns:
      global time vector

    • getGlobalInterpolation

      public final Interpolation getGlobalInterpolation()
      Returns global interpolation.
      Returns:
      global interpolation

    • putDemandVector

      public final void putDemandVector(Node origin, Node destination, Category category, FrequencyVector demand, double fraction)
      Add a demand vector to OD.
      Parameters:
      origin - origin
      destination - destination
      category - category
      demand - demand data, length has to be equal to the global time vector
      fraction - 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)
      Add a demand vector to OD.
      Parameters:
      origin - origin
      destination - destination
      category - category
      demand - 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, DurationVector 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 - origin
      destination - destination
      category - category
      demand - demand data, length has to be equal to the time vector
      timeVector - time vector
      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, DurationVector timeVector, Interpolation interpolation, double fraction)
      Add a demand vector to OD, by a fraction of total demand.
      Parameters:
      origin - origin
      destination - destination
      category - category
      demand - demand data, length has to be equal to the time vector
      timeVector - time vector
      interpolation - interpolation
      fraction - 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, DurationVector timeVector, Interpolation interpolation, double[] fraction)
      Add a demand vector to OD, by a fraction per time period of total demand.
      Parameters:
      origin - origin
      destination - destination
      category - category
      demand - demand data, length has to be equal to the time vector
      timeVector - time vector
      interpolation - interpolation
      fraction - 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 Optional<FrequencyVector> getDemandVector(Node origin, Node destination, Category category)
      Returns demand data for given origin, destination and categorization.
      Parameters:
      origin - origin
      destination - destination
      category - category
      Returns:
      demand data for given origin, destination and categorization, empty 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

    • getDurationVector

      public final Optional<DurationVector> getDurationVector(Node origin, Node destination, Category category)
      Returns interpolation for given origin, destination and categorization.
      Parameters:
      origin - origin
      destination - destination
      category - category
      Returns:
      interpolation for given origin, destination and categorization, empty 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 Optional<Interpolation> getInterpolation(Node origin, Node destination, Category category)
      Returns interpolation for given origin, destination and categorization.
      Parameters:
      origin - origin
      destination - destination
      category - category
      Returns:
      interpolation for given origin, destination and categorization, empty 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 - origin
      destination - destination
      category - category
      time - time
      sliceStart - 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 Optional<DemandPattern> getDemandPattern(Node origin, Node destination, Category category)
      Returns OD entry for given origin, destination and categorization.
      Parameters:
      origin - origin
      destination - destination
      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)
      Returns whether there is data for the specified origin, destination and category.
      Parameters:
      origin - origin
      destination - destination
      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 - origin
      destination - 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)
      Put trip vector.
      Parameters:
      origin - origin
      destination - destination
      category - category
      trips - 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, DurationVector timeVector)
      Sets demand data by number of trips. Interpolation over time is stepwise.
      Parameters:
      origin - origin
      destination - destination
      category - category
      trips - trip data, length has to be equal to the time vector - 1, each value is the number of trips during a period
      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)
      Get trip vector.
      Parameters:
      origin - origin
      destination - destination
      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 - origin
      destination - destination
      category - category
      periodIndex - 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 - origin
      destination - destination
      category - category
      periodIndex - index of time period
      trips - trips to add (may be negative)
      Throws:
      NoSuchElementException - if there is no demand data to increase
      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 negative
      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 - 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 - 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 - origin
      destination - 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