Implementation:Google deepmind Dm control Composer Define

Knowledge Sources	Google_deepmind_Dm_control
Domains	Composer, Observables
Last Updated	2026-02-15 04:00 GMT

Overview

The define module provides decorators for Entity methods returning MJCF elements and observables, enabling lazy evaluation and thread-safe caching of these properties.

Description

The module defines cached_property, a thread-safe descriptor that extends Python's built-in property. It evaluates the decorated function only once per object instance, storing the result in the instance's __dict__ and returning the cached value on subsequent accesses. For thread safety, it uses a threading.RLock but optimistically attempts a dict lookup before acquiring the lock, which profiling has shown saves a non-trivial amount of time.

The observable class extends cached_property and serves as a semantic marker for methods on Observables subclasses that return observable objects. The body of the decorated function is evaluated at Entity construction time and the observable is cached. An abstract_observable alias wraps abc.abstractproperty for declaring abstract observable requirements in base classes, indicating that subclasses need to implement a corresponding @observable-annotated method.

Usage

Use @define.cached_property to cache expensive MJCF element lookups on Entity subclasses. Use @define.observable to declare observables that should be cached after first evaluation. Use @define.abstract_observable in abstract base classes to require that subclasses provide specific observables.

Code Reference

Source Location

• Repository: Google_deepmind_Dm_control
• File: dm_control/composer/define.py
• Lines: 1-61

Signature

class cached_property(property):
    def __init__(self, func, doc=None):
    def __get__(self, obj, cls):

# Alias for abc.abstractproperty
abstract_observable = abc.abstractproperty

class observable(cached_property):
    """A decorator for base.Observables methods returning an observable."""
    pass

Import

from dm_control.composer import define

I/O Contract

Inputs

Name	Type	Required	Description
func	callable	Yes	The method to be decorated and cached
doc	str	No	Optional docstring for the property

Outputs

Name	Type	Description
cached_property	descriptor	A property descriptor that evaluates only once and caches the result in the instance dict
observable	descriptor	Same as cached_property but semantically marks the method as returning an observable

Usage Examples

from dm_control.composer import define
from dm_control.composer.observation.observable import base as observable_base


class MyEntityObservables:

    @define.observable
    def joint_positions(self):
        return observable_base.MJCFFeature('qpos', self._entity.joints)

    @define.observable
    def body_position(self):
        return observable_base.MJCFFeature('xpos', self._entity.root_body)


class MyEntity:

    @define.cached_property
    def joints(self):
        """Returns and caches the joint elements."""
        return self.mjcf_model.find_all('joint')