7 Actions

ASAM OpenSCENARIO 1.2.0 actions can be represented in and converted to ASAM OpenSCENARIO 2.0.0 in two ways.

  1. drive() with modifiers.

  2. Specialized action, defined in the domain model of ASAM OpenSCENARIO 2.0.0.

Both approaches are valid for converting ASAM OpenSCENARIO 1.2.0 scenarios. There are some exceptions to this approach. Where applicable, these are detailed in the specific section of the action and in Section 8, "Elements from ASAM OpenSCENARIO 1.2.0 not yet covered".

In the scope of the conversion of ASAM OpenSCENARIO 1.2.0 scenarios, for most actions both options can be used. Exceptions are listed through the section text and in the appendix.

Using drive() can in some cases result in a scenario specification that is less constrained than when using the equivalent specialized action. Depending on the use case you might start with specialized action conversion and move to drive variant as you move the scenario up the abstraction levels.

7.1 Action duration

General instructions for handling ASAM OpenSCENARIO 1.2.0 actions with regards to action duration.

  • Durable/Continuous

  • Instantaneous

Actions with the flag continuous can be represented using two drive actions:

  1. A drive action to reach the required condition.

  2. A request to continue driving with a condition satisfied from that moment until the next action on the same control axis (longitudinal/lateral) cancels it.

Specialized actions where the duration is relevant have the duration argument. The argument specifies the time in which the action needs to complete. In contrast to ASAM OpenSCENARIO 1.2.0 there is no direct way to specify that the action is to complete within specific covered distance (distance dynamics specification for SpeedChange and LaneChange actions).

7.2 Private actions

Private actions are executed by a list of actors that are specified in the parent ManeuverGroup. If multiple actors are executing the same action, an action is considered finished when the last actor finishes executing it.

7.2.1 SpeedAction

Example 1. Setting the initial speed
Code 14. ASAM OpenSCENARIO 1.2.0
<Private entityRef="Ego">
    <PrivateAction>
        <LongitudinalAction>
            <SpeedAction>
                <SpeedActionDynamics dynamicsShape="step" dynamicsDimension="time" value="0" />
                <SpeedActionTarget>
                    <AbsoluteTargetSpeed value="$Ego_InitSpeed_Ve0" />
                </SpeedActionTarget>
             </SpeedAction>
        </LongitudinalAction>
    </PrivateAction>
</Private>
Code 15. ASAM OpenSCENARIO 2.0.0
# Drive

ego.drive() with: along(s_ego); speed(ego_init_speed_ve0)

# Specialized action

ego.change_speed(target: target_ego_init_speed_ve0, rate_profile: asap)
Example 2. Changing the speed with different profile
Code 16. ASAM OpenSCENARIO 2.0.0
# Drive

do serial:
    car1.drive() with: speed(50kph)
    car1.drive() with: speed(100kph, at:end)

# Specialized action

do serial:
    car1.reach_speed(50kph, as_soon_as_possible)
    car1.reach_speed(100kph, cubic_accel)

7.2.2 LongitudinalDistanceAction and LateralDistanceAction

Example 3. continuous:`false`, freespace:`true`
Code 17. ASAM OpenSCENARIO 1.2.0
<ManeuverGroup maximumExecutionCount="1" name="Group 1">
    <Actors selectTriggeringEntities="false">
        <EntityRef entityRef="Car 1"/>
    </Actors>
    <Maneuver name="Maneuver 1">
        <ParameterDeclarations/>
        <Event priority="overwrite" maximumExecutionCount="1" name="Event 1">
            <Action name="Longitudinal Distance">
                <PrivateAction>
                    <LongitudinalAction>
                        <LongitudinalDistanceAction freespace="true" continuous="false" entityRef="Ego" distance="20.0">
                            <DynamicConstraints maxAcceleration="0.0" maxDeceleration="0.0" maxSpeed="0.0"/>
                        </LongitudinalDistanceAction>
                    </LongitudinalAction>

                </PrivateAction>
            </Action>
            <StartTrigger>
                <ConditionGroup>
                    <Condition delay="0.0" conditionEdge="none" name="Simulation Time">
                        <ByValueCondition>
                            <SimulationTimeCondition rule="equalTo" value="2.0"/>
                        </ByValueCondition>
                    </Condition>
                </ConditionGroup>
            </StartTrigger>
        </Event>
    </Maneuver>
  </ManeuverGroup>
...
Code 18. ASAM OpenSCENARIO 2.0.0
serial:
    parallel(duration: 2s):
        ego.drive()
        car1.drive() with:
            position(behind: ego, 50m)

    parallel:
        ego.drive()
        car1.drive() with:
            position(at:end, behind: ego, 20m)

Alternatively, for LongitudinalDistanceAction and LateralDistanceAction, the specialized actions change_space_gap and keep_space_gap can be used, with specification ahead/behind or left/right (see [code-lc-transfer-longitudinal-distance-concrete]). For LateralDistanceAction use values left_of and right_of for the direction argument of position modifier.

In this case distance is calculated along a specified axis, which corresponds to the ASAM OpenSCENARIO 1.2.0 freespace: true variant.
Example 4. Use of specialized actions to change longitudinal and lateral distances.
serial:
    parallel:
    # Reach specified distance
        car1.change_space_gap(target: 20m, direction: behind, reference: ego)
        car2.change_space_gap(target: 3m, direction: left, reference: ego)
    parallel:
    # Keep the attained distance
        car1.keep_space_gap(direction: longitudinal, reference: ego)
        car2.keep_space_gap(direction: lateral, reference: ego)
Example 5. continuous:`true`, freespace:`true`
Code 19. ASAM OpenSCENARIO 1.2.0
<ManeuverGroup maximumExecutionCount="1" name="Group 1">
    <Actors selectTriggeringEntities="false">
        <EntityRef entityRef="Car 1"/>
    </Actors>
    <Maneuver name="Maneuver 1">
        <ParameterDeclarations/>
        <Event priority="overwrite" maximumExecutionCount="1" name="Event 1">
            <Action name="Longitudinal Distance">
                <PrivateAction>
                    <LongitudinalAction>
                        <LongitudinalDistanceAction freespace="true" continuous="true" entityRef="Ego" distance="20.0">
                            <DynamicConstraints maxAcceleration="9.0" maxDeceleration="0.0" maxSpeed="25.0"/>
                        </LongitudinalDistanceAction>
                    </LongitudinalAction>
                </PrivateAction>
            </Action>
            <StartTrigger>
                <ConditionGroup>
                    <Condition delay="0.0" conditionEdge="none" name="Simulation Time">
                        <ByValueCondition>
                            <SimulationTimeCondition rule="equalTo" value="2.0"/>
                        </ByValueCondition>
                    </Condition>
                </ConditionGroup>
            </StartTrigger>
        </Event>
    </Maneuver>
  </ManeuverGroup>
...
Code 20. ASAM OpenSCENARIO 2.0.0
serial:
    parallel:
        ego.drive()
        car1.drive() with:
            position(behind_of: ego, 50m)

    parallel:
        ego.drive()
        car1.drive() with:
            position(at:end, behind_of: ego, 20m)
            speed([0kph..90kph])
            acceleration([0mpsps..9mpsps])

    parallel:
        ego.drive()
        car1.drive() with:
            position(behind_of: ego, 20m)
            speed([0kph..90kph])
        keep(car1.acceleration.translational.norm() < 9mpsps)

7.2.3 LaneChangeAction

Example 6. LaneChangeAction
Code 21. ASAM OpenSCENARIO 1.2.0
<ManeuverGroup maximumExecutionCount="1" name="CutOutManeuverGroup">
    <Actors selectTriggeringEntities="false">
        <EntityRef entityRef="LeadVehicle" />
    </Actors>
    <Maneuver name="CutOutManeuver">
        <Event name="CutOutEvent" priority="overwrite">
            <Action name="CutOutAction">
                <PrivateAction>
                    <LateralAction>
                        <LaneChangeAction>
                            <LaneChangeActionDynamics dynamicsShape="cubic" value="$Lateral_Velocity_Vy" dynamicsDimension="rate" />
                                <LaneChangeTarget>
                                    <RelativeTargetLane entityRef="TargetBlocking" value="1" />
                                </LaneChangeTarget>
                          </LaneChangeAction>
                      </LateralAction>
                </PrivateAction>
          ...
          ...
</ManeuverGroup>
Code 22. ASAM OpenSCENARIO 2.0.0
lead_vehicle.change_lane(target: lane(left_of: target_blocking), rate_profile: smooth, rate_peak: lateral_velocity_vy, duration: 5s)

7.2.4 LaneOffsetAction

LaneOffSetAction can be converted using change_lane action or with a follow_lane action. If a more detailed definition of an action shape is needed, change_lane with the same lane modifier (same_as parameter) is preferred. If the exact shape is not so important, follow_lane is less constrained.

Example 7. LaneOffsetAction
Code 23. ASAM OpenSCENARIO 1.2.0
<ManeuverGroup maximumExecutionCount="1" name="SwerveSequence">
    <Actors selectTriggeringEntities="false">
        <EntityRef entityRef="SideVehicle" />
    </Actors>
    <Maneuver name="SwerveManeuver">
        <Event name="SwerveEvent" priority="overwrite">
            <Action name="SwerveAction">
                <PrivateAction>
                    <LateralAction>
                        <LaneOffsetAction continuous="true">
                            <LaneOffsetActionDynamics maxLateralAcc="$Swerve_MaxLateralAcc" dynamicsShape="sinusoidal" />
                            <LaneOffsetTarget>
                                <AbsoluteTargetLaneOffset value="$Swerve_Offset_Left" />
                            </LaneOffsetTarget>
                        </LaneOffsetAction>
                    </LateralAction>
                </PrivateAction>
            </Action>
        ...
        ...
</ManeuverGroup>
Code 24. ASAM OpenSCENARIO 2.0.0
    do serial(15s):
        side_vehicle.follow_lane(swerve_offset_left, max_lateral_acc: swerve_max_lateral_acc)
        side_vehicle.follow_lane(0m, max_lateral_acc: swerve_max_lateral_acc)
        side_vehicle.follow_lane(-swerve_offset_left, max_lateral_acc: swerve_max_lateral_acc)
        side_vehicle.follow_lane(0m, max_lateral_acc: swerve_max_lateral_acc)

7.2.5 SynchronizeAction

Example 8. SynchronizeAction
Code 25. ASAM OpenSCENARIO 2.0.0
# Initial positions
ego_position: odr_point = map.create_odr_point(road_id: 0, lane_id: ego_init_position_lane_id, s: 0m)
ego_target_position: odr_point = map.create_odr_point(road_id: 0, lane_id: ego_init_position_lane_id, s: 80m)
s_ego: path = map.create_path([ego_position, ego_target_position], smooth)

car1_position: odr_point = map.create_odr_point(road_id: 1, lane_id: car1_init_position_lane_id, s: 20m)
car1_target_position: odr_point = map.create_odr_point(road_id: 1, lane_id: car1_init_position_lane_id, s: 120m)
s_car1: path = map.create_path([car1_position, car1_target_position], smooth)

s_target_speed_car1: speed = 80kph

serial:
    parallel(overlap: equal):
        ego.drive() with:
            along(s_ego)
            along(s_ego, start_offset: 0m, at: start)
            along(s_ego, end_offset: 0m, at: end)
            speed(50kph)
        car1.drive() with:
            along(s_car1)
            along(s_car1, start_offset: 0m, at: start)
            along(s_car1, end_offset: 0m, at: end)
            speed(40kph, at: start)
            speed(s_target_speed_car1, at: end)

7.2.6 AssignControllerAction, ActivateControllerAction, OverrideControllerValueAction

Please note that the following section and its sub-sections are non-normative.

In ASAM OpenSCENARIO 1.2.0, the handling of controllers depends in large part on the simulation environment. Here we propose an extension, which the simulation of ASAM OpenSCENARIO 2.0.0 environment should follow, to allow for migration of controller-related actions.

Example 9. A suggestion to allow for the handling of controllers in a uniform way.
Code 26. Defining the structs
struct osc_1_controller:
    var active_lateral: bool = false
    var active_longitudinal: bool = false

struct osc_1_controller_float_value:
    var active: bool = false
    var value: float = 0.0

struct osc_1_controller_gear_value:
    var active: bool = false
    var value: int = 0

struct osc_1_controller_values:
    var throttle: osc_1_controller_value
    var brake: osc_1_controller_value
    var clutch: osc_1_controller_value
    var parking_brake: osc_1_controller_value
    var steering_wheel_action: osc_1_controller_value
    var gear: osc_1_controller_gear_value

struct osc_1_bm : vehicle_bm
    controller: osc_1_controller
    overrides: osc_1_controller_values

With these struct definitions, the actions can be written as follows:

Code 27. Writing the actions
scenario controller_setup:
    ego: car
    car_1: car

    var my_alks_controller: osc_1_controller
    var my_behavior_model: osc_1_bm
    do:
        # First set up and activate the controller
        my_behavior_model.set_controller(my_alks_controller)
        ego.set_bm(my_behavior_model) # AssignController
        my_behavior_model.set_controller_active(lateral: true) # ActivateController

        ego.drive() with:
            speed(50kph)
        car_1.drive() with:
            position([30m..50m], ahead_of: ego)
            lane(same_as: ego)

    # Under some condition override the controller throttle value
    on ego.object_distance(car_1 direction: longitudinal, mode: bounding_box) < 10 m:
        # OverrideControllerValue
        my_behavior_model.activate_override(control: throttle, value: 0.77)

7.2.7 TeleportAction

The TeleportAction is used in two contexts. In the <Init> section it specifies the initial location of the entity. Such a case can be converted as in this example:

Example 10. A TeleportAction where the initial location of an entity is specified.
Code 28. ASAM OpenSCENARIO 1.2.0
<Private entityRef="Ego">
    <PrivateAction>
        <TeleportAction>
            <Position>
                <LanePosition roadId="0" laneId="$Ego_InitPosition_LaneId" offset="0.0" s="500.0">
                </LanePosition>
            </Position>
        </TeleportAction>
    </PrivateAction>
</Private>
Code 29. ASAM OpenSCENARIO 2.0.0
# Initial positions
ego_position: create_odr_point(road_id: 0, lane_id: ego_init_position_lane_id, s: 0m)
..
do parallel:
    ego.assign_position(ego_position)
    # ... rest of the position assignments

The second case is when the TeleportAction requests instant location change for an entity, during the scenario run. A simulation environment may or may not be able to fulfill this non-physical request, but it can be converted using the assign_position action.

7.2.8 AssignRouteAction

AssignRoute action can be mapped with drive together with the along modifier. In contrast to an ASAM OpenSCENARIO 1.2.0 instantaneous action, such a conversion has a duration. To ensure that the route assignment is valid for the entire scenario, add this action in parallel on the same level as the rest of your Story.

Example 11. AssignRouteAction
Code 30. ASAM OpenSCENARIO 2.0.0
waypoint_1: route_point = map.odr_to_route_point(create_odr_point(road_id: 0, lane_id: 1, s: 30m))
my_route: route = map.create_route([waypoint_1, ...]
do parallel:
    car1.drive() with:
        along(my_route)
    parallel:
        story_1: .....

7.2.9 AcquirePositionAction

AcquirePositionAction can be mapped to specialized action change_position, with the flag on_road_network.

Example 12. AcquirePositionAction
Code 31. ASAM OpenSCENARIO 2.0.0
position_1: odr_point = map.create_odr_point(road_id: 27, lane_id: 2, s: 50m)
do:
    car1.change_position(target: position_1, path_style: on_road_network)

7.2.10 FollowTrajectoryAction

If the vertex timing information is not to be used, FollowTrajectoryAction is mapped to replay_path (mode position) or follow_path (mode follow) actions. If the timing information is relevant, use replay_trajectory or follow_trajectory instead.

Example 13. FollowTrajectoryAction
Code 32. No timing information
    car1.drive() with:
        along(map.generate_route([vertex_1, ...]), routing_mode=straight)
    car2.follow_path(...)
Code 33. ASAM OpenSCENARIO 2.0.0 With timing information
    car1.replay_trajectory(...)

7.3 Global actions

These actions affect the entire scenario. They are probably mapped as actions on the top scenario.

7.3.1 EnvironmentAction

This action sets the fields in the current simulation environment (weather details and time of day). The action is converted to actions on the instance of the environment actor of ASAM OpenSCENARIO {VER_2_LATEST} or to constraints on the fields of environment actor.

The FractionalCloudCover enum can be converted to a clouds action, where the uint cloudiness parameter maps to the okta values of the enum.

Example 14. Set environment details for the duration of the scenario
    environment: environment

    do serial:
        # Initialization of celestial body
        environment.sun_position(azimuth: 135deg, elevation: 33deg, intensity: 100000lx)
        # Continuation of the scenario
        car_1.drive()
Example 15. Define a environment that changes during the scenario run
    car_1: vehicle
    environment: environment

    scenario weather_change:
        do serial:
            environment.rain(intensity: 0mmph, duration: 3min)
            environment.rain(intensity: 1mmph, duration: 1min)
            environment.rain(intensity: 7mmph, duration: 30s)
            parallel(duration: 3min, overlap: equal):
                environment.fog(visual_range: [100m..200m])
                environment.rain(intensity: 1mmph)

    hour_of_day: int # Any time of day between 3 pm and 5 pm
    keep(hour_of_day >= 15)
    keep(hour_of_day <= 17)

    # Any day between 10th and 20th of December
    min_date: time = environment.local_to_unix_time(2021, 12, 10, hour_of_day, 0, 0, 0)
    max_date: time = environment.local_to_unix_time(2021, 12, 20, hour_of_day, 0, 0, 0))
    keep(environment.datetime >= min_date)
    keep(environment.datetime <= max_date)

    do parallel(overlap: equal):
        weather_change()
        car_1.drive() with:
            speed([40kph..70kph])

7.3.2 AddEntityAction and RemoveEntityAction

In the simulation, activate the entity (set position and start tracking it) that was declared before. Remove the currently active entity from the simulation.

7.3.3 ParameterSetAction and ParameterModifyAction

Pairs with ParameterCondition. This action assigns or modifies values of the runtime variables.

Variables in ASAM OpenSCENARIO 2.0.0 are declared with the var keyword (see Example ParameterCondition).

7.3.4 TrafficSourceAction, TrafficSinkAction and TrafficSwarmAction

Actions that set up traffic spawning/destroying mechanisms. Vehicles spawned through this mechanism cannot be referenced directly. They affect conditions such as RelativeDistance if they contain entitySelection by object type. Objects created are of SpawnedObject type. They implement the Entity interface, but a SpawnedObject is never explicitly listed in a scenario.

7.4 User defined actions

UserDefinedAction, paired with the UserDefinedValueCondition gives a scenario writer the ability to communicate with the runtime environment. UserDefinedAction sends a request to execute some action. Action is defined with a string denoting the action type and a string denoting the additional content.

Interpretation of the action type and additional content is dependent on the contract between the scenario writer and the simulation environment.