1 package org.opentrafficsim.road.gtu.following;
2
3 import java.util.Collection;
4
5 import org.opentrafficsim.core.OTS_SCALAR;
6 import org.opentrafficsim.core.network.NetworkException;
7 import org.opentrafficsim.road.gtu.lane.LaneBasedGTU;
8
9 /**
10 * GTU following model interface. <br>
11 * GTU following models following this interface compute an acceleration.
12 * <p>
13 * Copyright (c) 2013-2015 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
14 * BSD-style license. See <a href="http://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
15 * <p>
16 * @version $Revision: 1401 $, $LastChangedDate: 2015-09-14 01:33:02 +0200 (Mon, 14 Sep 2015) $, by $Author: averbraeck $,
17 * initial version Jul 2, 2014 <br>
18 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
19 */
20 public interface GTUFollowingModel extends OTS_SCALAR
21 {
22 /**
23 * Compute the acceleration that would be used to follow a leader.<br>
24 * TODO We should probably add a <i>be ready to stop before</i> argument to prevent vehicles that cannot see their leader,
25 * or should slow down for a crossing from accelerating to unsafe speeds.
26 * @param follower LaneBasedGTU; the GTU for which acceleration is computed
27 * @param leaderSpeed DoubleScalar.Abs<SpeedUnit>; the speed of the leader
28 * @param headway DoubleScalar.Rel<LengthUnit>; the headway of the leader
29 * @param speedLimit DoubleScalarAbs<SpeedUnit>; the local speed limit
30 * @return AccelerationStep; the result of application of the GTU following model
31 * @throws NetworkException on network inconsistency
32 */
33 AccelerationStep computeAcceleration(final LaneBasedGTU follower, final Speed.Abs leaderSpeed,
34 final Length.Rel headway, final Speed.Abs speedLimit) throws NetworkException;
35
36 /**
37 * Compute the acceleration that would be used to follow a leader.<br>
38 * TODO We should probably add a <i>be ready to stop before</i> argument to prevent vehicles that cannot see their leader,
39 * or should slow down for a crossing from accelerating to unsafe speeds.
40 * @param followerSpeed DoubleScalar.Abs<SpeedUnit>; the speed of the follower at the current time
41 * @param followerMaximumSpeed DoubleScalar.Abs<SpeedUnit>; the maximum speed that the follower is capable of driving
42 * at
43 * @param leaderSpeed DoubleScalar.Abs<SpeedUnit>; the speed of the follower at the current time
44 * @param headway DoubleScalar.Rel<LengthUnit>; the <b>net</b> headway (distance between the front of the follower to
45 * the rear of the leader) at the current time
46 * @param speedLimit DoubleScalar.Abs<SpeedUnit>; the local speed limit
47 * @return DoubleScalar.Abs<AccelerationUnit>; the acceleration (or, if negative, deceleration) resulting from
48 * application of the GTU following model
49 */
50 Acceleration.Abs computeAcceleration(final Speed.Abs followerSpeed, Speed.Abs followerMaximumSpeed,
51 final Speed.Abs leaderSpeed, final Length.Rel headway, final Speed.Abs speedLimit);
52
53 /**
54 * Compute the lowest accelerations (or most severe decelerations) that would be used if a referenceGTU is present
55 * (inserted, or not removed) in a set of other GTUs.<br>
56 * If any GTU in the set of otherGTUs has a null headway (indicating that the other GTU is in fact parallel to the
57 * referenceGTU), prohibitive decelerations shall be returned.<br>
58 * Two AccelerationStep values are returned in a DualAccelerationStep.<br>
59 * TODO We should probably add a <i>be ready to stop before</i> argument to prevent vehicles that cannot see their leader,
60 * or should slow down for a crossing from accelerating to unsafe speeds.
61 * @param referenceGTU LaneBasedGTU; the GTU for which the accelerations are computed
62 * @param otherGTUs Collection<HeadwayGTU>; the other GTUs. A negative headway value indicates that the other GTU is a
63 * follower. NB. If the referenceGTU is contained in this Collection, it is ignored.
64 * @param speedLimit DoubleScalar.Abs<SpeedUnit>; the local speed limit
65 * @return DualAccelerationStep; the result with the lowest accelerations (or most severe decelerations) of application of
66 * the GTU following model of the referenceGTU for each leader and follower
67 * @throws NetworkException on network inconsistency
68 */
69 DualAccelerationStep computeAcceleration(final LaneBasedGTU referenceGTU, final Collection<HeadwayGTU> otherGTUs,
70 final Speed.Abs speedLimit) throws NetworkException;
71
72 /**
73 * Compute the acceleration that would be used if the is not leader in sight.
74 * @param gtu LaneBasedGTU; the GTU for which acceleration is computed
75 * @param speedLimit DoubleScalar.Abs<SpeedUnit>; the local speed limit
76 * @return AccelerationStep; the result of application of the GTU following model
77 * @throws NetworkException on network inconsistency
78 */
79 AccelerationStep computeAccelerationWithNoLeader(final LaneBasedGTU gtu, final Speed.Abs speedLimit)
80 throws NetworkException;
81
82 /**
83 * Compute the minimum <b>net</b> headway given the speed of the follower and the leader.<br>
84 * At the returned headway, the follower would decelerate with it's maximum comfortable deceleration.
85 * @param followerSpeed DoubleScalar.Abs<SpeedUnit>; speed of the follower
86 * @param leaderSpeed DoubleScalar.Abs<SpeedUnit>; speed of the leader
87 * @param precision DoubleScalar.Rel<LengthUnit>; the required precision of the result (must be > 0)
88 * @param speedLimit DoubleScalar.Abs<SpeedUnit>; the local speed limit
89 * @param followerMaximumSpeed DoubleScalar.Abs<SpeedUnit>; the maximum speed that the follower can drive at
90 * @return DoubleScalar.Rel<LengthUnit>
91 */
92 Length.Rel minimumHeadway(Speed.Abs followerSpeed, Speed.Abs leaderSpeed, Length.Rel precision,
93 Speed.Abs speedLimit, Speed.Abs followerMaximumSpeed);
94
95 /**
96 * Return the maximum safe deceleration for use in gap acceptance models. This is the deceleration that may be enforced upon
97 * a new follower due to entering a road or changing into an adjacent lane. The result shall be a <b>positive value</b>. In
98 * most car following models this value is named <cite>b</cite>.
99 * @return DoubleScalar.Abs<AccelerationUnit>; must be a positive value!
100 */
101 Acceleration.Abs maximumSafeDeceleration();
102
103 /**
104 * Return the step size of this GTU following model.
105 * @return DoubleScalar.Rel<TimeUnit>; the step size of the GTU following model
106 */
107 Time.Rel getStepSize();
108
109 /**
110 * Return the name of this GTU following model.
111 * @return String; just the name of the GTU following model
112 */
113 String getName();
114
115 /**
116 * Return complete textual information about this instantiation of this GTU following model.
117 * @return String; the name and parameter values of the GTU following model
118 */
119 String getLongName();
120
121 }