Variation Points

A campaign varies three things. An experiment has three parts, and each is a configuration surface with an owner and a schema – which is what lets a factor’s destination be checked before any compute is spent, and what decides which channel a value belongs to.

Channel

What it varies

Owned by

Checked against

scenario:

the trial – what happens during the run

scenario-execution

the parameters the .osc declares

sim:

the world – what the trial runs in

the simulator backend

the backend’s schema and the world itself

sut:

the system under test – how the stack is configured

the stack

the config file the campaign declares

One configuration: block can use all three:

execution:
  containers:
    sut:
      config_files:
        nav2: files/nav2_params.yaml        # format inferred from the extension
        bt:   files/nav2_bt.xml

configuration:
- name: three-aspects
  variations:
  - ParameterVariationList:
      sim: components.floorplan.floor.friction     # the world
      values: [0.6, 1.4]
  - ParameterVariationList:
      sut: nav2.local_costmap.local_costmap.ros__parameters.inflation_layer.inflation_radius
      values: [0.30, 0.55]                          # the system under test
  - ParameterVariationList:
      scenario: goal_pose                           # the trial
      values: [...]

Choosing between them is one question: who owns the schema this value is checked against? A key in a file the stack reads is sut:; a value the .osc declares and acts on – including what it passes to ros_launch – is scenario:; a value the simulator’s configuration declares is sim:.

That last point is worth stating because the boundary is not enforceable. A stack parameter can be declared in the .osc and written into the stack’s file at run time, and RoboVAST cannot tell that such a parameter is stack configuration rather than trial protocol. It is a rule you follow, not one you are stopped from breaking – and the cost of breaking it is that the value is checked by nobody, because the surface it belongs to was never consulted.

See the destination reference for the full rules, and the sut channel for what a config source is and how a format addresses one.

The variation types below are available by default.

General

ParameterVariationList

Creates configurations from a predefined list of parameter values.

Expected parameters:

  • scenario or sim: the destination this variation writes – a scenario parameter name, or a dotted key of the simulator backend. Either may be a list of destinations for simultaneous multi-parameter variation.

  • values: List of values for the parameter. When the destination is a list, each entry must itself be a list of values — one per destination.

Example (a scenario parameter):

- ParameterVariationList:
    scenario: robot_radius
    values:
    - 0.175
    - 0.22

Example (the simulator’s world, and a value inside it):

- ParameterVariationList:
    sim: config
    values:
    - world/depot_nav2.yaml
    - world/warehouse_nav2.yaml
- ParameterVariationList:
    sim: components.floorplan.floor.friction
    values: [0.6, 1.4]

Example (several destinations varied together):

- ParameterVariationList:
    scenario:
    - mesh_file
    - map_file
    values:
    - - environments/office/office.stl
      - environments/office/office.yaml
    - - environments/hospital/hospital.stl
      - environments/hospital/hospital.yaml

values includes a bare-string member, so a string-valued factor is written the obvious way — values: [world/depot.yaml, world/warehouse.yaml]. Without it, values: ["False"] is coerced to the boolean False and hands a bool to a parameter the scenario declares as string, leaving the nested-list form below as the only way to vary a string. With str in the union pydantic matches the exact type instead, so a quoted value stays a string.

The multi-destination form is the way to fix several values at one level without multiplying the configuration count:

- ParameterVariationList:
    scenario: [sim_launch_package, sim_launch_file, headless]
    values:
    - ["nav2_bringup", "tb4_simulation_launch.py", "False"]

Outputs

This variation writes one value. Name its destination with exactly one of scenario: (a parameter the scenario file declares) or sim: (a key of the simulator backend, or a path under its dotted root):

scenario: <parameter>
# or
sim: <backend key or path>

ParameterVariationDistributionUniform

Creates configurations with random parameter values from a uniform distribution.

Expected parameters:

  • scenario or sim: the destination this variation writes – a scenario parameter name, or a dotted key of the simulator backend

  • num_variations: Number of configurations to create

  • min: Minimum value for the parameter

  • max: Maximum value for the parameter

  • type: Data type of the parameter (e.g., int, float, string)

  • seed: Seed for random number generation to ensure reproducibility

Outputs

This variation writes one value. Name its destination with exactly one of scenario: (a parameter the scenario file declares) or sim: (a key of the simulator backend, or a path under its dotted root):

scenario: <parameter>
# or
sim: <backend key or path>

ParameterVariationDistributionGaussian

Creates configurations with random parameter values from a Gaussian (normal) distribution.

Expected parameters:

  • scenario or sim: the destination this variation writes – a scenario parameter name, or a dotted key of the simulator backend

  • num_variations: Number of configurations to create

  • mean: Mean value for the parameter

  • std: Standard deviation for the parameter

  • min: Minimum value for the parameter

  • max: Maximum value for the parameter

  • type: Data type of the parameter (e.g., int, float, string)

  • seed: Seed for random number generation to ensure reproducibility

Outputs

This variation writes one value. Name its destination with exactly one of scenario: (a parameter the scenario file declares) or sim: (a key of the simulator backend, or a path under its dotted root):

scenario: <parameter>
# or
sim: <backend key or path>

OneOfVariation

Branches the configuration pipeline by running each child variation independently on a copy of the current configurations.

All resulting branches are concatenated into a single flat list. This enables “one of N alternatives” semantics: every alternative becomes a separate configuration in the downstream pipeline.

Expected parameters:

  • variations: List of child variation entries, using the same syntax as the top-level variations: list.

Example:

- OneOfVariation:
    variations:
    - ObstacleVariation:
        scenario: {objects: static_objects}
        obstacle_configs:
        - amount: 3
          max_distance: 0.3
          model: file:///config/files/models/box.sdf.xacro
        seed: 42
        robot_diameter: 0.35
        count: 2
    - ObstacleVariationWithDistanceTrigger:
        scenario: {objects: dynamic_objects,
                   trigger_point: spawn_trigger_point,
                   trigger_threshold: spawn_trigger_threshold}
        trigger_distance: [1.0, 2.0]
        obstacle_configs:
        - amount: 1
          max_distance: 0.3
          model: file:///config/files/models/box.sdf.xacro
        seed: 42
        robot_diameter: 0.35
        count: 2

Showing what a variation produced

A variation that places something — obstacles at poses, a planned path, a start and a goal — can say so, and the Config tab’s config view draws it. Answer config_view_data() with neutral geometry:

from robovast.common.scene_markers import ConfigViewContribution, SceneMarker

class MyVariation(Variation):

    @classmethod
    def config_view_data(cls, config, base_path):
        placed = config["config"][config["_objects_parameter_name"]]
        return ConfigViewContribution(
            markers=[SceneMarker(kind="box", pos=[o.x, o.y], size=[0.5, 0.5, 1.0])
                     for o in placed],
            files={"map": config["config"].get("map_file", "")},
        )

Geometry, not domain vocabulary. A marker is a box at a pose, never “an obstacle” — which is what lets the 3D scene, the 2D map and anything added later all draw a variation they have never heard of. The kinds are box, cylinder, sphere, pose, path and point; each carries an optional label, color and group (markers sharing a group are shown and hidden together, and it defaults to the variation’s own name). A marker with no geometry for its kind is refused rather than drawn as nothing.

files names workspace-relative paths a panel may need — {"map": …} is what the map2d panel binds. Named rather than positional, so a variation with no map is simply missing the key. Return the relative path: the browser fetches it through the workspace, and an absolute path from the host that composed means nothing there. A campaign with no map-producing variation is not stuck: the panel also takes a map: path declared on it in the .vast (see The config view), which is the route for a map that is checked in.

Two properties worth knowing:

  • It is a pure function of the resolved configuration, called after composition. It must not re-run the variation or touch the filesystem — which is what lets the answer be recomputed for whichever configuration the reader clicks, instantly, with nothing composed again.

  • A hook that raises is reported, named, in the view, and the other variations still draw. A view that quietly lost one variation’s markers would be indistinguishable from a variation that placed nothing.

This replaces the desktop editor’s GUI_CLASS / GUI_RENDERER_CLASS, where a variation shipped a Qt widget and drew onto it imperatively. That tied every variation to one toolkit and one 2D projection; returning data instead is what lets one contribution serve every panel. robovast_nav’s port lives in robovast_nav/config_view.py.