Heuristic:Isaac sim IsaacGymEnvs DR Setup Only Flag

Knowledge Sources	IsaacGymEnvs Domain Randomization Docs Reproducibility Docs
Domains	Domain_Randomization, Reproducibility
Last Updated	2026-02-15 09:00 GMT

Overview

Use the `setup_only` flag for object scale and mass randomization to prevent GPU simulation instability and non-deterministic behavior during runtime domain randomization.

Description

IsaacGymEnvs supports domain randomization of physics properties (stiffness, damping, mass, scale) at runtime. However, randomizing object scales and masses during simulation (on environment resets) causes instability and non-determinism due to how these parameters are transferred from CPU to GPU in lower-level PhysX APIs. The `setup_only` flag restricts randomization to occur only once before simulation begins, applied uniformly across all environments.

Usage

Use this heuristic when configuring domain randomization for any task that randomizes scale or mass properties. Always set `setup_only: True` for scale and mass parameters in the DR YAML configuration. Other DR parameters (stiffness, damping, friction) can safely be randomized at runtime without this flag. This is especially critical for GPU-accelerated simulation where parallel environment updates interact with lower-level APIs.

The Insight (Rule of Thumb)

Action: Set `setup_only: True` in DR YAML for `scale` and mass-related properties.
Value: Randomization applied once at initialization instead of on every reset.
Trade-off: Less diversity in scale/mass across episode boundaries (all environments get the same randomized value). Stiffness, damping, and friction can still be randomized per-reset.
PhysX Limitation: Domain randomizations can only be applied on environment resets, not during simulation steps, due to PhysX constraints.

Reasoning

The PhysX GPU simulation processes scale and mass changes through a CPU-to-GPU synchronization path that is not deterministic when applied to subsets of environments at different times. The `setup_only` flag ensures all environments receive their randomized values simultaneously before any simulation step occurs, avoiding the race condition.

From `vec_task.py:610-617` (apply_randomizations docstring):

def apply_randomizations(self, dr_params):
    """Apply domain randomizations to the environment.

    Note that currently we can only apply randomizations only on resets,
    due to current PhysX limitations
    """

The `setup_only` check in the randomization loop from `vec_task.py:798-799`:

setup_only = attr_randomization_params.get('setup_only', False)
if (setup_only and not self.sim_initialized) or not setup_only:

Scale randomization path from `vec_task.py:775-787`:

if prop_name == 'scale':
    setup_only = prop_attrs.get('setup_only', False)
    if (setup_only and not self.sim_initialized) or not setup_only:
        # ... apply scale randomization ...
        self.gym.set_actor_scale(env, handle, new_scale)
    continue

From `docs/reproducibility.md`:

Runtime domain randomization of object scales or masses are known to cause both determinacy and simulation issues when running on the GPU. By default, in examples that use Domain Randomization, we use the `setup_only` flag to only randomize scales and masses once across all environments before simulation starts.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment