1 package org.opentrafficsim.road.gtu.lane.tactical.following;
2
3 import org.djunits.value.vdouble.scalar.Acceleration;
4 import org.djunits.value.vdouble.scalar.Length;
5 import org.djunits.value.vdouble.scalar.Speed;
6 import org.opentrafficsim.base.parameters.ParameterException;
7 import org.opentrafficsim.base.parameters.ParameterTypeAcceleration;
8 import org.opentrafficsim.base.parameters.ParameterTypeDouble;
9 import org.opentrafficsim.base.parameters.ParameterTypeDuration;
10 import org.opentrafficsim.base.parameters.ParameterTypeLength;
11 import org.opentrafficsim.base.parameters.ParameterTypes;
12 import org.opentrafficsim.base.parameters.Parameters;
13 import org.opentrafficsim.base.parameters.constraint.ConstraintInterface;
14 import org.opentrafficsim.road.gtu.lane.perception.PerceptionIterable;
15 import org.opentrafficsim.road.gtu.lane.perception.headway.Headway;
16 import org.opentrafficsim.road.gtu.lane.tactical.util.SpeedLimitUtil;
17 import org.opentrafficsim.road.network.speed.SpeedLimitInfo;
18
19 /**
20 * Implementation of the IDM. See <a
21 * href=https://en.wikipedia.org/wiki/Intelligent_driver_model>https://en.wikipedia.org/wiki/Intelligent_driver_model</a>
22 * <p>
23 * Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
24 * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
25 * </p>
26 * @author <a href="https://github.com/averbraeck">Alexander Verbraeck</a>
27 * @author <a href="https://tudelft.nl/staff/p.knoppers-1">Peter Knoppers</a>
28 * @author <a href="https://github.com/wjschakel">Wouter Schakel</a>
29 */
30 //@docs/06-behavior/parameters.md
31 public abstract class AbstractIdm extends AbstractCarFollowingModel
32 {
33
34 /** Acceleration parameter type. */
35 // @docs/06-behavior/parameters.md
36 protected static final ParameterTypeAcceleration A = ParameterTypes.A;
37
38 /** Comfortable deceleration parameter type. */
39 protected static final ParameterTypeAcceleration B = ParameterTypes.B;
40
41 /** Desired headway parameter type. */
42 protected static final ParameterTypeDuration T = ParameterTypes.T;
43
44 /** Stopping distance parameter type. */
45 protected static final ParameterTypeLength S0 = ParameterTypes.S0;
46
47 /** Adjustment deceleration parameter type. */
48 protected static final ParameterTypeAcceleration B0 = ParameterTypes.B0;
49
50 /** Speed limit adherence factor parameter type. */
51 protected static final ParameterTypeDouble FSPEED = ParameterTypes.FSPEED;
52
53 /** Acceleration flattening. */
54 // @docs/06-behavior/parameters.md
55 public static final ParameterTypeDouble DELTA = new ParameterTypeDouble("delta",
56 "Acceleration flattening exponent towards desired speed", 4.0, ConstraintInterface.POSITIVE);
57
58 /** Default IDM desired headway model. */
59 public static final DesiredHeadwayModel HEADWAY = new DesiredHeadwayModel()
60 {
61 @Override
62 public Length desiredHeadway(final Parameters parameters, final Speed speed) throws ParameterException
63 {
64 return Length.instantiateSI(parameters.getParameter(S0).si + speed.si * parameters.getParameter(T).si);
65 }
66 };
67
68 /** Default IDM desired speed model. */
69 public static final DesiredSpeedModel DESIRED_SPEED = new DesiredSpeedModel()
70 {
71 @Override
72 public Speed desiredSpeed(final Parameters parameters, final SpeedLimitInfo speedInfo) throws ParameterException
73 {
74 Speed consideredSpeed = SpeedLimitUtil.getLegalSpeedLimit(speedInfo).times(parameters.getParameter(FSPEED));
75 Speed maxVehicleSpeed = SpeedLimitUtil.getMaximumVehicleSpeed(speedInfo);
76 return consideredSpeed.le(maxVehicleSpeed) ? consideredSpeed : maxVehicleSpeed;
77 }
78 };
79
80 /**
81 * Constructor with modular models for desired headway and desired speed.
82 * @param desiredHeadwayModel DesiredHeadwayModel; desired headway model
83 * @param desiredSpeedModel DesiredSpeedModel; desired speed model
84 */
85 public AbstractIdm(final DesiredHeadwayModel desiredHeadwayModel, final DesiredSpeedModel desiredSpeedModel)
86 {
87 super(desiredHeadwayModel, desiredSpeedModel);
88 }
89
90 /**
91 * Determination of car-following acceleration, possibly based on multiple leaders. This implementation calculates the IDM
92 * free term, which is returned if there are no leaders. If there are leaders <code>combineInteractionTerm()</code> is
93 * invoked to combine the free term with some implementation specific interaction term. The IDM free term is limited by a
94 * deceleration of <code>B0</code> for cases where the current speed is above the desired speed. This method can be
95 * overridden if the free term needs to be redefined.
96 * @param parameters Parameters; Parameters.
97 * @param speed Speed; Current speed.
98 * @param desiredSpeed Speed; Desired speed.
99 * @param desiredHeadway Length; Desired headway.
100 * @param leaders PerceptionIterable<? extends Headway>; Set of leader headways (guaranteed positive) and speeds,
101 * ordered by headway (closest first).
102 * @throws ParameterException If parameter exception occurs.
103 * @return Car-following acceleration.
104 */
105 @Override
106 @SuppressWarnings("checkstyle:designforextension")
107 protected Acceleration followingAcceleration(final Parameters parameters, final Speed speed, final Speed desiredSpeed,
108 final Length desiredHeadway, final PerceptionIterable<? extends Headway> leaders) throws ParameterException
109 {
110 Acceleration a = parameters.getParameter(A);
111 Acceleration b0 = parameters.getParameter(B0);
112 double delta = parameters.getParameter(DELTA);
113 double aFree = a.si * (1 - Math.pow(speed.si / desiredSpeed.si, delta));
114 // limit deceleration in free term (occurs if speed > desired speed)
115 aFree = aFree > -b0.si ? aFree : -b0.si;
116 // return free term if there are no leaders
117 if (leaders.isEmpty())
118 {
119 return Acceleration.instantiateSI(aFree);
120 }
121 // return combined acceleration
122 return combineInteractionTerm(Acceleration.instantiateSI(aFree), parameters, speed, desiredSpeed, desiredHeadway,
123 leaders);
124 }
125
126 /**
127 * Combines an interaction term with the free term. There should be at least 1 leader for this method.
128 * @param aFree Acceleration; Free term of acceleration.
129 * @param parameters Parameters; Parameters.
130 * @param speed Speed; Current speed.
131 * @param desiredSpeed Speed; Desired speed.
132 * @param desiredHeadway Length; Desired headway.
133 * @param leaders PerceptionIterable<? extends Headway>; Set of leader headways (guaranteed positive) and speeds,
134 * ordered by headway (closest first).
135 * @return Combination of terms into a single acceleration.
136 * @throws ParameterException In case of parameter exception.
137 */
138 protected abstract Acceleration combineInteractionTerm(Acceleration aFree, Parameters parameters, Speed speed,
139 Speed desiredSpeed, Length desiredHeadway, PerceptionIterable<? extends Headway> leaders) throws ParameterException;
140
141 /**
142 * Determines the dynamic desired headway, which is non-negative.
143 * @param parameters Parameters; Parameters.
144 * @param speed Speed; Current speed.
145 * @param desiredHeadway Length; Desired headway.
146 * @param leaderSpeed Speed; Speed of the leading vehicle.
147 * @return Dynamic desired headway.
148 * @throws ParameterException In case of parameter exception.
149 */
150 protected final Length dynamicDesiredHeadway(final Parameters parameters, final Speed speed, final Length desiredHeadway,
151 final Speed leaderSpeed) throws ParameterException
152 {
153 double sStar = desiredHeadway.si + dynamicHeadwayTerm(parameters, speed, leaderSpeed).si;
154 /*
155 * Due to a power of 2 in the IDM, negative values of sStar are not allowed. A negative sStar means that the leader is
156 * faster to such an extent, that the equilibrium headway (s0+vT) is completely compensated by the dynamic part in
157 * sStar. This might occur if a much faster leader changes lane closely in front. The compensation is limited to the
158 * equilibrium headway minus the stopping distance (i.e. sStar > s0), which means the driver wants to follow with
159 * acceleration. Note that usually the free term determines acceleration in such cases.
160 */
161 Length s0 = parameters.getParameter(S0);
162 /*
163 * Limit used to be 0, but the IDM is very sensitive there. With a decelerating leader, an ok acceleration in one time
164 * step, may results in acceleration < -10 in the next.
165 */
166 return Length.instantiateSI(sStar >= s0.si ? sStar : s0.si);
167 }
168
169 /**
170 * Determines the dynamic headway term. May be used on individual leaders for multi-anticipative following.
171 * @param parameters Parameters; Parameters.
172 * @param speed Speed; Current speed.
173 * @param leaderSpeed Speed; Speed of the leading vehicle.
174 * @return Dynamic headway term.
175 * @throws ParameterException In case of parameter exception.
176 */
177 protected final Length dynamicHeadwayTerm(final Parameters parameters, final Speed speed, final Speed leaderSpeed)
178 throws ParameterException
179 {
180 Acceleration a = parameters.getParameter(A);
181 Acceleration b = parameters.getParameter(B);
182 return Length.instantiateSI(speed.si * (speed.si - leaderSpeed.si) / (2 * Math.sqrt(a.si * b.si)));
183 }
184
185 }