Implementation:Isaac sim IsaacGymEnvs DR Utils Random Samples

Metadata

Knowledge Sources	IsaacGymEnvs
Domains	Sim_to_Real Simulation
Last Updated	2026-02-15 00:00 GMT

Overview

Utility functions for generating random samples from configured distributions and applying them to Isaac Gym physics properties. These functions are the low-level building blocks of the domain randomization engine, handling distribution sampling, schedule scaling, operation application, and PhysX material bucketing.

Description

The dr_utils.py module provides four key functions:

• generate_random_samples() -- Draws samples from gaussian, uniform, or loguniform distributions with optional schedule scaling.
• apply_random_samples() -- Combines generated samples with original property values via additive or scaling operations, handling SimParams, structured arrays, and scalar properties.
• get_bucketed_val() -- Quantizes continuous property values to discrete material buckets for PhysX compatibility.
• check_buckets() -- Validates that the total material bucket count does not exceed the PhysX 64K limit.

Additionally, the module provides property getter/setter maps:

• get_property_setter_map() -- Maps property names to gym.set_actor_*_properties() functions.
• get_property_getter_map() -- Maps property names to gym.get_actor_*_properties() functions.
• get_default_setter_args() -- Maps property names to additional setter arguments (e.g., [True] for rigid body properties to recompute inertia).

Usage

from isaacgymenvs.utils.dr_utils import (
    apply_random_samples,
    generate_random_samples,
    check_buckets,
    get_bucketed_val,
    get_property_setter_map,
    get_property_getter_map,
    get_default_setter_args,
)

Code Reference

Source Location

• File: isaacgymenvs/utils/dr_utils.py (lines 35--239)

Signatures

def generate_random_samples(
    attr_randomization_params,   # dict with 'range', 'distribution', 'operation',
                                 #   optional 'schedule', 'schedule_steps'
    shape,                       # output shape for np.random
    curr_gym_step_count,         # current simulation step for schedule scaling
    extern_sample=None           # optional externally-provided sample
):
    """Generate random samples from the configured distribution.

    Returns:
        np.ndarray of sampled values with the given shape.
    """


def apply_random_samples(
    prop,                         # property object to modify (SimParams, ndarray, or scalar)
    og_prop,                      # original (cached) property values
    attr,                         # attribute name (e.g., 'damping', 'gravity', 'mass')
    attr_randomization_params,    # randomization config dict
    curr_gym_step_count,          # current simulation step
    extern_sample=None,           # optional external sample
    bucketing_randomization_params=None  # optional override params for bucketing
):
    """Apply random samples to a property, modifying it in-place."""


def get_bucketed_val(
    new_prop_val,                 # the randomized property value
    attr_randomization_params     # config dict with 'range', 'distribution', 'num_buckets'
):
    """Quantize a property value to the nearest material bucket.

    Returns:
        The bucketed (quantized) property value.
    """


def check_buckets(
    gym,       # Isaac Gym instance
    envs,      # list of environment handles
    dr_params  # full DR parameter dictionary
):
    """Validate that total material bucket count does not exceed 64K.

    Raises:
        AssertionError if bucket count exceeds 64000 or if shape count
        exceeds 64000 without explicit bucketing.
    """

I/O Contract

Inputs

Input Contract -- generate_random_samples

Name	Type	Description
attr_randomization_params	dict	Contains range ([lo, hi] or [mean, std]), distribution ("gaussian"/"uniform"/"loguniform"), operation ("additive"/"scaling"), optional schedule and schedule_steps.
shape	tuple	Shape of the output sample array.
curr_gym_step_count	int	Current simulation step count, used for schedule scaling.
extern_sample	np.ndarray or None	Optional externally-provided sample (bypasses internal sampling).

Input Contract -- apply_random_samples

Name	Type	Description
prop	SimParams, np.ndarray, or object	Property to randomize. SimParams for sim-level params, ndarray for structured DOF properties, object for shape properties.
og_prop	dict or ndarray	Original cached property values to apply operations against.
attr	str	Attribute name within the property (e.g., "damping", "gravity", "mass", "friction").
attr_randomization_params	dict	Randomization parameters for this attribute.
curr_gym_step_count	int	Current simulation step.
bucketing_randomization_params	dict or None	Optional override for bucketing range/distribution.

Outputs

Output Contract

Name	Type	Description
generate_random_samples return	np.ndarray	Sampled values with the requested shape, schedule-scaled and distribution-appropriate.
apply_random_samples side effect	modified prop	The prop object is modified in-place with randomized attribute values.
get_bucketed_val return	float	Quantized value snapped to the nearest bucket boundary.

Implementation Details

Distribution Sampling Logic

# Gaussian: range = [mean, std_dev]
mu, var = rand_range
sample = np.random.normal(mu, var, shape)

# Uniform: range = [low, high]
lo, hi = rand_range
sample = np.random.uniform(lo, hi, shape)

# Log-uniform: range = [low, high], samples uniform in log-space
lo, hi = rand_range
sample = np.exp(np.random.uniform(np.log(lo), np.log(hi), shape))

Schedule Scaling

if sched_type == 'linear':
    sched_scaling = 1 / sched_step * min(curr_gym_step_count, sched_step)
elif sched_type == 'constant':
    sched_scaling = 0 if curr_gym_step_count < sched_step else 1
else:
    sched_scaling = 1

# For scaling operations, interpolate between 1.0 (no effect) and sampled value:
if operation == 'scaling':
    sample = sample * sched_scaling + 1 * (1 - sched_scaling)
# For additive operations, simply scale the magnitude:
elif operation == 'additive':
    sample *= sched_scaling

Material Bucketing

def get_bucketed_val(new_prop_val, attr_randomization_params):
    if attr_randomization_params['distribution'] == 'uniform':
        lo, hi = attr_randomization_params['range'][0], attr_randomization_params['range'][1]
    else:
        # For gaussian: buckets span 2 stddev from mean
        lo = attr_randomization_params['range'][0] - 2 * np.sqrt(attr_randomization_params['range'][1])
        hi = attr_randomization_params['range'][0] + 2 * np.sqrt(attr_randomization_params['range'][1])
    num_buckets = attr_randomization_params['num_buckets']
    buckets = [(hi - lo) * i / num_buckets + lo for i in range(num_buckets)]
    return buckets[bisect(buckets, new_prop_val) - 1]

Property Getter/Setter Maps

def get_property_setter_map(gym):
    return {
        "dof_properties": gym.set_actor_dof_properties,
        "tendon_properties": gym.set_actor_tendon_properties,
        "rigid_body_properties": gym.set_actor_rigid_body_properties,
        "rigid_shape_properties": gym.set_actor_rigid_shape_properties,
        "sim_params": gym.set_sim_params,
    }

def get_default_setter_args(gym):
    return {
        "dof_properties": [],
        "tendon_properties": [],
        "rigid_body_properties": [True],  # recompute inertia
        "rigid_shape_properties": [],
        "sim_params": [],
    }

Related Pages

• Principle:Isaac_sim_IsaacGymEnvs_Runtime_Randomization
• Heuristic:Isaac_sim_IsaacGymEnvs_DR_Setup_Only_Flag