How to Enable and Configure COM Randomization in Microduck RL

Enable Center‑of‑Mass (CoM) randomization in Microduck RL by adding the randomize_com event term to your environment configuration, setting the field (e.g., "com_position"), body_set (e.g., "all" or "head"), and range parameters to control the randomization envelope.

CoM randomization is a critical domain randomization technique that improves policy robustness by varying the robot's mass distribution during training. In the pollen-robotics/microduck_rl framework, this is implemented as a configurable event term that integrates directly with the curriculum system.

What Is COM Randomization in Microduck RL

Center‑of‑Mass randomization perturbs the robot's mass distribution by applying offset values to body center‑of‑mass positions. This simulates manufacturing tolerances, payload variations, and modeling uncertainties that real robots encounter.

The implementation lives in two layers:

• MDP core: The randomize_com function in src/mjlab_microduck/tasks/mdp.py (line 5602) handles the physics manipulation
• Configuration: Environment config files define when and how the randomization applies via EventTermCfg

Locating the Core Implementation

The randomization logic resides in src/mjlab_microduck/tasks/mdp.py. The randomize_com function:

• Samples new offsets per episode using a configurable range
• Supports multiple body sets ("all" for full robot, "head" for head‑only)
• Caches offsets to prevent accumulation across environment resets
• Respects the field parameter to target specific CoM properties

# From mdp.py - conceptual structure

def randomize_com(env, event_cfg):
    # Samples offset from event_cfg.range

    # Applies to bodies in event_cfg.body_set

    # Resets cleanly on each episode

Configuring the Event Term

The EventTermCfg class connects the MDP function to your training pipeline. Key parameters include:

Parameter	Purpose	Typical Values
event_name	Must be "randomize_com" to invoke the correct function	"randomize_com"
field	Which CoM property to randomize	"com_position", "head_com_position"
body_set	Scope of affected bodies	"all", "head"
range	Min/max offset in meters	(-0.01, 0.01), (-0.03, 0.03)
seed	Optional reproducibility control	None, int

The default walking environment demonstrates this configuration in src/mjlab_microduck/tasks/microduck_velocity_env_cfg.py (line 414).

Step‑by‑Step Configuration

Add CoM Randomization to a Custom Environment

Create or modify an environment configuration file:

from mjlab_microduck.tasks import EventTermCfg

def make_my_custom_env_cfg(play: bool = False):
    cfg = make_microduck_velocity_env_cfg(play=play)
    
    # Enable CoM randomization with ±1cm range

    cfg.events["randomize_com"] = EventTermCfg(
        event_name="randomize_com",
        field="com_position",
        body_set="all",
        range=(-0.01, 0.01),
        seed=None,
    )
    return cfg

Adjust Randomization Intensity

Modify the range for more aggressive domain randomization:

# Increase to ±3cm for harder generalization

cfg.events["randomize_com"].params["range"] = (-0.03, 0.03)

Disable for Deterministic Evaluation

Remove the event entirely when you need reproducible behavior:

cfg.events.pop("randomize_com", None)

Curriculum Integration

The randomize_com event integrates with Microduck RL's curriculum system. The curriculum manager uses event_name to schedule when randomization activates during training.

Example progression strategy:

• Early training: No CoM randomization (stable learning)
• Mid training: Activate with small range (-0.01, 0.01)
• Late training: Expand to (-0.03, 0.03) for robustness

Reference implementations in roller‑based environments (microduck_velocity_rollers_env_cfg.py, microduck_standup_env_cfg.py, microduck_spin_env_cfg.py) show how multiple environments share this pattern.

Validation and Testing

The test suite validates proper event configuration. Key test file: tests/test_roller_standup_cfg.py (lines 370‑371) verifies the randomize_com event is present in the configuration.

Run the full test suite to validate your changes:

uv run --with pytest pytest tests/

Pre‑built Environment Examples

Multiple environment configurations already include randomize_com:

• microduck_velocity_env_cfg.py — Default walking with CoM randomization
• microduck_velocity_rollers_env_cfg.py — Roller locomotion variant
• microduck_standup_env_cfg.py — Stand‑up task
• microduck_spin_env_cfg.py — Spin behavior training

Each demonstrates slightly different parameter choices for task‑appropriate randomization.

Summary

• Enable CoM randomization by adding a randomize_com entry to cfg.events using EventTermCfg
• Configure scope with body_set ("all" or "head") and intensity with range (meters)
• Control timing via curriculum scheduling using the event_name field
• Locate implementation in src/mjlab_microduck/tasks/mdp.py and default configs in src/mjlab_microduck/tasks/microduck_velocity_env_cfg.py
• Validate your setup with pytest tests/

Frequently Asked Questions

What bodies can I randomize with randomize_com?

The body_set parameter accepts "all" for the full robot or "head" for head‑only randomization. According to the source code in mdp.py, these are the predefined body sets; custom sets require modifying the underlying body grouping logic.

How do I prevent CoM offsets from accumulating across episodes?

The randomize_com implementation caches original CoM values and applies fresh samples each episode rather than adding to previous offsets. This ensures consistent randomization behavior regardless of episode count.

Can I use different randomization ranges for different training phases?

Yes. The curriculum system in Microduck RL schedules events by event_name. Define multiple curriculum stages that modify or toggle the randomize_com event parameters at specific training iterations.

Does the seed parameter guarantee reproducible CoM values across runs?

Setting seed to a fixed integer makes the randomization deterministic for that environment instance. For full reproducibility across distributed training, ensure all environment workers receive coordinated seed values.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}