[SIM-950] Actuator Drive Model Improvements

CONTRIBUTORS.md

@@ -35,6 +35,7 @@ Guidelines for modifications:
 * Pascal Roth
 * Sheikh Dawood
 * Ossama Ahmed
+* Brian McCann
 
 ## Contributors
 

docs/source/api/lab/isaaclab.actuators.rst

@@ -32,6 +32,7 @@ Actuator Base
   :inherited-members:
 
 .. autoclass:: ActuatorBaseCfg
+  :noindex:
   :members:
   :inherited-members:
   :exclude-members: __init__, class_type
@@ -45,6 +46,7 @@ Implicit Actuator
   :show-inheritance:
 
 .. autoclass:: ImplicitActuatorCfg
+  :noindex:
   :members:
   :inherited-members:
   :show-inheritance:
@@ -59,6 +61,7 @@ Ideal PD Actuator
   :show-inheritance:
 
 .. autoclass:: IdealPDActuatorCfg
+  :noindex:
   :members:
   :inherited-members:
   :show-inheritance:
@@ -73,6 +76,7 @@ DC Motor Actuator
   :show-inheritance:
 
 .. autoclass:: DCMotorCfg
+  :noindex:
   :members:
   :inherited-members:
   :show-inheritance:
@@ -87,6 +91,7 @@ Delayed PD Actuator
   :show-inheritance:
 
 .. autoclass:: DelayedPDActuatorCfg
+  :noindex:
   :members:
   :inherited-members:
   :show-inheritance:
@@ -101,6 +106,7 @@ Remotized PD Actuator
   :show-inheritance:
 
 .. autoclass:: RemotizedPDActuatorCfg
+  :noindex:
   :members:
   :inherited-members:
   :show-inheritance:
@@ -115,6 +121,7 @@ MLP Network Actuator
   :show-inheritance:
 
 .. autoclass:: ActuatorNetMLPCfg
+  :noindex:
   :members:
   :inherited-members:
   :show-inheritance:
@@ -129,6 +136,7 @@ LSTM Network Actuator
   :show-inheritance:
 
 .. autoclass:: ActuatorNetLSTMCfg
+  :noindex:
   :members:
   :inherited-members:
   :show-inheritance:

scripts/get_omni_version.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2022-2025, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
+# All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+import omni.kit.app
+
+from isaaclab.app import AppLauncher
+
+app_launcher = AppLauncher(headless=True, enable_cameras=True)
+simulation_app = app_launcher.app
+
+app = omni.kit.app.get_app()
+kit_version = app.get_kit_version()
+print(kit_version)

source/isaaclab/config/extension.toml

@@ -1,7 +1,7 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "0.47.7"
+version = "0.49.7"
 
 # Description
 title = "Isaac Lab framework for Robot Learning"

source/isaaclab/docs/CHANGELOG.rst

@@ -1,6 +1,18 @@
 Changelog
 ---------
 
+0.49.7 (2025-11-4)
+~~~~~~~~~~~~~~~~~~
+
+Added
+^^^^^^^
+
+* Implemented drive model improvements for implicit actuators allowing them to configure a new feature within physx to apply
+  constraints on actuator effort dependent on the torque and velocity on the articulation.
+* Reorg some configuration files to avoid circular dependencies in actuator configuration.
+* Introduced a NamedTuple config classes as a way to organize related parameters, and extended the configuration parsing to
+  work with related (mutually dependent) parameters in the configurations.
+
 0.47.7 (2025-10-31)
 ~~~~~~~~~~~~~~~~~~~
 

source/isaaclab/isaaclab/actuators/__init__.py

@@ -23,15 +23,14 @@
 """
 
 from .actuator_base import ActuatorBase
-from .actuator_cfg import (
-    ActuatorBaseCfg,
-    ActuatorNetLSTMCfg,
-    ActuatorNetMLPCfg,
+from .actuator_base_cfg import ActuatorBaseCfg
+from .actuator_net import ActuatorNetLSTM, ActuatorNetMLP
+from .actuator_net_cfg import ActuatorNetLSTMCfg, ActuatorNetMLPCfg
+from .actuator_pd import DCMotor, DelayedPDActuator, IdealPDActuator, ImplicitActuator, RemotizedPDActuator
+from .actuator_pd_cfg import (
     DCMotorCfg,
     DelayedPDActuatorCfg,
     IdealPDActuatorCfg,
     ImplicitActuatorCfg,
     RemotizedPDActuatorCfg,
 )
-from .actuator_net import ActuatorNetLSTM, ActuatorNetMLP
-from .actuator_pd import DCMotor, DelayedPDActuator, IdealPDActuator, ImplicitActuator, RemotizedPDActuator

source/isaaclab/isaaclab/actuators/actuator_base.py

@@ -8,13 +8,12 @@
 import torch
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
-from typing import TYPE_CHECKING, ClassVar
+from typing import ClassVar
 
 import isaaclab.utils.string as string_utils
 from isaaclab.utils.types import ArticulationActions
 
-if TYPE_CHECKING:
-    from .actuator_cfg import ActuatorBaseCfg
+from .actuator_base_cfg import ActuatorBaseCfg
 
 
 class ActuatorBase(ABC):
@@ -76,6 +75,18 @@ class ActuatorBase(ABC):
     For implicit actuators, the :attr:`velocity_limit` and :attr:`velocity_limit_sim` are the same.
     """
 
+    drive_model: torch.Tensor
+    """Three parameters for each joint/env defining the:
+       (1)  [:,:,0] speed_effort_gradient : float = 1 (default),
+       (2)  [:,:,1] maximum_actuator_velocity : float = torch.inf (default), and
+       (3)  [:,:,2] velocity_dependent_resistance : float = 1 (default)
+
+    which define velocity and effort dependent constraints on the motor's performance.
+
+    This feature is only implemented in IsaacSim v5.0.
+
+    The shape is (num_envs, num_joints, 3)."""
+
     stiffness: torch.Tensor
     """The stiffness (P gain) of the PD controller. Shape is (num_envs, num_joints)."""
 
@@ -116,6 +127,7 @@ def __init__(
         viscous_friction: torch.Tensor | float = 0.0,
         effort_limit: torch.Tensor | float = torch.inf,
         velocity_limit: torch.Tensor | float = torch.inf,
+        drive_model: torch.Tensor | tuple[float, float, float] = ActuatorBaseCfg.DriveModelCfg(),
     ):
         """Initialize the actuator.
 
@@ -149,6 +161,9 @@ def __init__(
                 If a tensor, then the shape is (num_envs, num_joints).
             velocity_limit: The default velocity limit. Defaults to infinity.
                 If a tensor, then the shape is (num_envs, num_joints).
+            drive_model: Drive model for the actuator including speed_effort_gradient, max_actuator_velocity, and
+                velocity_dependent_resistance in that order. Defaults to (0.0, torch.inf, 0.0).
+                If a tensor then the shape is (num_envs, num_joints, 3).
         """
         # save parameters
         self.cfg = cfg
@@ -176,27 +191,44 @@ def __init__(
             ("friction", friction),
             ("dynamic_friction", dynamic_friction),
             ("viscous_friction", viscous_friction),
+            ("drive_model", drive_model, 3),
         ]
-        for param_name, usd_val in to_check:
+        for param_name, usd_val, *tuple_len in to_check:
+            # check if the parameter requires a tuple or a single float
+            if len(tuple_len) > 0:
+                shape = (self._num_envs, self.num_joints, tuple_len[0])
+            else:
+                shape = (self._num_envs, self.num_joints)
+
             cfg_val = getattr(self.cfg, param_name)
-            setattr(self, param_name, self._parse_joint_parameter(cfg_val, usd_val))
+            setattr(self, param_name, self._parse_joint_parameter(cfg_val, usd_val, shape, param_name=param_name))
             new_val = getattr(self, param_name)
 
             allclose = (
-                torch.all(new_val == usd_val) if isinstance(usd_val, (float, int)) else torch.allclose(new_val, usd_val)
+                torch.all(new_val == usd_val)
+                if isinstance(usd_val, (float, int))
+                else (
+                    all([torch.all(new_val[:, :, i] == float(v)) for i, v in enumerate(usd_val)])
+                    if isinstance(usd_val, tuple)
+                    else torch.allclose(new_val, usd_val)
+                )
             )
             if cfg_val is None or not allclose:
                 self._record_actuator_resolution(
                     cfg_val=getattr(self.cfg, param_name),
-                    new_val=new_val[0],  # new val always has the shape of (num_envs, num_joints)
+                    new_val=new_val[0],
                     usd_val=usd_val,
                     joint_names=joint_names,
                     joint_ids=joint_ids,
                     actuator_param=param_name,
                 )
 
-        self.velocity_limit = self._parse_joint_parameter(self.cfg.velocity_limit, self.velocity_limit_sim)
-        self.effort_limit = self._parse_joint_parameter(self.cfg.effort_limit, self.effort_limit_sim)
+        self.velocity_limit = self._parse_joint_parameter(
+            self.cfg.velocity_limit, self.velocity_limit_sim, param_name="velocity_limit"
+        )
+        self.effort_limit = self._parse_joint_parameter(
+            self.cfg.effort_limit, self.effort_limit_sim, param_name="effort_limit"
+        )
 
         # create commands buffers for allocation
         self.computed_effort = torch.zeros(self._num_envs, self.num_joints, device=self._device)
@@ -287,20 +319,35 @@ def _record_actuator_resolution(self, cfg_val, new_val, usd_val, joint_names, jo
 
         ids = joint_ids if isinstance(joint_ids, torch.Tensor) else list(range(len(joint_names)))
         for idx, name in enumerate(joint_names):
-            cfg_val_log = "Not Specified" if cfg_val is None else float(new_val[idx])
-            default_usd_val = usd_val if isinstance(usd_val, (float, int)) else float(usd_val[0][idx])
-            applied_val_log = default_usd_val if cfg_val is None else float(new_val[idx])
-            table.append([name, int(ids[idx]), default_usd_val, cfg_val_log, applied_val_log])
+            if len(new_val.shape) == 1:
+                cfg_val_log = "Not Specified" if cfg_val is None else float(new_val[idx])
+                default_usd_val = usd_val if isinstance(usd_val, (float, int)) else float(usd_val[0][idx])
+                applied_val_log = default_usd_val if cfg_val is None else float(new_val[idx])
+                table.append([name, int(ids[idx]), default_usd_val, cfg_val_log, applied_val_log])
+            else:
+                cfg_val_log = "Not Specified" if cfg_val is None else tuple(new_val[idx])
+                default_usd_val = usd_val if isinstance(usd_val, (tuple)) else tuple(usd_val[0][idx][:])
+                applied_val_log = default_usd_val if cfg_val is None else tuple(new_val[idx])
+                table.append([name, int(ids[idx]), default_usd_val, cfg_val_log, applied_val_log])
 
     def _parse_joint_parameter(
-        self, cfg_value: float | dict[str, float] | None, default_value: float | torch.Tensor | None
+        self,
+        cfg_value: tuple[float, ...] | dict[str, tuple[float, ...]] | float | dict[str, float] | None,
+        default_value: tuple[float, ...] | float | torch.Tensor | None,
+        expected_shape: tuple[int, ...] | None = None,
+        *,
+        param_name: str = "No name specified",
     ) -> torch.Tensor:
         """Parse the joint parameter from the configuration.
 
         Args:
             cfg_value: The parameter value from the configuration. If None, then use the default value.
             default_value: The default value to use if the parameter is None. If it is also None,
                 then an error is raised.
+            expected_shape: The expected shape for the tensor buffer. Usually defaults to (num_envs, num_joints).
+
+        Kwargs:
+            param_name: a string with the parameter name. (Optional used only in exception messages).
 
         Returns:
             The parsed parameter value.
@@ -309,38 +356,87 @@ def _parse_joint_parameter(
             TypeError: If the parameter value is not of the expected type.
             TypeError: If the default value is not of the expected type.
             ValueError: If the parameter value is None and no default value is provided.
-            ValueError: If the default value tensor is the wrong shape.
+            ValueError: If a tensor or tuple is the wrong shape.
         """
+        if expected_shape is None:
+            expected_shape = (self._num_envs, self.num_joints)
         # create parameter buffer
-        param = torch.zeros(self._num_envs, self.num_joints, device=self._device)
+        param = torch.zeros(*expected_shape, device=self._device)
+
         # parse the parameter
         if cfg_value is not None:
             if isinstance(cfg_value, (float, int)):
                 # if float, then use the same value for all joints
                 param[:] = float(cfg_value)
+            elif isinstance(cfg_value, tuple):
+                # if tuple, ensure we expect a tuple for this parameter
+                if len(expected_shape) < 3:
+                    raise TypeError(
+                        f"Invalid type for parameter value: {type(cfg_value)} for parameter {param_name}"
+                        + f"actuator on joints {self.joint_names}. Expected float or dict, got tuple"
+                    )
+                # ensure the tuple is the correct length, and assign to the last tensor dimensions across all joints
+                if not len(cfg_value) is expected_shape[2]:
+                    raise ValueError(
+                        f"Invalid tuple length for parameter {param_name}, got {len(cfg_value)}, expected"
+                        + f" {expected_shape[2]}"
+                    )
+                for i, v in enumerate(cfg_value):
+                    param[:, :, i] = float(v)
             elif isinstance(cfg_value, dict):
                 # if dict, then parse the regular expression
-                indices, _, values = string_utils.resolve_matching_names_values(cfg_value, self.joint_names)
-                # note: need to specify type to be safe (e.g. values are ints, but we want floats)
-                param[:, indices] = torch.tensor(values, dtype=torch.float, device=self._device)
+                indices, j, values = string_utils.resolve_matching_names_values(cfg_value, self.joint_names)
+                # if the expected shape has two dimensions, we expect floats
+                if len(expected_shape) < 3:
+                    # note: need to specify type to be safe (e.g. values are ints, but we want floats)
+                    param[:, indices] = torch.tensor(values, dtype=torch.float, device=self._device)
+                # otherwise, we expect tuples
+                else:
+                    # We can't directly assign tuples to tensors, so iterate through them
+                    for i, v in enumerate(values):
+                        # Raise an exception if the tuple is the incorrect length
+                        if len(v) is not expected_shape[2]:
+                            raise ValueError(
+                                f"Invalid tuple length for parameter {param_name} on joint {j[i]} at index"
+                                f" {indices[i]},"
+                                + f" expected {expected_shape[2]} got {len(v)}."
+                            )
+                        # Otherwise iterate through the tuple, and assign the values in order.
+                        for i2, v2 in enumerate(v):
+                            param[:, indices[i], i2] = float(v2)
             else:
                 raise TypeError(
                     f"Invalid type for parameter value: {type(cfg_value)} for "
-                    + f"actuator on joints {self.joint_names}. Expected float or dict."
+                    + f"actuator on joints {self.joint_names}. Expected tuple, float or dict."
                 )
         elif default_value is not None:
             if isinstance(default_value, (float, int)):
                 # if float, then use the same value for all joints
                 param[:] = float(default_value)
+            elif isinstance(default_value, tuple):
+                # if tuple, ensure we expect a tuple for this parameter
+                if len(expected_shape) < 3:
+                    raise TypeError(
+                        f"Invalid default type for parameter value: {type(default_value)} for "
+                        + f"actuator on joints {self.joint_names}. Expected float or dict, got tuple"
+                    )
+                # ensure the tuple is the correct length, and assign to the last tensor dimensions across all joints
+                if not len(default_value) is expected_shape[2]:
+                    raise ValueError(
+                        f"Invalid tuple length for parameter {param_name}, got {len(default_value)}, expected"
+                        + f" {expected_shape[2]}"
+                    )
+                for i, v in enumerate(default_value):
+                    param[:, :, i] = float(v)
             elif isinstance(default_value, torch.Tensor):
                 # if tensor, then use the same tensor for all joints
-                if default_value.shape == (self._num_envs, self.num_joints):
+                if tuple(default_value.shape) == expected_shape:
                     param = default_value.float()
                 else:
                     raise ValueError(
                         "Invalid default value tensor shape.\n"
-                        f"Got: {default_value.shape}\n"
-                        f"Expected: {(self._num_envs, self.num_joints)}"
+                        + f"Got: {tuple(default_value.shape)}\n"
+                        + f"Expected: {expected_shape}"
                     )
             else:
                 raise TypeError(