Use config type for stateful observation modifiers

Author: ooctipus

source/isaaclab/changelog.d/modifier-base-cfg.major.rst

@@ -0,0 +1,14 @@
+Changed
+^^^^^^^
+
+* **Breaking:** Required class-based observation modifiers to use
+  :class:`~isaaclab.utils.modifiers.ModifierBaseCfg`, allowing their lazy callable references to be instantiated
+  based on the configuration type. Replace ``ModifierCfg(func=MyModifier, params=...)`` with
+  ``ModifierBaseCfg(func=MyModifier, params=...)``; function modifiers continue to use
+  :class:`~isaaclab.utils.modifiers.ModifierCfg`.
+
+Fixed
+^^^^^
+
+* Fixed function and class-based observation modifiers failing after a configuration dictionary round-trip turned
+  their callable references into :class:`~isaaclab.utils.string.ResolvableString` values.

source/isaaclab/isaaclab/managers/manager_term_cfg.py

@@ -168,7 +168,8 @@ class ObservationTermCfg(ManagerTermBaseCfg):
     or stateful, and can be used to apply transformations to the observation data. For example,
     a modifier can be used to normalize the observation data or to apply a rolling average.
 
-    For more information on modifiers, see the :class:`~isaaclab.utils.modifiers.ModifierCfg` class.
+    For more information on modifiers, see :class:`~isaaclab.utils.modifiers.ModifierCfg` and
+    :class:`~isaaclab.utils.modifiers.ModifierBaseCfg`.
     """
 
     noise: NoiseCfg | NoiseModelCfg | None = None

source/isaaclab/isaaclab/managers/observation_manager.py

@@ -396,7 +396,10 @@ def compute_group(self, group_name: str, update_history: bool = False) -> torch.
             # apply post-processing
             if term_cfg.modifiers is not None:
                 for modifier in term_cfg.modifiers:
-                    obs = modifier.func(obs, **modifier.params)
+                    if isinstance(modifier, modifiers.ModifierBaseCfg):
+                        obs = modifier.func(obs)
+                    else:
+                        obs = modifier.func(obs, **modifier.params)
             if isinstance(term_cfg.noise, noise.NoiseCfg):
                 obs = term_cfg.noise.func(obs, term_cfg.noise)
             elif isinstance(term_cfg.noise, noise.NoiseModelCfg) and term_cfg.noise.func is not None:
@@ -577,52 +580,8 @@ def _prepare_terms(self):
 
                 # prepare modifiers for each observation
                 if term_cfg.modifiers is not None:
-                    # initialize list of modifiers for term
                     for mod_cfg in term_cfg.modifiers:
-                        # check if class modifier and initialize with observation size when adding
-                        if isinstance(mod_cfg, modifiers.ModifierCfg):
-                            # to list of modifiers - instantiate class-based modifiers
-                            if inspect.isclass(mod_cfg.func):
-                                mod_cfg.func = mod_cfg.func(cfg=mod_cfg, data_dim=obs_dims, device=self._env.device)
-                                # verify the instance is the correct type
-                                if not isinstance(mod_cfg.func, modifiers.ModifierBase):
-                                    raise TypeError(
-                                        f"Modifier function '{mod_cfg.func}' for observation term '{term_name}'"
-                                        f" is not an instance of 'ModifierBase'. Received: '{type(mod_cfg.func)}'."
-                                    )
-                                # add to list of class modifiers
-                                self._group_obs_class_instances.append(mod_cfg.func)
-                        else:
-                            raise TypeError(
-                                f"Modifier configuration '{mod_cfg}' of observation term '{term_name}' is not of"
-                                f" required type ModifierCfg, Received: '{type(mod_cfg)}'"
-                            )
-
-                        # check if function is callable
-                        if not callable(mod_cfg.func):
-                            raise AttributeError(
-                                f"Modifier '{mod_cfg}' of observation term '{term_name}' is not callable."
-                                f" Received: {mod_cfg.func}"
-                            )
-
-                        # TODO(jichuanh): improvement can be made in two ways:
-                        #                 1. modifier specific check can be done in the modifier class
-                        #                 2. general param vs function matching check can be a common utility
-                        # check if term's arguments are matched by params
-                        term_params = list(mod_cfg.params.keys())
-                        args = inspect.signature(mod_cfg.func).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
-                        # ignore first two arguments for env and env_ids
-                        # Think: Check for cases when kwargs are set inside the function?
-                        if len(args) > 1:
-                            if set(args[1:]) != set(term_params + args_with_defaults):
-                                raise ValueError(
-                                    f"Modifier '{mod_cfg}' of observation term '{term_name}' expects"
-                                    f" mandatory parameters: {args_without_defaults[1:]}"
-                                    f" and optional parameters: {args_with_defaults}, but received: {term_params}."
-                                )
+                        self._prepare_modifier(mod_cfg, term_name, obs_dims)
 
                 # prepare noise model classes
                 if term_cfg.noise is not None and isinstance(term_cfg.noise, noise.NoiseModelCfg):
@@ -659,3 +618,37 @@ def _prepare_terms(self):
                     term_cfg.func.reset()
             # add history buffers for each group
             self._group_obs_term_history_buffer[group_name] = group_entry_history_buffer
+
+    def _prepare_modifier(self, mod_cfg: modifiers.ModifierCfg, term_name: str, obs_dims: tuple[int, ...]) -> None:
+        """Validate a modifier configuration and construct its stateful implementation."""
+        if not isinstance(mod_cfg, modifiers.ModifierCfg):
+            raise TypeError(
+                f"Modifier configuration '{mod_cfg}' of observation term '{term_name}' is not of"
+                f" required type ModifierCfg, Received: '{type(mod_cfg)}'"
+            )
+        if not callable(mod_cfg.func):
+            raise AttributeError(
+                f"Modifier '{mod_cfg}' of observation term '{term_name}' is not callable. Received: {mod_cfg.func}"
+            )
+
+        if isinstance(mod_cfg, modifiers.ModifierBaseCfg):
+            mod_cfg.func = mod_cfg.func(cfg=mod_cfg, data_dim=obs_dims, device=self._env.device)
+            if not isinstance(mod_cfg.func, modifiers.ModifierBase):
+                raise TypeError(
+                    f"Modifier function '{mod_cfg.func}' for observation term '{term_name}' is not an instance of"
+                    f" 'ModifierBase'. Received: '{type(mod_cfg.func)}'."
+                )
+            self._group_obs_class_instances.append(mod_cfg.func)
+            return
+
+        term_params = list(mod_cfg.params.keys())
+        args = inspect.signature(mod_cfg.func).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
+        if len(args) > 1 and set(args[1:]) != set(term_params + args_with_defaults):
+            raise ValueError(
+                f"Modifier '{mod_cfg}' of observation term '{term_name}' expects mandatory parameters:"
+                f" {args_without_defaults[1:]} and optional parameters: {args_with_defaults}, but received:"
+                f" {term_params}."
+            )

source/isaaclab/isaaclab/utils/__init__.pyi

@@ -30,6 +30,7 @@ __all__ = [
     "convert_faces_to_triangles",
     "PRIMITIVE_MESH_TYPES",
     "ModifierCfg",
+    "ModifierBaseCfg",
     "ModifierBase",
     "DigitalFilter",
     "DigitalFilterCfg",
@@ -80,6 +81,7 @@ from .mesh import (
     PRIMITIVE_MESH_TYPES,
 )
 from .modifiers import (
+    ModifierBaseCfg,
     ModifierCfg,
     ModifierBase,
     DigitalFilter,

source/isaaclab/isaaclab/utils/modifiers/__init__.py

@@ -28,7 +28,7 @@
     cfg = modifiers.ModifierCfg(func=modifiers.clip, params={"bounds": (0.0, torch.inf)})
 
     # apply the modifier
-    my_modified_tensor = cfg.func(my_tensor, cfg)
+    my_modified_tensor = cfg.func(my_tensor, **cfg.params)
 
 
 Usage with a class modifier:

source/isaaclab/isaaclab/utils/modifiers/__init__.pyi

@@ -5,6 +5,7 @@
 
 __all__ = [
     "ModifierCfg",
+    "ModifierBaseCfg",
     "DigitalFilterCfg",
     "IntegratorCfg",
     "ModifierBase",
@@ -15,6 +16,6 @@ __all__ = [
     "scale",
 ]
 
-from .modifier_cfg import ModifierCfg, DigitalFilterCfg, IntegratorCfg
+from .modifier_cfg import ModifierBaseCfg, ModifierCfg, DigitalFilterCfg, IntegratorCfg
 from .modifier_base import ModifierBase
 from .modifier import DigitalFilter, Integrator, bias, clip, scale

source/isaaclab/isaaclab/utils/modifiers/modifier_base.py

@@ -12,7 +12,7 @@
 import torch
 
 if TYPE_CHECKING:
-    from .modifier_cfg import ModifierCfg
+    from .modifier_cfg import ModifierBaseCfg
 
 
 class ModifierBase(ABC):
@@ -31,19 +31,19 @@ class ModifierBase(ABC):
 
         from isaaclab.utils import modifiers
 
-        # define custom keyword arguments to pass to ModifierCfg
+        # define custom configuration values for the stateful modifier
         kwarg_dict = {"arg_1": VAL_1, "arg_2": VAL_2}
 
         # create modifier configuration object
-        # func is the class name of the modifier and params is the dictionary of arguments
-        modifier_config = modifiers.ModifierCfg(func=modifiers.ModifierBase, params=kwarg_dict)
+        # func is the class name and params are available to its constructor through the config
+        modifier_config = modifiers.ModifierBaseCfg(func=MyModifier, params=kwarg_dict)
 
         # define modifier instance
-        my_modifier = modifiers.ModifierBase(cfg=modifier_config)
+        my_modifier = modifier_config.func(cfg=modifier_config, data_dim=(256, 128), device="cuda")
 
     """
 
-    def __init__(self, cfg: ModifierCfg, data_dim: tuple[int, ...], device: str) -> None:
+    def __init__(self, cfg: ModifierBaseCfg, data_dim: tuple[int, ...], device: str) -> None:
         """Initializes the modifier class.
 
         Args:

source/isaaclab/isaaclab/utils/modifiers/modifier_cfg.py

@@ -16,26 +16,34 @@
 
 @configclass
 class ModifierCfg:
-    """Configuration parameters modifiers"""
+    """Configuration for a stateless function modifier.
+
+    Use :class:`ModifierBaseCfg` for a class-based stateful modifier.
+    """
 
     func: Callable[..., torch.Tensor] = MISSING
-    """Function or callable class used by modifier.
+    """Function used by the modifier.
 
     The function must take a torch tensor as the first argument. The remaining arguments are specified
     in the :attr:`params` attribute.
-
-    It also supports `callable classes <https://docs.python.org/3/reference/datamodel.html#object.__call__>`_,
-    i.e. classes that implement the ``__call__()`` method. In this case, the class should inherit from the
-    :class:`ModifierBase` class and implement the required methods.
     """
 
     params: dict[str, Any] = dict()
-    """The parameters to be passed to the function or callable class as keyword arguments. Defaults to
-    an empty dictionary."""
+    """The parameters passed to the function as keyword arguments. Defaults to an empty dictionary."""
+
+
+@configclass
+class ModifierBaseCfg(ModifierCfg):
+    """Configuration for a stateful modifier implemented by :class:`ModifierBase`.
+
+    The :attr:`func` field identifies the modifier class. The observation manager constructs the class with this
+    configuration, the observation dimensions, and the device. The :attr:`params` values are available to the
+    constructor through this configuration and are not forwarded to the modifier instance when it is called.
+    """
 
 
 @configclass
-class DigitalFilterCfg(ModifierCfg):
+class DigitalFilterCfg(ModifierBaseCfg):
     """Configuration parameters for a digital filter modifier.
 
     For more information, please check the :class:`DigitalFilter` class.
@@ -66,7 +74,7 @@ class DigitalFilterCfg(ModifierCfg):
 
 
 @configclass
-class IntegratorCfg(ModifierCfg):
+class IntegratorCfg(ModifierBaseCfg):
     """Configuration parameters for an integrator modifier.
 
     For more information, please check the :class:`Integrator` class.

source/isaaclab/isaaclab/utils/string.py

@@ -220,6 +220,11 @@ def _resolve(self) -> Callable:
     def __call__(self, *args, **kwargs):
         return self._resolve()(*args, **kwargs)
 
+    @property
+    def __signature__(self) -> inspect.Signature:
+        """Return the signature of the lazily resolved callable."""
+        return inspect.signature(self._resolve())
+
     def _split_ref(self) -> tuple[str | None, str]:
         """Parse ``module:attribute`` reference without importing."""
         value = str(self)