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