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:
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
Navigation
FloorplanVariation
Creates floorplan variations from variation files and generates corresponding map and mesh files.
Expected parameters:
scenario / sim: slot -> destination for the map and mesh slots, e.g.
scenario: {map: map_file} and sim: {mesh: components.floorplan.mesh}. The retired
positional name: [map_param, mesh_param] is refused.
variation_files: List of variation files to use for floorplan generation
(must contain at least one file).
num_variations: Number of floorplan variations to generate (minimum 1).
seed: Seed for random number generation to ensure reproducibility.
mesh_format (optional): 3D mesh format to produce, stl (default) or obj.
laser_height (optional): height (m) the occupancy grid is sliced at. Unset leaves
scenery_builder’s 0.7 m; a TurtleBot 4’s scanner sits at 0.2 m, and the two produce
materially different maps.
Generated outputs:
Map YAML file (maps/*.yaml)
Map PGM file (maps/*.pgm)
3D mesh file (3d-mesh/*.stl or 3d-mesh/*.obj)
Outputs
This variation writes several values, so a campaign binds each output slot to a channel and a destination:
scenario: {map: <parameter the scenario declares>}
sim: {mesh: <key of the simulator backend>}
Slots: map, mesh.
Every slot must be bound, each to exactly one channel.
FloorplanGeneration
Generates artifacts (maps and 3D meshes) from existing floorplan files without creating variations.
Unlike FloorplanVariation which creates multiple variations from
.variation files, this processes .fpm floorplan files directly and
generates exactly one configuration per input floorplan.
Expected parameters:
scenario / sim: slot -> destination for the map and mesh slots, e.g.
scenario: {map: map_file} and sim: {mesh: components.floorplan.mesh}. The retired
positional name: [map_param, mesh_param] is refused.
floorplans: List of paths to .fpm floorplan files to generate artifacts
for (must contain at least one file).
Generated outputs:
Map YAML file (maps/*.yaml)
Map PGM file (maps/*.pgm)
3D mesh file (3d-mesh/*.stl or 3d-mesh/*.obj)
Example:
- FloorplanGeneration:
name:
- map_file
- mesh_file
floorplans:
- floorplans/rooms/rooms.fpm
- floorplans/hallways/hallways.fpm
Outputs
This variation writes several values, so a campaign binds each output slot to a channel and a destination:
scenario: {map: <parameter the scenario declares>}
sim: {mesh: <key of the simulator backend>}
Slots: map, mesh.
Every slot must be bound, each to exactly one channel.
PathVariationRandom
Generates random navigation paths with multiple waypoints between start and goal poses.
Outputs (bound by the campaign, see PathVariationRandomConfig):
- PathVariationRandom:
scenario: {start: start_pose, goal: goal_poses}
path_length: 15.0
num_paths: 1
num_goal_poses: 4
min_distance: 1.0
seed: 42
robot_diameter: 0.35
Expected parameters:
num_goal_poses: Number of goal poses to generate per path.
path_length: Target path length in meters.
num_paths: Number of different paths to generate.
min_distance: Minimum distance between consecutive waypoints in meters.
map_file: Optional map file path (uses scenario default if omitted).
path_length_tolerance: Acceptable deviation from target path length in meters
(default: 0.5).
seed: Random seed for reproducible generation.
robot_diameter: Robot diameter for collision checking in meters.
Behaviour:
Generates sequential waypoints with target distances between them.
Validates path length within the specified tolerance.
Writes one pose or a list to goal according to how the scenario declares that
parameter (pose_3d versus list of pose_3d).
Uses path caching for performance optimization.
Outputs
This variation writes several values, so a campaign binds each output slot to a channel and a destination:
scenario: {start: <parameter the scenario declares>}
sim: {goal: <key of the simulator backend>}
Slots: start, goal.
Every slot must be bound, each to exactly one channel.
ObstacleVariation
Places random obstacles in the environment based on configured obstacle types.
The obstacles are placed along the route the robot drives, so the trial’s start and goal
are read through the start and goal input slots. A path variation ahead of this one
supplies them, and so does a campaign that states them in its own parameters: block –
with no path to inherit, the placement plans one itself.
Expected parameters:
reads (optional): Which parameter each input is read from, as
{start: <parameter>, goal: <parameter>}. Needed only where no earlier variation wrote
the slot – otherwise the name that variation bound is inherited. The goal parameter
may hold one pose or a list of them, whichever the scenario file declares.
obstacle_configs: List of obstacle configurations, each containing:
amount: Number of obstacles to place. Mutually exclusive with
amount_per_m.
amount_per_m: Obstacles per meter of path length (computed as
floor(amount_per_m × path_length)). Accepts a single float or a list of
floats — each value produces a separate variation. Mutually exclusive with
amount.
max_distance: Maximum distance from the path for obstacle placement.
Accepts a single float or a list of floats — each value produces a separate
variation.
model: Model name/path for the obstacle.
xacro_arguments: Arguments to pass to xacro for model generation. {size[i]}
placeholders are substituted from size, so the extents are stated once and the
argument names stay with the model file that defines them.
size: Extents in meters ([x, y, z] for a box). Required when the instances
slot is bound, i.e. when a simulator has to compile the placement rather than spawn it.
shape: What the obstacle is, for that simulator. box (default).
entity_prefix (optional): stem of the generated entity names, obstacle by
default. Give two populations in one campaign distinct stems.
seed: Seed for random number generation to ensure reproducibility.
robot_diameter: Diameter of the robot for collision checking.
map_file: Optional map file path (can be omitted if provided by a previous
variation).
count: Number of obstacle configurations to generate (default: 1).
Generated outputs:
Outputs
This variation writes several values, so a campaign binds each output slot to a channel and a destination:
scenario: {objects: <parameter the scenario declares>}
Slots: objects.
Every slot must be bound, each to exactly one channel.
Inputs
This variation reads values an earlier variation wrote. Where one did, the name it bound is inherited and nothing need be said here. Where the campaign sets the value in its own parameters: block instead, reads: says which parameter holds it:
reads:
start: <the parameter it is read from>
goal: <the parameter it is read from>
Inputs: start, goal.
ObstacleVariationWithDistanceTrigger
Places exactly one obstacle at a position at least trigger_distance arc-length ahead of the robot’s start along the planned path.
Two scenario parameters are written for use in the scenario script.
Expected parameters:
reads (optional): Which parameter each input is read from, as
{start: <parameter>, goal: <parameter>} – see ObstacleVariation.
trigger_point (slot): receives the obstacle’s spawn
pose position.
trigger_threshold (slot): receives the trigger
distance value that was used.
trigger_distance: Arc-length in meters from the start to the obstacle.
Accepts a single float or a list of floats — one output configuration is produced
per value.
obstacle_configs: List of obstacle configurations (same format as
ObstacleVariation). Total amount across all entries must equal
exactly 1.
seed: Seed for random number generation to ensure reproducibility.
robot_diameter: Diameter of the robot for collision checking in meters.
map_file: Optional map file path (uses scenario default if omitted).
count: Number of obstacle configurations to generate (default: 1).
Generated outputs:
objects: Placed obstacle with spawn pose and model information.
trigger_point: Position of the placed obstacle.
trigger_threshold: The trigger distance value that was applied.
Example:
- 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.0, 0.3]
model: file:///config/files/models/box.sdf.xacro
xacro_arguments: width:=0.5, length:=0.5, height:=1.0
seed: 42
robot_diameter: 0.35
count: 2
Outputs
This variation writes several values, so a campaign binds each output slot to a channel and a destination:
scenario: {objects: <parameter the scenario declares>}
sim: {trigger_point: <key of the simulator backend>}
Slots: objects, trigger_point, trigger_threshold.
Every slot must be bound, each to exactly one channel.
Inputs
This variation reads values an earlier variation wrote. Where one did, the name it bound is inherited and nothing need be said here. Where the campaign sets the value in its own parameters: block instead, reads: says which parameter holds it:
reads:
start: <the parameter it is read from>
goal: <the parameter it is read from>
Inputs: start, goal.
PathVariationRasterized
Creates route variations covering all areas of the map using a square grid rasterization.
Generates paths between raster points that meet specified path length criteria.
Expected parameters:
raster_size: Grid spacing between raster points in meters.
path_length: Target path length in meters.
robot_diameter: Robot diameter for collision checking in meters.
start_pose: Optional start position as parameter reference (@start_pose)
or direct pose with x, y, yaw. If omitted, all valid raster points
are used as potential start poses.
num_goal_poses: Number of goal poses per path (default: 1).
Single goal mode uses grid-to-grid paths; multi-goal mode uses a search radius
algorithm.
map_file: Optional map file path (uses scenario default if omitted).
raster_offset_x: X-axis offset for grid alignment in meters (default: 0.0).
raster_offset_y: Y-axis offset for grid alignment in meters (default: 0.0).
path_length_tolerance: Acceptable deviation from target path length in meters
(default: 0.5).
Behaviour:
Creates a square grid covering the entire map area, filtering points in obstacles
or too close to walls.
Single goal mode (num_goal_poses: 1): Generates paths from each valid
raster point to every other valid raster point for comprehensive coverage testing.
Multi-goal mode (num_goal_poses > 1): Calculates search radius as
(path_length / raster_size) / (num_goal_poses + 1) and generates multiple
waypoints per path.
Respects robot diameter for collision checking; grid alignment is controlled by
the offset parameters.
Generated outputs:
Outputs
This variation writes several values, so a campaign binds each output slot to a channel and a destination:
scenario: {start: <parameter the scenario declares>}
sim: {goal: <key of the simulator backend>}
Slots: start, goal.
Every slot must be bound, each to exactly one channel.
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.