Class TripGenerator

All Implemented Interfaces:
CondObserver<Condition,Actor>, NamedObjectOps
Direct Known Subclasses:
BasicTripGenerator, BurstTripGenerator, RoundTripGenerator

public abstract class TripGenerator extends Actor
Trip generator class. This is the base class for trip generators. It provides some abstract methods that must be implemented, the method restart() to restart a trip generator, and the method stop() to stop the trip generator.

Subclasses will implement the methods getNextInterval() and action(). The method getNextInterval() will typically return values created by a random-number generator. The method action() will schedule a sequence of events associated with a trip.

The interface TripDataListener, or the class TripDataAdapter that implements it, is used for obtaining data about individual trips.

See Also:
  • Constructor Details

    • TripGenerator

      public TripGenerator(DramaSimulation sim, String name, boolean intern)
      Constructor.
      Parameters:
      sim - the simulation
      name - the name of this object
      intern - true if this object should be interned in the simulation's name table; false otherwise
  • Method Details

    • setProbabilityFunction

      public void setProbabilityFunction(RealValuedFunctionTwo pf)
      Set the probability function. This function may be used under the following circumstances:
      • the starting hub and destination hub are in the same user domain.
      • the hubs' user domains have parent domains and those parent domains are identical.
      • the starting and destination hubs are members of the domain that is the parent domain of each hub's user domain.
      When these circumstances exist, one may select a trip based on the user domain or the common parent domain. When the user domain is selected, the trip (or one leg of a trip) uses the bike-sharing system and the user domain is used to compute the travel time. When the parent domain is selected, the trip (or one leg of a trip) does not use the bike sharing system and the parent domain is used to compute the travel time.

      The probability function is defined as a real-valued function f(d1,d2) whose range is [0.0, 1.0] and whose domain contains non-negative values of its arguments. When called, d1 will be the estimated delay computed using the delay table for the source hub's user domain and d2 will be the delay computed using the delay table for the parent domain of the source hub's user domain. The probability this function computes is the probability that the delay used is d1. If the function is null, the d1 will be used if it is less than d2. If d2 is used, bicycles will not be removed or added to a hub as the trip is assumed to use some other service.

      When the probability function is null and there is a choice between domains, the user domain is chosen if d1 < d2; otherwise the parent domain is chosen. A realistic probability function should take into account that the users will sometimes guess travel times incorrectly and that users may be less inclined to use a bicycle as trip durations increase and the trip becomes more tiring.

      Parameters:
      pf - the probability function; null for a default behavior
    • setProbabilitySimFunction

      public void setProbabilitySimFunction(SimFunctionTwo sfpf)
      Set the probability function using a simulation function. A simulation function allows a function to be specified as a simulation object that can be created using a factory. The probability function may be used under the following circumstances:
      • the starting hub and destination hub are in the same user domain.
      • the hubs' user domains have parent domains and those parent domains are identical.
      • the starting and destination hubs are members of the domain that is the parent domain of each hub's user domain.
      When these circumstances exist, one may select a trip based on the user domain or the common parent domain. When the user domain is selected, the trip (or one leg of a trip) uses the bike-sharing system and the user domain is used to compute the travel time. When the parent domain is selected, the trip (or one leg of a trip) does not use the bike sharing system and the parent domain is used to compute the travel time.

      The probability function is defined as a real-valued function f(d1,d2) whose range is [0.0, 1.0] and whose domain contains non-negative values of its arguments. When called, d1 will be the estimated delay computed using the delay table for the source hub's user domain and d2 will be the delay computed using the delay table for the parent domain of the source hub's user domain. The probability this function computes is the probability that the delay used is d1. If the function is null, the d1 will be used if it is less than d2. If d2 is used, bicycles will not be removed or added to a hub as the trip is assumed to use some other service.

      When the probability function is null and there is a choice between domains, the user domain is chosen if d1 < d2; otherwise the parent domain is chosen. A realistic probability function should take into account that the users will sometimes guess travel times incorrectly and that users may be less inclined to use a bicycle as trip durations increase and the trip becomes more tiring.

      Parameters:
      sfpf - the probability function; null for a default behavior
    • getProbabilityFunction

      protected RealValuedFunctionTwo getProbabilityFunction()
      Get the probability function. The probability function determines which of two domains to use for computing trip times and whether or not the bike-sharing system is used for a trip or portion of a trip. This function's definition is provided by the documentation for setProbabilityFunction(RealValuedFunctionTwo).
      Returns:
      the probability function
      See Also:
    • getNextInterval

      protected abstract double getNextInterval()
      Get the time interval to wait before scheduling the next trip.
      Returns:
      the next trip interarrival time
    • getInitialDelay

      protected double getInitialDelay()
      Get an initial delay. The initial delay is the delay before the trip generator is started. The default value is 0.0. After this initial delay is passed, the method getNextInterval() determines when a trip will start. As a result, the starting time for the first trip is the value getInitialDelay() + getNextInterval().
      Returns:
      the initial delay in seconds
    • setInitialDelay

      public void setInitialDelay(double delay)
      Set the initial delay. The initial delay is the simulation time to wait from the time a trip generator is created to the time the trip generator starts. This method may be called before the simulation is run (or restarted) and must not be called after the simulation is run (or restarted).
      Parameters:
      delay - the initial delay in seconds
      Throws:
      IllegalArgumentException - the delay was negative.
      IllegalStateException - an attempt to set the delay was made after the simulation had started.
    • createTripID

      protected long createTripID()
      Create a new trip ID. Trip IDs must be created using this method to avoid duplicating an ID.
      Returns:
      a new trip ID.
    • action

      protected abstract boolean action()
      Perform an action that generates a trip. Implementations of this method will typically call the Hub method Hub.sendUsers(Hub,int,boolean,Callable) or Hub.sendUsers(Hub,int,boolean,RealValuedFunctionTwo,Callable). The Callable argument handles multi-hop trips and also a final call to fireTripEnded(long,Hub) for successfully completed trips. The return value for sendUsers or sendUsers can be used to determine whether fireTripStarted(long,Hub,HubDomain) or fireTripFailedAtStart(long,Hub) should be called. If sendUsers or sendUsers is used mid-trip, a failure is noted by calling fireTripFailedMidstream(long,Hub) (which should not be called except for multi-hop trips). For multi-hop trips, the fireTripPauseStart(long,Hub) should be called to note that a trip has temporarily paused at an intermediate hub and fireTripPauseEnd(long,Hub,HubDomain) to indicate that the trip is continuing after a pause.

      Note: when this method returns false, the traffic generator cannot be restarted.

      Returns:
      true if more trips can be generated; false otherwise
    • stop

      public void stop()
      Stop the trip generator. If this method is called when a trip generator is not running, it will have no effect. After stop() is called, the traffic generator may be restarted. If one stops and restarts before the event associated with the initial delay is processed, the initial delay will be ignored.
      See Also:
    • isRunning

      public boolean isRunning()
      Determine if the trip generator is running.
      Returns:
      true if the trip generator is running; false if it is not running
    • restart

      public void restart()
      Restart the trip generator after it has been stopped. If the trip generator is already running, calling restart() will have no effect.
      See Also:
    • addTripDataListener

      public void addTripDataListener(TripDataListener listener)
      Add a trip data listener to the current object.
      Parameters:
      listener - the listener to add
    • removeTripDataListener

      public void removeTripDataListener(TripDataListener listener)
      Remove a trip data listener from the current object.
      Parameters:
      listener - the listener to remove
    • fireTripStarted

      protected void fireTripStarted(long tripID, Hub hub, HubDomain d)
      Notify each trip data listener that a trip has started.
      Parameters:
      tripID - the ID for this trip
      hub - the hub at which this event occurred
      d - the HubDomain used to determine the time the trip takes for the first hop.
    • fireTripPauseStart

      protected void fireTripPauseStart(long tripID, Hub hub)
      Notify each trip data listener that a trip has just paused at an intermediate hub.
      Parameters:
      tripID - the ID for this trip
      hub - the hub at which this event occurred
    • fireTripPauseEnd

      protected void fireTripPauseEnd(long tripID, Hub hub, HubDomain d)
      Notify each trip data listener that a trip is continuing after a pause.
      Parameters:
      tripID - the ID for this trip
      hub - the hub at which this event occurred
      d - the hub domain at which this event occurred
    • fireTripEnded

      protected void fireTripEnded(long tripID, Hub hub)
      Notify each trip data listener that a trip has started.
      Parameters:
      tripID - the ID for this trip
      hub - the hub at which this event occurred
    • fireTripFailedAtStart

      protected void fireTripFailedAtStart(long tripID, Hub hub)
      Notify each trip data listener that a trip failed to start.
      Parameters:
      tripID - the ID for this trip
      hub - the hub at which this event occurred
    • fireTripFailedMidstream

      protected void fireTripFailedMidstream(long tripID, Hub hub)
      Notify each trip data listener that a trip failed midstream.
      Parameters:
      tripID - the ID for this trip
      hub - the hub at which this event occurred
    • printConfiguration

      public void printConfiguration(String iPrefix, String prefix, boolean printName, PrintWriter out)
      Print the configuration for an instance of TripGenerator. The documentation for method SimObject.printConfiguration(String,String,boolean,java.io.PrintWriter) contains a description of how this method is used and how to override it. The method GenericActor.printConfiguration(String,String,boolean,java.io.PrintWriter) describes this method as it applies to all actors . The data that will be printed when this method is called are the following.

      For class TripGenerator:

      • the initial delay - the time to wait before trips are generated.
      Overrides:
      printConfiguration in class GenericActor<DramaSimulation,Actor,Condition,Domain,DomainMember,DramaFactory,Group>
      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
      prefix - a prefix string (typically whitespace) to put at the start of each line other than the initial line that is printed when printName is true
      printName - requests printing the name of an object
      out - the output print writer
    • printState

      public void printState(String iPrefix, String prefix, boolean printName, PrintWriter out)
      Print the configuration for an instance of TripGenerator. The documentation for method SimObject.printState(String,String,boolean,java.io.PrintWriter) contains a description of how this method is used and how to override it. The method GenericSimObject.printState(String,String,boolean,java.io.PrintWriter) describes this method as it applies to all actors. In addition, the state that is printed includes the following items.

      Defined in TripGenerator:

      • whether or not the trip generator is running and the next time an action will be run if the trip generator is running.
      Overrides:
      printState in class GenericSimObject<DramaSimulation,Actor,Condition,Domain,DomainMember,DramaFactory,Group>
      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
      prefix - a prefix string (typically whitespace) to put at the start of each line other than the initial line that is printed when printName is true
      printName - requests printing the name of an object
      out - the output print writer
    • clone

      protected Object clone() throws CloneNotSupportedException
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException
    • isInterned

      public boolean isInterned()
      Specified by:
      isInterned in interface NamedObjectOps
    • getObjectNamer

      protected Simulation getObjectNamer()
    • getName

      public final String getName()
      Specified by:
      getName in interface NamedObjectOps
    • canDelete

      public boolean canDelete()
      Specified by:
      canDelete in interface NamedObjectOps
    • delete

      public final boolean delete()
      Specified by:
      delete in interface NamedObjectOps
    • isDeleted

      public final boolean isDeleted()
      Specified by:
      isDeleted in interface NamedObjectOps
    • deletePending

      public final boolean deletePending()
      Specified by:
      deletePending in interface NamedObjectOps