Package org.opentrafficsim.road.gtu.lane.tactical.lmrs

Class LmrsFactory<T extends AbstractIncentivesTacticalPlanner>

java.lang.Object
org.opentrafficsim.core.parameters.ParameterFactoryByType
org.opentrafficsim.core.parameters.ParameterFactoryOneShot
org.opentrafficsim.road.gtu.lane.tactical.lmrs.LmrsFactory<T>
Type Parameters:
T - tactical planner type
All Implemented Interfaces:
ParameterFactory, LaneBasedTacticalPlannerFactory<T>, ModelComponentFactory
public class LmrsFactory<T extends AbstractIncentivesTacticalPlanner> extends ParameterFactoryOneShot implements LaneBasedTacticalPlannerFactory<T>
This tactical planner is general purpose for the use of the LMRS with any combination of defined sub-components. The class seconds as a parameter factory. For both model components and parameter values, the factory can be used specific to the GTU type. Model components can be set through command line arguments, or through calling set(Setting, Object). Parameters can be set through standard parameter factory methods.

Usage
The factory can be used as: 

 LmrsFactory<Lmrs> factory = new LmrsFactory<>(List.of(DefaultsNl.CAR, DefaultsNl.VAN), Lmrs::new);

 factory.set(Setting.ADAPTATION_SPEED, false);
The GTU list is optional (default is List.of(DefaultsNl.CAR, DefaultsNl.TRUCK)), and the second LmrsFactory.TacticalPlannerProvider argument can also be given as a list to specifiy different providers per GTU type. All settings must be provided either for all GTU types, or for a specific GTU type with which the factory was initialized. GTUs of other types can be generated within the simulation, so long as any of their parent types is within the list of the factory.

Command line arguments
This class can be mixed in with any program using command line arguments: 

 @Mixin
 private LmrsFactory<Lmrs> factory = new LmrsFactory<>(Lmrs::new);

 public static void main(String[] args)
 {
     Program program = new Program();
     CliUtil.changeOptionDefault(program, "gtuTypes", "NL.CAR|NL.VAN|NL.TRUCK");
     CliUtil.execute(program, args);
 }
Note: command line arguments and programmatically setting settings (set method) should in principle not both be used within the same program. Default command line arguments should be changed by the option default as in the example above, before the input args are executed.

Use command line argument --help to get a list of all available command line arguments. In the example the factory is initialized using the constructor of Lmrs as a supplier of the tactical planner class. Within the context of a program it may be necessary to use a supplier of an another implementation of a tactical planner instead. The supplier can be any function that follows the LmrsFactory.TacticalPlannerProvider signature, supplying an extension of AbstractIncentivesTacticalPlanner.

Command line arguments can be defined to contain values for specific GTU types. The following arguments allow a simulation with GTU types NL.CAR and NL.TRUCK, or any of their sub types. All GTUs will not generally keep to the slow lane (incentiveKeep), while trucks will limit themselves on the rightmost two lanes (incentiveStayRight). GTU types and the values that apply to them should be given in the same order. The number of values given should either be 1, or equal to the number of GTU types given. 

 --gtuTypes=NL.CAR|NL.TRUCK --incentiveKeep=false --incentiveStayRight=false|true
The pipe character (|) is used to separate values. If the pipe character is part of any value, values can be quoted. If a quote is part of a any value, the value can be quoted and the quote of the value can be escaped with a backslash \. The following code will set the --gtuTypes to [NL.CAR, NL.VAN, NL.T|RUCK]. 
 CliUtil.execute(new CommandLine(myProgram).setTrimQuotes(true), new String[] {"--gtuTypes=NL.CAR|NL.VAN|\"NL.T|RUCK\""});
One-shot mode

This class extends ParameterFactoryOneShot and can thus be used as a parameter factory. It supports one-shot mode. Any parameter set after setOneShotMode() is called and before the next GTU is generated is only applied to said GTU. At any other moment parameters that are set are fixed. This class implements setOneShotMode() to apply the same mode on model settings, applying only to the next GTU generated, after which settings are reverted to the state when setOneShotMode() was called.

Settings applicability
Many settings on perception components may only apply to some implementations of Fuller, see Table 1.

Table 1: Perception components for Fuller implementations
Setting Fuller implementation (FULLER_IMPLEMENTATION)
NONE SUMMATIVE ANTICIPATION_RELIANCE ATTENTION_MATRIX
PRIMARY_TASK - - ✓ -
TEMPORAL_ANTICIPATION - ✓ ✓ ✓
FRACTION_OVERESTIMATION - ✓ ✓ ✓
Tasks for mental model
TASK_CAR_FOLLOWING - ✓ ✓ ✓
TASK_FREE_ACCELERATION - - - ✓
TASK_TRAFFIC_LIGHTS - - - ✓
TASK_SIGNAL - - - ✓
TASK_LANE_CHANGE - ✓ ✓ ✓
TASK_COOPERATION - - - ✓
TASK_CONFLICTS - - - ✓
TASK_ROADSIDE_DISTRACTION - ✓ ✓ ✓
Behavioral adaptations for mental model
ADAPTATION_SPEED - ✓ ✓ ✓
ADAPTATION_HEADWAY - ✓ ✓ ✓
ADAPTATION_LANE_CHANGE - ✓ ✓ ✓
ADAPTATION_UPDATE_TIME - - - ✓

Copyright (c) 2026-2026 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See OpenTrafficSim License.

Author:
Wouter Schakel

  • Constructor Details

    • LmrsFactory

      public LmrsFactory(LmrsFactory.TacticalPlannerProvider<T> lmrsProvider)
      Constructor that will use default NL.CAR and NL.TRUCK GTU types.
      Parameters:
      lmrsProvider - provider for LMRS implementation, e.g. Lmrs::new
      Throws:
      NullPointerException - when lmrsProvider is null

    • LmrsFactory

      public LmrsFactory(List<GtuType> gtuTypes, LmrsFactory.TacticalPlannerProvider<T> lmrsProvider)
      Constructor with given GTU types and default LMRS implementation class.
      Parameters:
      gtuTypes - GTU types
      lmrsProvider - provider for LMRS implementation, e.g. Lmrs::new
      Throws:
      NullPointerException - when gtuTypes or lmrsProvider is null

    • LmrsFactory

      public LmrsFactory(List<GtuType> gtuTypes, List<LmrsFactory.TacticalPlannerProvider<T>> lmrsProviders)
      Constructor with given GTU types and LMRS implementation class per GTU type.
      Parameters:
      gtuTypes - GTU types
      lmrsProviders - providers for LMRS implementation for each GTU type, e.g. Lmrs::new, may contain null values (except first element)
      Throws:
      NullPointerException - when gtuTypes or lmrsProviders is null
      IllegalArgumentException - when gtuTypes and lmrsProviders are not of equal size

  • Method Details

    • setOneShotMode

      public void setOneShotMode()
      Sets the factory to one-shot mode. All LmrsFactory.Settings, parameters and correlations set or added between a call to this method and to create() are removed from the factory after the call to create().
      Overrides:
      setOneShotMode in class ParameterFactoryOneShot

    • resetState

      protected <V> void resetState()
      Resets the factory to the state when setOneShotMode() was called. Note that the parameter factory resets its own state when it has set parameter values.
      Type Parameters:
      V - setting value type

    • setStream

      public LmrsFactory<T> setStream(nl.tudelft.simulation.jstats.streams.StreamInterface stream)
      Sets the random number stream.
      Parameters:
      stream - random number stream
      Returns:
      this factory for method chaining

    • set

      public <V> LmrsFactory<T> set(LmrsFactory.Setting<V> setting, V value)
      Sets the setting value for all GTU types.
      Type Parameters:
      V - value type
      Parameters:
      setting - setting
      value - value used for all GTU types
      Returns:
      this factory for method chaining

    • set

      public <V> LmrsFactory<T> set(LmrsFactory.Setting<V> setting, V value, GtuType gtuType)
      Sets the setting value for given GTU type.
      Type Parameters:
      V - value type
      Parameters:
      setting - setting
      value - value
      gtuType - GTU type
      Returns:
      this factory for method chaining
      Throws:
      IllegalArgumentException - when the GTU type is not known

    • saveState

      protected <V> void saveState(LmrsFactory.Setting<V> setting, List<V> values)
      Saves the state of given setting when in one-shot mode and the setting was not already saved.
      Type Parameters:
      V - value type
      Parameters:
      setting - setting
      values - value list

    • get

      protected <V> V get(LmrsFactory.Setting<V> setting, GtuType gtuType)
      Returns value of setting for the GTU type.
      Type Parameters:
      V - value type
      Parameters:
      setting - setting
      gtuType - GTU type
      Returns:
      value from value array for the GTU type

    • get

      protected <V> V get(List<V> values, GtuType gtuType)
      Returns value from value array for the GTU type.
      Type Parameters:
      V - value type
      Parameters:
      values - values
      gtuType - GTU type
      Returns:
      value from value array for the GTU type

    • getParameters

      public Parameters getParameters(GtuType gtuType) throws ParameterException
      Description copied from interface: ModelComponentFactory
      Returns parameters for the given component. These parameters should contain, and possibly overwrite, parameters from sub-components. A parameter factory at the highest level (strategical planner) may overwrite any parameter. This combination allows that for sub-components, default factories can be used, while the parameter factory only overwrites parameters different for specific GTU types. The default implementation returns all default parameter values declared at the class.

      Conventional use is:
       Parameters parameters = this.subComponent1Factory.getParameters();
 this.subComponent2Factory.getParameters().setAllIn(parameters);
 parameters.setDefaultParameters(componentClass);
 parameters.setDefaultParameters(staticUtilityClass);
 return parameters;
      where all parameters used in componentClass are defined or forwarded in componentClass.
       // forwarded
 public static final ParameterTypeAcceleration A = ParameterTypes.A;

 // defined
 public static final ParameterTypeDouble FACTOR = new ParameterTypeDouble("factor", "factor on response", 1.0);
      The same holds for static utilities that are used. Parameters should be defined at the utility class, and parameters of used utilities should be included.

      Because high-level model components might determine what low-level components to use depending on GTU type, and hence which parameters might be required, the GTU type is given as input. Many components will however not need it to return the required parameters.

      Specified by:
      getParameters in interface ModelComponentFactory
      Parameters:
      gtuType - GTU type
      Returns:
      parameters for the given component
      Throws:
      ParameterException - on parameter exception

    • create

      public T create(LaneBasedGtu gtu) throws GtuException
      Description copied from interface: LaneBasedTacticalPlannerFactory
      Creates a new tactical planner for the given GTU.
      Specified by:
      create in interface LaneBasedTacticalPlannerFactory<T extends AbstractIncentivesTacticalPlanner>
      Parameters:
      gtu - GTU
      Returns:
      tactical planner for the given GTU
      Throws:
      GtuException - if the gtu is not suitable in any way for the creation of the tactical planner

    • getPerception

      protected LanePerception getPerception(LaneBasedGtu gtu)
      Returns perception for the GTU.
      Parameters:
      gtu - GTU
      Returns:
      perception for the GTU