1 package org.opentrafficsim.road.gtu.tactical.lmrs;
2
3 import org.djunits.value.vdouble.scalar.Acceleration;
4 import org.djunits.value.vdouble.scalar.Length;
5 import org.djutils.exceptions.Throw;
6 import org.opentrafficsim.base.parameters.ParameterException;
7 import org.opentrafficsim.core.gtu.GtuException;
8 import org.opentrafficsim.core.network.Link;
9 import org.opentrafficsim.core.network.route.Route;
10 import org.opentrafficsim.road.gtu.perception.FilteredIterable;
11 import org.opentrafficsim.road.gtu.perception.RelativeLane;
12 import org.opentrafficsim.road.gtu.perception.object.PerceivedLaneBasedObject;
13 import org.opentrafficsim.road.gtu.tactical.TacticalContextEgo;
14
15 /**
16 * Interface for acceleration incentives.
17 * <p>
18 * Copyright (c) 2013-2026 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
19 * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
20 * </p>
21 * @author Alexander Verbraeck
22 * @author Peter Knoppers
23 * @author Wouter Schakel
24 */
25 @FunctionalInterface
26 public interface AccelerationIncentive
27 {
28
29 /** Field to return when there is no reason to accelerate/decelerate. */
30 Acceleration NO_REASON = Acceleration.POS_MAXVALUE;
31
32 /**
33 * Determine acceleration.
34 * @param context tactical information such as parameters and car-following model
35 * @param lane lane on which to consider the acceleration
36 * @param mergeDistance distance over which a lane change is impossible
37 * @return acceleration
38 * @throws ParameterException on missing parameter
39 * @throws GtuException when there is a problem with the state of the GTU when planning a path
40 */
41 Acceleration accelerate(TacticalContextEgo context, RelativeLane lane, Length mergeDistance)
42 throws ParameterException, GtuException;
43
44 /**
45 * Returns an iterable with only those lane-based objects that are on the same road, i.e. only downstream of a possible
46 * merge.
47 * @param <T> type of lane-based object
48 * @param iterable iterable
49 * @param lane lane of objects
50 * @param mergeDistance distance within which the lane and current lane merge
51 * @return iterable with only those lane-based objects that are on the route
52 * @throws NullPointerException when any input is {@code null}
53 */
54 static <T extends PerceivedLaneBasedObject> Iterable<T> onRoad(final Iterable<T> iterable, final RelativeLane lane,
55 final Length mergeDistance)
56 {
57 Throw.whenNull(lane, "lane");
58 Throw.whenNull(mergeDistance, "mergeDistance");
59 if (!lane.isCurrent() && mergeDistance.gt0())
60 {
61 return new FilteredIterable<>(iterable, (trafficLight) ->
62 {
63 return trafficLight.getDistance().gt(mergeDistance);
64 });
65 }
66 return iterable;
67 }
68
69 /**
70 * Returns an iterable with only those lane-based objects that are on the route, accounting for longitudinal direction of
71 * the GTU type.
72 * @param <T> type of lane-based object
73 * @param iterable iterable
74 * @param route route, may be {@code null}
75 * @return iterable with only those lane-based objects that are on the route
76 * @throws NullPointerException when any input is {@code null}
77 */
78 static <T extends PerceivedLaneBasedObject> Iterable<T> onRoute(final Iterable<T> iterable, final Route route)
79 {
80 return new FilteredIterable<>(iterable, (t) ->
81 {
82 if (route == null)
83 {
84 return true; // when there is no route, we are always on it...
85 }
86 Link link = t.getLane().getLink();
87 if (route.contains(link.getStartNode()) && route.contains(link.getEndNode()))
88 {
89 return route.indexOf(link.getEndNode()) - route.indexOf(link.getStartNode()) == 1;
90 }
91 return false;
92 });
93 }
94
95 }