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