1 package org.opentrafficsim.road.gtu.lane.tactical.lanechangemobil;
2
3 import java.util.Collection;
4
5 import org.djunits.value.vdouble.scalar.Acceleration;
6 import org.djunits.value.vdouble.scalar.Speed;
7 import org.opentrafficsim.base.parameters.ParameterException;
8 import org.opentrafficsim.core.gtu.GtuException;
9 import org.opentrafficsim.road.gtu.lane.LaneBasedGtu;
10 import org.opentrafficsim.road.gtu.lane.perception.headway.Headway;
11
12 /**
13 * All lane change models must implement this interface. <br>
14 * TODO: Lane change models should use the perceived nearby GTUs rather than a provided list of same lane traffic, etc.
15 * <p>
16 * Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
17 * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
18 * </p>
19 * @author <a href="https://github.com/averbraeck">Alexander Verbraeck</a>
20 * @author <a href="https://github.com/peter-knoppers">Peter Knoppers</a>
21 */
22 public interface LaneChangeModel
23 {
24 /**
25 * Compute the acceleration and lane change.
26 * @param gtu the GTU for which the acceleration and lane change is computed
27 * @param sameLaneTraffic the set of observable GTUs in the current lane (can not be null and may include the
28 * <code>gtu</code>)
29 * @param rightLaneTraffic the set of observable GTUs in the adjacent lane where GTUs should drive in the absence of other
30 * traffic (must be null if there is no such lane)
31 * @param leftLaneTraffic the set of observable GTUs in the adjacent lane into which GTUs should merge to overtake other
32 * traffic (must be null if there is no such lane)
33 * @param speedLimit the local speed limit
34 * @param preferredLaneRouteIncentive route incentive to merge to the adjacent lane where GTUs should drive in the absence
35 * of other traffic
36 * @param laneChangeThreshold threshold that prevents lane changes that have very little benefit
37 * @param nonPreferredLaneRouteIncentive route incentive to merge to the adjacent lane into which GTUs should merge to
38 * overtake other traffic
39 * @return the result of the lane change and GTU following model
40 * @throws GtuException when the speed of the GTU can not be determined
41 * @throws ParameterException in case of a parameter problem.
42 */
43 @SuppressWarnings("checkstyle:parameternumber")
44 LaneMovementStep computeLaneChangeAndAcceleration(LaneBasedGtu gtu, Collection<Headway> sameLaneTraffic,
45 Collection<Headway> rightLaneTraffic, Collection<Headway> leftLaneTraffic, Speed speedLimit,
46 Acceleration preferredLaneRouteIncentive, Acceleration laneChangeThreshold,
47 Acceleration nonPreferredLaneRouteIncentive) throws GtuException, ParameterException;
48
49 /**
50 * Return the name of this GTU following model.
51 * @return just the name of the GTU following model
52 */
53 String getName();
54
55 /**
56 * Return complete textual information about this instantiation of this GTU following model.
57 * @return the name and parameter values of the GTU following model
58 */
59 String getLongName();
60
61 }