Configuration
This page documents all available parameters in the .vast configuration file format. The configuration file is written in YAML and defines all aspects of the RoboVAST workflow.
File Structure
A .vast configuration file has the following top-level structure:
version: 4
extends: common/base.vast # optional; see Extends
metadata:
title: "Project Title"
description: "Project description"
...
plugins:
- my_plugin==1.2.3
configuration:
- name: scenario1
...
execution:
...
analysis:
...
Version
Type: Integer
Required: Yes
Specifies the version of the configuration file format. A file you are authoring may declare only the current one:
version: 4
An older version is migrated forward rather than refused:
a campaign’s archived
_config/*.vastis upgraded in memory whenever it is read, so an old campaign can still be displayed, imported and re-run. That file is never rewritten – it is the record of what its author wrote.a file you are authoring is upgraded in place by
vast configuration upgrade, which preserves comments.
A newer version is refused: a format from a later robovast cannot be migrated backwards,
so the answer is to upgrade robovast. See src/robovast/common/migrations/README.md for
the ladder itself and for when the version is bumped at all.
Note
A key stated twice in one mapping is refused, naming both lines. YAML keeps the last of the two, so the losing block stays in the file, still reads as the configuration, and is applied to nothing – a campaign that runs, reports every cell normally, and was configured by something nobody wrote.
It is reachable by ordinary means rather than by typing a key twice on purpose: a block
indented at a list’s level belongs to the entry above it, so a sut: or parameters:
block written after one configuration’s body and before the next one’s - name: silently
replaces the block of the entry before it.
Anchors and <<: merge keys are unaffected – an explicit key overriding a merged one is
what a merge is for. Reading an archived campaign is not refused either: it already ran,
with the value a repeat keeps, and that is the value read back, with a warning saying so.
Extends
Type: String (a path)
Required: No
Another .vast this campaign is built on. Campaigns that differ in a few lines are
otherwise written by copying a neighbour, and what drifts afterwards is never the part anyone
meant to change – a container’s resources, a postprocessing step, a dashboard.
# common/nav2-base.vast -- no version, no execution: it is a fragment, not a campaign
execution:
containers:
simulation: {backend: roqsim, resources: {cpu: 1.0, memory: 6Gi}}
sut: {image: "family:robovast", resources: {cpu: 4, memory: 6Gi}}
runs: 5
version: 4
extends: common/nav2-base.vast
execution:
containers:
sut: {resources: {cpu: 8}} # memory: 6Gi is inherited
Mappings merge at every depth; lists and scalars are replaced. That is the rule to hold on
to, and the one you meet first: you cannot add one panel, one postprocessing step, one
run_files pattern or one configuration: entry – a list is inherited whole or restated
whole. Appending cannot be the default and still be undone, because a campaign that meant to
replace a list would silently run both.
A base may extends: a base in turn. Each link overrides the one beneath it, and a cycle is
refused naming the chain.
A base is a fragment, and is never validated on its own. It usually has no execution:,
which the schema requires, so only the merged document is a campaign. For the same reason
every relative path resolves against the campaign’s directory, not the base’s: a base is
part of its child rather than a document in its own right.
A base must live under the campaign’s project directory – beside it, in a subdirectory,
anywhere below it. There is no rule about which, and no marker key or second file extension: a
.vast another one extends is a base because something extends it. The containment rule is
the one that matters, because only the project directory is copied into a service workspace,
so a base outside it is simply absent wherever the campaign is not run from this tree; it is
refused rather than warned about, since a base is the campaign.
Resolution is total and happens when the file is loaded, so nothing downstream knows the key existed. Two consequences worth knowing:
A configuration’s identity does not change. It is hashed from the resolved block, so moving an existing campaign onto a base leaves every
config_identifieras it was and its results stay comparable with what it produced before.The archive keeps both.
_config/mirrors the project tree, so the campaign and every base it was built on are stored at the paths the author gave them, and a campaign reconstructed from its results still says what it said. Which of those files is the campaign is recorded in_config/.campaignrather than guessed at.
A base does not make a workspace ambiguous: with several .vast files, the ones others
extend are not candidates to launch. A file nothing extends still is – an orphan cannot be
told from a second campaign – so extending a sibling campaign works but is worth avoiding:
editing a campaign that others inherit from silently changes them, where a base extracted for
the purpose says what it is.
Metadata Section
Type: Dictionary
Required: No
The metadata section allows you to provide structured information about the run configuration. This section can contain arbitrary key-value pairs and nested structures. If present, the metadata will be included in the generated configurations.yaml file.
metadata:
title: "Robot Navigation Results"
description: "Autonomous navigation performance evaluation"
creator: "Your Name"
keywords: ["robotics", "navigation", "ROS2"]
license: "CC-BY-4.0"
custom_fields:
nested_data: "value"
All fields within metadata are optional and can be customized according to your needs.
Note
Campaign directory naming: if metadata.name is set, it is used as
the prefix for the campaign output directory:
<name>-YYYY-MM-DD-HHMMSS (e.g. navigation-evaluation-2026-03-10-142530).
When metadata.name is omitted the prefix defaults to campaign
(e.g. campaign-2026-03-10-142530).
Plugins Section
Type: List of strings
Required: No
The plugins section declares the Python plugin packages this campaign needs.
Two kinds of plugin resolve from it: variation types not built into robovast /
robovast-nav (for example the scenario_mt metamorphic types), and
postprocessing plugins — an entry-point postprocessing command, or the
third-party dependencies a local ./file.py:Class postprocessing plugin imports.
Each entry is a pip requirement specifier, in one of three
forms:
plugins:
# 1. published on a package index — pin the version
- my_plugin==1.2.3
# 2. a git repository — pin a ref (branch, tag, or commit)
- scenario_mt @ git+https://github.com/org/scenario_mt@main
# 3. a wheel you uploaded into this project — a workspace-relative path
- ./plugins/my_plugin-1.0.0-py3-none-any.whl
The packages are installed into a virtual environment under .robovast_plugins/
(next to your .vast for a workspace, or inside the campaign for a re-run), together
with their dependencies, and put on sys.path before the variations are composed — so
the variation type names resolve — and again before postprocessing runs, so postprocessing
plugins and their dependencies resolve (including on a re-run in a fresh process after a
service restart).
The install is resolved against robovast’s own environment, so anything the host
already provides is satisfied rather than reinstalled, and only what is genuinely missing
lands in the workspace. One consequence is worth stating: your plugin should not declare
a dependency on robovast. A plugin is loaded into robovast’s process, not installed
beside it, so the host always provides it — and an installer that ignored what was already
present would give the workspace a second copy of robovast, whose entry points would then
be the only ones the process could see. validate_project reports the declaration if it
finds it.
The directory does not travel: it is excluded from workspace pushes and from image build contexts, and it is rebuilt wherever a campaign is composed.
Note
Private git repositories. A git+https URL to a private repository needs
credentials. Provide a GitHub token at deployment time — set ROBOVAST_GIT_TOKEN
(or GITHUB_TOKEN / GH_TOKEN) in your project’s .env file (or the
environment) when you run vast cluster setup or
vast service upgrade; it is stored as a Kubernetes Secret, and removing
the variable and upgrading again deletes it.
That one token serves both places a private repository is reached, so there is
nothing per-project to configure: the service uses it to clone a top-level
plugins: entry, and a container’s python_packages git spec installs with it
inside the image build (as a BuildKit secret — mounted for the install step only,
so it is in no image layer and no build history, and no .vast ever carries a
credential).
One token covers every repository its account can read; nothing has to be declared per repository. It is reachable by any build this deployment runs, so prefer a read-only, org-scoped fine-grained PAT over a personal classic one:
go to GitHub → Settings → Developer settings → Fine-grained tokens;
Generate new token;
set Resource owner to your organization — not your personal account, or the token cannot see the organization’s repositories;
choose All repositories, or select the ones the campaigns install from;
set Contents to Read-only — nothing here writes;
generate it and store it securely; put it in
.envas above.
Check it before deploying, because the failure mode is misleading — a fine-grained
token returns 404 Not Found for a private repository it was not granted, and
git reports Write access to repository not granted for what is only a read
it may not do:
GH_TOKEN=<token> gh api repos/<org>/<repo> -q .full_name
A missing token fails before the build, when the ref is resolved to a commit:
cannot resolve … the repository needs credentials this deployment does not have.
Alternatively, upload a pre-built wheel into the project and reference it by its
workspace-relative path (form 3 above) — this needs no credentials at all.
Tip
For a single, dependency-free custom variation you do not need to package it: put
the .py file in your project and reference the class directly from a
variations entry as relative/path.py:ClassName (see Variation Points).
The module is archived with the campaign and hashed into its config identity, so such a
variation stays re-runnable — but it has to be one self-contained module, with no
sibling imports and no data file of its own. Anything larger belongs in plugins:.
Configuration presets
Type: Mapping of preset name → configuration body
Required: No
Reusable configuration bodies, composed by a configuration entry’s use:. A factorial
design is then written as its axes rather than as its cross product – a robot, a stack and a
trial are three presets, and each cell names the three it is:
configuration_presets:
robot-tb4:
parameters:
scenario: {description_package: nav2_minimal_tb4_description}
sim: {config: world/nav2.yaml}
stack-bringup:
parameters:
scenario: {params_file: files/nav2/nav2_params.yaml}
sut: {bringup.bt_navigator.ros__parameters.default_nav_to_pose_bt_xml: /config/files/bt.xml}
configuration:
- name: bringup-mppi-tb4
use: [robot-tb4, stack-bringup]
parameters:
sut: {bringup.velocity_smoother.ros__parameters.max_velocity: [0.306, 0.0, 1.9]}
A preset carries exactly what a configuration carries, minus what belongs to one
configuration: it may not set name:, and it may not use: another preset. Presets do
not nest – one flat level is what keeps “read the entry and the presets it names” a complete
account of what a configuration runs, and sharing presets between files is what
extends is for.
Do not reach for YAML merge keys instead. <<: is shallow, so where several presets
contribute to one subtree – three of them writing parameters.scenario, say – all but the
first are dropped with no error, and the campaign runs its full sweep against values nobody
wrote.
Precedence
Four layers, lowest to highest:
preset parameters < parameters < preset variations < variations
Two axes rather than four rules: preset before entry, and fixed before variation. Within a
layer, presets apply in use: order. The second axis is not new – a variation has always
won over the fixed value it varies – so presets split each existing layer in two and change no
existing precedence.
Overriding a preset is the ordinary case and is silent: the entry is more specific than the
axes it composes, and the override is visible where the reader is already looking.
{$absent: true} works there too, so an entry can delete a key a preset set.
The consequence worth knowing, because it will surprise someone: an entry’s ``parameters:`` does not beat a preset’s ``variations:``. To override a preset’s sweep, declare your own variation on that destination, which replaces the preset’s rather than crossing with it.
What is refused
a
use:naming a preset the file does not define, listing the ones it does;two presets writing one destination – which of them won would be decided by the order of a list two lines away, and the losing write is recorded nowhere. Set it in the configuration itself, which wins over every preset, or split the presets so one owns the destination.
sim:is compared on the flattened path, so the nested and dotted spellings of one destination collide as they should;two presets sweeping one destination, which is a factor crossed with itself;
name:oruse:inside a preset, and a preset named twice in oneuse:.
A preset that is never used is reported and not refused: vast configuration
export-configs copies the whole document and replaces only configuration:, so refusing
would turn a working command into one that emits files nothing can load.
Presets are resolved when the file is loaded, so nothing downstream sees them, and a
configuration’s identity is hashed from the resolved block – rewriting a campaign onto presets
leaves every config_identifier unchanged and its results comparable with what it produced
before.
Configuration Section
The configuration section defines which runs are to be executed. It is a list where each
entry represents a scenario. An entry states which presets it is built from (use:), the
fixed values it writes (parameters:, grouped by channel), and how those values are swept
(variations:).
Scenario Definition
Each scenario in the configuration list has the following structure:
name
Type: String
Required: Yes
A unique identifier for the scenario. This name will be used as the directory name for results. It must be lowercase and must not contain underscores, spaces, or periods (use hyphens instead).
configuration:
- name: test-scenario-1
parameters
Type: Dictionary of channel → values
Required: No
The fixed values this configuration writes, applying to all of its runs, grouped by the :ref:`channel <config-variation-destination>` they land in. One grammar for all three, so which channel a value goes to is said by the key it is under and never by the shape that key happens to have:
configuration:
- name: test-fixed
parameters:
scenario: # what the trial does: parameters the .osc declares
growth_rate: 0.07
initial_population: 123
goal_pose: {position: {x: 10.0, y: 5.0}}
sim: # what it runs in: nested, against the backend's schema
overrides: {components: {ceiling: {enabled: false}}}
sut: # how the stack is configured: FLAT <source>.<path> keys
nav2.local_costmap.local_costmap.ros__parameters.inflation_layer.inflation_radius: 0.55
scenario: names are checked against the ones the scenario file declares, so a parameter no
scenario has is refused rather than passed to nobody.
parameters and variations compose: these are the fixed base
of every cell, and a variation writing the same destination wins over the value here.
variations
Type: List of variation definitions
Required: No
Defines parameter variations to create multiple run configurations. Each variation uses a plugin-provided variation type. See Variation Points for available variation types.
Multiple variations are combined using Cartesian product to generate all possible parameter combinations.
Every factor names where it lands, with exactly one of three keys — scenario: for a
parameter the scenario file declares, sim: for the simulator’s own configuration,
sut: for a configuration file the system under test reads:
configuration:
- name: test-variations
variations:
- ParameterVariationList:
scenario: speed
values:
- 1.0
- 2.0
- 3.0
- ParameterVariationList:
sim: components.floorplan.floor.friction
values:
- 0.6
- 1.4
- ParameterVariationList:
sut: nav2.local_costmap.local_costmap.ros__parameters.inflation_layer.inflation_radius
values:
- 0.30
- 0.55
This example creates 3 × 2 × 2 = 12 run configurations.
The three keys sit at the same level and none is a default, so a factor’s destination is
readable from the line it is written on — and each is checked against the right schema: a
scenario: name against the scenario file’s declared parameters, a sim: key against
the simulator backend’s, a sut: destination against the config file the campaign
declared. See the simulation channel and the sut channel for what can go on the second and third.
Which channel a value belongs to is one question: who owns the schema it is checked
against? A key in a file the stack reads is sut:. A value the .osc declares and
acts on is scenario: — including a launch argument, because the scenario owns the
launch invocation and there is no file to address. A value the simulator’s own
configuration declares is sim:.
Warning
``scenario:`` and ``sut:`` overlap, and nothing validates the boundary. A stack
parameter can be declared in the .osc and written into the stack’s file at run time,
and RoboVAST cannot tell such a parameter from trial protocol — the scenario file
accepts any parameter it declares, whether or not the stack has a matching key. So this
is a rule you follow rather than one you are stopped from breaking, and the cost of
breaking it is a value checked by nobody.
Note
name: is not a destination and is refused, naming the three keys that are. In a
.vast that still carries it, it means scenario:; one spelling per destination
is what keeps the commonest line in a .vast from having two.
Variations that produce several values
A generator does not produce a value — PathVariationRandom produces a start pose and
goal poses, FloorplanGeneration a map and a 3D mesh. Those plugins declare output
slots, and the same two keys take a slot to destination mapping:
- PathVariationRandom:
scenario: {start: start_pose, goal: goal_poses}
path_length: 15.0
num_paths: 1
- FloorplanGeneration:
floorplans: [environments/secorolab/secorolab.fpm]
scenario: {map: map_file}
sim: {mesh: components.floorplan.mesh}
The floorplan case is why a plugin may use both keys at once: nav2 reads the occupancy map at run time, while the simulator has to compile the mesh into its model — the two artifacts sit on opposite sides of the compile boundary, and no single key could say so.
Every declared slot must be bound; an unknown slot is refused naming the ones that exist. A plugin may also declare optional outputs — obstacle geometry for a simulator to compile is one — which are simply not produced when left unbound.
A slot may name a destination on more than one channel, for the case where one value is wanted on both sides of the compile boundary. A drawn start pose is the example: the simulator compiles the robot where the path begins, and the stack under test is told where that is — one pose, so the trial no longer has to move the robot itself once the run is going.
- PathVariationRandom:
scenario: {start: start_pose, goal: goal_pose}
sim: {start: components.robot.pose}
Both destinations are written from the one call, so they cannot disagree. Binding the second is optional and changes nothing for a campaign that leaves it out. Note what this is not: two outputs whose contents differ — an obstacle’s spawner arguments and its compiled geometry — remain two slots, because they are two values rather than one value in two places.
Variations that read what an earlier one produced
Some plugins consume a value rather than only producing one. ObstacleVariation places
obstacles along the route the robot drives, so it needs the start and the goals — which
PathVariationRandom produced a moment earlier, under whatever parameter names this campaign
chose. It declares those as input slots, and normally binds nothing:
- PathVariationRandom:
scenario: {start: start_pose, goal: goal_poses}
- ObstacleVariation:
scenario: {objects: static_objects}
The name travels with the configuration: the variation that wrote start recorded the
parameter it bound, and the one reading start takes it from there. Rename the parameter and
you rename it once, on the line that writes it.
A configuration that sets the value itself has no earlier variation to inherit from — the
poses are in its own parameters: block — so it says where to read them with reads::
- name: one-fixed-route
parameters:
scenario:
start_pose: {position: {x: -2.0, y: -0.5}}
goal_poses: [{position: {x: 2.0, y: 0.5}}]
variations:
- ObstacleVariation:
scenario: {objects: static_objects}
reads: {start: start_pose, goal: goal_poses}
There is no conventional name to fall back on: an input that nothing wrote and no reads:
names is refused before the campaign runs, saying which slot and both ways to satisfy it.
reads: also wins where it is given, so a configuration can read a parameter other than the
one a preceding variation wrote. Each plugin’s inputs are listed with it under
Variation Points.
Varying the system under test
How the stack is configured belongs to a configuration. Not per campaign, and not per run: repetitions of a configuration share one configuration of the stack, which is what makes them repetitions.
A container declares the files that configure it, and a sut: destination names one of
them plus a path inside it:
execution:
containers:
sut:
config_files:
nav2: files/nav2_params.yaml # inferred: yaml
bt: files/nav2_bt.xml # inferred: xml
rmw: {file: files/dds_profile.custom, format: xml} # inference cannot help
configuration:
- name: inflation-vs-recovery
variations:
- ParameterVariationList:
sut: nav2.local_costmap.local_costmap.ros__parameters.inflation_layer.inflation_radius
values: [0.30, 0.55]
- ParameterVariationList:
sut: bt.//RecoveryNode[@name='NavigateRecovery']/@number_of_retries
values: [2, 6]
A source name is unique across the campaign, even though it is declared on a container.
A destination names a source and nothing else, so the container it sits under says who
owns and reads that file rather than scoping its name — the sut role, or an ad-hoc
container beside it for a stack that runs in more than one. Two containers declaring the
same name is refused for that reason, naming both.
The pairing is one to one in both directions: two sources may not name the same file either. Each source is loaded, edited and written back as a whole document, so two names for one file produce two documents and one staged path — the second write replaces the first, and every destination on the losing source silently does nothing. A file has one spelling that works, so the second name is refused rather than picked.
A format owns its own path syntax. RoboVAST splits a destination once, on the first
., to find the source; everything after that goes to the file’s format untouched. So
the mapping formats take dotted keys — with [0] for a list index and ['a.b'] for a
key a dot would otherwise split, which a ROS parameter file needs for
qos_overrides./tf — and the XML format takes XPath. The predicate in the example above
is doing real work: that behaviour tree names three different nodes RecoveryNode, so
nothing without predicates could pick one.
Formats are plugins, under the robovast.sut_formats entry point, with yaml,
json and xml built in and registered through that same entry point. A stack
configured by something else needs a package, not a change here — see
Add a config format for the system under test.
The extension names the format; format: is for a file whose name does not. An
extension no registered format claims, with no format: beside it, is refused naming the
ones that are — never guessed at, because the bad case is not the file that fails to parse
but the one that parses into a document whose addresses are all wrong.
Varying structure, not only values. A value need not be a scalar, so replacing a whole list, mapping or subtree is the ordinary case and each level is written out:
- ParameterVariationList:
sut: nav2.local_costmap.local_costmap.ros__parameters.plugins
values:
- ["obstacle_layer", "inflation_layer"]
- ["obstacle_layer", "voxel_layer", "inflation_layer"]
Enumerating the levels rather than saying “append” is deliberate: it is what keeps the
.vast the single source of truth for the variation space. For XML the same move covers
adding and removing children, because a subtree carries its own.
Absence is the one level an assignment cannot express — a configuration block that is present and empty is not one that is absent, and stacks tell them apart. It is a value, usable both as a fixed setting and as a factor level:
configuration:
- name: no-voxel
parameters:
sut:
nav2.local_costmap.local_costmap.ros__parameters.voxel_layer: {$absent: true}
A per-configuration ``sut:`` block is flat, unlike sim:, and this is the one place
the two channels differ. Everything after the source name belongs to the file’s format and
may be an XPath, which no nested mapping can express — so a block is one string key per
destination, split exactly once.
What each configuration gets
A rewritten copy of every source it touched, staged under its own configuration
directory and mounted at /config/<path> — the declared path, exactly where the
campaign’s own copy would otherwise be. The campaign’s file is never modified, and it is not
staged beside the copy, so that path holds one file: the one belonging to the cell that is
running.
Beside them, <campaign>/<config>/_config/sut.config records the whole resolved block —
a record, not an input, mirroring what sim: writes to sim.config and scenario:
to scenario.config. The rewritten copies are what the cell runs; this is what a reader
consults to see which factor produced which value, without diffing two copies of a stack’s
configuration.
Two things are refused rather than left to go wrong quietly:
a source declared on the
simulationorscenariocontainer — their configuration is addressed bysim:andscenario:, and two channels addressing one surface is how they come to disagree;a destination on the
envcarrier naming a variable RoboVAST sets for itself (CAMPAIGN_IDand its siblings).execution.envrefuses these already; this carrier reaches the same environment by a different route, so it is guarded against the same set rather than becoming a way around the rule.
A source whose path would land on a file the run itself owns at /config — the
entrypoint, the scenario, a parameter document — is refused at composition, naming the set.
Only the mount root is contested; the run writes nothing into a subdirectory of it, so
nav2/scenario.config is a campaign’s own business.
A declared source is excluded from run_files staging, so exactly one copy of it
reaches the container. Campaigns stage their inputs with patterns (files/*.yaml to pick
up a map), and a source caught by one is not an author error to correct — but staging the
original beside the rewritten copy would leave which file the stack opens deciding whether
the campaign varied anything, and a run against unvaried configuration succeeds and reports
normally. With one copy, a scenario still naming the old path fails on a missing file
instead. The content still reaches the configuration’s identity, hashed separately, and the
original is archived in <campaign>/_config/ without being mounted — composition reads it
to write each copy, so a restart, a retrigger or a workspace rebuilt from the campaign needs
it there.
What is checked before anything runs
Every destination is resolved against the declared source and checked against the file
itself, at composition — the component that owns the schema is the one that says what is
addressable. A configuration’s fixed sut: block is checked exactly as a factor is: a
mapping format’s assignment creates the path it is given, so an unchecked misspelling
would write a key the stack never reads, in a cell that runs and reports normally.
What must exist is the parent: a factor may legitimately set a key the file leaves at its default, so refusing an absent leaf would reject a correct campaign.
A format that cannot decide (a malformed XPath, say) leaves that destination unchecked and says so at warning level. A skipped check is never silent, because silence is indistinguishable from a check that passed.
Each plugin’s slots, and whether they are required, are listed with it under Variation Points.
Note
The retired positional form (name: [map_file, mesh_file]) is refused. Which output a
list entry meant depended on remembering its position, and the plugins whose destination
names are chosen per campaign could not be described by it at all.
Note
parameters and variations may be given together for the same scenario, on every
channel: the fixed block is what the configuration starts from and a factor writing the
same destination wins over it. That is how a cell holds one thing fixed while sweeping
another.
sim
Type: Dictionary
Required: No
Fixed values for the simulator this configuration runs in, written under
parameters: beside the other two channels. scenario: is what the trial does; sim:
is what it runs in:
configuration:
- name: roofless
parameters:
scenario: {goal_pose: {position: {x: 10.0, y: 5.0}}}
sim:
overrides:
plugins: {ceiling: {enabled: false}}
A nested mapping against the backend’s own schema, merged over execution.containers.simulation — which stays the campaign-wide default. A world belongs to a configuration, never to a campaign and never to a single run.
sut
Type: Dictionary
Required: No
Fixed values for how the system under test is configured in this configuration — the
third channel’s sibling of parameters and sim:
configuration:
- name: no-voxel
sut:
nav2.local_costmap.local_costmap.ros__parameters.voxel_layer: {$absent: true}
A flat mapping of <source>.<path> to value, unlike sim: everything after the
source name belongs to that file’s format and may be an XPath, which no nested mapping can
express. Merged under any variation writing the same destination, and checked against the
declaring file exactly as a factor’s destination is. See the sut channel
for what a source is.
Execution Section
The execution section specifies how and where tests are executed.
containers
Type: Mapping of container name → container block
Required: Yes
Every container this campaign runs. One namespace, shared by the schema, by
exec_in_container(container=...) and by a scenario’s remote("ipc:///ipc/<name>"),
so a name means the same thing everywhere.
Three names have a defined meaning, and how many actual containers back them depends on the campaign — a caller never has to know which:
scenarioRuns scenario-execution. Every campaign has one.
simulationThe simulator. May be its own container, the same container as
scenario(a simulator stepped in-process by scenario-execution), or the same one assut(a stack that bundles its own simulator).sutThe system under test.
Any other key is an ad-hoc container and must state its own image (and normally
command) — only the known roles have a default.
execution:
containers:
scenario:
resources: {cpu: 8}
sut:
image: family:robovast
system_packages: [ros-jazzy-navigation2]
Note what is not there: the scenario container names no image. Which RoboVAST image a container needs follows from its role, and which registry it comes from belongs to the deployment — see Container images.
Every block takes the same keys:
imageWhat the container starts from. With no package keys that is also what it runs; with them, a derived image is built on top. There is no separate
base_imageand no author-chosen tag — the tag is the container’s name — so a campaign states what a container adds, never what it adds to.This field is for images of your own, and is used exactly as written — never reprojected or re-tagged. Omit it on
scenarioto get the RoboVAST framework image, which is the normal case; writefamily:<member>to base a container of yours on a RoboVAST image while still following the deployment’s project. Container images has the whole story.provenanceRequired when ``image`` is one RoboVAST neither built nor publishes. Two fields,
source(the repository or path holding the image’s build definition) andrevision(the commit that built it), plus an optionalbuild_recipefor a build that is not the obvious one.containers: sut: image: my-registry/experiment-sut:humble provenance: source: https://github.com/org/experiment-images revision: 4f2a1c9e8b7d6a5f4e3c2b1a0f9e8d7c6b5a4938 build_recipe: cd compose && docker compose build
Without it, validation and launch both refuse the campaign. That one field otherwise makes the whole campaign untraceable: nothing in its results could say what the image was, so it could never be re-run or audited — and the gap only surfaces once it is too late to ask. RoboVAST cannot derive this, which is why the author has to state it.
Not needed for anything RoboVAST can identify itself: an image it builds (you declared
system_packages,python_packagesorros_packages), afamily:reference, abuild:reference, a container with noimageat all, or a concrete reference to a published family member such asghcr.io/<project>/robovast-roqsim:latest.If you would rather not track this, declaring
system_packages/python_packagesand droppingimagelets RoboVAST build the container and record everything automatically.--allow-opaque-imagelaunches anyway and records the exemption on the campaign.system_packagesapt packages (
apt-get install -y).Rendered as a single
RUNabove everypython_packagesgroup, because a pip install may need what apt provides. So adding one entry here invalidates every python layer below it — including the large, stable group an author put first precisely to protect it. Worth knowing before the change rather than after: on one campaign here, adding a single ROS package cost ~350 s of rebuilding and re-exporting a torch layer that was otherwise cached. Settle this list early; it is not a place to iterate.python_packagesPython packages, as install groups. Same vocabulary as the top-level
plugins:field — an index pin (shapely>=2.0), a git URL (pkg @ git+https://host/repo@ref), an uploaded workspace wheel (./plugins/foo.whl) — plus a source directory relative to this.vast(packages/my_pkg), which works here because the build copies the project dir into the image build context.Each element is either a spec (a group of one) or a list of specs installed together in one pip pass, which is one image layer. If no element is a list the whole list is a single group — the common case, and the one where order does not matter at all, because pip sees every local wheel at once and resolves an inter-package dependency against its sibling instead of against PyPI. Nest as soon as you want to choose the layer boundaries: order of groups is install order, and is what the layer cache keys on. Put the large and stable first, the small and frequently-bumped last — a group that changes invalidates every group after it, so the ordering is the whole difference between a five-second rebuild and a five-minute one.
The grouping only pays off if the cached layers are still there when the next build asks for them, which is what the cache scope protects — see Caching in-cluster.
ros_packagesROS packages built from source — for the ones apt and pip cannot supply at all: a package with a
source:entry and norelease:block inros/rosdistrohas no Debian on any distro and no PyPI distribution (px4_msgsis one).Each entry is a repository (
git:) at a required, pinnedref:(a commit sha or a release tag — a branch is refused), with an optionalpackages:list to take part of a monorepo. Omitpackages:and every package the repo contains is built.containers: scenario: ros_packages: - git: https://github.com/PX4/px4_msgs.git ref: 598c7aad7b2386f9406ebd2a2f841619fddc3c78
Every entry is cloned into one workspace and built in one
colcon build, so an inter-repo dependency resolves against the sibling being built rather than against a Debian that does not exist — and colcon decides what a repo contains, plain CMake projects included. Declaring this key alone is enough to make RoboVAST build the image. Full story: ROS packages built from source.commandWhat the container runs. Omitted for the roles RoboVAST drives itself — the scenario runner, and a sidecar’s scenario-execution server (which is what makes it drivable from a scenario with
remote()). Required for an ad-hoc container.resourcescpu/memory, per container. See resources.backend``simulation`` only — a simulator backend, which supplies the image, packages, environment and start command so the campaign does not restate them. See Simulators.
A version-1 file spreads the same settings across four keys — execution.image,
execution.resources, execution.secondary_containers and a top-level build:
section — and the ladder’s first step folds all four into containers. Authoring requires
the current version, so such a file is refused there, with vast configuration upgrade and
a line naming what each of the four becomes; an archived campaign that carries them is
migrated in memory when it is read, and its file is left as its author wrote it.
The containers package keys are distinct from the top-level plugins: field:
plugins: installs variation-type packages into the composer (before config
generation), while these bake code and apt into a container (before execution). They
share the python_packages vocabulary but scope different environments.
runs
Type: Integer
Required: Yes (unless specified in CLI)
Number of times to execute each run configuration. Multiple runs allow for statistical analysis of results.
execution:
runs: 20
Behaviours and logs
Neither of these is configurable.
The behaviour tree is always logged, as behaviors.jsonl in each run directory. A run
whose tree state was not recorded cannot be explained after the fact; the file is small —
tens to a few hundred KB, beside a rosbag measured in MB — and not recording it also costs
the live answer, since get_job_state reads it to say which action a wedged run is stuck
in. There is no campaign worth paying that for.
The file is ingested into the behaviors table of the results index — one row per behaviour
status change, plus a full snapshot of the tree at timestamp 0 so branches that never
executed are still present. Each row carries parent_id and child_index (structure),
tip_id (which leaf determined an ancestor’s status) and osc_file/osc_line
(where in the scenario source the behaviour came from). The Run view’s scenario-tree panel
reads this table. See the scenario-execution documentation for the file format.
The entrypoint’s own recorder is fixed at /rosout and /clock, which is exactly
what the merged run_log needs: /rosout for the lines, /clock
for the sim↔wall mapping (each message’s receive time is wall and its content is sim — see
Wall → sim: the clock map). What a run records
beyond that is the scenario’s bag_record to say, where it sits beside the behaviour
producing it.
This is the infrastructure recording, deliberately separate from bag_record: it starts
with the container, so it sees the stack coming up before any scenario does, and it runs on
the wall clock. The scenario’s own bag is recorded with use_sim_time, so both of its
axes are sim and it cannot carry that relation at any price. ROS images only; ignored where
ros2 is not on PATH.
Note
The output directory keeps its historical name logs/rosout_bag: it is an address the
postprocessing map, the docs and every existing campaign already use.
An execution image whose scenario_execution predates --bt-log ignores the flag
rather than failing, so the run still succeeds — it simply produces no behaviors.jsonl
and no behaviors table.
runs_per_job
Type: Integer
Required: No (default: 1)
How many runs are packed into a single job. A run is one configuration executed at one run-number (one scenario execution); a job is one unit of dispatch — one Kubernetes Job.
1(default): each job runs exactly one run. Right for simulators where setup dominates and one job should be one scenario (e.g. Gazebo).> 1: up to N runs are packed into one job and run sequentially inside a single simulator setup, with the simulator reset between them. This pays the simulator setup cost once per job instead of once per run — a big win for simulators with cheap per-run cost (e.g. MuJoCo). Runs are packed config-major, so a configuration’s repeated runs stay together within a job.
Packing is invisible to results: every run’s output is always written to
<config>/<run>/ regardless of how runs were grouped into jobs (see
Output Structure).
An upper bound, not a target. A job holds one compiled world and one configuration’s
files, so runs only share a job when they agree about both, and
ceil(num_configs * runs / runs_per_job) is the count you get when they all do:
configurations resolving to different simulator settings are never packed together — the simulator compiles its model once per process, so the second cell would run against the first one’s geometry;
configurations that stage files of their own (a
sut:block, or a variation that generates one) are never packed with a different configuration — each cell’s copy is mounted at/config/<path>, and only one file can be there.
Neither restricts a configuration’s own repeated runs, which is what runs_per_job is
for, and a campaign that varies only scenario parameters is affected by neither.
execution:
runs_per_job: 200 # pack up to 200 runs per job (one sim setup)
shm_size
Type: String (e.g. 1Gi, 512Mi)
Required: No (default: 512Mi)
Size of the pod’s shared /dev/shm. One tmpfs is mounted into every container of
the run, which is what lets ROS 2’s default Fast DDS use its shared-memory transport across
the scenario / sut / simulation boundary. (Unix sockets do not use it — those
are a separate, disk-backed volume — so this sizes DDS traffic and any other POSIX shared
memory the run maps.)
Most campaigns should not declare it. RoboVAST gives every run 512Mi unless the
.vast says otherwise, which is what makes one file mean the same thing on every
cluster. Left to Kubernetes the default is a trap: /dev/shm is a memory-backed
emptyDir with no size limit, so it is sized from the pod’s memory limits — or, when no
container declares resources.memory, from the whole node. A container that overruns
shared memory dies of SIGBUS (exit 135), not a clean OOMKilled, so the death
arrives with no reason attached to it.
There is deliberately no way to ask for the platform’s own default — it is the thing this default exists to avoid. Declare a size only to raise or lower the reservation:
execution:
shm_size: 2Gi # only because this campaign measured a peak above the default
Picking the number. Do not guess it twice: every run records what the pool actually held, so a campaign that has run once says what its successor should declare.
SELECT MAX(shm_peak_bytes), MAX(shm_limit_bytes) FROM runs;
shm_peak_bytes is the high-water mark over every tick of the run, bring-up included — a
participant allocates its segments as it starts, and a SIGBUS there loses the run just as
completely as one mid-trial. shm_limit_bytes is the size that was in force, which is how a
declaration is checked rather than assumed: it shows whether the size in force reached the
mount. NULL in either means unmeasured — a
campaign recorded before the monitor sampled the pool, or a runtime without /dev/shm — and
is not the same answer as “used none of it”.
get_campaign_summary turns the same two numbers into advice (shm_under_reserved when
the peak outgrew the size in force, shm_over_reserved when the reservation is paying for
room nothing used), sized on the peak plus 25% headroom. A campaign that ran before
shm_size had a default reports shm_not_declared instead, because it really was handed
whichever default its runtime applied.
Note
Shared memory is not always used, and then there is nothing to tune. A single-container run, a middleware that is not DDS, and nodes co-located in one process all touch almost none of it — and Fast DDS falls back to UDP where shared memory is unavailable. A peak that fits inside Docker’s own 64 MiB default is left alone, so no advice is offered for it. The measurement is still recorded: a peak of nearly nothing is a real answer about the experiment.
timeout
Type: Integer (seconds)
Required: No
Maximum wall-clock time (in seconds) allowed for a single job — one unit of work,
which is one run unless runs_per_job packs several into it. The number is used exactly
as declared; it is not scaled.
A job is the granularity the cluster can actually enforce at, which is why the budget is
stated in it: Kubernetes caps a Job, and cannot stop an individual run inside a packed
one. The declaration sets activeDeadlineSeconds on the Job spec, so Kubernetes
force-terminates the Job (marking it DeadlineExceeded) when the deadline expires.
If omitted (or null), runs fall back to a backstop of 1 hour per run
(activeDeadlineSeconds = 3600 * runs_per_job) so a hung Job is always eventually
killed rather than hanging the campaign indefinitely. The backstop is per-run and therefore
scales with packing, where a declared budget does not — deliberately: an hour is a number
chosen in ignorance of the campaign, so a job of 100 runs must not be killed after the
first few, while a declaration is a statement about the job and is taken at face value.
stalled still needs a per-run figure, and derives one as timeout / runs_per_job.
A Job hard-killed on its deadline is logged with HARD-KILLED by activeDeadlineSeconds in the service log for later analysis.
execution:
timeout: 3600 # 1 hour for the job
scenario_file
Type: String (file path)
Required: Yes
Path to the OpenSCENARIO 2 scenario file (.osc), relative to the .vast configuration file. This defines the scenario to execute for all configurations.
execution:
scenario_file: scenario.osc
simulation
Type: String (module:Class)
Required: No
Simulation backend passed to scenario-execution as --simulation <module:Class>. Required by scenarios that use wait_for_simulation_end() (e.g. MagBotSim); omit it for ROS/Gazebo scenarios that bring their own simulation.
execution:
simulation: scenario_execution_magbotsim.push_box_simulation:PushBoxSimulation
A simulation backend can also be combined with the ROS runner (see mode below): when
mode: ros2 is set, the ROS runner ticks the SimulationInterface inside its spin loop, so a
step-based simulation runs alongside the ROS behaviours that drive it (a simulation that publishes
/clock becomes the time source).
mode
Type: String (auto | ros2 | base)
Required: No (default auto)
Selects which scenario-execution runner runs inside the container. auto keeps the entrypoint’s
detection: the ROS runner (scenario_execution_ros) when ros2 is on PATH, otherwise the
non-ROS scenario_execution CLI. ros2 forces the ROS runner. Forcing ros2 is needed when a
simulation (SimulationInterface) must run alongside ROS behaviours: only the ROS runner provides
rclpy for the ROS behaviours, and it also ticks the SimulationInterface in its spin loop.
base forces the non-ROS scenario_execution CLI even when ros2 is on PATH – use it
for pure non-ROS scenarios (e.g. configs/examples/growth_sim) so they skip the unneeded
ROS runner in an image that ships ROS.
execution:
mode: ros2
simulation: my_pkg.my_module:MySimulation
run_as_user
Type: Integer
Required: No
The user ID (UID) to run the container as; 1000 if not specified. If your container requires running as root, set this to 0.
execution:
run_as_user: 1000
pre_command
Type: String (path to executable script)
Required: No
Path to an executable script that will be sourced before each run. The file is executed using source <pre_command>, allowing environment variables to be set and made available to the scenario execution.
Important constraints:
Must be a path to an existing executable file
No command line parameters are allowed
The file is sourced (not executed in a sub-shell), so environment variable changes persist
execution:
pre_command: /config/files/pre_command.sh
run_files:
- "**/files/*.sh"
Command execution context:
Runs before the scenario execution via
source <pre_command>Can modify the container environment
Environment variables set by the script are available to the scenario
If the script fails (exits with non-zero), the run fails
Note
Custom scripts can be included in the container using run_files (see below) to make them available at the specified path.
post_command
Type: String (path to executable)
Required: No
Path to an executable file that should be executed after the scenario completes. This is passed to the scenario execution as the --post-run parameter.
Important constraints:
Must be a path to an existing executable file
No command line parameters are allowed
No shell commands or piping allowed
The file must have executable permissions
execution:
post_command: /config/files/post_command.sh
run_files:
- "**/files/*.sh"
The post command script is executed by the scenario execution framework after the scenario finishes, allowing for cleanup or post-processing tasks.
Note
Custom scripts can be included in the container using run_files (see below) to make them available at the specified path.
run_files
Type: List of strings (glob patterns)
Required: No
List of glob patterns specifying which files from the scenario directory should be copied into the run container. This is useful for including run-specific files like scripts, models, or configuration files.
execution:
run_files:
- "**/files/*.py"
- "**/models/*.sdf"
- "**/maps/*"
Note
Patterns are matched against the path relative to the ``.vast``, and * crosses
/ — so "files/*" also picks up files/scene/scene.json and
files/__pycache__/*.pyc. Since run files are content-hashed into the configuration
identity, a stray .pyc changes that identity; prefer per-extension patterns over a
blanket directory glob.
generate
Type: List of generator entries
Required: No
Campaign inputs that are derived rather than authored — a navigation map compiled from a floorplan, a browser scene descriptor compiled from a simulation world, a mesh converted from CAD. Building those with a side script the user must remember to re-run is the failure this replaces: the campaign starts happily against a stale or absent artifact, passes, and only the results look wrong.
Each entry is - <generator>: {out: <dir>, ...} — the same single-key shorthand
postprocessing uses. out is a directory relative to the .vast:
execution:
generate:
- shell:
out: files/scene
inputs: ["../worlds/depot.yaml"]
command: >-
roqsim-export-web --world {inputs[0]} --out {out}
--manifest {out}/.generated.json
Generation runs once per campaign preparation, before ``run_files`` are collected, and
the produced files are appended to run_files. So a generated file behaves exactly like a
hand-written one: it is frozen into <campaign>/_config/, bind-mounted into the run at
/config/<path>, and content-hashed into the configuration identity — a campaign run
against a changed world therefore gets a different identifier instead of silently reusing
the old one. Nothing needs listing twice; do not also add a run_files pattern for the
generated directory.
Staleness. A generator is skipped when nothing it read has changed. What it read is
reported by the generator itself, in a .generated.json manifest
({"inputs": ["<path>", ...]}) written into its output directory — which is why the
example passes --manifest. This matters more than it looks: the true dependency set of a
compiled world includes the worlds it inherits from and their meshes, and a hand-written
list goes stale the first time someone replaces one. Where a tool cannot report its inputs,
shell falls back to the declared inputs, and a generator that reports nothing at all
simply re-runs every time — staleness always fails towards doing the work.
Auxiliary containers. A generator whose tool is not installed alongside RoboVAST can run
in a container instead, so the service’s environment stops mattering. With shell, add
image; inputs are copied into the container’s workspace and results copied back, so
{out} and {inputs[i]} are valid paths inside it:
- shell:
out: files/maps
image: ghcr.io/secorolab/scenery_builder
inputs: ["floorplans/rooms.fpm"]
command: floorplan --input {inputs[0]} --output {out}
In a campaign this is a container in the campaign’s auxiliary pod; vast configuration
generate on a development machine runs it as an ephemeral docker run.
Note
command is expanded with Python’s str.format, so {out} and {inputs[i]}
are substituted and a literal brace must be doubled ({{ / }}) — relevant when
the command passes JSON or a shell parameter expansion.
A bare command name is looked up beside the interpreter composing the campaign
first, then on PATH. So a tool installed into the same environment as RoboVAST is
found with no PATH setup, and one that is missing is reported with both locations
named rather than as a bare “no such file”. Give an absolute path to bypass the search.
Failures are loud, always. An unknown generator, a missing declared input, a command
that exits non-zero, or one that reports success but writes nothing — each stops the
campaign with an error naming the entry, before any compute is spent. On failure the
previous contents of out are left untouched rather than half-overwritten, and
vast config validate reports all of it without starting a run.
Warning
Inputs outside the project directory work in place, but not from a workspace. Only
the project directory is copied into a service workspace, so a generator reading a
sibling checkout (../other_repo/world.yaml) composes fine when the campaign is run
from the tree and fails when the same .vast is started from a workspace — which is
how the service runs it. Validation emits a warning naming the path. Keep generator
inputs under the .vast’s own directory unless the campaign is only ever run in place.
shell is built in. Other generators come from installed packages (the
robovast.input_generators entry-point group) or from a ./path.py:Class file
reference next to the .vast — see Add Input Generator Plugin for writing one.
env
Type: List of dictionaries
Required: No
Additional environment variables to set in the run container. Each list item should be a single key-value pair.
execution:
env:
- RMW_IMPLEMENTATION: rmw_cyclonedds_cpp
- CUSTOM_VAR: custom_value
- ENABLE_X11: "false"
Names RoboVAST sets itself are refused. The run’s own protocol travels in the
environment — what identifies the campaign (CAMPAIGN_ID), where results are written
(OUTPUT_DIR, SCENARIO_OUTPUT_DIR, RUN_OUTPUT_DIR), what the runner executes and
with which parameters (SCENARIO_FILE, SCENARIO_PARAMETER_FILE,
SCENARIO_EXECUTION_PARAMETERS), and the credentials results are uploaded with
(S3_*). Setting one of these is refused when the campaign is validated, naming it.
The refusal is at validation and not left to the backend on purpose. Whether a campaign’s
value would actually displace RoboVAST’s depends on emission order and on the backend’s
duplicate-key semantics, so “it happens not to win today” is not something to build on —
and the failure it would cause is the quiet kind. Repointing SCENARIO_PARAMETER_FILE
gives a run that succeeds, reads parameters belonging to nothing, and reports its results
under the configuration’s name regardless.
Display and GPU hints — DISPLAY, LIBGL_ALWAYS_SOFTWARE, NVIDIA_* — are
deliberately not reserved. They steer how a container renders rather than whether its
results mean what they say, and a campaign running headless has a real reason to set them.
resources
Type: Dictionary, inside a container block
Required: No
CPU and memory limits, declared per container, which Kubernetes enforces. The
scenario container’s values are also exposed as AVAILABLE_CPUS and AVAILABLE_MEM
inside it.
execution:
containers:
scenario:
image: ghcr.io/cps-test-lab/robovast:latest
resources: {cpu: 2}
sut:
image: ghcr.io/cps-test-lab/robovast:latest
resources: {cpu: 3, memory: 4Gi}
simulation:
image: ghcr.io/cps-test-lab/roqsim-ros:jazzy
command: [roqsim, sim, worlds/depot.yaml, --ros, --headless]
resources: {cpu: 5, memory: 8Gi, gpu: 1}
Available fields:
cpu(Optional): Number of CPU cores — whole (4), fractional (0.5) or in the millicore spelling Kubernetes uses ("500m") — or a per-cluster list. This is the reservation: what the cluster packs by, and so what decides how many trials run at once. With nocpu_limitbeside it, it is the ceiling as wellmemory(Optional): Memory reservation (e.g.8Gi,4096Mi), or a per-cluster list — and, with nomemory_limit, the ceiling toocpu_limit/memory_limit(Optional): the ceiling, when it should differ from the reservation. Omitted — the default — the limit equals the request, which is what every campaign meant before these existed. See Splitting the reservation from the ceiling belowgpu(Optional): Number of GPUs. Rarely needed. Omit it and the container running the simulator gets one wherever the cluster advertises GPUs, so the common case is to say nothing;gpu: 0opts out on a cluster that has them (worth doing for a camera-less world, which never renders). Setting it enables the NVIDIA runtime; the GPU must also be schedulable, whichvast cluster setuparranges — see GPU rendering, which also covers why the replica count caps concurrency without partitioning VRAM, and the comparability caveat for a campaign whose cells ran at different GPU concurrency.
Fractional cores are worth the trouble on the cluster, where a campaign’s throughput is
quota // pod_request: rounding a sidecar that measures 0.3 cores up to a whole one is
paid on every job of the sweep. The Monitor’s Details panel measures what each
container actually used and suggests the number to type here (see Web UI). A
millicore declaration goes into the Job as written.
Not declaring it at all — execution.sizing: calibrated measures each container on
each node instead, from one probe run there before the campaign places work on it.
You usually do not write the key. Left out, the mode is read from the file itself: a
campaign that declares resources has already answered the question and is fixed; one
that declares none is asking to be measured and is calibrated. So a new .vast gets
measured sizing by saying nothing, and one that already carries numbers keeps meaning what it
meant. Write the key to be explicit, or to have the mismatch refused rather than inferred.
execution:
sizing: calibrated # default: fixed
containers:
sut: {image: nav2:latest} # no `resources:` -- measured per node
simulation: {image: sim:latest}
The reason is portability, not density. A core count is a fact about the machine it was
measured on, so a .vast naming one asserts something it cannot know about the cluster it
lands on. Under calibrated the file says what to run and the cluster says how much of
itself that takes.
Declaring resources under calibrated states where measuring starts.
resources has one meaning in either mode: the container’s declared ceiling, the most it
may have. Under fixed that is also what it gets, because nothing measures it down; under
calibrated it is what the probe and every not-yet-measured node run at, and the bound a
measured figure may not exceed. resources.gpu is never measured: a device count is a
count, not a rate.
Before a node has been measured — the probe itself, and every job on a node whose probe
has not reported — a container that declares nothing asks for the deployment’s bootstrap for
its role (ROBOVAST_BOOTSTRAP_CPU / _MEMORY, see Cluster Execution). Resolved
per field, so a .vast stating only cpu keeps the deployment’s memory.
What it measures. CPU and memory, both from the same probe. CPU is read at a percentile that depends on the container’s role; memory is read at the maximum for every role, because exceeding a CPU reservation slows a container while exceeding a memory one kills it. The probe is a run in the job shape, and is treated as one all the way: while somebody is watching the campaign, the service asks the probe’s simulator for its health exactly as it asks a run’s (MCP Server, “How it is asked”). That read is a process started inside the simulator’s container and charged to its memory, so it is part of what the simulator’s limit must clear, and a probe spared it would be sized without it.
How the measurement becomes an allocation is a per-container calibration block, every
field optional and defaulted from the role and the deployment:
execution:
sizing: calibrated
containers:
sut:
image: nav2:latest
calibration:
size_on: 100 # percentile; 100 is the sample's max. Default: 100 for sut,
# 95 for every other role.
limit: request # limit == request, so it never throttles. Default: `request`
# for sut, `declared` elsewhere -- keep the ceiling, allow a burst.
headroom:
cpu: 1.4 # margin above the measurement; per resource
memory: 1.5
min:
cpu: 1 # the LEAST it may be sized to, whatever was measured
memory: 2Gi # never above `resources`, which stays the ceiling
size_on is worth knowing about for one reason beyond tuning: which statistic the system
under test is sized on is a decision this substrate asserts rather than a measured fact, and
setting it is how a campaign tests that decision. Doing so costs comparability — a system
under test read below its maximum will be throttled mid-plan, which
run_validity_view.quota_bound flags, and its runs cannot be compared with a campaign sized
any other way. That is the point when it is the experiment, and a mistake when it is not.
Neither resource is ever sized below a floor. CPU keeps a quarter core, memory keeps 512M.
They are what let a .vast say nothing about sizing and still get an allocation its containers
can live in: a probe reports a number, not whether its run got far enough for that number to mean
anything, and one that stopped during bring-up measures a fraction of what every later run needs.
Each floor is what a container that has actually started a stack uses, rather than a description
of any particular one — what a given container needs is what resources and min say.
min raises a floor for a container you know needs more, and answers what headroom
cannot: a multiplier scales a measurement that is wrong, a floor bounds it. cpu is in cores
and memory a Kubernetes quantity, as in resources. Neither ever lifts a container above
resources — a floor stated above that ceiling is refused, because no allocation satisfies
both.
The block is read only under calibrated; declaring one under fixed is refused rather
than ignored, since nothing there would read it.
Where calibration cannot run, the bootstrap stands — and is checked. A campaign with no more jobs than the cluster has nodes, or a cluster that can grow, never probes: no node would run a second job at the better size, so the probe would cost more than it saves. Those runs use the bootstrap, and if one is OOM-killed or throttled hard against it the campaign stops with an error naming the container. That is deliberately unlike a declared or measured allocation, where such a run is recorded and kept: nobody chose the bootstrap for this workload, so a run that dies against it says the default does not fit rather than anything about the stack — and every remaining run would carry the same fault.
A node that cannot be measured stops the campaign. Its jobs would run at the starting
allocation while every measured node’s ran at a measured figure, so the campaign would
silently mix two sizings — the inconsistency calibration exists to remove, arriving through
the act of failing to measure. The error names the node, why its probe was refused, and which
of the .vast or the deployment default to change.
Splitting the reservation from the ceiling — and this is a decision about a container’s role, not a tuning knob.
The reservation is what the scheduler packs by, so lowering it is what buys concurrency. The limit only decides when the kernel starts throttling. Which means:
The system under test should keep them equal, sized so it does not throttle. The property that protects the result is that its ceiling is never binding: an allocation the container never reaches cannot have shaped what the stack did, and equality is the conservative way to reach that while nothing measures what it actually got. It is worth over-reserving for.
run_validity_viewsays per run whether it held —quota_boundfor this ceiling,contendedfor other work taking cores it had not reserved.The simulator and scenario are not under test and may split, once it has been validated at the concurrency the campaign will actually run at — see the two costs below, both of which scale with concurrency rather than showing up in a single run. Measured on the shipped
basic_navexample, the simulator uses 0.34 cores sustained and peaks at 5.98 where the world’s geometry compiles — a ratio of ~18, so there is no honest single number. Reserving the peak costs more than an un-tuned campaign did; capping at the sustained figure clips a burst that changes nothing the robot experiences. What makes the soft limit safe is already recorded: realtime pacing normalises what the simulated world looks like, andruns.clock_map_*says per run whether the simulator kept pace.
execution:
containers:
simulation: # not under test: split
resources: {cpu: 0.5, cpu_limit: 6, memory: 2944Mi}
sut: # under test: do not split
resources: {cpu: 3, memory: 640Mi}
The size of the win depends on the world: the same simulator peaks at 5.98 cores in
basic_nav’s depot and 0.78 in nav_search’s empty room, so the two examples reserve
different figures and gain differently from the split.
What a split costs, and why it is a mode rather than a default. Two things follow from splitting any container, and neither is visible in one run:
The pod stops being
Guaranteed. Kubernetes assigns that class only when request equals limit for every container of the pod, so splitting the simulator downgrades the whole pod toBurstableeven though the system under test kept its equality. On a node running the static CPU manager that is what makes the SUT ineligible for exclusive cores, and it weakens the Memory Manager’s guarantees too. It costs nothing wherecpuManagerPolicyisnone— no container is eligible for exclusive cores there whatever its class — which is why the effect is latent rather than absent. The policy of each node is read when a campaign starts and recorded in itsexecution.yamlundercluster_info.cpu_manager_policies(execution_jsonin the campaign data).Bursts correlate. Forty simulators reserving 0.5 and permitted 6 are placed against 20 cores while able to demand 240, and they burst together — world compile happens at startup, and a batch starts at once. Whether a given run gets its burst then depends on its neighbours, which is the hidden variable comparability is trying to remove. Admission packs by the request, exactly as Kubernetes does, so it does not prevent this.
So: equality is the reproducible default, and a split is controlled overcommit — right for
an exploratory sweep, and something to validate before trusting a comparison drawn across a
campaign that used it. The counters say per run whether it bit (quota_bound, contended,
clock_map_*); they cannot make two runs’ conditions equal after the fact.
The system under test’s ceiling is set from a pilot, which is the assumption to keep in
view. Clipping is not proportional — measured here, 0.5% of ticks above the limit cost 22% of
the runs, because clipped work queues rather than vanishing. A campaign that searches toward
harder configurations can therefore exceed the peak a pilot measured, and the cells that do so
are the interesting ones. quota_bound is what says it happened; do not read the headroom as
a guarantee.
These figures are declarations, not a permanent shape. Per-node sizing measures each
container on the machine it is about to run on and lowers the reservation to what it needs
there; it never raises a ceiling a campaign set. The direction of travel is for a campaign not
to state these numbers at all — so read a figure here as this deployment’s current measurement
of one world on one cluster, not as a property of the workload worth copying into a new
campaign. Measure your own: get_campaign_summary reports what each container actually used
and suggests the number to type.
Memory is deliberately not split in the shipped examples. Exceeding a CPU limit costs speed; exceeding a memory limit is an OOM kill, so a request below the limit trades a run for density on a node where several containers peak together.
Per-cluster resource values are supported when multiple clusters need different allocations. See Cluster Execution for the full syntax.
execution:
containers:
scenario:
resources:
cpu:
- gcp-c4: 4 # 4 CPUs on the gcp-c4 cluster
- minikube: 8 # 8 CPUs on the one-node deployment
Note
Every container other than scenario runs alongside it in the same pod, sharing its
network and IPC namespaces — so they reach each
other over localhost, and over /ipc. One that declares no command runs
secondary_entrypoint.sh, i.e. a scenario_execution_server the scenario drives
with remote("ipc:///ipc/<name>"); one that declares a command runs that instead.
kubernetes
Type: Dictionary
Required: No
Settings that name things about the cluster a campaign runs on.
kubernetes.jobs.node
Type: String (a node alias)
Required: No
Confines every job of this campaign to the one node the operator registered under this alias:
execution:
kubernetes:
jobs:
node: bench-a
The operator registers the alias on the cluster — in ROBOVAST_JOB_NODE_ALIASES in the
.env that vast cluster setup and vast service upgrade read — and the campaign names
only the alias, so a .vast never carries a machine’s name and runs on any cluster that
registers the same alias. See Naming a node a campaign may be held to.
It narrows, never widens. The alias is ANDed onto the cluster’s job pool
(ROBOVAST_JOB_NODE_LABELS, Pinning pods to a node pool): registering an alias
for a node outside the pool is refused, and the pool is checked again when a campaign starts.
Admission counts capacity on that node only.
An unresolvable alias refuses the campaign when it starts, before any job exists — an alias nobody registered, or one whose node has left the pool. A campaign never falls back to the whole pool, because its results would then describe machines it did not ask for.
It is per campaign, like the rest of execution. A sweep across CPU levels on one node is
one campaign per level, each extending a shared base (extends:) and naming the same alias.
It does not isolate a job from its neighbours. A pinned job shares the node with whatever
else runs there, and a CPU request is a share of the node rather than a reservation of cores.
run_validity_view.contended says per run whether contention affected it.
The alias must be lowercase letters, digits, - and _, start and end with a letter or
digit, and be at most 63 characters (it is matched as a Kubernetes label value). A label
selector (KEY=VALUE), a label key (prefix/name) or a node name (anything with a dot
or an uppercase letter) is refused with a message naming the fix.
Node pools are not campaign settings
execution.kubernetes.jobs.node_labels and execution.kubernetes.control are refused.
Which nodes jobs and RoboVAST’s own pods may use is decided for the whole cluster:
jobs.node_labels→ROBOVAST_JOB_NODE_LABELSin the operator’s.envfor the pool, andexecution.kubernetes.jobs.nodeto confine one campaign to a node inside it.control.node_labels→vast cluster setup <config> --control-node-label KEY=VALUE.
An archived campaign carrying either key still reads, retriggers and seeds a workspace: the keys never affected its run, so they are dropped from the copy with a log line.
Results Processing Section
The results_processing section defines how run results should be processed after execution.
resources
Type: Mapping with cpu and memory
Required: No
How much of a machine this campaign’s postprocessing may use. Omitted, it takes a shared default sized for an ordinary campaign; a campaign that converts unusually many or unusually large rosbags, or whose own analysis plugins are hungry, raises it here.
results_processing:
resources:
cpu: 8
memory: 16Gi
postprocessing:
- rosbags_to_csv:
topics: [/cmd_vel, /odom]
cpu takes cores (8, 0.5) or millicores ("500m"); memory takes a Kubernetes
quantity (16Gi, 512Mi). Either may instead be a per-cluster list, exactly as in
execution resources:
resources:
cpu:
- my-big-cluster: 8
- my-laptop: 2
``cpu`` also decides how many rosbags are converted at once. The conversion runs one
process per bag and reads the CPU it is actually allowed rather than the machine’s core count,
so this is the single knob that makes conversion faster — there is no separate worker setting
to keep in step with it. (rosbags_process accepts a workers parameter to override just
the fan-out, for bags large enough that fewer, fatter workers win.)
It applies to the whole campaign, including a search’s per-batch conversions. A search
converts inside its loop, once per batch (see the search section),
and those conversions take this figure too — there is no separate key under search.
Note
The reservation is also the ceiling, and there is no ``cpu_limit``/``memory_limit`` here — unlike execution resources, where splitting the two deliberately buys density. Postprocessing runs on the same machines as trials, so a postprocessing step allowed past its reservation takes cores from a run that reserved honestly, and that run’s timing then depends on which campaign happened to be postprocessing beside it. Nothing in a run’s results records that, so it would be a hidden variable in the measurement rather than a visible cost.
Note
This raises what postprocessing reserves; it does not lower it below what the fixed steps need. Postprocessing also stages the campaign and ingests its results, and those steps have figures of their own that a campaign cannot know better than the deployment does — asking for less than they need would trade a slow step for a step killed for running out of memory. So a figure below them still holds the conversion (and its fan-out) to what was asked, while what the whole postprocessing step reserves stops at that floor.
postprocessing
Type: List of strings (plugin commands)
Required: No
Commands to run for postprocessing run results. These are executed before the evaluation GUI is launched and typically convert raw data files into more analysis-friendly formats.
All postprocessing commands are plugins. Each command is specified either as: - A simple string (for commands without parameters) - A dictionary with the plugin name as key and parameters as value
results_processing:
postprocessing:
- rosbags_tf_to_csv:
frames: [base_link, turtlebot4_base_link_gt]
- rosbags_to_webm:
topic: /camera/image_raw/compressed
fps: 30
- rosbags_action_to_csv:
action: navigate_to_pose
- command:
script: tools/custom_script.sh
args: [--arg, value]
To list all available plugins and their descriptions:
vast results postprocess-commands
Built-in Postprocessing Plugins:
rosbags_tf_to_csv: Convert ROS TF transformations to aposesCSV, map-relative, one row per frame per sample.framesis a list of child frame names, orallfor every child frame that resolves againstmap.allis for the web Run view’s 3D panel, which animates one scene body per frame: a world with people or movable props has a frame per skeleton bone and per prop, and listing them is per-world busywork that adding a prop silently invalidates.require(list) names the frames that must be present — a required frame yielding nothing fails the step, which is how a ground-truth frame missing from one simulator’s bags gets caught instead of silently analyzed as absent. An explicitframeslist requires itself, soframes: allis normally paired withrequire. Note that a frame latched once on/tf_staticbefore the dynamic chain tomapexists never resolves and so is not written (a body welded in a scene is already baked at that pose, so this costs a viewer nothing).rosbags_nav2bt_to_csv: Convert nav2’s behavior-tree log (/behavior_tree_log,nav2_msgs/msg/BehaviorTreeLog) to anav2_behavior_treeCSV — one row per status transition (timestamp, node_name, uid, previous_status, current_status, event_timestamp).uidis nav2’s per-node id, the only column separating two nodes that share anode_name(an unnamedRecoveryNodeappears once per instance in a default tree); it is empty for pre-Jazzy message definitions.timestampis the bag receive time, i.e. the same clock as every other table (see one clock per run); nav2 stamps its own events from a wall clock even underuse_sim_time, so that stamp is kept separately asevent_timestamprather than used to key the table. The log has no tree topology; pair it with therobovast_navplugin’snav2_bt_treecommand (below) to reconstruct the tree. No parameters. Requires/behavior_tree_login the scenario’sbag_record(...).nav2_bt_tree(requires therobovast_navpackage): Reconstruct nav2’s behavior tree by parsing the BT XML nav2 ran and joining it with thenav2_behavior_treetransitions, writing anav2_behaviorsCSV in the same schema as thebehaviorstable (so the Run view’s tree panel renders it). Requiredbt_xmlparameter (path, relative to the config dir, to the BT XML — must matchbt_navigator’sdefault_nav_to_pose_bt_xml). List it afterrosbags_nav2bt_to_csv.rosbags_to_csv: Extract a specific set of ROS topics from rosbags to separate CSV files. Requiredtopicsparameter (list of topic names to extract). For each topic one CSV file per bag is written next to the bag, named<bag>_<topic>.csv, with one column per scalar field of the message, flattened, so a vendor’s message (a robot stack’swheel_velsorhazard_detection) needs no decoder of its own — only its message package installed where the bags are converted, which is the campaign’s execution image (system_packages, orros_packagesfor one built from source). A recorded topic whose type cannot be loaded there fails the bag, naming the topic, the type and that fix, rather than being skipped: a converted-looking run short of a table is the failure nothing downstream can detect. A field declared as an array of numbers — aLaserScan’sranges, anImage’sdata, a covariance — is a single column holding the whole array asnum1:<dtype>:<count>:<base64 of the zlib-compressed little-endian values>; read it back withrobovast.results_processing.data.rosbags_common.decode_numeric_array, or anywhere else withnumpy.frombuffer(zlib.decompress(base64.b64decode(payload)), dtype='<' + dtype). Such a cell is wider than the per-cell limit of ordinary query results and comes back truncated there — thequery.csvexport (csv_url) returns it whole. A non-finite float, which is how a laser spells “no return”, is written asinfornanand stored as that number (A measurement with no finite value), in a scalar column and inside a packed array alike. A sequence of sub-messages (aPath’s poses) is still a column per element per field, so a topic carrying many of them is one to reduce to scalars in the run rather than to record whole. For occupancy grids userosbags_costmap_to_csv, whosecostmapstable the web Run view reads and which keeps the grid’s geometry beside its cells.rosbags_costmap_to_csv: Storenav_msgs/msg/OccupancyGridframes (nav2 costmaps, the static map) compactly and losslessly for the web Run view. Requiredtopicsparameter (list of grid topics, e.g.[/map, /global_costmap/costmap, /local_costmap/costmap]). Writes onecostmapstable row per message: the pose/geometry metadata (resolution, width, height, origin) plus the int8 cells zlib-compressed and base64-encoded. The map’s extent in meters iswidth×resolutionbyheight×resolution.rosbags_to_webm: Convert asensor_msgs/msg/CompressedImagetopic from ROS bags to WebM video files (VP9 codec), and register each in the run’s videos table so the camera panel andget_camera_framecan place it on the run’s timeline. Optionaltopicparameter (compressed image topic name, default/camera/image_raw/compressed) andfpsparameter (fallback frame rate when timestamps are unavailable, default30). The rate is otherwise derived from the frames’ own stamps as(n-1)/duration, so the first and last frames land exactly on their recorded moments and only mid-run jitter drifts.rosbags_action_to_csv: Extract ROS2 action feedback and status messages to two CSV files (<filename_prefix>_feedback.csvand<filename_prefix>_status.csv). Reads/<action>/_action/feedbackand/<action>/_action/statustopics. Nested data is flattened to columns. Requiredactionparameter (action name, e.g.navigate_to_pose). Optionalfilename_prefixparameter (default:action_<action>).rosbags_rosout_to_csv: Extract ROS log messages from the/rosouttopic in ROS bags to a CSV file. Optionalskip_levelsparameter (list of log levels to skip, e.g.[ERROR, FATAL]).run_log: Merge every container’s stdout with/rosoutinto onerun_log.csvper run, on the run’s playback clock (see run_log — everything the run said). Optionalmin_severity(warn/error; empty keeps everything, which is the default). Auto-injected — see the note below.resource_usage: Slice the job’s resource-monitor samples into oneresource_usage.csvper run — CPU and memory per container, per process name, per ~1 s tick (see resource_usage — what the run cost). No parameters. Auto-injected — see the note below.command: Execute arbitrary commands or scripts. Requiresscriptparameter, optionalargsparameter (list).compress: Create a gzipped tarball (<name>-<timestamp>.tar.gz) for each campaign directory; runs on the host (no Docker). Optionaloutput_dir(default: results directory),exclude_dirs(directory names to exclude, default['.cache']),overwrite(iffalse, skip when a tarball already exists; defaultfalse).
Note
``run_log`` and ``resource_usage`` run for every campaign without being declared.
Both turn a job-level artifact into a per-run table, and a run whose output cannot be
read afterwards cannot be explained — so they are appended after the rosbag conversions
(which produce the /rosout and /clock data they read) rather than waiting to be
asked for. Declare one explicitly only to change a parameter, which also keeps its own
position in the order; opt out with --skip run_log / --skip resource_usage.
Note
The rosbags_* names above are handled by a single unified plugin,
rosbags_process — the one that shows up in vast configuration plugins
and the list_plugins MCP tool. When several rosbags_* commands appear
in a config, they are transparently batched into one rosbags_process call
so each rosbag is read only once, and every kind of bag — a run’s own rosbag2
and the infrastructure logs/rosout_bag — is converted in the same scan and
worker pool. You can keep using the individual rosbags_* names (they remain
valid), or write rosbags_process directly with a list of handler type
entries when you need finer control:
postprocessing:
- rosbags_process:
plugins:
- type: tf_to_csv
frames: [base_link]
- type: to_csv
topics: [/cmd_vel, /odom]
plugins converts the bags in bag_dir (default rosbag2). Every
rosbags_process entry and every rosbags_* name in the list is combined into
the one conversion, bag directory by bag directory, and the logs/rosout_bag
handlers (rosout_to_csv, clock_to_csv) are added to it unless an entry
declares them itself or they are skipped — so write an entry per bag directory
whose handlers you set, and nothing for the rest.
See Add Postprocessing Command Plugin for how to add custom postprocessing plugins.
Recording a camera, and watching it back
Putting a camera in a run view takes three things, and they live in three different parts of a campaign — so here they are together. A reader who finds only one of them gets an empty panel:
# 1. the scenario records the image topic (in the .osc, not the .vast)
# bag_record(['/static_camera/image/compressed', ...])
# 2. postprocessing turns the recorded frames into a video, and registers it
results_processing:
postprocessing:
- rosbags_to_webm:
topic: /static_camera/image/compressed
# 3. the run view plays it. A bare `- camera:` is enough when the run has one video.
visualization:
results:
run_view:
panels:
- camera:
title: Monitor camera
position: {anchor: center, width: 560, height: 560}
Validation catches the common half-step: a camera panel with no step that produces a video
is refused before the campaign runs, rather than showing an empty panel after the compute is
spent.
The videos table is what joins steps 2 and 3. One row per recording, in the run’s
videos.csv:
Column |
Meaning |
|---|---|
|
The recorded topic, and how a panel or tool picks between several cameras. |
|
The video, relative to the run directory. |
|
First and last frame, in seconds on the run’s timeline — the same clock every other table’s timestamps use (see one clock per run). |
|
The rate written into the container, and how many frames it holds. |
t_start is the load-bearing one. The encode re-times frames onto a constant rate and drops
the bag stamps, so the file alone cannot say when its first frame was — and a camera that came
up ten seconds into a trial would otherwise replay as though it had run from the start.
This is a contract, not rosbags_to_webm’s private file. That step is the first
producer, not the owner: anything that puts a video in a run directory may write the same row —
another postprocessing step, a simulator that renders its own, a script of your own — and the
camera panel and get_camera_frame then work for it unchanged. Without that, the only way to
reach the panel would be “record a CompressedImage through a rosbag”, which is a
ROS-shaped assumption in a feature that has no reason to carry one.
publication
Type: List of strings or dictionaries (plugin commands)
Required: No
Defines publication plugins that package or distribute the results directory after postprocessing. Each entry is either a plugin name (string) or a dictionary with the plugin name as key and plugin-specific parameters as value.
Publication plugins are executed by vast results publish and operate on the
full results directory (parent of campaign directories).
results_processing:
publication:
- zip:
include_filter:
- "*.csv"
- "/_config/*"
exclude_filter:
- "*.pyc"
omit_hidden: true
destination: archives/
Built-in Publication Plugins:
zip: Create a zip archive for every campaign directory under the results directory. Optional parameters:filename: Template for the zip filename. Supports{key}placeholders resolved from the.vastfile’smetadata:section and the built-in{timestamp}placeholder (extracted from the campaign directory name, e.g.campaign-2026-03-05-121530→2026-03-05-121530). Example:my_dataset_{robot_id}_{timestamp}.zip. If omitted, the default name<campaign-dir-name>.zipis used. A descriptive error listing all available placeholders is raised when an unknown placeholder is referenced.include_filter: List of glob patterns. Only matching files are included. Patterns starting with/are anchored to the campaign root; patterns without/match on the basename only; other patterns are matched against the full relative path. If omitted, all files are candidates.exclude_filter: List of glob patterns. Matching files are excluded regardless ofinclude_filter.destination: Directory where zip files are written. Relative paths are resolved from the results directory. Defaults to the results directory itself.overwrite: Controls behavior when the output zip file already exists.truealways overwrites silently;falsealways skips silently. Omit (or leave unset) to be prompted interactively — the default answer is yes (overwrite). Passing--force/-fon the CLI is equivalent to settingoverwrite: truefor every plugin.omit_hidden: Whentrue, directory components whose names start with_are stripped from the file paths inside the archive. The files are still selected byinclude_filter/exclude_filterusing their original on-disk paths; only the stored archive member path is affected.For example, a file stored on disk as
campaign-2026-03-05-163338/_config/my_file.yamlis placed in the zip ascampaign-2026-03-05-163338/my_file.yaml. Defaults tofalse.metadata: Optional dict of metadata fields to merge into themetadata:section of the campaign’smetadata.yamlbefore including it in the archive. Typical fields aretitleanddescription. The mergedmetadata.yamlis always written regardless ofinclude_filter/exclude_filter.
Multiple zip entries may be defined to produce different archives from the
same campaign:
results_processing:
publication:
- zip:
filename: my_dataset_{robot_id}_{timestamp}.zip
include_filter: ["*.csv"]
destination: csv-archives/
overwrite: false # skip if archive already exists
- zip:
filename: my_dataset_{robot_id}_{timestamp}_videos.zip
include_filter: ["*.webm"]
destination: video-archives/
See Add Publication Plugin for how to add custom publication plugins.
metadata_processing
Type: List of strings or dictionaries (plugin commands)
Required: No
Defines metadata processing plugins that run after generic metadata generation.
results_processing:
metadata_processing:
- my_plugin
- my_plugin:
param1: value1
Visualization Section
The visualization section declares everything the web UI draws for this campaign, and it
is shaped like the UI: one key per place a declaration appears, so reading it says where
each block shows up.
visualization:
config: # the Config tab
panels: [...] # its third column, per generated configuration
# (see :ref:`config-view` for the panel reference)
results: # the Results tab
run_view:
panels: [...] # the replay panels (the playback bar comes for free)
timeline: {...} # which table defines the playback clock
explorer:
notebooks: [...] # analysis notebooks, one tab each
data_browser:
plots: [...] # campaign-scoped declared plots
Note
This replaced a flat visualization.panels beside a separate top-level evaluation:
block (evaluation.visualization for the notebooks, evaluation.plots for the plots).
The evaluation: key is gone — it is not accepted, and a .vast still using it is
refused by name. See the key map in the web UI page.
results.explorer.notebooks
Type: List of dictionaries
Required: No
Defines analysis notebooks for the Results Explorer. Each entry creates a tab, executed
server-side against the DATA_DIR contract for the selected tree node.
Each dictionary can have a custom name and four reserved keys for different analysis scopes:
run: Path to Jupyter notebook for analyzing a single runconfig: Path to Jupyter notebook for analyzing all runs of a configurationbatch: Path to Jupyter notebook for analyzing one batch of a search (the configurations a strategy proposed in a single ask/tell round)campaign: Path to Jupyter notebook for analyzing all runs in a campaign
visualization:
results:
explorer:
notebooks:
- Analysis:
run: analysis/analysis_run.ipynb
config: analysis/analysis_config.ipynb
batch: analysis/analysis_batch.ipynb
campaign: analysis/analysis_campaign.ipynb
- Performance:
run: analysis/performance_run.ipynb
config: analysis/performance_config.ipynb
Notebook requirements:
Each notebook must include the following placeholder line:
DATA_DIR = ''
The RoboVAST GUI automatically replaces this with the path to the selected run directory when executing the notebook.
batch notebooks only appear for searches (a batch tree node exists only in
search mode, in both front-ends). Because the search results layout is flat — every
batch’s configurations live directly under the campaign root — DATA_DIR alone cannot
identify the batch, so a batch notebook receives the campaign root as its DATA_DIR
plus an injected BATCH variable (the batch index), and selects its configurations from
campaign.db:
DATA_DIR = ''
BATCH = None # injected: the index of the selected batch
Complete Example
Here’s a complete example showing all major configuration options:
version: 4
configuration:
- name: parameter-sweep
scenario_file: scenario.osc
variations:
- ParameterVariationList:
name: velocity
values: [1.0, 2.0, 3.0]
- ParameterVariationDistributionUniform:
name: obstacle_count
num_variations: 5
min: 1
max: 10
type: int
seed: 42
- name: baseline
scenario_file: scenario.osc
parameters:
- velocity: 2.0
- obstacle_count: 5
execution:
containers:
scenario:
image: ghcr.io/cps-test-lab/robovast:latest
resources:
cpu: 4
memory: 8Gi
sut:
image: ghcr.io/cps-test-lab/robovast:latest
resources:
cpu: 3
memory: 4Gi
runs: 20
pre_command: /config/files/prepare_test.sh
post_command: /config/files/post_command.sh
run_as_user: 1000
run_files:
- "**/files/*"
- "**/models/*.sdf"
env:
- RMW_IMPLEMENTATION: rmw_cyclonedds_cpp
results_processing:
postprocessing:
- rosbags_tf_to_csv:
frames: [base_link]
- rosbags_to_csv
- rosbags_to_webm
visualization:
results:
explorer:
notebooks:
- Analysis:
run: analysis/analysis_run.ipynb
config: analysis/analysis_config.ipynb
campaign: analysis/analysis_campaign.ipynb