Implementation:ARISE Initiative Robosuite DomainRandomizationWrapper

Metadata:

Overview

Concrete wrapper for applying domain randomization to robosuite environments provided by the wrappers module.

Description

The DomainRandomizationWrapper wraps a MujocoEnv and applies randomization via four modder objects: TextureModder, CameraModder, LightingModder, and DynamicsModder. Each modder is responsible for randomizing a specific aspect of the simulation environment and can be enabled or disabled independently through constructor arguments.

Execution Flow:

On reset():

Restores the default domain parameters
Calls the base environment's reset method
Saves the default domain state for future restoration
Applies randomization if randomize_on_reset=True

On step(action):

Executes the action in the base environment
Optionally applies randomization every N steps if randomize_every_n_steps > 0
Returns the standard RL tuple (observation, reward, done, info)

Each randomization type can be configured through dedicated argument dictionaries that specify the ranges and parameters for randomization. The wrapper maintains internal state to track step counts and manage the randomization schedule.

Usage

Wrap an environment after calling robosuite.make() with USING_INSTANCE_RANDOMIZATION=True. The instance randomization flag ensures that the MuJoCo models are loaded with the necessary modding infrastructure enabled. Without this flag, the modder objects will not be able to access or modify simulation parameters.

The wrapper is designed to be used as part of a standard RL training loop, seamlessly integrating with existing training infrastructure. It follows the OpenAI Gym interface conventions for compatibility with popular RL libraries.

Code Reference

Source: robosuite

File: robosuite/wrappers/domain_randomization_wrapper.py

Lines: L84-276

Signature:

class DomainRandomizationWrapper:
    def __init__(self, env, seed=None, randomize_color=True, randomize_camera=True,
                 randomize_lighting=True, randomize_dynamics=True,
                 color_randomization_args=DEFAULT_COLOR_ARGS,
                 camera_randomization_args=DEFAULT_CAMERA_ARGS,
                 lighting_randomization_args=DEFAULT_LIGHTING_ARGS,
                 dynamics_randomization_args=DEFAULT_DYNAMICS_ARGS,
                 randomize_on_reset=True, randomize_every_n_steps=1):
        """
        Args:
            env (MujocoEnv): environment to wrap
            seed (int): random seed for reproducibility
            randomize_color/camera/lighting/dynamics (bool): enable each type
            *_randomization_args (dict): per-type configuration dicts
            randomize_on_reset (bool): randomize on each reset()
            randomize_every_n_steps (int): mid-episode randomization frequency (0=manual only)
        """

Import:

from robosuite.wrappers import DomainRandomizationWrapper

I/O Contract

Inputs (Constructor)

Parameter	Type	Required	Default	Description
env	MujocoEnv	Yes	N/A	The robosuite environment to wrap
seed	int	No	None	Random seed for reproducible randomization
randomize_color	bool	No	True	Enable texture/color randomization
randomize_camera	bool	No	True	Enable camera parameter randomization
randomize_lighting	bool	No	True	Enable lighting randomization
randomize_dynamics	bool	No	True	Enable physics dynamics randomization
color_randomization_args	dict	No	DEFAULT_COLOR_ARGS	Configuration for texture randomization
camera_randomization_args	dict	No	DEFAULT_CAMERA_ARGS	Configuration for camera randomization
lighting_randomization_args	dict	No	DEFAULT_LIGHTING_ARGS	Configuration for lighting randomization
dynamics_randomization_args	dict	No	DEFAULT_DYNAMICS_ARGS	Configuration for dynamics randomization
randomize_on_reset	bool	No	True	Whether to randomize on each episode reset
randomize_every_n_steps	int	No	1	Frequency of mid-episode randomization (0 for manual only)

Outputs

reset() returns:

OrderedDict: Observations from the randomized environment, matching the observation space of the wrapped environment

step(action) returns:

4-tuple: (OrderedDict, float, bool, dict)
- OrderedDict: Next observation after taking the action
- float: Scalar reward value
- bool: Episode termination flag
- dict: Additional diagnostic information

Usage Examples

Basic Usage

import numpy as np
import robosuite as suite
import robosuite.macros as macros
from robosuite.wrappers import DomainRandomizationWrapper

# Critical: set BEFORE environment creation to enable modding infrastructure
macros.USING_INSTANCE_RANDOMIZATION = True

# Create environment
env = suite.make(
    env_name="Lift",
    robots="Panda",
    has_renderer=False,
    has_offscreen_renderer=True,
    use_camera_obs=True,
    control_freq=20,
)

# Wrap with domain randomization
wrapped_env = DomainRandomizationWrapper(
    env=env,
    seed=42,
    randomize_on_reset=True,
    randomize_every_n_steps=0  # Only randomize on reset, not mid-episode
)

# Standard RL training loop
for episode in range(100):
    obs = wrapped_env.reset()  # Environment randomized here
    done = False
    episode_reward = 0

    while not done:
        action = np.random.uniform(-1, 1, wrapped_env.action_dim)
        obs, reward, done, info = wrapped_env.step(action)
        episode_reward += reward

    print(f"Episode {episode}: Reward = {episode_reward}")

Custom Randomization Configuration

import robosuite as suite
import robosuite.macros as macros
from robosuite.wrappers import DomainRandomizationWrapper

# Set instance randomization before environment creation
macros.USING_INSTANCE_RANDOMIZATION = True

# Create base environment
env = suite.make(
    env_name="Stack",
    robots="Sawyer",
    has_renderer=False,
)

# Custom randomization parameters
custom_color_args = {
    "geom_names": None,  # Randomize all geometries
    "randomize_local": True,
    "randomize_material": True,
    "local_rgb_interpolation": 0.5,
    "local_method": "gaussian"
}

custom_dynamics_args = {
    "randomize_position": True,
    "randomize_quaternion": True,
    "position_perturbation_size": 0.02,
    "quaternion_perturbation_size": 0.01
}

# Wrap with selective randomization
wrapped_env = DomainRandomizationWrapper(
    env=env,
    seed=123,
    randomize_color=True,
    randomize_camera=False,  # Disable camera randomization
    randomize_lighting=True,
    randomize_dynamics=True,
    color_randomization_args=custom_color_args,
    dynamics_randomization_args=custom_dynamics_args,
    randomize_on_reset=True,
    randomize_every_n_steps=10  # Randomize every 10 steps during episode
)

# Training loop
obs = wrapped_env.reset()
for step in range(1000):
    action = policy.get_action(obs)
    obs, reward, done, info = wrapped_env.step(action)

    if done:
        obs = wrapped_env.reset()

Minimal Randomization for Debugging

import robosuite as suite
import robosuite.macros as macros
from robosuite.wrappers import DomainRandomizationWrapper

macros.USING_INSTANCE_RANDOMIZATION = True

env = suite.make(
    env_name="Door",
    robots="Panda",
    has_renderer=False,
)

# Only randomize lighting for debugging
wrapped_env = DomainRandomizationWrapper(
    env=env,
    seed=0,
    randomize_color=False,
    randomize_camera=False,
    randomize_lighting=True,  # Only lighting enabled
    randomize_dynamics=False,
    randomize_on_reset=True,
    randomize_every_n_steps=0
)

# Test randomization
for i in range(5):
    obs = wrapped_env.reset()
    print(f"Reset {i}: Lighting randomized, other aspects deterministic")

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment