1 package org.opentrafficsim.road.gtu.lane.tactical.following;
2
3 import java.util.SortedMap;
4
5 import org.djunits.unit.AccelerationUnit;
6 import org.djunits.value.vdouble.scalar.Acceleration;
7 import org.djunits.value.vdouble.scalar.Length;
8 import org.djunits.value.vdouble.scalar.Speed;
9 import org.opentrafficsim.core.gtu.behavioralcharacteristics.BehavioralCharacteristics;
10 import org.opentrafficsim.core.gtu.behavioralcharacteristics.ParameterException;
11 import org.opentrafficsim.road.network.speed.SpeedLimitInfo;
12
13 import nl.tudelft.simulation.language.Throw;
14
15 /**
16 * Default implementation where desired speed and headway are pre-calculated for car-following.
17 * <p>
18 * Copyright (c) 2013-2016 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
19 * BSD-style license. See <a href="http://opentrafficsim.org/docs/current/license.html">OpenTrafficSim License</a>.
20 * <p>
21 * @version $Revision$, $LastChangedDate$, by $Author$, initial version Apr 2016 <br>
22 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
23 */
24 public abstract class AbstractCarFollowingModel implements CarFollowingModel
25 {
26
27 /**
28 * Forwards the calculation to a similar method with desired speed and desired (equilibrium) headway pre-calculated.
29 * Additionally, if the headway to the (first) leader is negative, <tt>Double.NEGATIVE_INFINITY</tt> is returned as an
30 * 'inappropriate' acceleration, since car-following models are then undefined. This may for example occur when checking a
31 * gap in an adjacent lane for lane changing. It is then up to the client to decide what to do. E.g. limit deceleration to
32 * an extent depending on the circumstances, or divert from a certain behavior.
33 * @param behavioralCharacteristics behavioral characteristics
34 * @param speed current speed
35 * @param speedLimitInfo info regarding the desired speed for car-following
36 * @param leaders set of leader headways and speeds, ordered by headway (closest first)
37 * @return car-following acceleration
38 * @throws ParameterException if parameter exception occurs
39 * @throws NullPointerException if any input is null
40 */
41 @Override
42 public final Acceleration followingAcceleration(final BehavioralCharacteristics behavioralCharacteristics,
43 final Speed speed, final SpeedLimitInfo speedLimitInfo, final SortedMap<Length, Speed> leaders)
44 throws ParameterException
45 {
46 Throw.whenNull(behavioralCharacteristics, "Behavioral characteristics may not be null.");
47 Throw.whenNull(speed, "Speed may not be null.");
48 Throw.whenNull(speedLimitInfo, "Speed limit info may not be null.");
49 Throw.whenNull(leaders, "Leaders may not be null.");
50 // Catch negative headway
51 if (!leaders.isEmpty() && leaders.firstKey().si <= 0)
52 {
53 return new Acceleration(Double.NEGATIVE_INFINITY, AccelerationUnit.SI);
54 }
55 // Forward to method with desired speed and headway predetermined by this car-following model.
56 return followingAcceleration(behavioralCharacteristics, speed, desiredSpeed(behavioralCharacteristics,
57 speedLimitInfo), desiredHeadway(behavioralCharacteristics, speed), leaders);
58 }
59
60 /**
61 * Determination of car-following acceleration, possibly based on multiple leaders.
62 * @param behavioralCharacteristics behavioral characteristics
63 * @param speed current speed
64 * @param desiredSpeed desired speed
65 * @param desiredHeadway desired headway
66 * @param leaders set of leader headways (guaranteed positive) and speeds, ordered by headway (closest first)
67 * @return car-following acceleration
68 * @throws ParameterException if parameter exception occurs
69 */
70 protected abstract Acceleration followingAcceleration(BehavioralCharacteristics behavioralCharacteristics, Speed speed,
71 Speed desiredSpeed, Length desiredHeadway, SortedMap<Length, Speed> leaders) throws ParameterException;
72
73 /** {@inheritDoc} */
74 @SuppressWarnings("checkstyle:designforextension")
75 @Override
76 public String toString()
77 {
78 return getLongName();
79 }
80
81 }