Initializes manager term classes only when sim starts (#2117)

# Description

To support creation of managers before the simulation starts playing (as
needed by the event manager for USD randomizations), the MR in #2040
added a callback to resolve scene entities at runtime. However, certain
class-based manager terms can also not be initialized if the simulation
is not playing. Those terms may often rely on parameters that are only
available once simulation plays (for instance, joint position limits).

This MR moves the initializations of class-based manager terms to the
callback too.

Fixes #2136

## Type of change

- Bug fix (non-breaking change which fixes an issue)

## Checklist

- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

---------

Co-authored-by: Kelly Guo <kellyg@nvidia.com>

Author: Mayankm96

source/isaaclab/isaaclab/envs/direct_marl_env.py

@@ -135,7 +135,6 @@ def __init__(self, cfg: DirectMARLEnvCfg, render_mode: str | None = None, **kwar
         #   that must happen before the simulation starts. Example: randomizing mesh scale
         if self.cfg.events:
             self.event_manager = EventManager(self.cfg.events, self)
-            print("[INFO] Event Manager: ", self.event_manager)
 
             # apply USD-related randomization events
             if "prestartup" in self.event_manager.available_modes:
@@ -198,6 +197,9 @@ def __init__(self, cfg: DirectMARLEnvCfg, render_mode: str | None = None, **kwar
 
         # perform events at the start of the simulation
         if self.cfg.events:
+            # we print it here to make the logging consistent
+            print("[INFO] Event Manager: ", self.event_manager)
+
             if "startup" in self.event_manager.available_modes:
                 self.event_manager.apply(mode="startup")
 

source/isaaclab/isaaclab/envs/direct_rl_env.py

@@ -141,7 +141,6 @@ def __init__(self, cfg: DirectRLEnvCfg, render_mode: str | None = None, **kwargs
         #   that must happen before the simulation starts. Example: randomizing mesh scale
         if self.cfg.events:
             self.event_manager = EventManager(self.cfg.events, self)
-            print("[INFO] Event Manager: ", self.event_manager)
 
             # apply USD-related randomization events
             if "prestartup" in self.event_manager.available_modes:
@@ -202,6 +201,9 @@ def __init__(self, cfg: DirectRLEnvCfg, render_mode: str | None = None, **kwargs
 
         # perform events at the start of the simulation
         if self.cfg.events:
+            # we print it here to make the logging consistent
+            print("[INFO] Event Manager: ", self.event_manager)
+
             if "startup" in self.event_manager.available_modes:
                 self.event_manager.apply(mode="startup")
 

source/isaaclab/isaaclab/envs/manager_based_env.py

@@ -140,7 +140,6 @@ def __init__(self, cfg: ManagerBasedEnvCfg):
         # note: this is needed here (rather than after simulation play) to allow USD-related randomization events
         #   that must happen before the simulation starts. Example: randomizing mesh scale
         self.event_manager = EventManager(self.cfg.events, self)
-        print("[INFO] Event Manager: ", self.event_manager)
 
         # apply USD-related randomization events
         if "prestartup" in self.event_manager.available_modes:
@@ -232,6 +231,8 @@ def load_managers(self):
 
         """
         # prepare the managers
+        # -- event manager (we print it here to make the logging consistent)
+        print("[INFO] Event Manager: ", self.event_manager)
         # -- recorder manager
         self.recorder_manager = RecorderManager(self.cfg.recorders, self)
         print("[INFO] Recorder Manager: ", self.recorder_manager)

source/isaaclab/isaaclab/envs/mdp/events.py

@@ -1162,7 +1162,9 @@ def __init__(self, cfg: EventTermCfg, env: ManagerBasedEnv):
         event_name = cfg.params.get("event_name")
         texture_rotation = cfg.params.get("texture_rotation", (0.0, 0.0))
 
-        # check to make sure replicate_physics is set to False, else raise warning
+        # check to make sure replicate_physics is set to False, else raise error
+        # note: We add an explicit check here since texture randomization can happen outside of 'prestartup' mode
+        #   and the event manager doesn't check in that case.
         if env.cfg.scene.replicate_physics:
             raise RuntimeError(
                 "Unable to randomize visual texture material with scene replication enabled."
@@ -1260,7 +1262,9 @@ def __init__(self, cfg: EventTermCfg, env: ManagerBasedEnv):
         event_name = cfg.params.get("event_name")
         mesh_name: str = cfg.params.get("mesh_name", "")  # type: ignore
 
-        # check to make sure replicate_physics is set to False, else raise warning
+        # check to make sure replicate_physics is set to False, else raise error
+        # note: We add an explicit check here since texture randomization can happen outside of 'prestartup' mode
+        #   and the event manager doesn't check in that case.
         if env.cfg.scene.replicate_physics:
             raise RuntimeError(
                 "Unable to randomize visual color with scene replication enabled."

source/isaaclab/isaaclab/managers/event_manager.py

@@ -7,6 +7,7 @@
 
 from __future__ import annotations
 
+import inspect
 import torch
 from collections.abc import Sequence
 from prettytable import PrettyTable
@@ -186,15 +187,6 @@ def apply(
         if mode not in self._mode_term_names:
             omni.log.warn(f"Event mode '{mode}' is not defined. Skipping event.")
             return
-        # check if mode is pre-startup and scene replication is enabled
-        if mode == "prestartup" and self._env.scene.cfg.replicate_physics:
-            omni.log.warn(
-                "Scene replication is enabled, which may affect USD-level randomization."
-                " When assets are replicated, their properties are shared across instances,"
-                " potentially leading to unintended behavior."
-                " For stable USD-level randomization, consider disabling scene replication"
-                " by setting 'replicate_physics' to False in 'InteractiveSceneCfg'."
-            )
 
         # check if mode is interval and dt is not provided
         if mode == "interval" and dt is None:
@@ -363,6 +355,24 @@ def _prepare_terms(self):
 
             # resolve common parameters
             self._resolve_common_term_cfg(term_name, term_cfg, min_argc=2)
+
+            # check if mode is pre-startup and scene replication is enabled
+            if term_cfg.mode == "prestartup" and self._env.scene.cfg.replicate_physics:
+                raise RuntimeError(
+                    "Scene replication is enabled, which may affect USD-level randomization."
+                    " When assets are replicated, their properties are shared across instances,"
+                    " potentially leading to unintended behavior."
+                    " For stable USD-level randomization, please disable scene replication"
+                    " by setting 'replicate_physics' to False in 'InteractiveSceneCfg'."
+                )
+
+            # for event terms with mode "prestartup", we assume a callable class term
+            # can be initialized before the simulation starts.
+            # this is done to ensure that the USD-level randomization is possible before the simulation starts.
+            if inspect.isclass(term_cfg.func) and term_cfg.mode == "prestartup":
+                omni.log.info(f"Initializing term '{term_name}' with class '{term_cfg.func.__name__}'.")
+                term_cfg.func = term_cfg.func(cfg=term_cfg, env=self._env)
+
             # check if mode is a new mode
             if term_cfg.mode not in self._mode_term_names:
                 # add new mode

source/isaaclab/isaaclab/managers/manager_base.py

@@ -112,7 +112,7 @@ def __call__(self, *args) -> Any:
         Returns:
             The value of the term.
         """
-        raise NotImplementedError
+        raise NotImplementedError("The method '__call__' should be implemented by the subclass.")
 
 
 class ManagerBase(ABC):
@@ -136,32 +136,34 @@ def __init__(self, cfg: object, env: ManagerBasedEnv):
         self.cfg = copy.deepcopy(cfg)
         self._env = env
 
-        # parse config to create terms information
-        if self.cfg:
-            self._prepare_terms()
-
         # if the simulation is not playing, we use callbacks to trigger the resolution of the scene
         # entities configuration. this is needed for cases where the manager is created after the
         # simulation, but before the simulation is playing.
+        # FIXME: Once Isaac Sim supports storing this information as USD schema, we can remove this
+        #   callback and resolve the scene entities directly inside `_prepare_terms`.
         if not self._env.sim.is_playing():
             # note: Use weakref on all callbacks to ensure that this object can be deleted when its destructor
             # is called
             # The order is set to 20 to allow asset/sensor initialization to complete before the scene entities
             # are resolved. Those have the order 10.
             timeline_event_stream = omni.timeline.get_timeline_interface().get_timeline_event_stream()
-            self._resolve_scene_entities_handle = timeline_event_stream.create_subscription_to_pop_by_type(
+            self._resolve_terms_handle = timeline_event_stream.create_subscription_to_pop_by_type(
                 int(omni.timeline.TimelineEventType.PLAY),
-                lambda event, obj=weakref.proxy(self): obj._resolve_scene_entities_callback(event),
+                lambda event, obj=weakref.proxy(self): obj._resolve_terms_callback(event),
                 order=20,
             )
         else:
-            self._resolve_scene_entities_handle = None
+            self._resolve_terms_handle = None
+
+        # parse config to create terms information
+        if self.cfg:
+            self._prepare_terms()
 
     def __del__(self):
         """Delete the manager."""
-        if self._resolve_scene_entities_handle:
-            self._resolve_scene_entities_handle.unsubscribe()
-            self._resolve_scene_entities_handle = None
+        if self._resolve_terms_handle:
+            self._resolve_terms_handle.unsubscribe()
+            self._resolve_terms_handle = None
 
     """
     Properties.
@@ -206,7 +208,7 @@ def find_terms(self, name_keys: str | Sequence[str]) -> list[str]:
         specified as regular expressions or a list of regular expressions. The search is
         performed on the active terms in the manager.
 
-        Please check the :meth:`isaaclab.utils.string_utils.resolve_matching_names` function for more
+        Please check the :meth:`~isaaclab.utils.string_utils.resolve_matching_names` function for more
         information on the name matching.
 
         Args:
@@ -249,11 +251,10 @@ def _prepare_terms(self):
     Internal callbacks.
     """
 
-    def _resolve_scene_entities_callback(self, event):
-        """Resolve the scene entities configuration.
+    def _resolve_terms_callback(self, event):
+        """Resolve configurations of terms once the simulation starts.
 
-        This callback is called when the simulation starts. It is used to resolve the
-        scene entities configuration for the terms.
+        Please check the :meth:`_process_term_cfg_at_play` method for more information.
         """
         # check if config is dict already
         if isinstance(self.cfg, dict):
@@ -266,17 +267,26 @@ def _resolve_scene_entities_callback(self, event):
             # check for non config
             if term_cfg is None:
                 continue
-            # resolve the scene entity configuration
-            self._resolve_scene_entity_cfg(term_name, term_cfg)
+            # process attributes at runtime
+            # these properties are only resolvable once the simulation starts playing
+            self._process_term_cfg_at_play(term_name, term_cfg)
 
     """
-    Helper functions.
+    Internal functions.
     """
 
     def _resolve_common_term_cfg(self, term_name: str, term_cfg: ManagerTermBaseCfg, min_argc: int = 1):
-        """Resolve common term configuration.
+        """Resolve common attributes of the term configuration.
+
+        Usually, called by the :meth:`_prepare_terms` method to resolve common attributes of the term
+        configuration. These include:
 
-        Usually, called by the :meth:`_prepare_terms` method to resolve common term configuration.
+        * Resolving the term function and checking if it is callable.
+        * Checking if the term function's arguments are matched by the parameters.
+        * Resolving special attributes of the term configuration like ``asset_cfg``, ``sensor_cfg``, etc.
+        * Initializing the term if it is a class.
+
+        The last two steps are only possible once the simulation starts playing.
 
         By default, all term functions are expected to have at least one argument, which is the
         environment object. Some other managers may expect functions to take more arguments, for
@@ -303,29 +313,31 @@ def _resolve_common_term_cfg(self, term_name: str, term_cfg: ManagerTermBaseCfg,
                 f" Received: '{type(term_cfg)}'."
             )
 
-        # iterate over all the entities and parse the joint and body names
-        if self._env.sim.is_playing():
-            self._resolve_scene_entity_cfg(term_name, term_cfg)
-
         # get the corresponding function or functional class
         if isinstance(term_cfg.func, str):
             term_cfg.func = string_to_callable(term_cfg.func)
+        # check if function is callable
+        if not callable(term_cfg.func):
+            raise AttributeError(f"The term '{term_name}' is not callable. Received: {term_cfg.func}")
 
-        # initialize the term if it is a class
+        # check if the term is a class of valid type
         if inspect.isclass(term_cfg.func):
             if not issubclass(term_cfg.func, ManagerTermBase):
                 raise TypeError(
                     f"Configuration for the term '{term_name}' is not of type ManagerTermBase."
                     f" Received: '{type(term_cfg.func)}'."
                 )
-            term_cfg.func = term_cfg.func(cfg=term_cfg, env=self._env)
+            func_static = term_cfg.func.__call__
+            min_argc += 1  # forward by 1 to account for 'self' argument
+        else:
+            func_static = term_cfg.func
         # check if function is callable
-        if not callable(term_cfg.func):
+        if not callable(func_static):
             raise AttributeError(f"The term '{term_name}' is not callable. Received: {term_cfg.func}")
 
-        # check if term's arguments are matched by params
+        # check statically if the term's arguments are matched by params
         term_params = list(term_cfg.params.keys())
-        args = inspect.signature(term_cfg.func).parameters
+        args = inspect.signature(func_static).parameters
         args_with_defaults = [arg for arg in args if args[arg].default is not inspect.Parameter.empty]
         args_without_defaults = [arg for arg in args if args[arg].default is inspect.Parameter.empty]
         args = args_without_defaults + args_with_defaults
@@ -338,8 +350,22 @@ def _resolve_common_term_cfg(self, term_name: str, term_cfg: ManagerTermBaseCfg,
                     f" and optional parameters: {args_with_defaults}, but received: {term_params}."
                 )
 
-    def _resolve_scene_entity_cfg(self, term_name: str, term_cfg: ManagerTermBaseCfg):
-        """Resolve the scene entity configuration for the term.
+        # process attributes at runtime
+        # these properties are only resolvable once the simulation starts playing
+        if self._env.sim.is_playing():
+            self._process_term_cfg_at_play(term_name, term_cfg)
+
+    def _process_term_cfg_at_play(self, term_name: str, term_cfg: ManagerTermBaseCfg):
+        """Process the term configuration at runtime.
+
+        This function is called when the simulation starts playing. It is used to process the term
+        configuration at runtime. This includes:
+
+        * Resolving the scene entity configuration for the term.
+        * Initializing the term if it is a class.
+
+        Since the above steps rely on PhysX to parse over the simulation scene, they are deferred
+        until the simulation starts playing.
 
         Args:
             term_name: The name of the term.
@@ -362,3 +388,8 @@ def _resolve_scene_entity_cfg(self, term_name: str, term_cfg: ManagerTermBaseCfg
                 omni.log.info(msg)
             # store the entity
             term_cfg.params[key] = value
+
+        # initialize the term if it is a class
+        if inspect.isclass(term_cfg.func):
+            omni.log.info(f"Initializing term '{term_name}' with class '{term_cfg.func.__name__}'.")
+            term_cfg.func = term_cfg.func(cfg=term_cfg, env=self._env)

source/isaaclab/isaaclab/managers/observation_manager.py

@@ -352,6 +352,14 @@ def _prepare_terms(self):
         # we store it as a separate list to only call reset on them and prevent unnecessary calls
         self._group_obs_class_modifiers: list[modifiers.ModifierBase] = list()
 
+        # make sure the simulation is playing since we compute obs dims which needs asset quantities
+        if not self._env.sim.is_playing():
+            raise RuntimeError(
+                "Simulation is not playing. Observation manager requires the simulation to be playing"
+                " to compute observation dimensions. Please start the simulation before using the"
+                " observation manager."
+            )
+
         # check if config is dict already
         if isinstance(self.cfg, dict):
             group_cfg_items = self.cfg.items()
@@ -407,8 +415,10 @@ def _prepare_terms(self):
                 # add term config to list to list
                 self._group_obs_term_names[group_name].append(term_name)
                 self._group_obs_term_cfgs[group_name].append(term_cfg)
+
                 # call function the first time to fill up dimensions
                 obs_dims = tuple(term_cfg.func(self._env, **term_cfg.params).shape)
+
                 # create history buffers and calculate history term dimensions
                 if term_cfg.history_length > 0:
                     group_entry_history_buffer[term_name] = CircularBuffer(