Package org.opentrafficsim.road.gtu.lane

Class AbstractLaneBasedGTU

  • All Implemented Interfaces:
    Serializable, Locatable, EventProducerInterface, org.opentrafficsim.base.Identifiable, Drawable, GTU, LaneBasedGTU
    public abstract class AbstractLaneBasedGTU
extends AbstractGTU
implements LaneBasedGTU
    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-2022 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
    BSD-style license. See OpenTrafficSim License.

    Version:
    $Revision: 1408 $, $LastChangedDate: 2015-09-24 15:17:25 +0200 (Thu, 24 Sep 2015) $, by $Author: pknoppers $, initial version Oct 22, 2014
    Author:
    Alexander Verbraeck, Peter Knoppers
    See Also:
    Serialized Form

    • Field Detail

      • initialLocationThresholdDifference

        public static Length initialLocationThresholdDifference
        The threshold distance for differences between initial locations of the GTU on different lanes.

      • 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.

    • Constructor Detail

      • AbstractLaneBasedGTU

        public AbstractLaneBasedGTU​(String id,
                            GTUType gtuType,
                            OTSRoadNetwork 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
        network - OTSRoadNetwork; the network that the GTU is initially registered in
        Throws:
        GTUException - when initial values are not correct

    • Method Detail

      • isSafeToChange

        public final boolean isSafeToChange()
                             throws GTUException
        Hack method. TODO remove and solve better
        Returns:
        safe to change
        Throws:
        GTUException - on error

      • enterLane

        public void enterLane​(Lane lane,
                      Length position,
                      GTUDirectionality gtuDirection)
               throws GTUException
        insert GTU at a certain position. This can happen at setup (first initialization), and after a lane change of the GTU. The relative position that will be registered is the referencePosition (dx, dy, dz) = (0, 0, 0). Front and rear positions are relative towards this position.
        Parameters:
        lane - Lane; the lane to add to the list of lanes on which the GTU is registered.
        gtuDirection - GTUDirectionality; the direction of the GTU on the lane (which can be bidirectional). If the GTU has a positive speed, it is moving in this direction.
        position - Length; the position on the lane.
        Throws:
        GTUException - when positioning the GTU on the lane causes a problem

      • addGtuToLane

        protected void addGtuToLane​(Lane lane,
                            Length position)
                     throws GTUException
        Part of 'enterLane' which registers the GTU with the lane so the lane can report its GTUs.
        Parameters:
        lane - Lane; lane
        position - Length; position
        Throws:
        GTUException - on exception

      • leaveLane

        public void leaveLane​(Lane lane)
               throws GTUException
        Unregister the GTU from a lane.
        Parameters:
        lane - Lane; the lane to remove from the list of lanes on which the GTU is registered.
        Throws:
        GTUException - when leaveLane should not be called

      • leaveLane

        public void leaveLane​(Lane lane,
                      boolean beingDestroyed)
               throws GTUException
        Leave a lane but do not complain about having no lanes left when beingDestroyed is true.
        Parameters:
        lane - Lane; the lane to leave
        beingDestroyed - boolean; if true, no complaints about having no lanes left
        Throws:
        GTUException - in case leaveLane should not be called

      • finalizeLaneChange

        protected void finalizeLaneChange​(LateralDirectionality laneChangeDirection)
        Performs the finalization of a lane change by leaving the from lanes.
        Parameters:
        laneChangeDirection - LateralDirectionality; direction of lane change

      • getDirection

        public final GTUDirectionality getDirection​(Lane lane)
                                     throws GTUException
        Return the directionality of a lane on which the GTU is registered for its current operational plan.
        Specified by:
        getDirection in interface LaneBasedGTU
        Parameters:
        lane - Lane; the lane for which we want to know the direction
        Returns:
        GTUDirectionality; the direction on the given lane
        Throws:
        GTUException - in case the GTU is not registered on the Lane

      • positions

        public final Map<Lane,​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.
        Specified by:
        positions in interface LaneBasedGTU
        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,​Length> positions​(RelativePosition relativePosition,
                                              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.
        Specified by:
        positions in interface LaneBasedGTU
        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 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.
        Specified by:
        position in interface LaneBasedGTU
        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.

      • translatedPosition

        public Length translatedPosition​(Lane projectionLane,
                                 RelativePosition relativePosition,
                                 Time when)
                          throws GTUException
        Return the longitudinal position that the indicated relative position of this GTU would have if it were to change to another Lane with a / the current CrossSectionLink. This point may be before the begin or after the end of the link of the projection lane of the GTU. This preserves the length of the GTU.
        Parameters:
        projectionLane - Lane; the lane onto which the position of this GTU must be projected
        relativePosition - RelativePosition; the point on this GTU that must be projected
        when - Time; the time for which to project the position of this GTU
        Returns:
        Length; the position of this GTU in the projectionLane
        Throws:
        GTUException - when projectionLane it not in any of the CrossSectionLink that the GTU is on

      • projectedPosition

        public Length projectedPosition​(Lane projectionLane,
                                RelativePosition relativePosition,
                                Time when)
                         throws GTUException
        Return the longitudinal position on the projection lane that has the same fractional position on one of the current lanes of the indicated relative position. This preserves the fractional positions of all relative positions of the GTU.
        Parameters:
        projectionLane - Lane; the lane onto which the position of this GTU must be projected
        relativePosition - RelativePosition; the point on this GTU that must be projected
        when - Time; the time for which to project the position of this GTU
        Returns:
        Length; the position of this GTU in the projectionLane
        Throws:
        GTUException - when projectionLane it not in any of the CrossSectionLink that the GTU is on

      • position

        public Length position​(Lane lane,
                       RelativePosition relativePosition,
                       Time when)
                throws GTUException
        Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane.
        Specified by:
        position in interface LaneBasedGTU
        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 DirectedLanePosition getReferencePosition()
                                          throws GTUException
        Return the current Lane, position and directionality of the GTU.
        Specified by:
        getReferencePosition in interface LaneBasedGTU
        Returns:
        DirectedLanePosition; 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

      • scheduleEnterLeaveTriggers

        protected void scheduleEnterLeaveTriggers()
                                   throws NetworkException,
                                          SimRuntimeException,
                                          GTUException
        Schedule the triggers for this GTU that are going to happen until the next evaluation time. Also schedule the registration and deregistration of lanes when the vehicle enters or leaves them, at the exact right time.
        Note: when the GTU makes a lane change, the vehicle will be registered for both lanes during the entire maneuver.
        Throws:
        NetworkException - on network inconsistency
        SimRuntimeException - should never happen
        GTUException - when a branch is reached where the GTU does not know where to go next

      • 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.
        Specified by:
        fractionalPositions in interface LaneBasedGTU
        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,
                                                        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.
        Specified by:
        fractionalPositions in interface LaneBasedGTU
        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,
                                       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.
        Specified by:
        fractionalPosition in interface LaneBasedGTU
        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.
        Specified by:
        fractionalPosition in interface LaneBasedGTU
        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,
                             SimEventInterface<Duration> event)
        Add an event to the list of lane triggers scheduled for this GTU.
        Specified by:
        addTrigger in interface LaneBasedGTU
        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

      • getDesiredSpeed

        public Speed getDesiredSpeed()
        This method returns the current desired speed of the GTU. This value is required often, so implementations can cache it.
        Specified by:
        getDesiredSpeed in interface LaneBasedGTU
        Returns:
        Speed; current desired speed

      • getCarFollowingAcceleration

        public Acceleration getCarFollowingAcceleration()
        This method returns the current car-following acceleration of the GTU. This value is required often, so implementations can cache it.
        Specified by:
        getCarFollowingAcceleration in interface LaneBasedGTU
        Returns:
        Acceleration; current car-following acceleration

      • getTurnIndicatorStatus

        public final TurnIndicatorStatus getTurnIndicatorStatus​(Time time)
        Specified by:
        getTurnIndicatorStatus in interface LaneBasedGTU
        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.
        Specified by:
        setTurnIndicatorStatus in interface LaneBasedGTU
        Parameters:
        turnIndicatorStatus - TurnIndicatorStatus; the new status of the turn indicator.