Implementation:Google deepmind Dm control MuJoCo Index
| Knowledge Sources | |
|---|---|
| Domains | Robotics Simulation, Data Access |
| Last Updated | 2026-02-15 04:00 GMT |
Overview
The index module implements named indexing for MuJoCo model and data arrays, allowing users to access simulation data by human-readable element names (e.g., data.qpos['hinge']) instead of raw integer indices.
Description
The module builds a mapping from MuJoCo dimension size names (such as nbody, ngeom, njnt) to lists of element names by parsing the name address arrays in mjModel. It constructs Axis objects for each dimension, with two concrete implementations: RegularNamedAxis for dimensions where each name maps to exactly one index (e.g., body positions), and RaggedNamedAxis for dimensions where names map to variable-length slices (e.g., qpos indices per joint depend on joint type -- a free joint uses 7 indices while a hinge uses 1). Hard-coded column names (e.g., x, y, z for 3D position fields; qw, qx, qy, qz for quaternion fields; r, g, b, a for RGBA fields) provide named access to the second dimension of 2D arrays.
FieldIndexer wraps individual numpy arrays from MuJoCo structs and intercepts __getitem__ and __setitem__ to convert string-based keys into numpy-compatible indices via the appropriate Axis objects. It also provides a rich __repr__ method that displays element names alongside array values for interactive inspection. The struct_indexer function creates an immutable container (via make_struct_indexer) where each dynamically-sized field in an mjModel or mjData struct is exposed as a FieldIndexer.
The make_axis_indexers function is the main entry point: it takes an MjModel instance, extracts element names from the model's name arrays, computes element sizes for ragged dimensions from address arrays, handles special cases like mocap bodies and named columns, and returns a dictionary mapping size names to Axis objects.
Usage
This module powers the physics.named.data and physics.named.model interfaces used throughout dm_control tasks and user code. It is typically not used directly; instead, users access named indexing through the Physics wrapper. Use named indexing whenever you need to read or write simulation data by element name rather than integer index.
Code Reference
Source Location
- Repository: Google_deepmind_Dm_control
- File: dm_control/mujoco/index.py
- Lines: 1-674
Signature
class Axis(metaclass=abc.ABCMeta):
@abc.abstractmethod
def convert_key_item(self, key_item): ...
class UnnamedAxis(Axis):
def convert_key_item(self, key_item): ...
class RegularNamedAxis(Axis):
def __init__(self, names): ...
def convert_key_item(self, key_item): ...
class RaggedNamedAxis(Axis):
def __init__(self, element_names, element_sizes, singleton=False): ...
def convert_key_item(self, key_item): ...
class FieldIndexer:
def __init__(self, parent_struct, field_name, axis_indexers): ...
def __getitem__(self, key): ...
def __setitem__(self, key, value): ...
def make_axis_indexers(model) -> dict: ...
def struct_indexer(struct, struct_name, size_to_axis_indexer) -> StructIndexer: ...
def make_struct_indexer(field_indexers) -> StructIndexer: ...
Import
from dm_control.mujoco import index
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| model | mjbindings.MjModelWrapper | Yes (for make_axis_indexers) | A MuJoCo model instance used to extract element names and sizes |
| struct | MjModel or MjData wrapper | Yes (for struct_indexer) | The wrapped ctypes structure to create indexers for |
| struct_name | str | Yes (for struct_indexer) | MuJoCo struct name (e.g., 'mjmodel', 'mjdata') |
| size_to_axis_indexer | dict | Yes (for struct_indexer) | Dictionary mapping size names to Axis instances (from make_axis_indexers) |
| key | str, int, list, or slice | Yes (for FieldIndexer) | The indexing expression (may contain element names) |
Outputs
| Name | Type | Description |
|---|---|---|
| make_axis_indexers() | dict[str, Axis] | Mapping from size names to Axis objects for named indexing |
| struct_indexer() | StructIndexer | Immutable container with FieldIndexer attributes for each dynamic field |
| FieldIndexer[key] | np.ndarray | The indexed array data, with string keys converted to numeric indices |
Usage Examples
Basic Usage
# Named indexing is typically accessed through the Physics wrapper:
from dm_control import suite
env = suite.load('cartpole', 'swingup')
physics = env.physics
# Access body position by name
cart_pos = physics.named.data.xpos['cart']
pole_pos = physics.named.data.xpos['pole_1']
# Access joint position by name
hinge_qpos = physics.named.data.qpos['hinge_1']
# Access with column names
cart_x = physics.named.data.xpos['cart', 'x']
cart_z = physics.named.data.xpos['cart', 'z']
# Set values by name
physics.named.data.qpos['hinge_1'] = 0.5
Direct Module Usage
from dm_control.mujoco import index
# Build axis indexers from a model
axis_indexers = index.make_axis_indexers(model)
# Create a struct indexer for named data access
named_data = index.struct_indexer(data, 'mjdata', axis_indexers)
fingertip_xpos = named_data.xpos['fingertip']