Apply dexterous lump review updates to the Direct layer

Fold the reviewed lump changes that belong to this part's content:

- Share per-family sim settings through task-cfg base mixins.
- Deduplicate backend scene presets via inner-class defaults and nest
  single-consumer helper cfgs in the shadow-hand Direct cfg.
- Compute the orientation error through
  isaaclab.utils.math.quat_error_magnitude and delete the local
  direct_reorient_rotation_distance primitive.
- Rename direct_reorient_reward to reorient_reward: shared symbols
  carry no paradigm prefix.

Source commits on the lump branch: 2c22af0, 792e400,
42675b6, c6140f9, 173e9dc.

Author: hujc7

source/isaaclab_tasks/changelog.d/task-cleanup-dex-part03.minor.rst

@@ -8,4 +8,6 @@ Fixed
 ^^^^^
 
 * Fixed dexterous hand resets that could initialize joints below their lower
-  position limits.
+  position limits. Reset joint positions now sample uniformly across the full
+  joint range; previously the distribution was biased toward the lower half of
+  the range.

source/isaaclab_tasks/isaaclab_tasks/core/reorient/config/allegro_hand/allegro_hand_direct_env_cfg.py

@@ -119,20 +119,26 @@ class PhysicsCfg(PresetCfg):
         )
     },
 )
+
+
 # Simulation settings shared by the Direct and manager variants (configclass
 # deep-copies these defaults per cfg instance). The solver-common base material
 # is sufficient: only friction values are set, so no PhysX-specific
 # ``physxMaterial`` attributes are authored.
-ALLEGRO_SIM_CFG = SimulationCfg(
-    dt=1 / 120,
-    render_interval=4,
-    physics_material=RigidBodyMaterialBaseCfg(static_friction=1.0, dynamic_friction=1.0),
-    physics=PhysicsCfg(),
-)
+@configclass
+class AllegroHandTaskCfgBase:
+    """Shared Allegro task settings inherited by both the Direct and the manager configurations."""
+
+    sim: SimulationCfg = SimulationCfg(
+        dt=1 / 120,
+        render_interval=4,
+        physics_material=RigidBodyMaterialBaseCfg(static_friction=1.0, dynamic_friction=1.0),
+        physics=PhysicsCfg(),
+    )
 
 
 @configclass
-class AllegroHandEnvCfg(DirectRLEnvCfg):
+class AllegroHandEnvCfg(AllegroHandTaskCfgBase, DirectRLEnvCfg):
     # env
     decimation = 4
     episode_length_s = 10.0
@@ -141,8 +147,6 @@ class AllegroHandEnvCfg(DirectRLEnvCfg):
     state_space = 0
     asymmetric_obs = False
     obs_type = "full"
-    # simulation
-    sim: SimulationCfg = ALLEGRO_SIM_CFG
     # robot
     robot_cfg: ArticulationCfg = ROBOT_CFG
 

source/isaaclab_tasks/isaaclab_tasks/core/reorient/config/shadow_hand/shadow_hand_env_cfg.py

@@ -274,18 +274,16 @@ class ShadowHandSceneCfg(PresetCfg):
     Newton does not support Fabric cloning, so ``clone_in_fabric`` must be ``False``.
     """
 
-    physx: InteractiveSceneCfg = InteractiveSceneCfg(
-        num_envs=8192,
-        env_spacing=0.75,
-        replicate_physics=True,
-        clone_in_fabric=True,
-    )
-    newton_mjwarp: InteractiveSceneCfg = InteractiveSceneCfg(
-        num_envs=8192,
-        env_spacing=0.75,
-        replicate_physics=True,
-        clone_in_fabric=False,
-    )
+    @configclass
+    class SceneCfg(InteractiveSceneCfg):
+        """Shadow Direct scene defaults; backend presets only set ``clone_in_fabric``."""
+
+        num_envs = 8192
+        env_spacing = 0.75
+        replicate_physics = True
+
+    physx: InteractiveSceneCfg = SceneCfg(clone_in_fabric=True)
+    newton_mjwarp: InteractiveSceneCfg = SceneCfg(clone_in_fabric=False)
     default: InteractiveSceneCfg = physx
     newton_kamino = newton_mjwarp
 
@@ -328,26 +326,38 @@ class PhysicsCfg(PresetCfg):
         )
     },
 )
+
+
 # Simulation settings shared by the Direct and manager variants (configclass
 # deep-copies these defaults per cfg instance). The solver-common base material
 # is sufficient: only friction values are set, so no PhysX-specific
 # ``physxMaterial`` attributes are authored.
-SHADOW_SIM_CFG = SimulationCfg(
-    dt=1 / 120,
-    render_interval=2,
-    physics_material=RigidBodyMaterialBaseCfg(static_friction=1.0, dynamic_friction=1.0),
-    physics=PhysicsCfg(),
-)
-OPENAI_SIM_CFG = SimulationCfg(
-    dt=1 / 60,
-    render_interval=3,
-    physics_material=RigidBodyMaterialBaseCfg(static_friction=1.0, dynamic_friction=1.0),
-    physics=PhysicsCfg(),
-)
+@configclass
+class ShadowHandTaskCfgBase:
+    """Shared Shadow task settings inherited by both the Direct and the manager configurations."""
+
+    sim: SimulationCfg = SimulationCfg(
+        dt=1 / 120,
+        render_interval=2,
+        physics_material=RigidBodyMaterialBaseCfg(static_friction=1.0, dynamic_friction=1.0),
+        physics=PhysicsCfg(),
+    )
+
+
+@configclass
+class ShadowHandOpenAITaskCfgBase(ShadowHandTaskCfgBase):
+    """Shared OpenAI-variant task settings (60 Hz stepping) for both paradigms."""
+
+    sim: SimulationCfg = SimulationCfg(
+        dt=1 / 60,
+        render_interval=3,
+        physics_material=RigidBodyMaterialBaseCfg(static_friction=1.0, dynamic_friction=1.0),
+        physics=PhysicsCfg(),
+    )
 
 
 @configclass
-class ShadowHandEnvCfg(DirectRLEnvCfg):
+class ShadowHandEnvCfg(ShadowHandTaskCfgBase, DirectRLEnvCfg):
     # env
     decimation = 2
     episode_length_s = 10.0
@@ -357,8 +367,6 @@ class ShadowHandEnvCfg(DirectRLEnvCfg):
     asymmetric_obs = False
     obs_type = "full"
 
-    # simulation
-    sim: SimulationCfg = SHADOW_SIM_CFG
     # robot
     robot_cfg: ShadowHandRobotCfg = ROBOT_CFG
     actuated_joint_names = SHADOW_ACTUATED_JOINT_NAMES
@@ -405,7 +413,7 @@ class ShadowHandEnvCfg(DirectRLEnvCfg):
 
 
 @configclass
-class ShadowHandOpenAIEnvCfg(ShadowHandEnvCfg):
+class ShadowHandOpenAIEnvCfg(ShadowHandOpenAITaskCfgBase, ShadowHandEnvCfg):
     # env
     decimation = 3
     episode_length_s = 8.0
@@ -414,8 +422,6 @@ class ShadowHandOpenAIEnvCfg(ShadowHandEnvCfg):
     state_space = 187
     asymmetric_obs = True
     obs_type = "openai"
-    # simulation
-    sim: SimulationCfg = OPENAI_SIM_CFG
     # reset
     reset_position_noise = 0.01  # range of position at reset
     reset_dof_pos_noise = 0.2  # range of dof pos at reset

source/isaaclab_tasks/isaaclab_tasks/core/reorient/mdp/__init__.pyi

@@ -10,9 +10,8 @@ __all__ = [
     "success_bonus",
     "track_orientation_inv_l2",
     "track_pos_l2",
-    "direct_reorient_rotation_distance",
     "evaluate_reorient_success",
-    "direct_reorient_reward",
+    "reorient_reward",
     "max_consecutive_success",
     "object_away_from_goal",
     "object_away_from_robot",
@@ -21,8 +20,7 @@ __all__ = [
 from .commands import ReorientCommand, ReorientCommandCfg
 from .observations import goal_quat_diff
 from .rewards import (
-    direct_reorient_reward,
-    direct_reorient_rotation_distance,
+    reorient_reward,
     evaluate_reorient_success,
     success_bonus,
     track_orientation_inv_l2,

source/isaaclab_tasks/isaaclab_tasks/core/reorient/mdp/rewards.py

@@ -100,21 +100,6 @@ def track_orientation_inv_l2(
     return 1.0 / (dtheta + rot_eps)
 
 
-@torch.jit.script
-def direct_reorient_rotation_distance(object_quat: torch.Tensor, target_quat: torch.Tensor) -> torch.Tensor:
-    """Compute the Direct reorientation orientation distance [rad].
-
-    Args:
-        object_quat: Object ``(x, y, z, w)`` orientations.
-        target_quat: Target ``(x, y, z, w)`` orientations.
-
-    Returns:
-        Per-environment orientation distances [rad], in ``[0, pi]``.
-    """
-    quat_diff = math_utils.quat_mul(object_quat, math_utils.quat_conjugate(target_quat))
-    return 2.0 * torch.asin(torch.clamp(torch.linalg.norm(quat_diff[:, 0:3], ord=2, dim=-1), max=1.0))
-
-
 @torch.jit.script
 def evaluate_reorient_success(
     object_quat: torch.Tensor, target_quat: torch.Tensor, success_tolerance: float
@@ -133,12 +118,12 @@ def evaluate_reorient_success(
     Returns:
         Per-environment success flags and orientation errors [rad].
     """
-    orientation_error = direct_reorient_rotation_distance(object_quat, target_quat)
+    orientation_error = math_utils.quat_error_magnitude(object_quat, target_quat)
     return orientation_error <= success_tolerance, orientation_error
 
 
 @torch.jit.script
-def direct_reorient_reward(
+def reorient_reward(
     reset_buf: torch.Tensor,
     reset_goal_buf: torch.Tensor,
     successes: torch.Tensor,

source/isaaclab_tasks/isaaclab_tasks/core/reorient/reorient_direct_env.py

@@ -20,7 +20,7 @@
 from isaaclab.sim.spawners.from_files import GroundPlaneCfg, spawn_ground_plane
 from isaaclab.utils.math import quat_conjugate, quat_mul, sample_uniform, saturate, scale_transform, unscale_transform
 
-from isaaclab_tasks.core.reorient.mdp.rewards import direct_reorient_reward, evaluate_reorient_success
+from isaaclab_tasks.core.reorient.mdp.rewards import evaluate_reorient_success, reorient_reward
 from isaaclab_tasks.core.reorient.reorient_task_base import GOAL_MARKER_POSITION, IN_HAND_POS_OFFSET
 from isaaclab_tasks.core.utils import EpisodeErrorRecorder, randomize_rotation, sample_joint_positions_within_limits
 
@@ -185,7 +185,7 @@ def _get_rewards(self) -> torch.Tensor:
         # the success flags and orientation errors were computed this step by
         # :meth:`_get_dones`; the recorder and the reward reuse them
         self._orientation_error.update(self._orientation_error_buf)
-        total_reward, goal_resets, successes, consecutive_successes = direct_reorient_reward(
+        total_reward, goal_resets, successes, consecutive_successes = reorient_reward(
             self.reset_buf,
             self.reset_goal_buf,
             self.successes,

source/isaaclab_tasks/test/core/test_dexterous_task_math.py

@@ -17,7 +17,7 @@
 
 import isaaclab.utils.math as math_utils
 
-from isaaclab_tasks.core.reorient.mdp.rewards import direct_reorient_rotation_distance, evaluate_reorient_success
+from isaaclab_tasks.core.reorient.mdp.rewards import evaluate_reorient_success
 
 _DEVICES = ["cpu"] + (["cuda:0"] if torch.cuda.is_available() else [])
 
@@ -35,8 +35,8 @@ def _quats(device, *quats):
 
 @pytest.mark.parametrize("device", _DEVICES)
 def test_rotation_distance_recovers_known_angles(device):
-    distance = direct_reorient_rotation_distance(
-        _quats(device, _IDENTITY, _ROT90_X, _ROT180_Z), _quats(device, _IDENTITY, _IDENTITY, _IDENTITY)
+    _, distance = evaluate_reorient_success(
+        _quats(device, _IDENTITY, _ROT90_X, _ROT180_Z), _quats(device, _IDENTITY, _IDENTITY, _IDENTITY), 0.4
     )
     torch.testing.assert_close(distance, torch.tensor([0.0, math.pi / 2, math.pi], device=device), atol=1e-5, rtol=0.0)