9.1 Parameters
In ASAM OpenSCENARIO, parameters provide a central extension mechanism for scenarios.
-
With the help of parameters, a scenario designer can make parameterization points of a scenario explicit.
-
The scenario designer can define constraints to restrict the possible concrete parameter values to reasonable values. This avoids misuse and improves understandability of scenarios, especially when passed to test designers.
External applications can read the provided parameters and thus implement sophisticated methods to assign concrete values to the parameters. This extension method allows scenarios to be reused for a large space of concrete values, for example, the re-simulation of one scenario with different speeds.
Every attribute of an ASAM OpenSCENARIO language element may contain either the actual attribute or a reference to a parameter.
Each parameter is defined in the ParameterDeclaration
by its name
, the parameterType
, a default, type-specific initialization value
, and optional constraintGroups
. When using a parameter, more precisely the parameter value
, anywhere in the scenario, then the parameter is referenced by its name
with a "$" prefix.
All parameters that are used in a scenario shall be defined in ParameterDeclaration
where they are declared by their individual names. Because they are declared and not used as a reference, the name
has no "$" prefix.
Naming of parameters works differently than naming of scenario elements (see Introduction). While scenario elements may be made unique by providing prefixes, this does not apply to parameter names. The reason for this is that scenario elements are globally referenceable, whereas parameters have a scope.
The scope of a parameter is the subtree rooted in the element where the ParameterDeclaration
is located.
That means, if a parameter "ego_speed" is defined at the root of a Maneuver
, "ego_speed" may be referenced in every Event
, Action
and Trigger
located in that Maneuver
. The parameter shall not be used in other Maneuver
instances.
If there are multiple parameters with the same name and overlapping scopes in the scenario, only the parameter with the smallest scope that subsumes the location is accessible. As an example, if the Maneuver
"Overtake" declares a parameter "ego_speed" and "Overtake" contains a FollowTrajectoryAction
that also declares a parameter "ego_speed", then only the second declaration of "ego_speed" is visible in the FollowTrajectoryAction
.
A parameter is considered global if it is a child of the OpenSCENARIO
element that is the root of any ASAM OpenSCENARIO file. Global parameters may be overwritten by external tools (see, for example, Section 9.3, "Parameter value distribution file").
Since every language element may either be the actual type or a referenced parameter, it is also generally allowed to use a reference as, for example, parameterType
on another ParameterDeclaration
.
Using a parameter reference in the name
field of another parameter declaration is allowed.
But it is strongly advised not to do such chaining of parameters or mutual referencing, as this can easily lead to deadlocks.
The assignment of values to parameters declared in a Catalog
is allowed in a CatalogReference
.
There is a type inference check defined by the standard, which ensures that the parameterType
matches. The check is not ensured by the XML validator and therefore must be implemented by the simulator.
Parameter values are evaluated and set at load time of the simulation. They cannot be changed during runtime. Therefore, the evaluation result of a ParameterCondition
is determined in the first step cycle of a simulation and does not change during runtime. Parameters can be used to configure if an action shall be executed or not for different concrete scenarios.
Parameter names starting with OSC are reserved for special use in future versions of ASAM OpenSCENARIO. Generally, the OSC prefix shall not be used.
These naming rules apply to parameters:
-
All parameter names must begin with a letter of the alphabet (a-z, A-Z) or an underscore (_).
-
After the first initial character, names can also contain numbers (0-9).
-
Parameter names are treated case-sensitive.
The parameter name must match the regular expression [A-Za-z_][A-Za-z0-9_]*.
Special rules apply to referencing parameters within a Catalog
(see Section 9.5, "Parameters in catalogs").