CarFollowingUtil.java

  1. package org.opentrafficsim.road.gtu.lane.tactical.util;

  2. import org.djunits.unit.AccelerationUnit;
  3. import org.djunits.unit.SpeedUnit;
  4. import org.djunits.value.vdouble.scalar.Acceleration;
  5. import org.djunits.value.vdouble.scalar.Length;
  6. import org.djunits.value.vdouble.scalar.Speed;
  7. import org.djutils.exceptions.Throw;
  8. import org.djutils.exceptions.Try;
  9. import org.opentrafficsim.base.parameters.ParameterException;
  10. import org.opentrafficsim.base.parameters.Parameters;
  11. import org.opentrafficsim.core.gtu.GtuException;
  12. import org.opentrafficsim.road.gtu.lane.perception.PerceptionIterable;
  13. import org.opentrafficsim.road.gtu.lane.perception.PerceptionIterableSet;
  14. import org.opentrafficsim.road.gtu.lane.perception.headway.AbstractHeadway;
  15. import org.opentrafficsim.road.gtu.lane.perception.headway.Headway;
  16. import org.opentrafficsim.road.gtu.lane.perception.headway.HeadwayGtu;
  17. import org.opentrafficsim.road.gtu.lane.tactical.following.CarFollowingModel;
  18. import org.opentrafficsim.road.network.speed.SpeedLimitInfo;

  19. /**
  20.  * Static methods regarding car-following for composition in tactical planners.
  21.  * <p>
  22.  * Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
  23.  * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
  24.  * </p>
  25.  * @author <a href="https://github.com/averbraeck">Alexander Verbraeck</a>
  26.  * @author <a href="https://github.com/wjschakel">Wouter Schakel</a>
  27.  */
  28. public final class CarFollowingUtil
  29. {

  30.     /**
  31.      * Do not instantiate.
  32.      */
  33.     private CarFollowingUtil()
  34.     {
  35.         //
  36.     }

  37.     /**
  38.      * Follow a set of headway GTUs.
  39.      * @param carFollowingModel CarFollowingModel; car-following model
  40.      * @param parameters Parameters; parameters
  41.      * @param speed Speed; current speed
  42.      * @param speedLimitInfo SpeedLimitInfo; speed limit info
  43.      * @param distance Length; distance
  44.      * @param leaderSpeed Speed; speed of the leader
  45.      * @return acceleration for following the leader
  46.      * @throws ParameterException if a parameter is not given or out of bounds
  47.      */
  48.     public static Acceleration followSingleLeader(final CarFollowingModel carFollowingModel, final Parameters parameters,
  49.             final Speed speed, final SpeedLimitInfo speedLimitInfo, final Length distance, final Speed leaderSpeed)
  50.             throws ParameterException
  51.     {
  52.         return carFollowingModel.followingAcceleration(parameters, speed, speedLimitInfo, createLeader(distance, leaderSpeed));
  53.     }

  54.     /**
  55.      * Follow a set of headway GTUs.
  56.      * @param carFollowingModel CarFollowingModel; car-following model
  57.      * @param parameters Parameters; parameters
  58.      * @param speed Speed; current speed
  59.      * @param speedLimitInfo SpeedLimitInfo; speed limit info
  60.      * @param leader HeadwayGtu; leader
  61.      * @return acceleration for following the leader
  62.      * @throws ParameterException if a parameter is not given or out of bounds
  63.      */
  64.     public static Acceleration followSingleLeader(final CarFollowingModel carFollowingModel, final Parameters parameters,
  65.             final Speed speed, final SpeedLimitInfo speedLimitInfo, final HeadwayGtu leader) throws ParameterException
  66.     {
  67.         return carFollowingModel.followingAcceleration(parameters, speed, speedLimitInfo, new PerceptionIterableSet<>(leader));
  68.     }

  69.     /**
  70.      * Stop within given distance.
  71.      * @param carFollowingModel CarFollowingModel; car-following model
  72.      * @param parameters Parameters; parameters
  73.      * @param speed Speed; current speed
  74.      * @param speedLimitInfo SpeedLimitInfo; speed limit info
  75.      * @param distance Length; distance to stop over
  76.      * @return acceleration to stop over distance
  77.      * @throws ParameterException if a parameter is not given or out of bounds
  78.      */
  79.     public static Acceleration stop(final CarFollowingModel carFollowingModel, final Parameters parameters, final Speed speed,
  80.             final SpeedLimitInfo speedLimitInfo, final Length distance) throws ParameterException
  81.     {
  82.         return carFollowingModel.followingAcceleration(parameters, speed, speedLimitInfo, createLeader(distance, Speed.ZERO));
  83.     }

  84.     /**
  85.      * Return constant acceleration in order to stop in specified distance. The car-following model is used to determine the
  86.      * stopping distance (i.e. distance remaining at stand still, e.g. 1-3m).
  87.      * @param carFollowingModel CarFollowingModel; car-following model
  88.      * @param parameters Parameters; parameters
  89.      * @param speed Speed; current speed
  90.      * @param distance Length; distance to stop over
  91.      * @return constant acceleration in order to stop in specified distance
  92.      * @throws ParameterException on missing parameter
  93.      */
  94.     public static Acceleration constantAccelerationStop(final CarFollowingModel carFollowingModel, final Parameters parameters,
  95.             final Speed speed, final Length distance) throws ParameterException
  96.     {
  97.         Length s0 = carFollowingModel.desiredHeadway(parameters, Speed.ZERO);
  98.         return new Acceleration(-0.5 * speed.si * speed.si / (distance.si - s0.si), AccelerationUnit.SI);
  99.     }

  100.     /**
  101.      * Calculate free acceleration.
  102.      * @param carFollowingModel CarFollowingModel; car-following model
  103.      * @param parameters Parameters; parameters
  104.      * @param speed Speed; current speed
  105.      * @param speedLimitInfo SpeedLimitInfo; speed limit info
  106.      * @return acceleration free acceleration
  107.      * @throws ParameterException if a parameter is not given or out of bounds
  108.      */
  109.     public static Acceleration freeAcceleration(final CarFollowingModel carFollowingModel, final Parameters parameters,
  110.             final Speed speed, final SpeedLimitInfo speedLimitInfo) throws ParameterException
  111.     {
  112.         PerceptionIterableSet<Headway> leaders = new PerceptionIterableSet<>();
  113.         return carFollowingModel.followingAcceleration(parameters, speed, speedLimitInfo, leaders);
  114.     }

  115.     /**
  116.      * Returns an acceleration based on the car-following model in order to adjust the speed to a given value at some location
  117.      * ahead. This is done by placing a virtual vehicle somewhere near the location. Both the location and speed of this virtual
  118.      * vehicle are dynamically adjusted to resemble a car-following situation. To explain, first consider the situation where a
  119.      * virtual vehicle is placed at the target speed and such that the equilibrium headway is in line with the location:
  120.      *
  121.      * <pre>
  122.      *
  123.      *  ___    location of target speed --)|        ___
  124.      * |___|(--------------s--------------) (--h--)|___| ))) vTar
  125.      * </pre>
  126.      *
  127.      * Here, {@code s} is the distance to the target speed, and {@code h} is the desired headway if the vehicle would drive at
  128.      * the target speed {@code vTar}.<br>
  129.      * <br>
  130.      * In this way car-following models will first underestimate the required deceleration, as the virtual vehicle is actually
  131.      * stationary and does not move with {@code vTar} at all. Because of this underestimation, strong deceleration is required
  132.      * later. This behavior is not in line with the sensitivity parameters of the car-following model.<br>
  133.      * <br>
  134.      * To correct for the fact that the virtual vehicle is actually not moving, the speed difference should be larger, i.e. the
  135.      * speed of the virtual vehicle {@code vTar'} should be lower. We require:
  136.      * <ul>
  137.      * <li>if {@code v = vTar} then {@code vTar' = vTar}, otherwise there is an incentive to accelerate or decelerate for no
  138.      * good reason</li>
  139.      * <li>if {@code vTar ~ 0} then {@code vTar' ~ 0}, as car-following models are suitable for stopping and need no additional
  140.      * incentive to decelerate in such cases</li>
  141.      * <li>if {@code 0 < vTar < v} then {@code vTar' < vTar}, introducing additional deceleration to compensate for the fact
  142.      * that the virtual vehicle does not move
  143.      * </ul>
  144.      * These requirements are met by {@code vTar' = vTar * (vTar/v) = vTar^2/v}.<br>
  145.      * <br>
  146.      * Furthermore, if {@code v < vTar} we get {@code vTar' > vTar} leading to additional acceleration. Acceleration is then
  147.      * appropriate, and possibly limited by a free term in the car-following model.<br>
  148.      * <br>
  149.      * The virtual vehicle is thus placed with speed {@code vTar'} at a distance {@code s + h'} where {@code h'} is the desired
  150.      * headway if the vehicle would drive at speed {@code vTar'}. Both {@code vTar'} and {@code h'} depend on the current speed
  151.      * of the vehicle, so the virtual vehicle in this case actually moves, but not with {@code vTar}.<br>
  152.      * <br>
  153.      * This approach has been tested with the IDM+ to deliver decelerations in line with the parameters. On a plane with initial
  154.      * speed ranging from 0 to 33.33m/s and a target speed in 300m also ranging from 0 to 33.33m/s, strongest deceleration is
  155.      * equal to the car-following model stopping from 33.33m/s to a stand-still vehicle in 300m (+ stopping distance of 3m).
  156.      * Throughout the plane the maximum deceleration of each scenario is close to this value, unless the initial speed is so
  157.      * low, and the target speed is so high, that such levels of deceleration are never required.<br>
  158.      * <br>
  159.      * @param carFollowingModel CarFollowingModel; car-following model to use
  160.      * @param parameters Parameters; parameters
  161.      * @param speed Speed; current speed
  162.      * @param speedLimitInfo SpeedLimitInfo; info regarding the desired speed for car-following
  163.      * @param distance Length; distance to the location of the target speed
  164.      * @param targetSpeed Speed; target speed
  165.      * @return acceleration acceleration based on the car-following model in order to adjust the speed
  166.      * @throws ParameterException if parameter exception occurs
  167.      * @throws NullPointerException if any input is null
  168.      * @throws IllegalArgumentException if the distance or target speed is not at least 0
  169.      */
  170.     public static Acceleration approachTargetSpeed(final CarFollowingModel carFollowingModel, final Parameters parameters,
  171.             final Speed speed, final SpeedLimitInfo speedLimitInfo, final Length distance, final Speed targetSpeed)
  172.             throws ParameterException
  173.     {
  174.         Throw.whenNull(parameters, "Parameters may not be null.");
  175.         Throw.whenNull(speed, "Speed may not be null.");
  176.         Throw.whenNull(speedLimitInfo, "Speed limit info may not be null.");
  177.         Throw.whenNull(distance, "Distance may not be null");
  178.         Throw.whenNull(targetSpeed, "Target speed may not be null");
  179.         Throw.when(distance.si < 0, IllegalArgumentException.class, "Distance must be at least 0.");
  180.         Throw.when(targetSpeed.si < 0, IllegalArgumentException.class, "Target speed must be at least 0.");
  181.         // adjust speed of virtual vehicle to add deceleration incentive as the virtual vehicle does not move
  182.         Speed virtualSpeed;
  183.         if (speed.si > 0)
  184.         {
  185.             virtualSpeed = new Speed(targetSpeed.si * targetSpeed.si / speed.si, SpeedUnit.SI);
  186.         }
  187.         else
  188.         {
  189.             virtualSpeed = new Speed(Double.MAX_VALUE, SpeedUnit.SI);
  190.         }
  191.         // set distance in line with equilibrium headway at virtual speed
  192.         Length virtualDistance = distance.plus(carFollowingModel.desiredHeadway(parameters, virtualSpeed));
  193.         // calculate acceleration towards virtual vehicle with car-following model
  194.         return carFollowingModel.followingAcceleration(parameters, speed, speedLimitInfo,
  195.                 createLeader(virtualDistance, virtualSpeed));
  196.     }

  197.     /**
  198.      * Create a single leader set.
  199.      * @param headway Length; distance to the leader
  200.      * @param speed Speed; leader speed
  201.      * @return Set; set with a single leader
  202.      */
  203.     private static PerceptionIterable<Headway> createLeader(final Length headway, final Speed speed)
  204.     {
  205.         PerceptionIterable<Headway> leaders =
  206.                 Try.assign(() -> new PerceptionIterableSet<>(new CarFollowingHeadway(headway, speed)),
  207.                         "Exception during headway creation.");
  208.         return leaders;
  209.     }

  210.     /**
  211.      * Simple headway implementation for minimum car-following information.
  212.      * <p>
  213.      * Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
  214.      * <br>
  215.      * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
  216.      * </p>
  217.      * @author <a href="https://github.com/averbraeck">Alexander Verbraeck</a>
  218.      * @author <a href="https://tudelft.nl/staff/p.knoppers-1">Peter Knoppers</a>
  219.      * @author <a href="https://github.com/wjschakel">Wouter Schakel</a>
  220.      */
  221.     public static class CarFollowingHeadway extends AbstractHeadway
  222.     {
  223.         /** */
  224.         private static final long serialVersionUID = 20180226L;

  225.         /** Speed of the leader. */
  226.         private final Speed speed;

  227.         /**
  228.          * Constructor.
  229.          * @param headway Length; distance to the leader
  230.          * @param speed Speed; leader speed
  231.          * @throws GtuException on exception
  232.          */
  233.         public CarFollowingHeadway(final Length headway, final Speed speed) throws GtuException
  234.         {
  235.             super(headway);
  236.             this.speed = speed;
  237.         }

  238.         /** {@inheritDoc} */
  239.         @Override
  240.         public String getId()
  241.         {
  242.             return null;
  243.         }

  244.         /** {@inheritDoc} */
  245.         @Override
  246.         public Length getLength()
  247.         {
  248.             return null;
  249.         }

  250.         /** {@inheritDoc} */
  251.         @Override
  252.         public Speed getSpeed()
  253.         {
  254.             return this.speed;
  255.         }

  256.         /** {@inheritDoc} */
  257.         @Override
  258.         public ObjectType getObjectType()
  259.         {
  260.             return null;
  261.         }

  262.         /** {@inheritDoc} */
  263.         @Override
  264.         public Acceleration getAcceleration()
  265.         {
  266.             return null;
  267.         }
  268.     }

  269. }