Renames RandomizationManager to EventManager (isaac-sim#460)

# Description Renames the `RandomizationManager` to `EventManager` for clarity as the manager takes care of all kind of events that go beyond pure randomization (such as resets). Fixes isaac-sim#413 ## Type of change - Breaking change (fix or feature that would cause existing functionality to not work as expected) - This change requires a documentation update ## Checklist - [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./orbit.sh --format` - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [x] I have run all the tests with `./orbit.sh --test` and they pass - [x] 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
iamdrfly · Mar 20, 2024 · 77aa3bf · 77aa3bf
1 parent 6854bc6
commit 77aa3bf
Show file tree

Hide file tree

Showing 45 changed files with 449 additions and 293 deletions.
diff --git a/docs/source/api/orbit/omni.isaac.orbit.envs.mdp.rst b/docs/source/api/orbit/omni.isaac.orbit.envs.mdp.rst
@@ -19,10 +19,10 @@ Actions
     :show-inheritance:
     :exclude-members: __init__, class_type
 
-Randomization
--------------
+Events
+------
 
-.. automodule:: omni.isaac.orbit.envs.mdp.randomizations
+.. automodule:: omni.isaac.orbit.envs.mdp.events
     :members:
 
 Commands

diff --git a/docs/source/api/orbit/omni.isaac.orbit.managers.rst b/docs/source/api/orbit/omni.isaac.orbit.managers.rst
@@ -17,8 +17,8 @@
     ActionManager
     ActionTerm
     ActionTermCfg
-    RandomizationManager
-    RandomizationTermCfg
+    EventManager
+    EventTermCfg
     CommandManager
     CommandTerm
     CommandTermCfg
@@ -82,9 +82,25 @@ Action Manager
     :members:
     :exclude-members: __init__
 
+Event Manager
+-------------
+
+.. autoclass:: EventManager
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: EventTermCfg
+    :members:
+    :exclude-members: __init__
+
 Randomization Manager
 ---------------------
 
+.. deprecated:: v0.3
+    The Randomization Manager is deprecated and will be removed in v0.4.
+    Please use the :class:`EventManager` class instead.
+
 .. autoclass:: RandomizationManager
     :members:
     :inherited-members:

diff --git a/docs/source/tutorials/03_envs/create_base_env.rst b/docs/source/tutorials/03_envs/create_base_env.rst
@@ -7,7 +7,7 @@ Creating a Base Environment
 .. currentmodule:: omni.isaac.orbit
 
 Environments bring together different aspects of the simulation such as
-the scene, observations and actions spaces, randomizations, etc. to create a
+the scene, observations and actions spaces, reset events etc. to create a
 coherent interface for various applications. In Orbit, environments are
 implemented as :class:`envs.BaseEnv` and :class:`envs.RLTaskEnv` classes.
 The two classes are very similar, but :class:`envs.RLTaskEnv` is useful for
@@ -46,7 +46,8 @@ is composed of the following components:
 * :class:`scene.InteractiveScene` - The scene that is used for the simulation.
 * :class:`managers.ActionManager` - The manager that handles actions.
 * :class:`managers.ObservationManager` - The manager that handles observations.
-* :class:`managers.RandomizationManager` - The manager that handles randomizations.
+* :class:`managers.EventManager` - The manager that schedules operations (such as domain randomization)
+  at specified simulation events. For instance, at startup, on resets, or periodic intervals.
 
 By configuring these components, the user can create different variations of the same environment
 with minimal effort. In this tutorial, we will go through the different components of the
@@ -110,40 +111,42 @@ default values for this tutorial.
    :language: python
    :pyobject: ObservationsCfg
 
-Defining randomizations
------------------------
+Defining events
+---------------
 
 At this point, we have defined the scene, actions and observations for the cartpole environment.
 The general idea for all these components is to define the configuration classes and then
-pass them to the corresponding managers. The randomization manager is no different.
+pass them to the corresponding managers. The event manager is no different.
 
-The :class:`managers.RandomizationManager` class is responsible for randomizing everything related
-to the simulation state. This includes randomizing (or resetting) the scene, randomizing physical
-properties (such as mass, friction, etc.), and visual properties (such as colors, textures, etc.).
-Each of these are specified through the :class:`managers.RandomizationTermCfg` class, which
-takes in the :attr:`managers.RandomizationTermCfg.func` that specifies the function or callable
-class that performs the randomization. Additionally, it expects the **mode** of randomization.
-The mode specifies when the randomization term should be applied. It is possible to specify
-your own mode, but Orbit provides three modes out of the box:
+The :class:`managers.EventManager` class is responsible for events corresponding to changes
+in the simulation state. This includes resetting (or randomizing) the scene, randomizing physical
+properties (such as mass, friction, etc.), and varying visual properties (such as colors, textures, etc.).
+Each of these are specified through the :class:`managers.EventTermCfg` class, which
+takes in the :attr:`managers.EventTermCfg.func` that specifies the function or callable
+class that performs the event.
 
-* ``"startup"`` - Randomize only once at environment startup.
-* ``"reset"`` - Randomize on every call to an environment's reset.
-* ``"interval"`` - Randomize at a given fixed interval.
+Additionally, it expects the **mode** of the event. The mode specifies when the event term should be applied.
+It is possible to specify your own mode. For this, you'll need to adapt the :class:`~envs.BaseEnv` class.
+However, out of the box, Orbit provides three commonly used modes:
 
-For this example, we randomize the pole's mass on startup. This is done only once since this operation
-is expensive and we don't want to do it on every reset. We also randomize the initial joint state of
-the cartpole and the pole at every reset.
+* ``"startup"`` - Event that takes place only once at environment startup.
+* ``"reset"`` - Event that occurs on environment termination and reset.
+* ``"interval"`` - Event that are executed at a given interval, i.e., periodically after a certain number of steps.
+
+For this example, we define events that randomize the pole's mass on startup. This is done only once since this
+operation is expensive and we don't want to do it on every reset. We also create an event to randomize the initial
+joint state of the cartpole and the pole at every reset.
 
 .. literalinclude:: ../../../../source/standalone/tutorials/03_envs/create_cartpole_base_env.py
    :language: python
-   :pyobject: RandomizationCfg
+   :pyobject: EventCfg
 
 Tying it all together
 ---------------------
 
 Having defined the scene and manager configurations, we can now define the environment configuration
 through the :class:`envs.BaseEnvCfg` class. This class takes in the scene, action, observation and
-randomization configurations.
+event configurations.
 
 In addition to these, it also takes in the :attr:`envs.BaseEnvCfg.sim` which defines the simulation
 parameters such as the timestep, gravity, etc. This is initialized to the default values, but can

diff --git a/docs/source/tutorials/03_envs/create_rl_env.rst b/docs/source/tutorials/03_envs/create_rl_env.rst
@@ -57,7 +57,7 @@ The Code Explained
 ~~~~~~~~~~~~~~~~~~
 
 We already went through parts of the above in the :ref:`tutorial-create-base-env` tutorial to learn
-about how to specify the scene, observations, actions and randomizations. Thus, in this tutorial, we
+about how to specify the scene, observations, actions and events. Thus, in this tutorial, we
 will focus only on the RL components of the environment.
 
 In Orbit, we provide various implementations of different terms in the :mod:`envs.mdp` module. We will use

diff --git a/source/extensions/omni.isaac.orbit/config/extension.toml b/source/extensions/omni.isaac.orbit/config/extension.toml
@@ -1,7 +1,7 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "0.14.1"
+version = "0.15.0"
 
 # Description
 title = "ORBIT framework for Robot Learning"

diff --git a/source/extensions/omni.isaac.orbit/docs/CHANGELOG.rst b/source/extensions/omni.isaac.orbit/docs/CHANGELOG.rst
@@ -1,6 +1,18 @@
 Changelog
 ---------
 
+0.15.0 (2024-03-17)
+~~~~~~~~~~~~~~~~~~~
+
+Deprecated
+^^^^^^^^^^
+
+* Renamed :class:`omni.isaac.orbit.managers.RandomizationManager` to :class:`omni.isaac.orbit.managers.EventManager`
+  class for clarification as the manager takes care of events such as reset in addition to pure randomizations.
+* Renamed :class:`omni.isaac.orbit.managers.RandomizationTermCfg` to :class:`omni.isaac.orbit.managers.EventTermCfg`
+  for consistency with the class name change.
+
+
 0.14.1 (2024-03-16)
 ~~~~~~~~~~~~~~~~~~~
 

diff --git a/source/extensions/omni.isaac.orbit/omni/isaac/orbit/assets/articulation/articulation.py b/source/extensions/omni.isaac.orbit/omni/isaac/orbit/assets/articulation/articulation.py
@@ -156,11 +156,11 @@ def body_physx_view(self) -> physx.RigidBodyView:
             However, this led to confusion with the link ordering as they were not ordered in the same way as the
             articulation view.
 
-            Therefore, this attribute will be removed in v0.3.0. Please use the :attr:`root_physx_view` attribute
+            Therefore, this attribute will be removed in v0.4.0. Please use the :attr:`root_physx_view` attribute
             instead.
 
         """
-        dep_msg = "The attribute 'body_physx_view' will be removed in v0.3.0. Please use 'root_physx_view' instead."
+        dep_msg = "The attribute 'body_physx_view' will be removed in v0.4.0. Please use 'root_physx_view' instead."
         warnings.warn(dep_msg, DeprecationWarning)
         carb.log_error(dep_msg)
         return self._body_physx_view

diff --git a/source/extensions/omni.isaac.orbit/omni/isaac/orbit/assets/rigid_object/rigid_object.py b/source/extensions/omni.isaac.orbit/omni/isaac/orbit/assets/rigid_object/rigid_object.py
@@ -97,10 +97,10 @@ def body_physx_view(self) -> physx.RigidBodyView:
 
         .. deprecated:: v0.3.0
 
-            The attribute 'body_physx_view' will be removed in v0.3.0. Please use :attr:`root_physx_view` instead.
+            The attribute 'body_physx_view' will be removed in v0.4.0. Please use :attr:`root_physx_view` instead.
 
         """
-        dep_msg = "The attribute 'body_physx_view' will be removed in v0.3.0. Please use 'root_physx_view' instead."
+        dep_msg = "The attribute 'body_physx_view' will be removed in v0.4.0. Please use 'root_physx_view' instead."
         warnings.warn(dep_msg, DeprecationWarning)
         carb.log_error(dep_msg)
         return self.root_physx_view

diff --git a/source/extensions/omni.isaac.orbit/omni/isaac/orbit/envs/base_env.py b/source/extensions/omni.isaac.orbit/omni/isaac/orbit/envs/base_env.py
@@ -12,7 +12,7 @@
 
 import omni.isaac.core.utils.torch as torch_utils
 
-from omni.isaac.orbit.managers import ActionManager, ObservationManager, RandomizationManager
+from omni.isaac.orbit.managers import ActionManager, EventManager, ObservationManager
 from omni.isaac.orbit.scene import InteractiveScene
 from omni.isaac.orbit.sim import SimulationContext
 from omni.isaac.orbit.utils.timer import Timer
@@ -64,10 +64,10 @@ class BaseEnv:
       raw actions at different levels of abstraction. For example, in case of a robotic arm, the raw actions
       can be joint torques, joint positions, or end-effector poses. Similarly for a mobile base, it can be
       the joint torques, or the desired velocity of the floating base.
-    * **Randomization Manager**: The randomization manager that randomizes different elements in the scene.
-      This includes resetting the scene to a default state or randomize the scene at different intervals
-      of time. The randomization manager can be configured to randomize different elements of the scene
-      such as the masses of objects, friction coefficients, or apply random pushes to the robot.
+    * **Event Manager**: The event manager orchestrates operations triggered based on simulation events.
+      This includes resetting the scene to a default state, applying random pushes to the robot at different intervals
+      of time, or randomizing properties such as mass and friction coefficients. This is useful for training
+      and evaluating the robot in a variety of scenarios.
 
     The environment provides a unified interface for interacting with the simulation. However, it does not
     include task-specific quantities such as the reward function, or the termination conditions. These
@@ -190,7 +190,7 @@ def load_managers(self):
         """Load the managers for the environment.
 
         This function is responsible for creating the various managers (action, observation,
-        randomization, etc.) for the environment. Since the managers require access to physics handles,
+        events, etc.) for the environment. Since the managers require access to physics handles,
         they can only be created after the simulator is reset (i.e. played for the first time).
 
         .. note::
@@ -209,9 +209,9 @@ def load_managers(self):
         # -- observation manager
         self.observation_manager = ObservationManager(self.cfg.observations, self)
         print("[INFO] Observation Manager:", self.observation_manager)
-        # -- randomization manager
-        self.randomization_manager = RandomizationManager(self.cfg.randomization, self)
-        print("[INFO] Randomization Manager: ", self.randomization_manager)
+        # -- event manager
+        self.event_manager = EventManager(self.cfg.events, self)
+        print("[INFO] Event Manager: ", self.event_manager)
 
     """
     Operations - MDP.
@@ -270,9 +270,9 @@ def step(self, action: torch.Tensor) -> VecEnvObs:
         if self.sim.has_gui():
             self.sim.render()
 
-        # post-step: step interval randomization
-        if "interval" in self.randomization_manager.available_modes:
-            self.randomization_manager.randomize(mode="interval", dt=self.step_dt)
+        # post-step: step interval event
+        if "interval" in self.event_manager.available_modes:
+            self.event_manager.apply(mode="interval", dt=self.step_dt)
 
         # return observations and extras
         return self.observation_manager.compute(), self.extras
@@ -303,7 +303,7 @@ def close(self):
             # destructor is order-sensitive
             del self.action_manager
             del self.observation_manager
-            del self.randomization_manager
+            del self.event_manager
             del self.scene
             del self.viewport_camera_controller
             # clear callbacks and instance
@@ -327,9 +327,9 @@ def _reset_idx(self, env_ids: Sequence[int]):
         """
         # reset the internal buffers of the scene elements
         self.scene.reset(env_ids)
-        # randomize the MDP for environments that need a reset
-        if "reset" in self.randomization_manager.available_modes:
-            self.randomization_manager.randomize(env_ids=env_ids, mode="reset")
+        # apply events such as randomizations for environments that need a reset
+        if "reset" in self.event_manager.available_modes:
+            self.event_manager.apply(env_ids=env_ids, mode="reset")
 
         # iterate over all managers and reset them
         # this returns a dictionary of information which is stored in the extras
@@ -341,6 +341,6 @@ def _reset_idx(self, env_ids: Sequence[int]):
         # -- action manager
         info = self.action_manager.reset(env_ids)
         self.extras["log"].update(info)
-        # -- randomization manager
-        info = self.randomization_manager.reset(env_ids)
+        # -- event manager
+        info = self.event_manager.reset(env_ids)
         self.extras["log"].update(info)
diff --git a/source/extensions/omni.isaac.orbit/omni/isaac/orbit/envs/base_env_cfg.py b/source/extensions/omni.isaac.orbit/omni/isaac/orbit/envs/base_env_cfg.py
@@ -11,11 +11,12 @@
 
 from __future__ import annotations
 
+import warnings
 from dataclasses import MISSING
 from typing import Literal
 
 import omni.isaac.orbit.envs.mdp as mdp
-from omni.isaac.orbit.managers import RandomizationTermCfg as RandTerm
+from omni.isaac.orbit.managers import EventTermCfg as EventTerm
 from omni.isaac.orbit.scene import InteractiveSceneCfg
 from omni.isaac.orbit.sim import SimulationCfg
 from omni.isaac.orbit.utils import configclass
@@ -67,14 +68,14 @@ class ViewerCfg:
 
 
 @configclass
-class DefaultRandomizationManagerCfg:
-    """Configuration of the default randomization manager.
+class DefaultEventManagerCfg:
+    """Configuration of the default event manager.
 
     This manager is used to reset the scene to a default state. The default state is specified
     by the scene configuration.
     """
 
-    reset_scene_to_default = RandTerm(func=mdp.reset_scene_to_default, mode="reset")
+    reset_scene_to_default = EventTerm(func=mdp.reset_scene_to_default, mode="reset")
 
 
 @configclass
@@ -86,6 +87,7 @@ class BaseEnvCfg:
     """Viewer configuration. Default is ViewerCfg()."""
     sim: SimulationCfg = SimulationCfg()
     """Physics simulation configuration. Default is SimulationCfg()."""
+
     # ui settings
     ui_window_class_type: type | None = BaseEnvWindow
     """The class type of the UI window. Default is None.
@@ -100,15 +102,51 @@ class BaseEnvCfg:
 
     # general settings
     decimation: int = MISSING
-    """Number of control action updates @ sim dt per policy dt."""
+    """Number of control action updates @ sim dt per policy dt.
+
+    For instance, if the simulation dt is 0.01s and the policy dt is 0.1s, then the decimation is 10.
+    This means that the control action is updated every 10 simulation steps.
+    """
 
     # environment settings
     scene: InteractiveSceneCfg = MISSING
-    """Scene settings"""
+    """Scene settings.
+
+    Please refer to the :class:`omni.isaac.orbit.scene.InteractiveSceneCfg` class for more details.
+    """
+
     observations: object = MISSING
-    """Observation space settings."""
+    """Observation space settings.
+
+    Please refer to the :class:`omni.isaac.orbit.managers.ObservationManager` class for more details.
+    """
+
     actions: object = MISSING
-    """Action space settings."""
-    randomization: object = DefaultRandomizationManagerCfg()
-    """Randomization settings. Default is the default randomization manager, which resets
-    the scene to its default state."""
+    """Action space settings.
+
+    Please refer to the :class:`omni.isaac.orbit.managers.ActionManager` class for more details.
+    """
+
+    events: object = DefaultEventManagerCfg()
+    """Event settings. Defaults to the basic configuration that resets the scene to its default state.
+
+    Please refer to the :class:`omni.isaac.orbit.managers.EventManager` class for more details.
+    """
+
+    randomization: object | None = None
+    """Randomization settings. Default is None.
+
+    .. deprecated:: 0.3.0
+        This attribute is deprecated and will be removed in v0.4.0. Please use the :attr:`events`
+        attribute to configure the randomization settings.
+
+    """
+
+    def __post_init__(self):
+        if self.randomization is not None:
+            warnings.warn(
+                "The 'randomization' attribute is deprecated and will be removed in a future release. "
+                "Please use the 'events' attribute to configure the randomization settings.",
+                DeprecationWarning,
+            )
+            self.events = self.randomization