Skip to content

108. Smart Replay scenario modifiers

You can use the following modifier files to modify actor behavior to create variations for a Smart Replay scenario:

  • sr_change_vehicle_lateral
  • sr_change_vehicle_speed
  • sr_erratic_driver
  • sr_erratic_driver_index
  • sr_random_erratic_driver

108.1 Prerequisites for using Smart Replay modifiers

These modifiers can only be used with Smart Replay scenarios and will not work with any other scenarios.

108.2 Working with Modifiers

Follow these steps to use the Smart Replay modifiers:

  1. Create a new OSC file to apply the required changes to your selected Smart Replay scenario. For example, if you have created a my_sr_scenario Smart Replay scenario, create a file called my_sr_scenario_lateral.osc or something similar, indicating the change your test will make.
  2. In the new test OSC file, import the Smart Replay Scenario you want to modify.
  3. Import the modifier file from the common modifiers library at $FTX/smart_replay/common/modifiers.
  4. Extend sut.sr_scenario and add one or more instances of the modifier with parameters for one or more vehicles.
  5. Extend top.main to invoke the Smart Replay Scenario. Note that you can omit this last step if, in step 2, you import either the exact or the behavioral test files instead of the scenario. It doesn't matter which one you choose, as importing the modifier in step 3 will make the test behavioral regardless.

108.3 Modifying the lateral position of vehicles

To use the common Smart Replay lateral change modifier, use the following steps:

  1. In a new OSC file, import the Smart Replay Scenario you want to modify.
  2. Import the sr_change_vehicle_lateral.osc modifier file from the common modifiers library.
  3. Extend sut.sr_scenario and add one or more instances of the modifier with parameters for one or more vehicles.
  4. Extend top.main to invoke the Smart Replay Scenario.

108.3.1 Example of sr_change_vehicle_lateral

OSC2 code: sr_change_vehicle_lateral
import "$FTX/qa/regression/user_docs_examples/osc/sr_scenario/double_cut_in.osc"          
import "$FTX/smart_replay/common/modifiers/sr_change_vehicle_lateral.osc"                 


extend top.main:                                                                          
    do sut.sr_scenario()


extend sut.sr_scenario:                                                                   
    lateral_change_1: change_vehicle_lateral(vehicle_idx: 0,
                                             lateral_change: 6m,
                                             on_duration: 3.0s,
                                             on_time: 0.0s)

    lateral_change_2: change_vehicle_lateral(vehicle_idx: 1,
                                             lateral_change: -6m,
                                             on_duration: 3.0s,
                                             on_time: 0.0s)

108.3.1.1 Parameters of sr_change_vehicle_lateral

Use the following parameters to define the lateral position of vehicles.

Parameter Description
vehicle_idx The index of the driver in the list of vehicles, based on its position in the sut.sr_scenario.npc_vehicles list of the Smart Replay scenario you want to modify.
lateral_change The change in length, in meters, to apply to the vehicle in the selected mode (additive or absolute). Lateral movement to the left must be a positive value. Lateral movement to the right must be a negative value.
on_duration The duration, in seconds, of the lateral change.
on_time The time, in seconds, when the lateral change should start.
mode The mode of the lateral shift change, which can be either additive (default) which changes the lateral position based on the current value, or absolute which changes the lateral position relative to the initial lateral position.
off_time The time, in seconds, to stop the lateral change. The default is 0s. If provided, the lateral change will be cancelled at this time, and return to the original position of the trajectory.
off_duration The duration, in seconds, for how long it takes to return to the original lateral position of the trajectory. The default is 0 seconds and the return is determined by the on_duration time.
log_modifications Specifies whether to log modifications to the vehicle. The default is false. If set to true, the modifications will be logged.

108.3.2 Examples of modifying lateral positions of vehicles

The following examples demonstrate how to use the sr_change_vehicle_lateral modifier to define the lateral position of vehicles in a Smart Replay scenario.

Example 1

Move the vehicle at index 2 of the vehicles list in the modified Smart Replay scenario 2m to the right relative to the original trajectory (absolute mode), starting at t=5s. The transition should occur within a duration of 2.5s and remain until the end of the scenario. Log this change when it occurs. This move is relative to the original trajectory, and there is absolute mode.

    change_lateral: change_vehicle_lateral(vehicle_idx: 2,
                                           lateral_change: -2m,
                                           on_time: 5s,
                                           on_duration: 2.5s,
                                           log_modifications: true
                                           mode: absolute)

Example 2

Move the vehicle at index 1 of the vehicles list in the modified Smart Replay scenario 1m to the left relative to the original trajectory (absolute mode), starting at t=2s. The transition should occur within a duration of 3s. At t=10, start returning to the original trajectory. The transition back should occur within a duration of 2s.

    change_lateral: change_vehicle_lateral(vehicle_idx: 1,
                                           lateral_change: 1m,
                                           on_time: 2s,
                                           on_duration: 3s,
                                           off_time: 10s,
                                           off_duration: 2s
                                           mode: absolute)

Example 3

Move the vehicle at index 1 of the vehicles list in the modified Smart Replay scenario to a lateral position of 1m to the left of its initial position (additive mode) at t=4s. The transition should occur within a duration of 1.5s. At t=8, start returning to the original trajectory. The transition back should occur within a duration of 1.5s.

    change_lateral: change_vehicle_lateral(vehicle_idx: 1,
                                           lateral_change: 1m,
                                           on_time: 4s,
                                           on_duration: 1.5s,
                                           off_time: 8s)

108.4 Modifying the speed of vehicles

To use the common Smart Replay speed change modifier, use the following steps:

  1. In a new OSC file, import the Smart Replay Scenario you want to modify.
  2. Import the sr_change_vehicle_speed.osc modifier file from the common modifiers library.
  3. Extend sut.sr_scenario and add one or more instances of the modifier with parameters for one or more vehicles.
  4. Extend top.main to invoke the Smart Replay Scenario.

108.4.1 Example of sr_change_vehicle_speed

OSC2 code: sr_change_vehicle_speed
import "$FTX/qa/regression/user_docs_examples/osc/sr_scenario/double_cut_in.osc"    
import "$FTX/smart_replay/common/modifiers/sr_change_vehicle_speed.osc"             

extend sut.sr_scenario:                                                             
    change_speed_1: change_vehicle_speed(vehicle_idx: 0,
                                         speed_change: 10mph,
                                         on_duration: 2.0s,
                                         on_time: 0.0s)
    change_speed_2: change_vehicle_speed(vehicle_idx: 1,
                                         speed_change: -10mph,
                                         on_duration: 2.0s,
                                         on_time: 0.0s)

extend top.main:                                                                   
    do sut.sr_scenario()

108.4.1.1 Parameters of sr_change_vehicle_speed

Use the following parameters to define the speed of vehicles.

Parameter Description
vehicle_idx The index of the driver in the list of vehicles, based on it's position in the sut.sr_scenario.npc_vehicles list of the Smart Replay scenario you want to modify.
speed_change The change in speed, in kilometers per hour (kph) or meters per second (mps), to apply to the vehicle in the selected mode (additive or absolute).
on_time The time, in seconds, at which the speed change should start.
on_duration The duration of the speed change, in seconds.
mode The mode of the speed change can be set to either additive (default) which adjusts the speed based on the current value, or absolute which adjusts the speed to a specific speed. If changing a vehicle's speed with mode: additive will bring it to a negative speed, or providing a negative speed with mode: absolute, the vehicle will simply stop, it will not drive in reverse. Changing a vehicle's speed with mode: absolute changes the actual absolute speed.
off_time The time, in seconds, to stop the speed change. The default is 0s. If provided, the lateral speed will be canceled at this time, and return to the original speed.
off_duration The duration, in seconds, for how long it takes to return to the original speed. The default is 0 seconds and the return is determined by the on_duration time.
log_modifications Specifies whether to log modifications to the vehicle. The default is false. If set to true, the modifications will be logged.

108.4.2 Examples of modifying speeds of vehicles

The following examples demonstrate how to use the parameters to define the speed changes of vehicles in a Smart Replay scenario.

Example 1

Increase the speed of the vehicle at index 1 of the vehicles list in the modified Smart Replay scenario to 15kph faster than the original speed (additive mode), starting at t=10s. The transition should occur within a duration of 7s and remain until the end of the scenario. Log this change when it occurs.

    change_speed: change_vehicle_speed(vehicle_idx: 1,
                                       speed_change: 15kph,
                                       on_time: 10s,
                                       on_duration: 7s,
                                       log_modifications: true)

Example 2

Decrease the speed of the vehicle at index 2 of the vehicles list in the modified Smart Replay scenario to 10kph slower than the original speed (additive mode), starting at t=2s. The transition should occur within a duration of 4s. At t=20s, start returning to the original speed. The transition back should occur within a duration of 3s. Log this change when it occurs.

    change_speed: change_vehicle_speed(vehicle_idx: 2,
                                       speed_change: -10kph,
                                       on_time: 2s,
                                       on_duration: 4s,
                                       off_time: 20s,
                                       off_duration: 3s,
                                       log_modifications: true)

Example 3

Increase the speed of the vehicle at index 2 of the vehicles list in the modified Smart Replay scenario to a speed of 120kph (absolute mode) at t=5s. The transition should occur within a duration of 8s. At t=20, start returning to the original speed. The transition back should also occur within a duration of 5s.

    change_speed: change_vehicle_speed(vehicle_idx: 2,
                                       speed_change: 120kph,
                                       on_time: 5s,
                                       on_duration: 8s,
                                       off_time: 20s,
                                       off_duration: 5s,
                                       mode: absolute)

108.5 Configuring erratic driving simulations

Erratic drivers continuously change their lateral position and speed in an unstable manner, making them unpredictable. The effects may vary considerably depending on the parameters and seed used for each run.

Note

It is recommended to import sr_erratic_driver_index.osc or sr_random_erratic_driver.osc from the common modifier library, as these files contain built-in erratic driver definitions. To set the parameters manually, use sr_erratic_driver_lateral and sr_erratic\_driver\_speed modifiers provided by the sr_erratic_driver.osc module.

To use the sr_erratic_driver.osc file, follow these steps:

  1. In a new OSC file, import the Smart Replay Scenario you want to modify.
  2. Import the sr_erratic_driver file.
  3. Extend sut.sr_scenario and add an instance of the erratic_driver_lateral and erratic_driver_speed modifiers.
  4. Extend top.main to invoke the Smart Replay Scenario.

108.5.1 sr_erratic_driver_lateral

The sr_erratic_driver_lateral modifier changes the lateral position of the erratic driver. It randomizes a time for the first lateral change and then randomizes the lateral change and the duration of the change to occur. When that duration has passed, the behavior will randomize the next lateral change continuously. This yields a continuously unstable lateral position for the erratic driver.

Use the following parameters to define the lateral position of an erratic driver.

Parameter Description
erratic_lateral_idx The index of the erratic driver in the list of vehicles in the order it appears in the sut.sr_scenario.npc_vehicles list of the Smart Replay scenario you want to modify. The default is the first vehicle in the list.
max_absolute_lat_shift_m The maximum absolute lateral shift in meters relative to the trajectory's original lateral position.
max_change_time_s The maximum time, in seconds, for the first lateral change to start between the lateral changes.
log_modifications Specifies whether to log modifications to the vehicle. The default is false. If set to true, the modifications will be logged.

108.5.2 sr_erratic_driver_speed

The sr_erratic_driver_speed modifier changes the speed of the erratic driver. It randomizes a time for the first speed change and then randomizes the speed change and the duration of the change to occur. When that duration has passed, the behavior will randomize the next speed change continuously. This yields a continuously unstable speed for the erratic driver.

Use the following parameters to define speed changes of an erratic driver.

Parameter Description
erratic_speed_idx The index of the erratic driver in the list of vehicles in the order it appears in the sut.sr_scenario.npc_vehicles list of the Smart Replay scenario you want to modify. The default is the first vehicle in the list.
max_absolute_speed_change_m The maximum absolute speed change, in kilometers per hour, relative to the trajectory's original speed.
max_change_time_s The maximum time, in seconds, for the first speed change to start, and between speed changes.
log_modifications Specifies whether to log modifications to the vehicle. The default is false. If set to true, the modifications will be logged.

108.5.3 Example of sr_erratic_driver

OSC2 code: sr_erratic_driver_lateral and sr_erratic_driver_speed
import "$FTX/qa/regression/user_docs_examples/osc/sr_scenario/double_cut_in.osc"
import "$FTX/smart_replay/common/modifiers/sr_erratic_driver.osc"

extend sut.sr_scenario:
    # Set the lateral position of the 2nd NPC in the list of NPC vehicles erratic with the default parameters.
    lateral_change: erratic_driver_lateral(erratic_lateral_idx: 1)
    # Set the speed of the 1st NPC in the list of NPC vehicles erratic with the default parameters.
    speed_change: erratic_driver_speed(erratic_speed_idx: 0)

extend top.main:
    do sut.sr_scenario()

108.6 sr_erratic_driver_index

The sr_erratic_driver_index.osc is a convenient application of the sr_erratic_driver_speed and sr_erratic_driver_lateral modifiers that you can use to change the behavior of one specific vehicle to behave like an erratic driver.

To use the sr_erratic_driver_index modifier, follow these steps:

  1. In a new OSC file, import the Smart Replay Scenario you want to modify.
  2. Import the sr_erratic_driver_index.osc file from the common modifiers library.
  3. Extend sut.sr_scenario and set the erratic driver index and logging preference.
  4. Extend top.main to invoke the Smart Replay Scenario.

You can only define the following two parameters.

Parameter Description
erratic_driver_idx The index of the erratic driver in the list of vehicles in the order that it appears in the sut.sr_scenario.npc_vehicles list of the Smart Replay scenario you want to modify. The default is the first vehicle in the list.
log_erratic_driver_modifications Specifies whether to log modifications to the vehicle. The default is false. If set to true, the modifications will be logged.

Example

OSC2 code: sr_erratic_driver_index
import "$FTX/qa/regression/user_docs_examples/osc/sr_scenario/double_cut_in.osc"
import "$FTX/smart_replay/common/modifiers/sr_erratic_driver_index.osc"

extend top.main:
    do sut.sr_scenario()

extend sut.sr_scenario:
    keep(erratic_driver_idx == 1)
    keep(log_erratic_driver_modifications == true)

108.7 sr_random_erratic_driver

The sr_random_erratic_driver.osc is a convenient application of the sr_erratic_driver_speed and sr_erratic_driver_lateral modifiers that you can use to change the behavior of a randomly-selected vehicle. The vehicle will be randomly selected from the list of vehicles in the Smart Replay scenario being modified.

To use the sr_random_erratic_driver modifier, follow these steps:

  1. In a new OSC file, import the Smart Replay Scenario you want to modify.
  2. Import the sr_random_erratic_driver.osc modifier file from the common modifiers library.
  3. Extend sut.sr_scenario and set the logging preference.
  4. Extend top.main to invoke the Smart Replay Scenario.

You can only define the logging parameter.

Parameter Description
log_erratic_driver_modifications Specifies whether to log modifications to the vehicle. The default is false. If set to true, the modifications will be logged.

Example

OSC2 code: sr_random_erratic_driver
import "$FTX/qa/regression/user_docs_examples/osc/sr_scenario/double_cut_in.osc"
import "$FTX/smart_replay/common/modifiers/sr_random_erratic_driver.osc"

extend sut.sr_scenario:
    keep(log_erratic_driver_modifications == true)

extend top.main:
    do sut.sr_scenario()