parent 7e8ebe6

author Brian McCann <[email protected]> 1762808364 -0500
committer Brian McCann <[email protected]> 1762808383 -0500

This change implements the necessary changes to the articulation and actuator classes in order to configure the new actuator drive model including velocity and effort dependent constraints on motor actuation. For details see https://nvidia-omniverse.github.io/PhysX/physx/5.6.1/docs/Articulations.html#articulation-drive-stability and https://docs.omniverse.nvidia.com/kit/docs/omni_physics/latest/extensions/runtime/source/omni.physics.tensors/docs/api/python.html#omni.physics.tensors.impl.api.ArticulationView.set_dof_drive_model_properties

Author: bmccann-bdai

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

@@ -36,6 +36,9 @@ Actuator Base
   :inherited-members:
   :exclude-members: __init__, class_type
 
+.. autoclass:: isaaclab.actuators.actuator_base_cfg.ActuatorBaseCfg.DriveModelCfg
+  :members:
+
 Implicit Actuator
 -----------------
 

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,8 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "0.48.1"
+
+version = "0.48.2"
 
 # Description
 title = "Isaac Lab framework for Robot Learning"

source/isaaclab/docs/CHANGELOG.rst

@@ -1,14 +1,25 @@
 Changelog
 ---------
 
-0.48.1 (2025-11-10)
+0.48.2 (2025-11-10)
 ~~~~~~~~~~~~~~~~~~~
 
-Changed
-^^^^^^^
+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.
+* 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.
 
-* Refactored modules related to the actuator configs in order to remediate a circular import necessary to support future
-  actuator drive model improvements.
+0.48.1 (2025-11-10)                                                                                                           
+~~~~~~~~~~~~~~~~~~~                                                                                                           
+                                                                                                                              
+Changed                                                                                                                       
+^^^^^^^                                                                                                                       
+                                                                                                                              
+* Refactored modules related to the actuator configs in order to remediate a circular import necessary to support future      
+  actuator drive model improvements.  
 
 0.48.0 (2025-11-03)
 ~~~~~~~~~~~~~~~~~~~
@@ -71,6 +82,16 @@ Added
 
 * Added parameter :attr:`~isaaclab.terrains.TerrainImporterCfg.use_terrain_origins` to allow generated sub terrains with grid origins.
 
+0.48.2 (2025-11-10)
+~~~~~~~~~~~~~~~~~~
+
+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.
+* 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/actuator_base.py

@@ -8,13 +8,17 @@
 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
 
+<<<<<<< HEAD
 if TYPE_CHECKING:
     from .actuator_base_cfg import ActuatorBaseCfg
+=======
+from .actuator_base_cfg import ActuatorBaseCfg
+>>>>>>> ed1544b8ca (parent 7e8ebe67ef3e3c280eb3fda39443d643317fdeca)
 
 
 class ActuatorBase(ABC):
@@ -84,6 +88,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)."""
 
@@ -124,6 +140,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.
 
@@ -160,6 +177,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
@@ -187,19 +207,32 @@ 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,
@@ -303,20 +336,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.
@@ -325,38 +373,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) == 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) != 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) == 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(

source/isaaclab/isaaclab/actuators/actuator_base_cfg.py

@@ -4,6 +4,11 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 from dataclasses import MISSING
+<<<<<<< HEAD
+=======
+from torch import inf
+from typing import NamedTuple
+>>>>>>> ed1544b8ca (parent 7e8ebe67ef3e3c280eb3fda39443d643317fdeca)
 
 from isaaclab.utils import configclass
 
@@ -48,6 +53,21 @@ class ActuatorBaseCfg:
 
     """
 
+<<<<<<< HEAD
+=======
+    """Optional (min v5) settings to the drive model capturing performance envelope velocity-effort dependence.
+
+    See: https://docs.omniverse.nvidia.com/kit/docs/omni_physics/107.3/_downloads/f44e831b7f29e7c2ec8e3f2c54418430/drivePerformanceEnvelope.pdf
+    """
+
+    class DriveModelCfg(NamedTuple):
+        speed_effort_gradient: float = 0.0
+        max_actuator_velocity: float = inf
+        velocity_dependent_resistance: float = 0.0
+
+    drive_model: dict[str, DriveModelCfg] | DriveModelCfg | None = None
+
+>>>>>>> ed1544b8ca (parent 7e8ebe67ef3e3c280eb3fda39443d643317fdeca)
     velocity_limit: dict[str, float] | float | None = None
     """Velocity limit of the joints in the group. Defaults to None.