Package org.opentrafficsim.road.gtu.lane

Class LaneBasedGtu

java.lang.Object
org.djutils.event.LocalEventProducer
org.opentrafficsim.core.gtu.Gtu
org.opentrafficsim.road.gtu.lane.LaneBasedGtu
All Implemented Interfaces:
Serializable, Remote, nl.tudelft.simulation.dsol.animation.Locatable, org.djutils.base.Identifiable, org.djutils.event.EventProducer, org.opentrafficsim.base.geometry.OtsLocatable, org.opentrafficsim.base.HierarchicallyTyped<GtuType,Gtu>, Drawable, DynamicSpatialObject, SpatialObject
public class LaneBasedGtu extends Gtu
This class contains most of the code that is needed to run a lane based GTU.
The starting point of a LaneBasedTU is that it can be in multiple lanes at the same time. This can be due to a lane change (lateral), or due to crossing a link (front of the GTU is on another Lane than rear of the GTU). If a Lane is shorter than the length of the GTU (e.g. when we do node expansion on a crossing, this is very well possible), a GTU could occupy dozens of Lanes at the same time.

When calculating a headway, the GTU has to look in successive lanes. When Lanes (or underlying CrossSectionLinks) diverge, the headway algorithms have to look at multiple Lanes and return the minimum headway in each of the Lanes. When the Lanes (or underlying CrossSectionLinks) converge, "parallel" traffic is not taken into account in the headway calculation. Instead, gap acceptance algorithms or their equivalent should guide the merging behavior.

To decide its movement, an AbstractLaneBasedGtu applies its car following algorithm and lane change algorithm to set the acceleration and any lane change operation to perform. It then schedules the triggers that will add it to subsequent lanes and remove it from current lanes as needed during the time step that is has committed to. Finally, it re-schedules its next movement evaluation with the simulator.

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
See Also:

  • Field Details

    • initialLocationThresholdDifference

      public static org.djunits.value.vdouble.scalar.Length initialLocationThresholdDifference
      The threshold distance for differences between initial locations of the GTU on different lanes.

    • eventMargin

      public static org.djunits.value.vdouble.scalar.Length eventMargin
      Margin to add to plan to check of the path will enter the next section.

    • CACHING

      public static boolean CACHING
      Caching on or off.

    • CACHED_POSITION

      public static int CACHED_POSITION
      cached position count.

    • NON_CACHED_POSITION

      public static int NON_CACHED_POSITION
      cached position count.

    • LANEBASED_MOVE_EVENT

      public static org.djutils.event.EventType LANEBASED_MOVE_EVENT
      The lane-based event type for pub/sub indicating a move.
      Payload: [String gtuId, PositionVector currentPosition, Direction currentDirection, Speed speed, Acceleration acceleration, TurnIndicatorStatus turnIndicatorStatus, Length odometer, Link id of referenceLane, Lane id of referenceLane, Length positionOnReferenceLane]

    • LANEBASED_DESTROY_EVENT

      public static org.djutils.event.EventType LANEBASED_DESTROY_EVENT
      The lane-based event type for pub/sub indicating destruction of the GTU.
      Payload: [String gtuId, PositionVector finalPosition, Direction finalDirection, Length finalOdometer, Link referenceLink, Lane referenceLane, Length positionOnReferenceLane]

    • LANE_ENTER_EVENT

      public static org.djutils.event.EventType LANE_ENTER_EVENT
      The event type for pub/sub indicating that the GTU entered a new lane (with the FRONT position if driving forward; REAR if driving backward).
      Payload: [String gtuId, String link id, String lane id]

    • LANE_EXIT_EVENT

      public static org.djutils.event.EventType LANE_EXIT_EVENT
      The event type for pub/sub indicating that the GTU exited a lane (with the REAR position if driving forward; FRONT if driving backward).
      Payload: [String gtuId, String link id, String lane id]

    • LANE_CHANGE_EVENT

      public static org.djutils.event.EventType LANE_CHANGE_EVENT
      The event type for pub/sub indicating that the GTU change lane.
      Payload: [String gtuId, LateralDirectionality direction, String fromLaneId, Length position]

  • Constructor Details

    • LaneBasedGtu

      public LaneBasedGtu(String id, GtuType gtuType, org.djunits.value.vdouble.scalar.Length length, org.djunits.value.vdouble.scalar.Length width, org.djunits.value.vdouble.scalar.Speed maximumSpeed, org.djunits.value.vdouble.scalar.Length front, RoadNetwork network) throws GtuException
      Construct a Lane Based GTU.
      Parameters:
      id - String; the id of the GTU
      gtuType - GtuType; the type of GTU, e.g. TruckType, CarType, BusType
      length - Length; the maximum length of the GTU (parallel with driving direction)
      width - Length; the maximum width of the GTU (perpendicular to driving direction)
      maximumSpeed - Speed;the maximum speed of the GTU (in the driving direction)
      front - Length; front distance relative to the reference position
      network - RoadNetwork; the network that the GTU is initially registered in
      Throws:
      GtuException - when initial values are not correct

  • Method Details

    • init

      public void init(LaneBasedStrategicalPlanner strategicalPlanner, LanePosition longitudinalPosition, org.djunits.value.vdouble.scalar.Speed initialSpeed) throws NetworkException, nl.tudelft.simulation.dsol.SimRuntimeException, GtuException, OtsGeometryException
      Parameters:
      strategicalPlanner - LaneBasedStrategicalPlanner; the strategical planner (e.g., route determination) to use
      longitudinalPosition - LanePosition; the initial position of the GTU
      initialSpeed - Speed; the initial speed of the car on the lane
      Throws:
      NetworkException - when the GTU cannot be placed on the given lane
      nl.tudelft.simulation.dsol.SimRuntimeException - when the move method cannot be scheduled
      GtuException - when initial values are not correct
      OtsGeometryException - when the initial path is wrong

    • setParent

      public void setParent(Gtu gtu) throws GtuException
      All lanes the GTU is on will be left.
      Overrides:
      setParent in class Gtu
      Throws:
      GtuException

    • reinit

      public void reinit(LanePosition initialLongitudinalPosition) throws NetworkException, nl.tudelft.simulation.dsol.SimRuntimeException, GtuException, OtsGeometryException
      Reinitializes the GTU on the network using the existing strategical planner and zero speed.
      Parameters:
      initialLongitudinalPosition - LanePosition; initial position
      Throws:
      NetworkException - when the GTU cannot be placed on the given lane
      nl.tudelft.simulation.dsol.SimRuntimeException - when the move method cannot be scheduled
      GtuException - when initial values are not correct
      OtsGeometryException - when the initial path is wrong

    • changeLaneInstantaneously

      public void changeLaneInstantaneously(LateralDirectionality laneChangeDirection) throws GtuException
      Change lanes instantaneously.
      Parameters:
      laneChangeDirection - LateralDirectionality; the direction to change to
      Throws:
      GtuException - in case lane change fails

    • initLaneChange

      public void initLaneChange(LateralDirectionality laneChangeDirection) throws GtuException
      Register on lanes in target lane.
      Parameters:
      laneChangeDirection - LateralDirectionality; direction of lane change
      Throws:
      GtuException - exception

    • finalizeLaneChange

      protected void finalizeLaneChange(LateralDirectionality laneChangeDirection) throws GtuException
      Performs the finalization of a lane change by leaving the from lanes.
      Parameters:
      laneChangeDirection - LateralDirectionality; direction of lane change
      Throws:
      GtuException - if position or direction could not be obtained

    • setFinalizeLaneChangeEvent

      public void setFinalizeLaneChangeEvent(nl.tudelft.simulation.dsol.formalisms.eventscheduling.SimEventInterface<org.djunits.value.vdouble.scalar.Duration> event)
      Sets event to finalize lane change.
      Parameters:
      event - SimEventInterface<SimTimeDoubleUnit>; event

    • move

      protected boolean move(org.djutils.draw.point.OrientedPoint2d fromLocation) throws nl.tudelft.simulation.dsol.SimRuntimeException, GtuException, OperationalPlanException, NetworkException, org.opentrafficsim.base.parameters.ParameterException
      Overrides:
      move in class Gtu
      Throws:
      nl.tudelft.simulation.dsol.SimRuntimeException
      GtuException
      OperationalPlanException
      NetworkException
      org.opentrafficsim.base.parameters.ParameterException

    • scheduleEnterEvent

      protected void scheduleEnterEvent() throws GtuException, OperationalPlanException, nl.tudelft.simulation.dsol.SimRuntimeException
      Checks whether the GTU will enter a next cross-section during the (remainder of) the tactical plan. Only one event will be scheduled. Possible additional events are scheduled upon entering the cross-section.
      Throws:
      GtuException - exception
      OperationalPlanException - exception
      nl.tudelft.simulation.dsol.SimRuntimeException - exception

    • enterCrossSection

      protected void enterCrossSection() throws GtuException, OperationalPlanException, nl.tudelft.simulation.dsol.SimRuntimeException
      Appends a new cross-section at the downstream end. Possibly schedules a next enter event.
      Throws:
      GtuException - exception
      OperationalPlanException - exception
      nl.tudelft.simulation.dsol.SimRuntimeException - exception

    • scheduleLeaveEvent

      protected void scheduleLeaveEvent() throws GtuException, OperationalPlanException, nl.tudelft.simulation.dsol.SimRuntimeException
      Checks whether the GTU will leave a cross-section during the (remainder of) the tactical plan. Only one event will be scheduled. Possible additional events are scheduled upon leaving the cross-section.
      Throws:
      GtuException - exception
      OperationalPlanException - exception
      nl.tudelft.simulation.dsol.SimRuntimeException - exception

    • leaveCrossSection

      protected void leaveCrossSection() throws GtuException, OperationalPlanException, nl.tudelft.simulation.dsol.SimRuntimeException
      Removes registration between the GTU and the lanes in the most upstream cross-section. Possibly schedules a next leave event.
      Throws:
      GtuException - exception
      OperationalPlanException - exception
      nl.tudelft.simulation.dsol.SimRuntimeException - exception

    • scheduleTriggers

      protected void scheduleTriggers(Lane lane) throws GtuException, OperationalPlanException, nl.tudelft.simulation.dsol.SimRuntimeException
      Schedules all trigger events during the current operational plan on the lane.
      Parameters:
      lane - Lane; lane
      Throws:
      GtuException - exception
      OperationalPlanException - exception
      nl.tudelft.simulation.dsol.SimRuntimeException - exception

    • getNextLaneForRoute

      public final Lane getNextLaneForRoute(Lane lane)
      Returns the next lane for a given lane to stay on the route.
      Parameters:
      lane - Lane; the lane for which we want to know the next Lane
      Returns:
      Lane; next lane, null if none

    • getNextLanesForRoute

      public Set<Lane> getNextLanesForRoute(Lane lane)
      Returns a set of Lanes that can be followed considering the route.
      Parameters:
      lane - Lane; the lane for which we want to know the next Lane
      Returns:
      set of Lanes that can be followed considering the route

    • positions

      public final Map<Lane,org.djunits.value.vdouble.scalar.Length> positions(RelativePosition relativePosition) throws GtuException
      Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the vehicle is registered.
      Note: If a GTU is registered in multiple parallel lanes, the lateralLaneChangeModel is used to determine the center line of the vehicle at this point in time. Otherwise, the average of the center positions of the lines will be taken.
      Parameters:
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      Returns:
      the lanes and the position on the lanes where the GTU is currently registered, for the given position of the GTU.
      Throws:
      GtuException - when the vehicle is not on one of the lanes on which it is registered.

    • positions

      public final Map<Lane,org.djunits.value.vdouble.scalar.Length> positions(RelativePosition relativePosition, org.djunits.value.vdouble.scalar.Time when) throws GtuException
      Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the vehicle is registered.
      Parameters:
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      when - Time; the future time for which to calculate the positions.
      Returns:
      the lanes and the position on the lanes where the GTU will be registered at the time, for the given position of the GTU.
      Throws:
      GtuException - when the vehicle is not on one of the lanes on which it is registered.

    • position

      public final org.djunits.value.vdouble.scalar.Length position(Lane lane, RelativePosition relativePosition) throws GtuException
      Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane at the current simulation time.
      Parameters:
      lane - Lane; the position on this lane will be returned.
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      Returns:
      DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.
      Throws:
      GtuException - when the vehicle is not on the given lane.

    • position

      public org.djunits.value.vdouble.scalar.Length position(Lane lane, RelativePosition relativePosition, org.djunits.value.vdouble.scalar.Time when) throws GtuException
      Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane.
      Parameters:
      lane - Lane; the position on this lane will be returned.
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      when - Time; the future time for which to calculate the positions.
      Returns:
      DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.
      Throws:
      GtuException - when the vehicle is not on the given lane.

    • getReferencePosition

      public LanePosition getReferencePosition() throws GtuException
      Return the current Lane, position and directionality of the GTU.
      Returns:
      LanePosition; the current Lane, position and directionality of the GTU
      Throws:
      GtuException - in case the reference position of the GTU cannot be found on the lanes in its current path

    • fractionalPositions

      public final Map<Lane,Double> fractionalPositions(RelativePosition relativePosition) throws GtuException
      Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the vehicle is registered, as fractions of the length of the lane. This is important when we want to see if two vehicles are next to each other and we compare an 'inner' and 'outer' curve.
      Parameters:
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      Returns:
      the lanes and the position on the lanes where the GTU is currently registered, for the given position of the GTU.
      Throws:
      GtuException - when the vehicle is not on one of the lanes on which it is registered.

    • fractionalPositions

      public final Map<Lane,Double> fractionalPositions(RelativePosition relativePosition, org.djunits.value.vdouble.scalar.Time when) throws GtuException
      Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the vehicle is registered, as fractions of the length of the lane. This is important when we want to see if two vehicles are next to each other and we compare an 'inner' and 'outer' curve.
      Parameters:
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      when - Time; the future time for which to calculate the positions.
      Returns:
      the lanes and the position on the lanes where the GTU will be registered at the time, for the given position of the GTU.
      Throws:
      GtuException - when the vehicle is not on one of the lanes on which it is registered.

    • fractionalPosition

      public final double fractionalPosition(Lane lane, RelativePosition relativePosition, org.djunits.value.vdouble.scalar.Time when) throws GtuException
      Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane, as a fraction of the length of the lane. This is important when we want to see if two vehicles are next to each other and we compare an 'inner' and 'outer' curve.
      Parameters:
      lane - Lane; the position on this lane will be returned.
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      when - Time; the future time for which to calculate the positions.
      Returns:
      the fractional relative position on the lane at the given time.
      Throws:
      GtuException - when the vehicle is not on the given lane.

    • fractionalPosition

      public final double fractionalPosition(Lane lane, RelativePosition relativePosition) throws GtuException
      Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane, as a fraction of the length of the lane. This is important when we want to see if two vehicles are next to each other and we compare an 'inner' and 'outer' curve.
      Parameters:
      lane - Lane; the position on this lane will be returned.
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      Returns:
      the fractional relative position on the lane at the given time.
      Throws:
      GtuException - when the vehicle is not on the given lane.

    • addTrigger

      public final void addTrigger(Lane lane, nl.tudelft.simulation.dsol.formalisms.eventscheduling.SimEventInterface<org.djunits.value.vdouble.scalar.Duration> event)
      Add an event to the list of lane triggers scheduled for this GTU.
      Parameters:
      lane - Lane; the lane on which the event occurs
      event - SimEventInterface<SimTimeDoubleUnit>; SimeEvent<SimTimeDoubleUnit> the event

    • setVehicleModel

      public void setVehicleModel(VehicleModel vehicleModel)
      Sets a vehicle model.
      Parameters:
      vehicleModel - VehicleModel; vehicle model

    • getVehicleModel

      public VehicleModel getVehicleModel()
      Returns the vehicle model.
      Returns:
      VehicleModel; vehicle model

    • destroy

      public void destroy()
      Overrides:
      destroy in class Gtu

    • getStrategicalPlanner

      public final LaneBasedStrategicalPlanner getStrategicalPlanner()
      Overrides:
      getStrategicalPlanner in class Gtu

    • getStrategicalPlanner

      public final LaneBasedStrategicalPlanner getStrategicalPlanner(org.djunits.value.vdouble.scalar.Time time)
      Overrides:
      getStrategicalPlanner in class Gtu

    • getNetwork

      public RoadNetwork getNetwork()
      Returns:
      the road network to which the LaneBasedGtu belongs

    • getDesiredSpeed

      public org.djunits.value.vdouble.scalar.Speed getDesiredSpeed()
      This method returns the current desired speed of the GTU. This value is required often, so implementations can cache it.
      Returns:
      Speed; current desired speed

    • getCarFollowingAcceleration

      public org.djunits.value.vdouble.scalar.Acceleration getCarFollowingAcceleration()
      This method returns the current car-following acceleration of the GTU. This value is required often, so implementations can cache it.
      Returns:
      Acceleration; current car-following acceleration

    • getTurnIndicatorStatus

      public final TurnIndicatorStatus getTurnIndicatorStatus()
      Returns:
      the status of the turn indicator

    • getTurnIndicatorStatus

      public final TurnIndicatorStatus getTurnIndicatorStatus(org.djunits.value.vdouble.scalar.Time time)
      Parameters:
      time - Time; time to obtain the turn indicator status at
      Returns:
      the status of the turn indicator at the given time

    • setTurnIndicatorStatus

      public final void setTurnIndicatorStatus(TurnIndicatorStatus turnIndicatorStatus)
      Set the status of the turn indicator.
      Parameters:
      turnIndicatorStatus - TurnIndicatorStatus; the new status of the turn indicator.

    • getLateralPosition

      public org.djunits.value.vdouble.scalar.Length getLateralPosition(Lane lane) throws GtuException
      Returns the lateral position of the GTU relative to the lane center line. Negative values are towards the right.
      Parameters:
      lane - Lane; lane to consider (most important regarding left/right, not upstream downstream)
      Returns:
      Length; lateral position of the GTU relative to the lane center line
      Throws:
      GtuException - when the vehicle is not on the given lane.

    • setInstantaneousLaneChange

      public void setInstantaneousLaneChange(boolean instantaneous)
      Sets whether the GTU perform lane changes instantaneously or not.
      Parameters:
      instantaneous - boolean; whether the GTU perform lane changes instantaneously or not

    • isInstantaneousLaneChange

      public boolean isInstantaneousLaneChange()
      Returns whether the GTU perform lane changes instantaneously or not.
      Returns:
      boolean; whether the GTU perform lane changes instantaneously or not

    • getTacticalPlanner

      public LaneBasedTacticalPlanner getTacticalPlanner()
      Overrides:
      getTacticalPlanner in class Gtu

    • getTacticalPlanner

      public LaneBasedTacticalPlanner getTacticalPlanner(org.djunits.value.vdouble.scalar.Time time)
      Overrides:
      getTacticalPlanner in class Gtu

    • setNoLaneChangeDistance

      public final void setNoLaneChangeDistance(org.djunits.value.vdouble.scalar.Length distance)
      Set distance over which the GTU should not change lane after being created.
      Parameters:
      distance - Length; distance over which the GTU should not change lane after being created

    • laneChangeAllowed

      public final boolean laneChangeAllowed()
      Returns whether a lane change is allowed.
      Returns:
      whether a lane change is allowed

    • isBrakingLightsOn

      public boolean isBrakingLightsOn()
      The default implementation returns true if the deceleration is larger than a speed-dependent threshold given by:

      c0 * g(v) + c1 + c3*v^2

      where c0 = 0.2, c1 = 0.15 and c3 = 0.00025 (with c2 = 0 implicit) are empirically derived averages, and g(v) is 0 below 25 km/h or 1 otherwise, representing that the engine is disengaged at low speeds.
      Returns:
      boolean; whether the braking lights are on

    • isBrakingLightsOn

      public boolean isBrakingLightsOn(org.djunits.value.vdouble.scalar.Time when)
      The default implementation returns true if the deceleration is larger than a speed-dependent threshold given by:

      c0 * g(v) + c1 + c3*v^2

      where c0 = 0.2, c1 = 0.15 and c3 = 0.00025 (with c2 = 0 implicit) are empirically derived averages, and g(v) is 0 below 25 km/h or 1 otherwise, representing that the engine is disengaged at low speeds.
      Parameters:
      when - Time; time
      Returns:
      boolean; whether the braking lights are on

    • getProjectedLength

      public org.djunits.value.vdouble.scalar.Length getProjectedLength(Lane lane) throws GtuException
      Get projected length on the lane.
      Parameters:
      lane - Lane; lane to project the vehicle on
      Returns:
      Length; the length on the lane, which is different from the actual length during deviative tactical plans
      Throws:
      GtuException - when the vehicle is not on the given lane

    • toString

      public String toString()
      Overrides:
      toString in class Object