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 several times. A run-time variation can produce a new value on each reset without rebuilding the scene.

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: droid_abs_joint_pos
  camera_extrinsics_wrist_camera (CameraExtrinsicsVariation, run-time)
    Enable: droid_abs_joint_pos.camera_extrinsics_wrist_camera.enabled=true  (default: False)
    Fields:
      droid_abs_joint_pos.camera_extrinsics_wrist_camera.sampler_cfg.high = [0.005,0.005,0.005]
      droid_abs_joint_pos.camera_extrinsics_wrist_camera.sampler_cfg.low = [-0.005,-0.005,-0.005]

Asset: light
  hdr_image (HDRImageVariation, build-time)
    Enable: light.hdr_image.enabled=true  (default: False)
    Fields:
      light.hdr_image.hdr_names = []

Asset: bowl_ycb_robolab
  (no variations)

...

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 rubiks_cube_hot3d_robolab.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
`CameraExtrinsicsVariation`	run-time	Adds a small sampled offset to a camera’s nominal local position on every reset.
`CameraIntrinsicsBuildTimeVariation`	build-time	Perturbs a pinhole camera’s focal lengths and principal point when the environment is built.
`CameraIntrinsicsRunTimeVariation`	run-time	Perturbs a pinhole camera’s focal lengths and principal point on every reset.
`HDRImageVariation`	build-time	Samples a single HDR and attaches it to a dome light.
`LightColorTemperatureVariation`	build-time	Samples a white-point color temperature (Kelvin) and applies it to a light.
`LightColorVariation`	build-time	Samples an RGB color and applies it to a light.
`LightDirectionVariation`	build-time	Samples a continuous orientation and applies it to a directional light.
`LightIntensityVariation`	build-time	Samples a single intensity and applies it to a light.