7.6 Conditions and triggers

A scenario can be regarded as a collection of meaningful actions whose activation is regulated by triggers. These triggers play an important role on how a scenario evolves because the same set of actions may lead to a multitude of different outcomes. The outcome strongly depends on how actions are triggered in relation to one other. In ASAM OpenSCENARIO, a trigger is the outcome arising from a combination of conditions and always evaluates to either true or false.

In ASAM OpenSCENARIO, a condition is a container for logical expressions and is assessed at runtime. The condition operates on the current and previous evaluations of its logical expressions to produce a Boolean output that is used by triggers.

7.6.1 Triggers and condition groups

The Trigger class is an association of ConditionGroup instances, which are an association of Condition instances. At runtime, a condition group evaluates to either true or false and its outcome is calculated as the AND operation between all its conditions:

A conditionGroup is evaluated to true when all its associated conditions are evaluated to true.

The outcome of a trigger is calculated as the OR operation between all its condition groups.

A trigger evaluates to true when at least one of its condition groups evaluates to true.

Formally, a trigger containing N instances of ConditionGroup at time t_d is defined as:

\[T(t_{d}) = \bigvee_{n=1}^{N} ConditionGroup_{n}(t_{d})\]

Let M_n be the number of conditions in a condition group m, and Condition_nm be condition n of condition group m. Replacing the condition group formulation in the expression above gives the trigger as:

\[T(t_{d}) = \bigvee_{n=1}^{N} \left ( \bigwedge_{m=1}^{M_{n}} Condition_{nm}(t_{d}) \right )\]

ASAM OpenSCENARIO v1.0 allows instances of the Trigger class to be empty, for example, no condition groups defined. Empty triggers are not meaningful and are kept for the sake of downward compatibility. This is expected to be addressed in the next major version where a trigger shall be defined with at least one condition group. An empty trigger is always evaluated to false.

Example

A trigger is formed by three condition groups. Let M_n be the number of conditions in condition Group n. The first condition group has two associated conditions (M₁ = 2), the second condition group has three associated conditions (M₂ = 3) and the third condition group has one associated condition (M₃ = 1).

The trigger value is T(t_d) and is calculated as a function of its conditions' evaluations. Let CE_mn be the evaluation of condition n of condition group m:

\[T(t_{d}) = ((C_{11}(t_{d}) \wedge C_{12}(t_{d})) \vee (C_{21}(t_{d}) \wedge C_{22}(t_{d}) \wedge C_{23}(t_{d})) \vee (C_{31}(t_{d})))\]

7.6.1.1 Start trigger

An instance of the Trigger class instantiated as a start trigger is used to move a runtime instantiation of a Storyboard element from the standbyState to the runningState. Only the Act class and Event class host start triggers and any element that does not contain a start trigger inherits the start trigger from its parent element. For example, starting an act via a start trigger also starts its maneuver groups and maneuvers, but only starts events if they have no own start triggers defined. An act that has no explicit start trigger defined is started when the enclosing Storyboard enters runningState. Furthermore, no events may start if they do not belong to an act that is in the runningState.

The Story class is an exception to the rules above since it does not require a formal start trigger given that starting a simulation is equivalent to starting the Story.

7.6.1.2 Stop trigger

A stop trigger is used to force a runtime instantiation of a StoryboardElement to transition from its standbyState or runningState to the completeState. Only the storyboard and the act host stop triggers. All storyboard elements inherit the stop triggers from their parent. This is true even if the storyboard element under consideration has its own stop triggers. For example, if a story is affected by a stop trigger, so are all its acts, even though they have their own stop triggers.

When a stop trigger is received, the concerned storyboard element is expected to transition to the completeState with a stopTransition, and clear all remaining number of executions, if applicable. If the trigger occurs when the element is in the runningState, it is expected that its execution is terminated immediately.

If no stop trigger is defined for the Storyboard, the scenario has no explicit end and the simulation can only be stopped by the simulation tool.

7.6.2 Condition edges

When edges are defined, with rising, falling, and risingOrFalling, the condition evaluation is also dependent on past values of its logical expression at the discrete time t_d-1. See Figure 34 for the possible evaluations of a condition, given the available edges.

Figure 34. Evaluation of a speed condition with a greaterThan rule, for all possible edge values

7.6.2.1 Rising edges

When conditions have rising edges defined (conditionEdge = rising), the condition evaluation at discrete time t_d is true when its logical expressions at t_d evaluates to true and the logical expression at t_d-1 was evaluated to false:

\[C_{R}(t_{d}) = LogicalExpression(t_{d}) \wedge \overline{LogicalExpression(t_{d-1})}\]

7.6.2.2 Falling edges

In opposite to a rising edge, a falling edge condition (conditionEdge="falling") evaluates to true when its logical expression at t_d evaluates to false and the logical expression at t_d-1 evaluates to true:

\[C_{F}(t_{d}) = \overline{LogicalExpression(t_{d})} \wedge LogicalExpression(t_{d-1})\]

7.6.2.3 Rising or falling edges

When a condition was defined with rising or falling edges (conditionEdge="risingOrFalling"), the condition evaluation is simply a combination of rising or falling edges:

\[C_{RoF}(t_{d}) = C_{R}(t_{d}) \vee C_{F}(t_{d})\]

7.6.2.4 None edges

With none edges defined (conditionEdge="none"), the evaluation of a condition is the evaluation of its logical expression:

\[C_{N}(t_{d}) = LogicalExpression(t_{d})\]

7.6.3 Condition delay

A delay is a modification of a condition that allows past values of the condition evaluation to be used in the present t_d. When a delay Δt is defined, a condition at time t_d is represented by the evaluation of the logical expressions associated to that condition, at t_d-Δt, rather than the evaluation of its logical expressions at time t_d. In other words, evaluation of a delayed condition at time t_d it is equivalent to the evaluation of a similar condition, but without delay, at time t_d-Δt:

\[C_{D}(t_{d}) = C(t_{d-\Delta})\]

7.6.4 Corner cases of edges and delays

Both edge and delay concepts rely on previous evaluations of the logical expression of a condition. Depending on when the condition is evaluated, these previous evaluations of the logical expression may not be available.

When a condition defined with edge is checked for the first time, no information about previous evaluations of its logical expression is available. At runtime, when a condition defined with edge is checked for the first time, it shall always evaluate to false. During the second time the condition is checked, the current and previous evaluations of its logical expression are used for edge detection. Note that constantly true logical expressions do NOT trigger a conditionEdge="rising". ASAM OpenSCENARIO expects a condition to be checked for the first time once its enclosing storyboard element enters the standbyState. If standbyState is not defined, runningState shall be used.

In case of conditions defined with delay, if t_d < Δt, the concerned condition evaluates to false.

7.6.5 Condition types

The base condition type contains three basic elements: name, delay, and conditionEdge. Whereas the first element is self-explanatory, clarification on the other terms is given in the preceding sections. Other elements of a condition depend on its subtype, of which there are two: ByEntityCondition and ByValueCondition.

7.6.5.1 ByEntityConditions

The ByEntityCondition class hosts classes of conditions which use the states entities to perform the conditional evaluation. The conditional evaluation may depend on the value of a single state, or on how the value of any one given state relates to another state. The other state may be:

within the entity
between entities
between the entity and the corresponding characteristics of the road network

Entity conditions require the definition of triggering entities whose states are used in the conditional evaluation. If more than one triggering entity is defined, the user is given two alternatives to determine when the condition evaluates to true: either all triggering entities verify the logical expression or at least one entity verifies the logical expression.

7.6.5.2 ByValueConditions

The ByValueCondition classes hosts condition classes with logical expressions that depend on simulation states rather than entity states. Examples are scenario states, times, and traffic signal information.

Value conditions also provide a wrapper for external conditions that may depend on values that are not accessible from the scenario and are only available to the user implementation. Examples are pressing buttons, custom signals, and commands.