or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

composer.mdindex.mdmjcf.mdphysics.mdsuite.mdviewer.md
tile.json

tessl/pypi-dm-control

Continuous control environments and MuJoCo Python bindings for physics-based simulation and Reinforcement Learning

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/dm-control@1.0.x

To install, run

npx @tessl/cli install tessl/pypi-dm-control@1.0.0

index.mddocs/

dm-control

DeepMind's comprehensive software stack for physics-based simulation and Reinforcement Learning environments, built on top of the MuJoCo physics engine. Provides Python bindings to MuJoCo physics, a suite of RL environments, an interactive environment viewer, and libraries for composing and modifying MuJoCo MJCF models.

Package Information

  • Package Name: dm-control
  • Language: Python
  • Installation: pip install dm-control

Core Imports

import dm_control

Common for working with RL environments:

from dm_control import suite

For physics simulation:

from dm_control import mujoco

For MJCF model manipulation:

from dm_control import mjcf

For environment composition:

from dm_control import composer

Basic Usage

from dm_control import suite

# Load a built-in environment
env = suite.load('cartpole', 'balance')

# Reset environment and get initial observation
time_step = env.reset()
print(f"Initial observation: {time_step.observation}")

# Take a random action
action = env.action_spec().generate_value()
time_step = env.step(action)

# Render the environment
pixels = env.physics.render(height=240, width=320, camera_id=0)

For physics simulation:

from dm_control.mujoco import Physics

# Load a physics model from XML
physics = Physics.from_xml_path('/path/to/model.xml')

# Apply controls and step simulation
physics.set_control([0.1, -0.2, 0.5])
physics.step()

# Access named data elements
joint_positions = physics.named.data.qpos
print(f"Joint positions: {joint_positions}")

Architecture

dm-control is organized into several interconnected modules:

  • Suite: Pre-built RL environments with standardized tasks across different domains
  • MuJoCo: Low-level physics simulation bindings and utilities
  • MJCF: Object-oriented library for creating and manipulating MuJoCo XML models
  • Composer: Framework for programmatically building complex RL environments
  • Locomotion: Specialized environments and utilities for locomotion research
  • Viewer: Interactive GUI for visualizing and controlling environments

The package follows a layered architecture where higher-level modules (Suite, Composer) build upon lower-level physics simulation (MuJoCo) and model definition (MJCF) capabilities.

Capabilities

Environment Suite

Pre-built collection of continuous control RL environments across diverse domains including locomotion, manipulation, and classic control. Provides standardized interfaces, consistent action/observation spaces, and benchmark task definitions.

def load(domain_name: str, task_name: str, task_kwargs=None, environment_kwargs=None, visualize_reward=False):
    """Load an environment from the suite."""

def build_environment(domain_name: str, task_name: str, task_kwargs=None, environment_kwargs=None, visualize_reward=False):
    """Build environment with comprehensive error handling."""

# Available environment collections
ALL_TASKS: tuple  # All available (domain, task) pairs
BENCHMARKING: tuple  # Benchmarking task subset
EASY: tuple  # Easy difficulty tasks
HARD: tuple  # Hard difficulty tasks
TASKS_BY_DOMAIN: dict  # Tasks organized by domain

Environment Suite

Physics Simulation

Low-level MuJoCo physics simulation interface providing direct access to the physics engine, rendering capabilities, and state management. Enables fine-grained control over simulation parameters and dynamics.

class Physics:
    """Main MuJoCo physics simulation interface."""
    
    @classmethod
    def from_xml_path(cls, xml_path: str) -> 'Physics':
        """Create Physics instance from XML file."""
    
    def step(self) -> None:
        """Advance simulation by one timestep."""
    
    def set_control(self, control: np.ndarray) -> None:
        """Set control signals for actuators."""
    
    def render(self, height: int, width: int, camera_id: int = 0) -> np.ndarray:
        """Render camera view to numpy array."""

class Camera:
    """Camera for rendering and scene queries."""
    
    def render(self) -> np.ndarray:
        """Render camera view."""

Physics Simulation

MJCF Model Building

Object-oriented library for creating, manipulating, and composing MuJoCo MJCF models programmatically. Provides high-level abstractions for model elements while maintaining full compatibility with MuJoCo's XML format.

def from_xml_string(xml_string: str) -> 'RootElement':
    """Parse MJCF model from XML string."""

def from_path(path: str) -> 'RootElement':
    """Parse MJCF model from file path."""

class RootElement:
    """Root element of MJCF model."""
    
class Element:
    """Base class for MJCF elements."""
    
def export_with_assets(model, out_dir: str) -> None:
    """Export model with all assets to directory."""

MJCF Model Building

Environment Composition

Framework for programmatically building complex RL environments by combining entities, arenas, and tasks. Enables modular environment design with reusable components and flexible composition patterns.

class Environment:
    """Composer environment for custom RL tasks."""
    
class Entity:
    """Base class for environment entities."""
    
class Arena:
    """Base class for environment arenas."""
    
class Task:
    """Base class for RL tasks."""
    
class Robot:
    """Base class for robotic entities."""
    
@cached_property
def cached_property(func):
    """Cached property decorator."""
    
@observable
def observable(func):
    """Observable decorator for entity properties."""

Environment Composition

Environment Viewer

Interactive GUI application for visualizing environments, executing policies, and exploring simulation dynamics. Provides real-time rendering, camera controls, and policy execution capabilities.

def launch(environment_loader, policy=None, title='Explorer', width=1024, height=768) -> None:
    """
    Launch interactive environment viewer.
    
    Parameters:
    - environment_loader: Callable that returns Environment instance
    - policy: Optional policy function for automatic control
    - title: Window title
    - width, height: Window dimensions
    """

Environment Viewer

Types

# Core environment types
class TimeStep:
    """Environment timestep containing observations and rewards."""
    observation: dict
    reward: float
    discount: float
    step_type: int

# Physics types  
class NamedView:
    """Named view of MuJoCo data structures."""
    model: object
    data: object

# Composer types
class Observables:
    """Collection of observable quantities."""
    
class EpisodeInitializationError(Exception):
    """Error during episode initialization."""