Naming conventions

Actor naming

The SUT and the Ego actor

The term "SUT" refers to the System Under Test. All related scenarios and metrics should refer to the SUT in a similar fashion in order to clearly separate this actor from any other actor in a scenario.

There are many different types of SUTs, including:

A central vehicle-controlling hub, such as a mining site control or a port control, including the controlled vehicles.
Autonomous vehicles such as cars, trucks, buses, off-road vehicles, robots, and so on.
Components or functions of autonomous vehicles.
Components or functions of driver-assistance systems.

An SUT vehicle is sometimes also referred to as "Ego". For example, a vehicle cut-in maneuver describes a lane change happening ahead of an SUT vehicle or Ego.

Convention

The actor for the SUT is always sut and metrics referring to it should have sut in their name and descriptions.

Here are some examples:

OSC2 code: examples of the convention

# Scenario maneuver definition
scenario sut.vehicle_cut_in

# Coverage item for the SUT's speed:
    var sut_speed_at_start: speed = sample(
        sut.car.state.speed, @start)
    cover(sut_speed_at_start,
        text: "SUT speed at start (in kph)",
        unit: kph,
        buckets: [0,5,10,15,20,25,30,35,40,45,50,60,
            70,80,90,100,110,120,140,160,180,200])

Exception

The EuroNCAP protocols and their related scenarios have a different convention for actor naming. For EuroNCAP scenarios specifically, the SUT vehicle actor is called VUT. Scenarios should be defined under the sut actor, since this is the Foretellix OSC2 API, but the metrics should reference VUT.

Here are examples of the exception:

OSC2 code: example for EuroNCAP

# Scenario definition
scenario sut.aeb_car_to_motorcycle_rear_stationary

# Coverage item for VUT/SUT speed in EuroNCAP AEB_car_2_car scenario:
    var speed_of_vut := sample(sut.car.state.speed, @braking_vut.start)
    cover(speed_of_vut,text:"Actual speed of VUT",unit: kph,range: [49..50],every:1)

Linter rule name

LINT_STANDARD_NAMING

Other Actors/NPCs

Other Non-Principal Characters (NPCs) or actors in a scenario typically play a distinct role in the scenario. The names of the actors should indicate their role in the scenario, and metric names should reference the related actor.

Specifically, the name of the actor should indicate the type of the actor, either a generic actor, such as vehicle or plain_object or a specific type such as truck or person, as well as its action inside the scenario. Using similar actor names across scenarios and especially within scenario families helps users understand those scenarios more quickly.

Convention

[<descriptor-or-action>_]<actor>[_<count>]

<descriptor-or-action>: This optional component describes the behavior of the actor inside the scenario as distinct from any other actors of the same type. For example, cut_in_vehicle is used for vehicle inside the vehicle_cut_in() scenario.
<actor>: This required component describes the type of actor, for example vehicle or person. It should be selected if possible from the list of OSC2 actors. If it is not predefined, then it must be documented and used consistently across Foretellix scenarios. An actor can also be a group of the same type, for example, a vehicle_group, truck_group, or a plain_object_group.
<count>: This optional component is a number starting from 1 and should be used if there are more than one vehicles performing the same action. For example, cut_in_vehicle_1 and cut_in_vehicle_2 appear in the double_vehicle_cut_in() scenario.

Additional conventions are:

Use underscores to link the components of the name together.
In the scenario documentation, in code comments or in text displayed in tools, use hyphens and spaces to separate the components of the name and capitalize abbreviations such as SUT.

Here are some examples:

OSC2 code: examples of actor names

lead_vehicle
cut_in_vehicle
cut_in_vehicle_1, cut_in_vehicle_2, cut_in_vehicle_3
cut_out_vehicle
cut_out_truck
oncoming_vehicle
crossing_person
crossing_person_group
traffic_jam_vehicle_group

Exception

The EuroNCAP protocols and their related scenarios have a different convention for actor naming. For EuroNCAP scenarios specifically, the lead_vehicle in the car_2_car scenarios is called GVT (Global Vehicle Target).

Here is an example for the exception:

OSC2 code: examples for EuroNCAP

scenario sut.aeb_c2c_rear_braking:
    gvt: vehicle
    gvt_speed: speed with:
        keep(it in [49..50]kph)

Linter rule name

LINT_ACTOR_FIELD_NAME

Scenario naming

Naming scenarios consistently helps users in various ways. It helps them to:

Understand the purpose of a scenario.
Identify similar scenarios or scenarios in the same family.
Navigate the directory structure containing the scenario files.
Identify systematic issues of the SUT when viewing scenarios in a test suite or analyzing test suite results.
Figure out which driving function the scenario targets, such as an ADAS function or a SAE level driving function.

Convention

For standalone scenarios:

[<function>_][<descriptor-or-action>_]<actor>_<action-or-maneuver>[_and_<another-action-or-maneuver>]

For mixes:

[<function>_]mix_[<descriptor-or-action>_]<actor>_<action-or-maneuver>_with_[<descriptor-or-action>_]<actor>_<action-or-maneuver>

<function>: This optional component is the ADAS or SAE level function.
<descriptor-or-action>: This optional component indicates the behavior of the actor in the scenario as distinct from any other actors of the same type. For example, cut_in_vehicle is used for vehicle inside the vehicle_cut_in() scenario.
<actor>: This required component describes the type of the principal actor and should be selected if possible from the list of OSC2 actors. If it is not predefined, then it must be documented and used consistently across Foretellix scenarios.
<action-or-maneuver>: This required component is the principal action or maneuver in the scenario.
_and_<another-action-or-maneuver>: This optional component is another actor and maneuver in the scenario preceded by _and_.

Additional conventions are:

Use underscores to link the components of the name together.
In the scenario documentation, in code comments or in text displayed in tools, use hyphens and spaces to separate the components of the name and capitalize abbreviations such as SUT,

Example

OSC2 code: example scenario names

# A scenario where the SUT performs a merge (ego_merge)
sut_merge

# A scenario where a vehicle ahead of the SUT performs a cut-out
lead_vehicle_cut_out  

# A scenario where a vehicle ahead of the SUT performs a cut-out and slows down
lead_vehicle_cut_out_and_slow

# A mix of a scenario where a vehicle ahead of the SUT
# performs a cut-out and slows down
# and a scenario with oncoming traffic
mix_lead_vehicle_cut_out_and_slow_with_oncoming_traffic

# A scenario where a vehicle performs a cut-in
vehicle_cut_in

# A scenario where a vehicle performs a cut-in targeting a SUT with ACC function
acc_vehicle_cut_in

# A mix of a scenario where a vehicle ahead of the SUT performs a cut-out and slows down
# and a scenario with oncoming traffic targeting an AEB function
aeb_mix_lead_vehicle_cut_out_and_slow_with_oncoming_traffic

Linter rule name

LINT_ADAS_FUNC_NOT_PREFIX

Scenario file naming

Using consistent file names for all files belonging to a scenario helps to navigate the directory structure and find the right file.

Convention

<scenario_name>_top.osc: This top-level file imports all the files related to the scenario and is typically the main file to be imported into the test file.
<scenario_name>.osc: This file defines the scenario interface: the actors and the fields used to constrain their behavior during the scenario.
<scenario_name>_imp.osc: This file defines the scenario implementation: the do block describing the behavior of the actors during the scenario.
<scenario_name or scenario_family_name or function_name>_checks.osc: This file contains checker definitions specific to a single scenario, a scenario family or an ADAS or SAE level function.
<scenario_name or scenario_family_name or function_name>_kpi.osc: This file contains KPI definitions specific to a single scenario, a scenario family or an ADAS or SAE level function.
<scenario_name or scenario_family_name or function_name>_cover.osc: This file contains coverage definitions specific to a single scenario, a scenario family or an ADAS or SAE level function.

Additional conventions are:

If a coverage item, KPI or check is specific to a certain scenario it should be contained in the <scenario_name>_checks/cover/kpi.osc file.
If a coverage item, KPI or check is applicable to a whole scenario family it should be contained in the <scenario_family_name>_checks/cover/kpi.osc file.
If a coverage item, KPI or check is specific to a SUT function and usable across multiple scenarios it should be contained in the <function_name>_checks/cover/kpi.osc file.

Examples

Example OSC2 filenames

# Scenario-specific files:
lead_vehicle_top.osc
lead_vehicle.osc
lead_vehicle_imp.osc
lead_vehicle_checks.osc
lead_vehicle_kpi.osc
lead_vehicle_cover.osc

# Generic files:
aeb_checks.osc
acc_kpi.osc
cut_out_family_cover.osc

Linter rule name

Not yet implemented.

KPIs, metrics and coverage

In order to understand what a KPI, metric or coverage item measures, it is important to provide information about:

Who is the actor (SUT or NPC) or what is the scenario element (road property, environment property) whose attribute or property is being measured?
What is the metric item—the attribute or property—whose value is collected?

In the description and comments it is essential to provide detailed information about any reference points, coordinate systems or mathematical expressions used in calculating the metric item's value.
When is the data extracted?

Coverage items and KPIs often represent a value recorded or sampled at a specific point in time. The value can be related to a certain event, or it can be a computed value such as the minimum, maximum, or average value of a metric item collected multiple times during the scenario.

When a user reviews the metrics and coverage items in Foretify Manager, this information is necessary because the OSC2 code is not immediately available for review. Furthermore, similar metrics across multiple scenarios need to be consistent in their naming to facilitate proper interpretation of the test results.

Naming convention for KPIs, metrics and coverage

Who is the actor and what is being measured must be indicated in the names of all KPIs, coverage items and metrics. Specifying when the data is collected is mandatory only if collection is event-based and not either a computed value or a value that remains constant throughout the scenario. For example:

ttc_at_lane_change_end is sampled at a specific point in time, so it is necessary to indicate when the data is collected.
min_ttc is global and computed from all TTC values collected during scenario execution, so it is not necessary to indicate when the data is collected.
vehicle_color or vehicle_type are global constant values that do not change during the scenario, so it is not necessary to indicate when the data is collected.

For metrics of a single actor:

[<descriptor>_]<actor>_<metric-item>[_at_<event>]

For metrics between two actors:

[<descriptor>_]<actor>_<metric-item>_to_<actor>[_at_<event>]

<descriptor>

This optional component indicates the behavior of the actor inside the scenario as distinct from any other actors of the same type. If a descriptor is used in the name of the actor, it should be used here as well.

<actor>

This required component is the name of the actor or actors whose metric item is being collected. For relative values like the distance between two actors or relative_speed, both actors should be included. Exceptions are:

When there is no specific second actor. For example, TTC is measured globally from the SUT to all actors in the scenario.
When the primary actor is the SUT and there is no second metric with the same name. In this case, the name is unambiguous.

<metric-item>

This required component is the item whose values are collected.

at_<event>

This component is the event at which the value is collected. This component is optional for metric items whose value is constant throughout the scenario or is computed. Otherwise, this component is mandatory.

Examples

OSC2 code: examples of metric names

# Single actor
lead_vehicle_speed_at_start
cut_in_vehicle_average_acceleration
cut_out_vehicle_speed_at_lane_change_start

# Two or more actors, relative values
min ttc                      # equivalent to sut_min_ttc_to_all_other_actors  
sut_distance_to_lead_vehicle_at_start
sut_rel_speed_to_cut_in_vehicle_at_lane_change_start

Linter rule name

Not yet implemented.

Convention for condition-based metric items

If the time frame of observation or sampling is based on a condition, such as acc_active, or there is a named scenario phase, such as cut_in, use the keyword while to make clear what the observed time frame is.

For condition-based metrics, the convention is:

<metric-item>_while_<condition-or-phase-name>

<metric-item>: This required component is the item that is being measured.
<condition-or-phase-name>: This required component is the name of the condition or the phase during which the item's values are collected.

Examples

OSC2 code: condition-based metrics

min_ttc_while_cut_in
max_lateral_jerk_while_lca_active

Linter rule name

Not yet implemented.

Naming convention for time-based metric items

Sometimes it is not possible to use either a condition or a scenario phase to define the observation time frame. One such example is when sampling between two independently defined events such as @cut_in.start and @acc_engages.

For metrics sampled between two independent events, the convention is:

<metric-item>_between_<event>_and_<event>

<metric-item>: This required component is the item that is being measured.
<event>: The name of each event between which the item is measured.

Examples

OSC2 code: metric sampled between two events

max_jerk_between_cut_in_start_and_acc_engages

Linter rule name

Not yet implemented.

Naming convention for cross-coverage items

For cross coverage items, the convention is:

cross_<coverage-item>_<coverage-item>

<coverage-item>: This required component is the name of each coverage item that is being crossed.

Examples

OSC2 code: cross coverage

 cross_cut_in_duration_lon_lane_distance_to_cut_in_vehicle_at_start

Linter rule name

LINT_CROSS_BAD_PREFIX