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.

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.