1 package org.opentrafficsim.road.gtu.lane.tactical.following;
2
3 import java.util.Collection;
4
5 import org.djunits.value.vdouble.scalar.Acceleration;
6 import org.djunits.value.vdouble.scalar.Duration;
7 import org.djunits.value.vdouble.scalar.Length;
8 import org.djunits.value.vdouble.scalar.Speed;
9 import org.djunits.value.vdouble.scalar.Time;
10 import org.opentrafficsim.core.gtu.GTUException;
11 import org.opentrafficsim.road.gtu.lane.LaneBasedGTU;
12 import org.opentrafficsim.road.gtu.lane.perception.headway.Headway;
13
14 /**
15 * GTU following model interface. <br>
16 * GTU following models following this interface compute an acceleration.
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/license.html">OpenTrafficSim License</a>.
20 * <p>
21 * @version $Revision: 1401 $, $LastChangedDate: 2015-09-14 01:33:02 +0200 (Mon, 14 Sep 2015) $, by $Author: averbraeck $,
22 * initial version Jul 2, 2014 <br>
23 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
24 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
25 */
26 public interface GTUFollowingModelOld extends CarFollowingModel
27 {
28 /**
29 * Compute the acceleration that would be used to follow a leader.<br>
30 * @param gtu LaneBasedGTU; the GTU for which acceleration is computed
31 * @param leaderSpeed Speed; the speed of the leader
32 * @param headway Length; the headway of the leader
33 * @param maxDistance Length; the maximum distance we can cover at the current time, e.g. as the result of a lane drop
34 * @param speedLimit Speed; the local speed limit
35 * @return AccelerationStep; the result of application of the GTU following model
36 * @throws GTUException when the speed of the gtu cannot be determined
37 */
38 AccelerationStep computeAccelerationStep(final LaneBasedGTU gtu, final Speed leaderSpeed, final Length headway,
39 final Length maxDistance, final Speed speedLimit) throws GTUException;
40
41 /**
42 * Compute the acceleration that would be used to follow a leader.<br>
43 * @param gtu LaneBasedGTU; the GTU for which acceleration is computed
44 * @param leaderSpeed Speed; the speed of the leader
45 * @param headway Length; the headway of the leader
46 * @param maxDistance Length; the maximum distance we can cover at the current time, e.g. as the result of a lane drop
47 * @param speedLimit Speed; the local speed limit
48 * @param stepSize given step size, which can be longer or shorter than the provided step size in the algorithms.
49 * @return AccelerationStep; the result of application of the GTU following model
50 * @throws GTUException when the speed of the gtu cannot be determined
51 */
52 AccelerationStep computeAccelerationStep(final LaneBasedGTU gtu, final Speed leaderSpeed, final Length headway,
53 final Length maxDistance, final Speed speedLimit, final Duration stepSize) throws GTUException;
54
55 /**
56 * Compute the acceleration that would be used to follow a leader.<br>
57 * @param followerSpeed Speed; the speed of the follower at the current time
58 * @param followerMaximumSpeed Speed; the maximum speed that the follower is capable of driving at
59 * @param leaderSpeed Speed; the speed of the follower at the current time
60 * @param headway Length; the <b>net</b> headway (distance between the front of the follower to the rear of the leader)
61 * at the current time, or the maximum distance we can cover at the current time, e.g. as the result of a lane
62 * drop
63 * @param speedLimit Speed; the local speed limit
64 * @return Acceleration; the acceleration (or, if negative, deceleration) resulting from application of the GTU following
65 * model
66 */
67 Acceleration computeAcceleration(final Speed followerSpeed, Speed followerMaximumSpeed, final Speed leaderSpeed,
68 final Length headway, final Speed speedLimit);
69
70 /**
71 * Compute the acceleration that would be used to follow a leader.<br>
72 * @param followerSpeed Speed; the speed of the follower at the current time
73 * @param followerMaximumSpeed Speed; the maximum speed that the follower is capable of driving at
74 * @param leaderSpeed Speed; the speed of the follower at the current time
75 * @param headway Length; the <b>net</b> headway (distance between the front of the follower to the rear of the leader)
76 * at the current time, or the maximum distance we can cover at the current time, e.g. as the result of a lane
77 * drop
78 * @param speedLimit Speed; the local speed limit
79 * @param stepSize given step size, which can be longer or shorter than the provided step size in the algorithms.
80 * @return Acceleration; the acceleration (or, if negative, deceleration) resulting from application of the GTU following
81 * model
82 */
83 Acceleration computeAcceleration(final Speed followerSpeed, Speed followerMaximumSpeed, final Speed leaderSpeed,
84 final Length headway, final Speed speedLimit, final Duration stepSize);
85
86 /**
87 * Compute the acceleration that would be used to follow a leader.<br>
88 * @param followerSpeed Speed; the speed of the follower at the current time
89 * @param leaderSpeed Speed; the speed of the follower at the current time
90 * @param headway Length; the <b>net</b> headway (distance between the front of the follower to the rear of the leader)
91 * at the current time, or the maximum distance we can cover at the current time, e.g. as the result of a lane
92 * drop
93 * @param speedLimit Speed; the local speed limit
94 * @param currentTime to be used to determine the validity of the AccelerationStep
95 * @return Acceleration; the acceleration (or, if negative, deceleration) resulting from application of the GTU following
96 * model
97 */
98 AccelerationStep computeAccelerationStep(Speed followerSpeed, Speed leaderSpeed, Length headway,
99 Speed speedLimit, Time currentTime);
100
101 /**
102 * Compute the acceleration that would be used to follow a leader.<br>
103 * @param followerSpeed Speed; the speed of the follower at the current time
104 * @param leaderSpeed Speed; the speed of the follower at the current time
105 * @param headway Length; the <b>net</b> headway (distance between the front of the follower to the rear of the leader)
106 * at the current time, or the maximum distance we can cover at the current time, e.g. as the result of a lane
107 * drop
108 * @param speedLimit Speed; the local speed limit
109 * @param currentTime to be used to determine the validity of the AccelerationStep
110 * @param stepSize given step size, which can be longer or shorter than the provided step size in the algorithms.
111 * @return Acceleration; the acceleration (or, if negative, deceleration) resulting from application of the GTU following
112 * model
113 */
114 AccelerationStep computeAccelerationStep(Speed followerSpeed, Speed leaderSpeed, Length headway,
115 Speed speedLimit, Time currentTime, final Duration stepSize);
116
117 /**
118 * Compute the lowest accelerations (or most severe decelerations) that would be used if a referenceGTU is present
119 * (inserted, or not removed) in a set of other GTUs.<br>
120 * If any GTU in the set of otherGTUs has a null headway (indicating that the other GTU is in fact parallel to the
121 * referenceGTU), prohibitive decelerations shall be returned.<br>
122 * Two AccelerationStep values are returned in a DualAccelerationStep.<br>
123 * or should slow down for a crossing from accelerating to unsafe speeds.
124 * @param gtu LaneBasedGTU; the GTU for which the accelerations are computed
125 * @param otherHeadways Collection<HeadwayGTU>; the other GTUs. A negative headway value indicates that the other
126 * GTU is a follower. NB. If the referenceGTU is contained in this Collection, it is ignored.
127 * @param maxDistance Length; the maximum distance we can cover at the current time, e.g. as the result of a lane drop
128 * @param speedLimit Speed; the local speed limit
129 * @return DualAccelerationStep; the result with the lowest accelerations (or most severe decelerations) of application of
130 * the GTU following model of the referenceGTU for each leader and follower
131 * @throws GTUException when the speed of the gtu cannot be determined
132 */
133 DualAccelerationStep computeDualAccelerationStep(final LaneBasedGTU gtu,
134 final Collection<Headway> otherHeadways, final Length maxDistance, final Speed speedLimit) throws GTUException;
135
136 /**
137 * Compute the lowest accelerations (or most severe decelerations) that would be used if a referenceGTU is present
138 * (inserted, or not removed) in a set of other GTUs.<br>
139 * If any GTU in the set of otherGTUs has a null headway (indicating that the other GTU is in fact parallel to the
140 * referenceGTU), prohibitive decelerations shall be returned.<br>
141 * Two AccelerationStep values are returned in a DualAccelerationStep.<br>
142 * or should slow down for a crossing from accelerating to unsafe speeds.
143 * @param gtu LaneBasedGTU; the GTU for which the accelerations are computed
144 * @param otherHeadways Collection<HeadwayGTU>; the other GTUs. A negative headway value indicates that the other
145 * GTU is a follower. NB. If the referenceGTU is contained in this Collection, it is ignored.
146 * @param maxDistance Length; the maximum distance we can cover at the current time, e.g. as the result of a lane drop
147 * @param speedLimit Speed; the local speed limit
148 * @param stepSize given step size, which can be longer or shorter than the provided step size in the algorithms.
149 * @return DualAccelerationStep; the result with the lowest accelerations (or most severe decelerations) of application of
150 * the GTU following model of the referenceGTU for each leader and follower
151 * @throws GTUException when the speed of the gtu cannot be determined
152 */
153 DualAccelerationStep computeDualAccelerationStep(final LaneBasedGTU gtu,
154 final Collection<Headway> otherHeadways, final Length maxDistance, final Speed speedLimit,
155 final Duration stepSize) throws GTUException;
156
157 /**
158 * Compute the acceleration that would be used if the is not leader in sight.
159 * @param gtu LaneBasedGTU; the GTU for which acceleration is computed
160 * @param maxDistance Length; the maximum distance we can cover at the current time, e.g. as the result of a lane drop
161 * @param speedLimit Speed; the local speed limit
162 * @return AccelerationStep; the result of application of the GTU following model
163 * @throws GTUException when the speed of the gtu cannot be determined
164 */
165 AccelerationStep computeAccelerationStepWithNoLeader(final LaneBasedGTU gtu, final Length maxDistance,
166 final Speed speedLimit) throws GTUException;
167
168 /**
169 * Compute the acceleration that would be used if the is not leader in sight.
170 * @param gtu LaneBasedGTU; the GTU for which acceleration is computed
171 * @param maxDistance Length; the maximum distance we can cover at the current time, e.g. as the result of a lane drop
172 * @param speedLimit Speed; the local speed limit
173 * @param stepSize given step size, which can be longer or shorter than the provided step size in the algorithms.
174 * @return AccelerationStep; the result of application of the GTU following model
175 * @throws GTUException when the speed of the gtu cannot be determined
176 */
177 AccelerationStep computeAccelerationStepWithNoLeader(final LaneBasedGTU gtu, final Length maxDistance,
178 final Speed speedLimit, final Duration stepSize) throws GTUException;
179
180 /**
181 * Compute the minimum <b>net</b> headway given the speed of the follower and the leader.<br>
182 * At the returned headway, the follower would decelerate with it's maximum comfortable deceleration.
183 * @param followerSpeed Speed; speed of the follower
184 * @param leaderSpeed Speed; speed of the leader
185 * @param precision Length; the required precision of the result (must be > 0)
186 * @param maxDistance Length; the maximum distance we can cover at the current time, e.g. as the result of a lane drop
187 * @param speedLimit Speed; the local speed limit
188 * @param followerMaximumSpeed Speed; the maximum speed that the follower can drive at
189 * @return Length
190 */
191 Length minimumHeadway(Speed followerSpeed, Speed leaderSpeed, Length precision,
192 final Length maxDistance, Speed speedLimit, Speed followerMaximumSpeed);
193
194 /**
195 * Return the maximum safe deceleration for use in gap acceptance models. This is the deceleration that may be enforced upon
196 * a new follower due to entering a road or changing into an adjacent lane. The result shall be a <b>positive value</b>. In
197 * most car following models this value is named <cite>b</cite>.
198 * @return Acceleration; must be a positive value!
199 */
200 Acceleration getMaximumSafeDeceleration();
201
202 /**
203 * Return the standard step size of this GTU following model.
204 * @return Duration; the standard step size of the GTU following model
205 */
206 Duration getStepSize();
207
208 /**
209 * Return the name of this GTU following model.
210 * @return String; just the name of the GTU following model
211 */
212 String getName();
213
214 /**
215 * Return complete textual information about this instantiation of this GTU following model.
216 * @return String; the name and parameter values of the GTU following model
217 */
218 String getLongName();
219
220 }