How to Specify a Backlash Twin Task in Microduck RL Training

Microduck RL automatically registers backlash twin tasks during initialization by wrapping standard task configurations with make_backlash_variant, which swaps the robot model for a backlash-aware version and updates observation terms.

The pollen-robotics/microduck_rl repository implements backlash twin tasks to simulate realistic gear-play in robotics training. When you specify a backlash twin task in Microduck RL, the framework automatically wraps your base configuration with specialized handlers that account for mechanical backlash without changing observation or action dimensions.

Understanding the Backlash Twin Task ID Convention

All backlash twins follow a strict naming convention. The framework inserts the string -Backlash- immediately before MicroDuck in the standard task ID.

For example, the standard velocity task Mjlab-Velocity-Flat-MicroDuck becomes Mjlab-Velocity-Flat-Backlash-MicroDuck. This convention applies across all task types including velocity, locomotion, and manipulation scenarios.

How Backlash Tasks Are Registered in Microduck RL

Registration occurs automatically when the package initializes. In src/mjlab_microduck/tasks/__init__.py, the framework defines a tuple _BACKLASH_TASKS that maps base task creators to their backlash-specific configurations.

The _BACKLASH_TASKS Tuple Structure

Each entry in _BACKLASH_TASKS contains four elements: the base task creator function, any additional keyword arguments, the RL configuration class, and the appropriate backlash robot configuration. The available robot configs include _BL_WALK, _BL_ALLCOL, and _BL_ROLLERS, which correspond to different locomotion modes.

The Registration Flow

A loop iterates through _BACKLASH_TASKS and calls register_mjlab_task with a modified configuration returned by make_backlash_variant. This function, implemented in src/mjlab_microduck/tasks/backlash.py, transforms the standard task configuration into its backlash twin before registration completes.

What make_backlash_variant Modifies

The make_backlash_variant function performs four critical modifications to the base configuration. These changes ensure the simulation accurately models mechanical backlash while maintaining training stability.

Robot Model Substitution

The function replaces the standard robot entity with a backlash-specific version. It selects from predefined constants in src/mjlab_microduck/robot/microduck_constants.py, such as MICRODUCK_WALK_BACKLASH_ROBOT_CFG, which define robots with ±1° gear-play hinges.

Observation Term Updates

Standard observation terms joint_pos and joint_vel are swapped for backlash-aware equivalents. The framework uses joint_pos_rel_backlash and joint_vel_rel_backlash, implemented in mdp.py, which calculate positions and velocities relative to the backlash joint states.

Reward Function Adjustments

The function modifies the soft-limit reward to ignore the newly added passive backlash joints. It also updates the pose-reward entity selector so that regular expressions that previously matched all non-passive joints now explicitly exclude entries matching *_backlash.

Preserved Dimensions

Despite these modifications, the returned ManagerBasedRlEnvCfg maintains identical observation and action dimensions. Both remain at 61 observations and 14 actions, ensuring compatibility with pre-trained policies and network architectures.

Running a Backlash Twin Task from the CLI

Once installed, launch a backlash twin exactly like any standard task. The training script located at src/mjlab_microduck/train_cli.py automatically resolves the task ID and constructs the appropriate environment.

uv run train Mjlab-Velocity-Flat-Backlash-MicroDuck --env.scene.num-envs 64

For large-scale training with rough terrain, increase the parallel environment count:

uv run train Mjlab-Velocity-Rough-Backlash-MicroDuck \
    --env.scene.num-envs 4096 \
    --agent.max_iterations 5000

Manual Creation of Backlash Variants (Python API)

While automatic registration handles most use cases, you can manually create backlash variants for custom experiments. Import make_backlash_variant and the appropriate robot configuration, then convert any base task configuration.

from mjlab_microduck.tasks import make_backlash_variant
from mjlab_microduck.tasks.microduck_velocity_env_cfg import (
    make_microduck_velocity_env_cfg,
)
from mjlab_microduck.robot.microduck_constants import (
    MICRODUCK_WALK_BACKLASH_ROBOT_CFG,
)

# Create base configuration for flat ground

base_cfg = make_microduck_velocity_env_cfg()

# Convert to backlash twin

backlash_cfg = make_backlash_variant(
    base_cfg,
    robot_cfg=MICRODUCK_WALK_BACKLASH_ROBOT_CFG,
)

# Use with trainer or export to ONNX

This approach allows fine-grained control over the conversion process when the automatic registration does not meet specific experimental requirements.

Summary

• Backlash twin tasks use the -Backlash- infix in their task IDs, positioned before MicroDuck.
• Registration occurs automatically in src/mjlab_microduck/tasks/__init__.py through the _BACKLASH_TASKS tuple and make_backlash_variant.
• The make_backlash_variant function in src/mjlab_microduck/tasks/backlash.py swaps robot models, updates observation terms to joint_pos_rel_backlash/joint_vel_rel_backlash, and adjusts rewards to ignore passive backlash joints.
• Observation and action dimensions remain fixed at 61/14 regardless of backlash configuration.
• Launch twins via CLI using standard syntax, or manually create configurations using the Python API.

Frequently Asked Questions

What is the naming convention for backlash twin tasks?

Insert -Backlash- immediately before MicroDuck in the standard task ID. For example, Mjlab-Velocity-Flat-MicroDuck becomes Mjlab-Velocity-Flat-Backlash-MicroDuck. This convention is enforced by the registration logic in src/mjlab_microduck/tasks/__init__.py.

How does make_backlash_variant affect observation dimensions?

The function preserves the original observation and action dimensions. Despite adding backlash-specific joint states internally, the environment maintains 61 observations and 14 actions, ensuring compatibility with existing policy networks.

Can I create a backlash variant for custom tasks?

Yes. Import make_backlash_variant from src/mjlab_microduck/tasks/backlash.py and pass your custom ManagerBasedRlEnvCfg along with a backlash robot configuration from microduck_constants.py. This manual approach bypasses the automatic registration in __init__.py.

Which robot configurations are available for backlash variants?

The repository provides three primary backlash robot configurations in src/mjlab_microduck/robot/microduck_constants.py: _BL_WALK for standard locomotion, _BL_ALLCOL for collision-robust scenarios, and _BL_ROLLERS for wheeled locomotion. Each maps to constants like MICRODUCK_WALK_BACKLASH_ROBOT_CFG.

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