1 package org.opentrafficsim.road.gtu.lane.perception.mental;
2
3 import static org.opentrafficsim.base.parameters.constraint.NumericConstraint.POSITIVE;
4 import static org.opentrafficsim.base.parameters.constraint.NumericConstraint.POSITIVEZERO;
5
6 import java.util.Set;
7
8 import org.djutils.exceptions.Throw;
9 import org.djutils.exceptions.Try;
10 import org.djutils.immutablecollections.ImmutableSet;
11 import org.opentrafficsim.base.parameters.ParameterException;
12 import org.opentrafficsim.base.parameters.ParameterTypeDouble;
13 import org.opentrafficsim.base.parameters.Parameters;
14 import org.opentrafficsim.road.gtu.lane.LaneBasedGtu;
15 import org.opentrafficsim.road.gtu.lane.perception.LanePerception;
16
17 /**
18 * Task-capability interface in accordance to Fuller (2011). Task demand is the sum of demands described by individual
19 * {@code Task}s. These take exogenous information to describe the workload in fundamental relations. Task demand is divided by
20 * task capability to arrive at a task saturation. Task saturation is input to {@code BehavioralAdaptation}s which alter
21 * parameters describing personal traits, such as desired headway and desired speed. In this way, task demand is kept at an
22 * equilibrium as described by Fuller.
23 * <p>
24 * A {@code BehavioralAdaptation} may also determine what the level of situational awareness is, which includes determining
25 * reaction time. Both situational awareness and reaction time parameters can be used in perception to model deteriorated
26 * perception due to a task demand imbalance.
27 * <p>
28 * Fuller, R., Driver control theory: From task difficulty homeostasis to risk allostasis, in Handbook of Traffic Psychology.
29 * 2011. p. 13-26
30 * <p>
31 * Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
32 * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
33 * </p>
34 * @author <a href="https://github.com/averbraeck">Alexander Verbraeck</a>
35 * @author <a href="https://github.com/peter-knoppers">Peter Knoppers</a>
36 * @author <a href="https://github.com/wjschakel">Wouter Schakel</a>
37 */
38 public abstract class Fuller implements Mental
39 {
40
41 /** Task capability in nominal task capability units, i.e. mean is 1. */
42 public static final ParameterTypeDouble TC = new ParameterTypeDouble("TC", "Task capability", 1.0, POSITIVE);
43
44 /** Task saturation. */
45 public static final ParameterTypeDouble TS = new ParameterTypeDouble("TS", "Task saturation", 0.0, POSITIVEZERO);
46
47 /** Over-estimation parameter type. Negative values reflect under-estimation. */
48 public static final ParameterTypeDouble OVER_EST = new ParameterTypeDouble("OVER_EST", "Over estimation factor.", 1.0);
49
50 /** Behavioral adaptations depending on task saturation. */
51 private final Set<BehavioralAdaptation> behavioralAdapatations;
52
53 /**
54 * Constructor with custom situational awareness.
55 * @param behavioralAdapatations behavioralAdapatations
56 */
57 public Fuller(final Set<BehavioralAdaptation> behavioralAdapatations)
58 {
59 Throw.whenNull(behavioralAdapatations, "Behavioral adaptations may not be null.");
60 this.behavioralAdapatations = behavioralAdapatations;
61 }
62
63 @Override
64 public void apply(final LanePerception perception) throws ParameterException
65 {
66 LaneBasedGtu gtu = Try.assign(() -> perception.getGtu(), "Could not obtain GTU.");
67 Parameters parameters = gtu.getParameters();
68 // a) the fundamental diagrams of task workload are defined in the tasks
69 // b) sum task demand (possibly with anticipation reliance in sub-class)
70 parameters.setClaimedParameter(TS, getTotalTaskDemand(perception) / parameters.getParameter(TC), this);
71 // c) behavioral adaptation
72 for (BehavioralAdaptation behavioralAdapatation : this.behavioralAdapatations)
73 {
74 behavioralAdapatation.adapt(parameters);
75 }
76 // d) situational awareness can be implemented by one of the behavioral adaptations
77 // e) perception errors from situational awareness or otherwise by sub-class and included in the perception step
78 // f) reaction time from situational awareness or otherwise by sub-class and included in the perception step
79 }
80
81 /**
82 * Returns the total level of task demand, possibly after anticipation reliance.
83 * @param perception perception
84 * @return level of task demand
85 * @throws ParameterException if a parameter is missing or out of bounds
86 */
87 protected abstract double getTotalTaskDemand(LanePerception perception) throws ParameterException;
88
89 /**
90 * Returns the currently active tasks.
91 * @return tasks
92 */
93 public abstract ImmutableSet<? extends Task> getTasks();
94
95 }