0
# dm-control
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: dm-control
7
- **Language**: Python
8
- **Installation**: `pip install dm-control`
9

10
## Core Imports
11

12
```python
13
import dm_control
14
```
15

16
Common for working with RL environments:
17

18
```python
19
from dm_control import suite
20
```
21

22
For physics simulation:
23

24
```python
25
from dm_control import mujoco
26
```
27

28
For MJCF model manipulation:
29

30
```python
31
from dm_control import mjcf
32
```
33

34
For environment composition:
35

36
```python
37
from dm_control import composer
38
```
39

40
## Basic Usage
41

42
```python
43
from dm_control import suite
44

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

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

52
# Take a random action
53
action = env.action_spec().generate_value()
54
time_step = env.step(action)
55

56
# Render the environment
57
pixels = env.physics.render(height=240, width=320, camera_id=0)
58
```
59

60
For physics simulation:
61

62
```python
63
from dm_control.mujoco import Physics
64

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

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

72
# Access named data elements
73
joint_positions = physics.named.data.qpos
74
print(f"Joint positions: {joint_positions}")
75
```
76

77
## Architecture
78

79
dm-control is organized into several interconnected modules:
80

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

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

90
## Capabilities
91

92
### Environment Suite
93

94
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.
95

96
```python { .api }
97
def load(domain_name: str, task_name: str, task_kwargs=None, environment_kwargs=None, visualize_reward=False):
98
    """Load an environment from the suite."""
99

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

103
# Available environment collections
104
ALL_TASKS: tuple  # All available (domain, task) pairs
105
BENCHMARKING: tuple  # Benchmarking task subset
106
EASY: tuple  # Easy difficulty tasks
107
HARD: tuple  # Hard difficulty tasks
108
TASKS_BY_DOMAIN: dict  # Tasks organized by domain
109
```
110

111
[Environment Suite](./suite.md)
112

113
### Physics Simulation
114

115
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.
116

117
```python { .api }
118
class Physics:
119
    """Main MuJoCo physics simulation interface."""
120
    
121
    @classmethod
122
    def from_xml_path(cls, xml_path: str) -> 'Physics':
123
        """Create Physics instance from XML file."""
124
    
125
    def step(self) -> None:
126
        """Advance simulation by one timestep."""
127
    
128
    def set_control(self, control: np.ndarray) -> None:
129
        """Set control signals for actuators."""
130
    
131
    def render(self, height: int, width: int, camera_id: int = 0) -> np.ndarray:
132
        """Render camera view to numpy array."""
133

134
class Camera:
135
    """Camera for rendering and scene queries."""
136
    
137
    def render(self) -> np.ndarray:
138
        """Render camera view."""
139
```
140

141
[Physics Simulation](./physics.md)
142

143
### MJCF Model Building
144

145
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.
146

147
```python { .api }
148
def from_xml_string(xml_string: str) -> 'RootElement':
149
    """Parse MJCF model from XML string."""
150

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

154
class RootElement:
155
    """Root element of MJCF model."""
156
    
157
class Element:
158
    """Base class for MJCF elements."""
159
    
160
def export_with_assets(model, out_dir: str) -> None:
161
    """Export model with all assets to directory."""
162
```
163

164
[MJCF Model Building](./mjcf.md)
165

166
### Environment Composition
167

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

170
```python { .api }
171
class Environment:
172
    """Composer environment for custom RL tasks."""
173
    
174
class Entity:
175
    """Base class for environment entities."""
176
    
177
class Arena:
178
    """Base class for environment arenas."""
179
    
180
class Task:
181
    """Base class for RL tasks."""
182
    
183
class Robot:
184
    """Base class for robotic entities."""
185
    
186
@cached_property
187
def cached_property(func):
188
    """Cached property decorator."""
189
    
190
@observable
191
def observable(func):
192
    """Observable decorator for entity properties."""
193
```
194

195
[Environment Composition](./composer.md)
196

197
### Environment Viewer
198

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

201
```python { .api }
202
def launch(environment_loader, policy=None, title='Explorer', width=1024, height=768) -> None:
203
    """
204
    Launch interactive environment viewer.
205
    
206
    Parameters:
207
    - environment_loader: Callable that returns Environment instance
208
    - policy: Optional policy function for automatic control
209
    - title: Window title
210
    - width, height: Window dimensions
211
    """
212
```
213

214
[Environment Viewer](./viewer.md)
215

216
## Types
217

218
```python { .api }
219
# Core environment types
220
class TimeStep:
221
    """Environment timestep containing observations and rewards."""
222
    observation: dict
223
    reward: float
224
    discount: float
225
    step_type: int
226

227
# Physics types  
228
class NamedView:
229
    """Named view of MuJoCo data structures."""
230
    model: object
231
    data: object
232

233
# Composer types
234
class Observables:
235
    """Collection of observable quantities."""
236
    
237
class EpisodeInitializationError(Exception):
238
    """Error during episode initialization."""
239
```