Principle:Google deepmind Dm control Entity Definition

Attribute	Value
Principle	Entity Definition
Workflow	Composer_Environment_Building
Domain	Reinforcement_Learning, Composition
Source	dm_control
Last Updated	2026-02-15 00:00 GMT

Overview

An entity is a self-contained, reusable physical object that encapsulates its own MJCF model, observables, and lifecycle callbacks within a compositional simulation framework.

Description

In physics-based reinforcement learning, environments are assembled from many distinct physical objects: robots, props, terrain features, and sensors. Without a principled abstraction, code for defining these objects becomes entangled with code for building the full scene and computing rewards. The Entity Definition principle addresses this by requiring every physical object to be represented as an independent unit that:

Owns a single MJCF (MuJoCo XML) sub-model describing its geometry, joints, actuators, and sensors.
Declares the set of observables it can produce (joint angles, positions, camera images, etc.).
Exposes lifecycle callbacks (episode initialization, before/after simulation steps) so that per-object logic runs at the correct phase of the simulation loop.
Supports hierarchical attachment so that one entity can be rigidly or freely connected to another, forming a tree of sub-models that is compiled into a single physics scene.

The entity is deliberately separated from the concept of a task (which defines rewards and termination) and an arena (which defines the ground plane and lighting). This separation ensures that the same robot or prop entity can be reused across many different tasks and arenas without modification.

A specialized sub-type, the Robot, extends the base entity by additionally requiring an actuators property, acknowledging that controllable agents have a distinguished set of actuator elements.

The entity also provides a cached property mechanism through a decorator that evaluates a property exactly once per object instance and stores the result. This is used both for MJCF element look-ups (which should not change after construction) and for observable construction.

Usage

Use the Entity Definition principle whenever you need to model a discrete physical object in a compositional simulation:

Defining a robot: Subclass the Robot variant, implement _build to load or construct the MJCF model, and expose actuators.
Defining a prop: Subclass Entity directly, implement _build and mjcf_model.
Attaching objects together: Call entity.attach(child_entity) to rigidly connect a child model to a parent at a designated attachment site.
Providing observations: Override _build_observables to return an Observables subclass whose methods are decorated with @define.observable.
Per-episode variation: Override initialize_episode_mjcf to modify the MJCF model between episodes, or initialize_episode to set physics state at the start of each episode.

Theoretical Basis

The Entity Definition principle follows a well-known pattern in software engineering called the Component or Compositional Model pattern. Each entity is a component with:

Entity
  +-- mjcf_model        (data: the XML sub-model)
  +-- observables        (outputs: what can be observed)
  +-- callbacks          (hooks: lifecycle methods)
  +-- children[]         (composition: attached sub-entities)
  +-- parent?            (back-reference to parent entity)

The lifecycle of an entity within an episode proceeds as:

for each episode:
    entity.initialize_episode_mjcf(random_state)   # modify XML if needed
    # physics is recompiled
    entity.after_compile(physics, random_state)     # cache compiled bindings
    entity.initialize_episode(physics, random_state) # set initial state
    for each control step:
        entity.before_step(physics, random_state)
        for each physics substep:
            entity.before_substep(physics, random_state)
            physics.step()
            entity.after_substep(physics, random_state)
        entity.after_step(physics, random_state)

The hierarchical attachment model means the full MJCF scene is the union of all entity sub-models, merged by the MJCF library at compile time. Each entity retains a weak reference to its parent, enabling traversal of the entity tree via iter_entities.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment