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