Variations#
Variations are a structured way of introducing randomization into simulated environments.
Variations are automatically available in Arena-defined environments. Activating the variation causes that particular source of randomness to be injected into the environment.
Build-time and run-time variations#
Some properties must be chosen before the environment is created. Others can change whenever an environment resets during policy rollouts. Arena calls these build-time and run-time variations.
Type |
When it changes |
Where the drawn value applies |
Examples |
|---|---|---|---|
Build-time |
Before the environment is built |
Every parallel environment and episode in that build |
Background image, lighting changes. |
Run-time |
When an environment resets |
One episode in one parallel environment |
Camera extrinsics, camera intrinsics |
This distinction matters when planning an evaluation. To collect several values of a
build-time variation, the environment must be rebuilt; the Experiment
Runner gives each rebuild its own seed. Set num_rebuilds in the Run; with the default of 1,
each enabled build-time variation draws one value for the whole Run. A run-time variation can
produce a new value on each
reset without rebuilding the scene. Both kinds draw their values from the variation’s own
generator, seeded from --seed (see Environment Builder).
In-order asset selection (RigidAssetSelectionVariation in Available variations) is the
exception: rebuild k spawns the k-th name of its registry_names, so set num_rebuilds to the
length of the list to spawn each name once. To give each name its own episode count, list the
counts in the same order in rollout_limit.num_episodes_per_rebuild; for example,
registry_names: [cracker_box, sugar_box] with num_rebuilds: 2 and
num_episodes_per_rebuild: [20, 5] runs 20 episodes with the cracker box and 5 with the sugar box.
A RigidObjectSet fits neither row: it assigns one member
to each parallel environment when the environment is built and keeps it for every episode of that
build. It is part of the environment definition rather than a variation, so it has no
asset_selection.
Discovering available variations#
Pass --list_variations to print every Hydra-configurable variation for the selected
environment and then exit before rollout:
python isaaclab_arena/evaluation/policy_runner.py \
--policy_type zero_action \
--list_variations \
pick_and_place_maple_table
The output lists each asset (scene asset or embodiment), the variation name, whether it is run-time or build-time, the Hydra path to enable it, and all tunable fields with their current defaults:
Variations (Hydra-configurable)
================================
...
Asset: pick_up_object
mass (ObjectMassVariation, run-time)
Enable: pick_up_object.mass.enabled=true (default: False)
Fields:
pick_up_object.mass.recompute_inertia = True
pick_up_object.mass.sampler_cfg.high = [2.0]
pick_up_object.mass.sampler_cfg.low = [0.05]
...
asset_selection (RigidAssetSelectionVariation, build-time)
Enable: pick_up_object.asset_selection.enabled=true (default: False)
Fields:
pick_up_object.asset_selection.registry_names = []
pick_up_object.asset_selection.sampler_cfg.random_choice = False
...
Enabling variations#
To enable a variation, with default control parameters append its enabled=true override token
after the environment subcommand. For example, to enable the HDR image and camera extrinsics variations
run:
python isaaclab_arena/evaluation/policy_runner.py \
--viz kit \
--policy_type zero_action \
--num_steps 50 \
--enable_cameras \
pick_and_place_maple_table \
light.hdr_image.enabled=true \
droid_abs_joint_pos.camera_extrinsics_wrist_camera.enabled=true
The same run with tunable variation control parameters spelled out:
python isaaclab_arena/evaluation/policy_runner.py \
--viz kit \
--policy_type zero_action \
--num_steps 50 \
--enable_cameras \
pick_and_place_maple_table \
light.hdr_image.enabled=true \
"light.hdr_image.hdr_names=[home_office_robolab,billiard_hall_robolab,garage_robolab]" \
droid_abs_joint_pos.camera_extrinsics_wrist_camera.enabled=true \
"droid_abs_joint_pos.camera_extrinsics_wrist_camera.sampler_cfg.low=[-0.01,-0.01,-0.01]" \
"droid_abs_joint_pos.camera_extrinsics_wrist_camera.sampler_cfg.high=[0.01,0.01,0.01]"
The hdr_names list restricts HDR sampling to the three named maps instead of the full
registered set. The sampler_cfg.low / sampler_cfg.high vectors widen the camera
extrinsics jitter range to ±10 mm per axis.
To see the available variations and control parameters for a specific environment, see Discovering available variations.
With Isaac Lab’s record_demos.py and Arena’s environment_registration_callback,
append the same variation overrides to the recording command, for example
pick_up_object.mass.enabled=true for pick_and_place_maple_table.
Arena consumes its variation overrides and returns the remaining arguments to the Isaac Lab script.
See Teleoperation Data Collection
for recording setup and the full command using the callback.
Configuring variations in an experiment config#
When running experiments with experiment_runner.py, variations are configured per run via a
dedicated variations field instead of command-line override tokens. The field maps each
dotted Hydra path to its value. For example, the entry light.hdr_image.enabled: true is
equivalent to the command-line override light.hdr_image.enabled=true.
The example config isaaclab_arena_environments/experiment_configs/droid_pnp_variations_experiment.yaml
enables three variations on a single run:
# Copyright (c) 2026, The Isaac Lab Arena Project Developers (https://github.com/isaac-sim/IsaacLab-Arena/blob/main/CONTRIBUTORS.md).
# All rights reserved.
#
# SPDX-License-Identifier: Apache-2.0
runs:
variations_demo:
environment:
type: pick_and_place_maple_table
enable_cameras: true
embodiment: droid_rel_joint_pos
policy:
type: zero_action
rollout_limit:
num_steps: 10
# Number of times the environment is rebuilt with different variation values.
num_rebuilds: 5
# The variations to enable for this run.
variations:
light.hdr_image.enabled: true
light.intensity.enabled: true
droid_rel_joint_pos.camera_extrinsics_wrist_camera.enabled: true
Run it with:
python isaaclab_arena/evaluation/experiment_runner.py \
--viz kit \
--experiment_config isaaclab_arena_environments/experiment_configs/droid_pnp_variations_experiment.yaml
--list_variations works with experiment_runner.py too, printing the variations catalogue for
each run’s environment:
python isaaclab_arena/evaluation/experiment_runner.py \
--list_variations \
--experiment_config isaaclab_arena_environments/experiment_configs/droid_pnp_variations_experiment.yaml
Available variations#
The variations shipped in isaaclab_arena/variations/ are listed below. Run-time variations
are realised via an event term and resampled during simulation (e.g. per reset); build-time
variations are sampled once and applied to asset configs before the environment is composed.
Variation |
Type |
Description |
|---|---|---|
|
build-time |
Picks the registered asset a rigid object spawns from a list of names. Rebuild k spawns the
k-th name, or a random one with |
|
run-time |
Adds a small sampled offset to a camera’s nominal local position on every reset. |
|
build-time |
Perturbs a pinhole camera’s focal lengths and principal point when the environment is built. |
|
run-time |
Perturbs a pinhole camera’s focal lengths and principal point on every reset. |
|
build-time |
Samples a single HDR and attaches it to a dome light. |
|
build-time |
Samples a white-point color temperature (Kelvin) and applies it to a light. |
|
build-time |
Samples an RGB color and applies it to a light. |
|
build-time |
Samples a continuous orientation and applies it to a directional light. |
|
build-time |
Samples a single intensity and applies it to a light. |