Principle:Isaac sim IsaacGymEnvs Runtime Randomization
| Knowledge Sources | |
|---|---|
| Domains | |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Mechanism for sampling random values from configured distributions and applying them to physics properties during simulation. This principle covers the low-level random sample generation and property modification that underpins the domain randomization engine.
Description
At runtime (typically on environment resets), the DR system generates random samples from specified distributions and applies them to physics properties via additive or scaling operations. The utility functions in dr_utils.py provide the core sampling and application logic used by both VecTask and ADRVecTask.
The runtime randomization pipeline has three stages:
Stage 1 -- Sample Generation: generate_random_samples() draws samples from the configured distribution:
- Gaussian:
np.random.normal(mu, var, shape)-- mean and variance parameterized. - Uniform:
np.random.uniform(lo, hi, shape)-- bounded interval. - Log-uniform:
exp(np.random.uniform(log(lo), log(hi), shape))-- uniform in log-space, producing samples that span orders of magnitude naturally.
Schedule scaling is applied to modulate randomization strength over training: linear schedules ramp from zero to full, constant schedules toggle at a threshold step.
Stage 2 -- Property Application: apply_random_samples() takes the generated sample and combines it with the original property value:
- Additive:
new_value = original_value + sample - Scaling:
new_value = original_value * sample
The function handles three property types: gymapi.SimParams (gravity, rest_offset), np.ndarray (structured arrays like DOF properties), and individual scalar properties.
Stage 3 -- Material Bucketing: For PhysX shape properties, get_bucketed_val() quantizes continuous values to the nearest bucket to stay within PhysX's 64K material limit. check_buckets() validates the total bucket count before simulation begins.
External samples can be provided via extern_sample for correlated randomization across properties (e.g., from a full-covariance distribution via actor_params_generator).
Usage
These utility functions are called internally by apply_randomizations() -- they are not typically invoked directly by task implementations:
from isaacgymenvs.utils.dr_utils import (
apply_random_samples,
generate_random_samples,
check_buckets,
get_bucketed_val,
)
Theoretical Basis
The runtime randomization follows a stratified sampling with bucketed quantization pattern:
RANDOMIZE(property, original, params, step):
1. SAMPLE = draw from distribution(params.range, params.distribution)
2. Apply schedule scaling:
- linear: scale = min(step, schedule_steps) / schedule_steps
- constant: scale = 0 if step < schedule_steps else 1
- none: scale = 1
3. Apply operation:
- additive: new_val = original + (SAMPLE * scale)
- scaling: new_val = original * (SAMPLE * scale + 1 * (1 - scale))
4. If num_buckets specified:
- Quantize new_val to nearest bucket in [lo, hi] / num_buckets
5. Set property via gym API
Key design decisions:
- Schedule scaling for scaling operations interpolates between 1.0 (no randomization) and the sampled value, ensuring smooth ramp-up. For additive operations, it simply scales the sample magnitude.
- Log-uniform sampling is critical for parameters like damping and stiffness where the ratio matters more than absolute difference. Sampling uniformly in log-space gives equal probability to each order of magnitude.
- Bucketed quantization uses bisect to find the nearest bucket boundary, trading continuous variation for PhysX material compatibility. The bucket boundaries are linearly spaced between the distribution's low and high bounds.