Heuristic:ARISE Initiative Robosuite Domain Randomization Tuning

Knowledge Sources	robosuite DR Demo Limitations
Domains	Sim_To_Real, Optimization, Robotics_Simulation
Last Updated	2026-02-15 07:00 GMT

Overview

Domain randomization requires careful tuning of randomization ranges, timing, and which modalities to randomize; excessive randomization makes tasks unlearnable, and color randomization has a MuJoCo version dependency.

Description

The `DomainRandomizationWrapper` orchestrates four randomization modalities: color/texture, camera, lighting, and dynamics. Each modality has configurable ranges and can be toggled independently. The wrapper supports two randomization schedules: per-reset (new domain each episode) and per-N-steps (domain changes mid-episode). Getting these parameters right is critical for sim-to-real transfer: too little randomization provides no transfer benefit, while too much makes the task unlearnable in simulation. Additionally, the `USING_INSTANCE_RANDOMIZATION` macro must be set before environment creation to take effect, and color randomization has a version-specific limitation.

Usage

Use this heuristic when:

Configuring domain randomization for sim-to-real transfer
Observing that a previously learnable task becomes unlearnable after adding DR
Debugging visual artifacts during domain-randomized training
Setting up the `DomainRandomizationWrapper` for the first time

The Insight (Rule of Thumb)

Action: Start with only one randomization modality enabled (e.g., lighting only), verify the task is still learnable, then progressively add more.
Action: Set `USING_INSTANCE_RANDOMIZATION = True` in your script before calling `robosuite.make()` or creating the DR wrapper, if you want per-instance (e.g., whole robot arm) rather than per-geom randomization.
Action: Set `randomize_color=False` unless you are using `mujoco==3.1.1`, as color randomization is broken on other versions.
Value: Default randomization frequency is `randomize_every_n_steps=1` (every step). For stable training, consider `randomize_on_reset=True` with `randomize_every_n_steps=0` to randomize only per episode.
Trade-off: Per-step randomization provides maximum diversity but can destabilize training. Per-episode randomization is more stable but provides less variety.
Warning: `hard_reset` must be `False` when using DomainRandomizationWrapper to avoid segfaults (see Hard_Reset_Vs_Soft_Reset heuristic).

Reasoning

Domain randomization for sim-to-real works by training policies that are robust to visual and physical variations, so they transfer better to real-world conditions. However, the randomization must stay within physically plausible bounds. The four modalities have different impacts:

Color/Texture Randomization: Changes material colors and textures. Currently version-locked to `mujoco==3.1.1` due to texture upload API changes. The `TextureModder` supports random RGB, noise textures, and gradient textures.

Camera Randomization: Perturbs camera position, rotation, and field of view. Small perturbations (a few degrees/centimeters) improve robustness; large perturbations make visual observations meaningless.

Lighting Randomization: Changes light positions, directions, colors, and ambient/diffuse/specular properties. Generally safe to randomize with moderate ranges.

Dynamics Randomization: Modifies physics parameters like friction, damping, and stiffness. This is the most sensitive modality: excessive dynamics randomization can make manipulation tasks physically impossible (e.g., zero friction means objects cannot be grasped).

Code evidence from `robosuite/demos/demo_domain_randomization.py:59-63`:

env = DomainRandomizationWrapper(
    env,
    randomize_color=False,  # randomize_color currently only works for mujoco==3.1.1
    randomize_camera=False,  # less jarring when visualizing
    randomize_dynamics=False,
)

Code evidence from `robosuite/macros.py:13-16`:

# Instance Randomization
# Used if we want to randomize geom groups uniformly per instance -- e.g.: entire robot arm, vs. per-joint geom
# This should get set to True in your script BEFORE an environment is created or the DR wrapper is used
USING_INSTANCE_RANDOMIZATION = False

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment