112. Warmup limitations

Some customers have simulation limitations during the Ego's warmup phase, for example, vehicles placed too close to the Ego, presence within a junction, or restricted lateral movement.

If a Smart Replay scenario is created where a warmup limitation occurs during the Ego's warmup period, the scenario will start running but will fail with an error from the Ego.

The warmup limitations feature helps prevent such failures by blocking the export of scenarios that could cause a failure if a known warmup limitation is detected. When properly configured, the feature ensures that export fails instead of allowing a faulty scenario to proceed.

112.1 Prerequisites

The latest version of Smart Replay Warmup Limitations is located in the <installation-folder>/smart_replay_tools/bin directory.

You must install Smart Replay Warmup Limitations on the computer that has access to the Foretify Manager where the warmup limitations will be configured.

Before using the warmup limitations tools, ensure you have the following:

Python 3.9 or above installed on your system
Foretify Manager Python SDK installed

Note

All tool executions (e.g., ./smart_replay_warmup_limitations_api) should be run using paths relative to the <installation-folder>/smart_replay_tools/bin directory.

112.2 Watchers and interval names

Intervals represent specific periods of time in your tests when a particular behavior was active. In Foretify, there are several interval sources, and each scenario from a run is automatically linked to an interval.
Watchers allow you to create custom intervals.

Warmup limitations are customer-specific. To identify warmup limitations, you must first have watchers that will create the relevant intervals.

For example, if the Ego can't be in a junction during warmup, then a watcher is required when the Ego is inside the junction. A watcher already exists for this specific example:

global modifier sut_vehicle.junction_checkers:
    watcher traverse_junction is traverse_junction(vehicle: actor)

The traverse_junction is a watcher modifier that emits intervals when a vehicle traverses a junction.

Each interval created by this watcher instance has a well-defined name, in our example it is sut_vehicle.junction_checkers.traverse_junction.

This name is stored in the run data for each interval, so it can be used to explicitly identify warmup limitation intervals.

112.3 Warmup limitation workflow

The workflow to create and use warmup limitations is as follows:

Create or identify watchers that are potential warmup limitations

Find the relevant watchers in your OSC code, or create new watchers that will create intervals that could be warmup limitations. Note that different stacks may have different warmup limitations.
Configure interval names of potential warmup limitations

Once we have the names of all watcher instances that may have warmup limitations, we can configure Foretify Manager accordingly. This includes creating, updating, or deleting warmup limitations.

The Foretify Manager configuration consists of the following data:
- Name: A unique name for the limitation. This name should be a user-defined identifier without spaces that may include alphanumeric characters and special characters like .-_. For example, ego_in_junction.
- Interval Name: The name of the watcher that creates the relevant interval. It must exactly match the watcher's name; otherwise, it will not work, as a watcher cannot find intervals that do not match its name. For example, sut_vehicle.junction_checkers.traverse_junction, sut_vehicle.speed_checkers.over_legal_limit, speed_above_limit. The interval name must be unique. If another limitation uses the same interval name, it will fail.
- Limitation message: Specify a human-readable error that will be displayed if the warmup limitation interferes with the warmup time. For example, Ego is in junction.
Example using the Warmup Limitations API
```
./smart_replay_warmup_limitations_api \
--host fmanager.example.com --port 8080 --user user@fmanager.com --https \
create 
--name "speed_limit" 
--interval_name "speed_above_limit" 
--limitation_message "Speed should not exceed 50 km/h"
```
See Creating a new warmup limitation.
Configure warmup limitations groups

To simplify the process of specifying limitations for each Smart Replay extraction configuration, you can create warmup limitation groups. This way, each configuration can be linked to a single group instead of listing all the limitations individually.

Each warmup limitation group consists of the following configuration:
- Name: A unique string identifying the group. This is a user-defined identifier without spaces that may include alphanumeric characters and the characters .-_. For example, driver_v1.2-v1.5
- List of warmup limitations: The list of warmup limitation IDs to be included in this group.
Related links:
- See Creating a group of warmup limitations.
- See Updating an existing warmup limitation.

Add a warmup limitation group for the Smart Replay extraction configuration

When creating Smart Replay user configurations, add the warmup limitation group name.

Example

./smart_replay_configurations_api 
  --host localhost 
  --port 8080
  --user adminfmanager 
  --https 
  create 
  --config_file "$FTX_BASIC/exe_platforms/config/model_config.osc" 
  --warmup 100 
  --cooldown 100 
  --display_name "new_configuration"
  --warmup_limitation_group_name "group-123"

See Creating a new Smart Replay configuration.