From 74b13068f4fcfd64da11e719e3f303bca6ae39ad Mon Sep 17 00:00:00 2001 From: AntoineRichard Date: Wed, 12 Aug 2026 11:18:06 +0200 Subject: [PATCH 1/4] Deprecate IO descriptors Mark IO descriptor APIs and CLI options for removal in Isaac Lab 3.2 while preserving their compatibility behavior.\n\nRemove the deployment tutorial and generated YAML examples so new users are directed toward LEAPP where supported. --- ...ocity_flat_anymal_d_v0_IO_descriptors.yaml | 349 --------- ...ac_velocity_flat_g1_v0_IO_descriptors.yaml | 724 ------------------ .../newton/warp-env-migration.rst | 7 + .../01_io_descriptors/io_descriptors_101.rst | 315 -------- docs/source/policy_deployment/index.rst | 1 - .../changelog.d/deprecate-io-descriptors.rst | 6 + .../isaaclab/envs/manager_based_env.py | 26 +- .../isaaclab/envs/manager_based_env_cfg.py | 7 +- .../isaaclab/envs/utils/io_descriptors.py | 27 + .../isaaclab/managers/action_manager.py | 21 +- .../isaaclab/managers/observation_manager.py | 8 + .../changelog.d/deprecate-io-descriptors.rst | 7 + .../envs/manager_based_env_warp.py | 26 +- .../envs/utils/io_descriptors.py | 7 + .../managers/action_manager.py | 21 +- .../managers/observation_manager.py | 9 + .../changelog.d/deprecate-io-descriptors.rst | 6 + .../isaaclab_rl/entrypoints/common.py | 7 +- 18 files changed, 169 insertions(+), 1405 deletions(-) delete mode 100644 docs/source/_static/policy_deployment/01_io_descriptors/isaac_velocity_flat_anymal_d_v0_IO_descriptors.yaml delete mode 100644 docs/source/_static/policy_deployment/01_io_descriptors/isaac_velocity_flat_g1_v0_IO_descriptors.yaml delete mode 100644 docs/source/policy_deployment/01_io_descriptors/io_descriptors_101.rst create mode 100644 source/isaaclab/changelog.d/deprecate-io-descriptors.rst create mode 100644 source/isaaclab_experimental/changelog.d/deprecate-io-descriptors.rst create mode 100644 source/isaaclab_rl/changelog.d/deprecate-io-descriptors.rst diff --git a/docs/source/_static/policy_deployment/01_io_descriptors/isaac_velocity_flat_anymal_d_v0_IO_descriptors.yaml b/docs/source/_static/policy_deployment/01_io_descriptors/isaac_velocity_flat_anymal_d_v0_IO_descriptors.yaml deleted file mode 100644 index f44840c0f908..000000000000 --- a/docs/source/_static/policy_deployment/01_io_descriptors/isaac_velocity_flat_anymal_d_v0_IO_descriptors.yaml +++ /dev/null @@ -1,349 +0,0 @@ -# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). -# All rights reserved. -# -# SPDX-License-Identifier: BSD-3-Clause - -actions: -- action_type: JointAction - clip: null - dtype: torch.float32 - extras: - description: Joint action term that applies the processed actions to the articulation's - joints as position commands. - full_path: isaaclab.envs.mdp.actions.joint_actions.JointPositionAction - joint_names: - - LF_HAA - - LH_HAA - - RF_HAA - - RH_HAA - - LF_HFE - - LH_HFE - - RF_HFE - - RH_HFE - - LF_KFE - - LH_KFE - - RF_KFE - - RH_KFE - mdp_type: Action - name: joint_position_action - offset: - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.4000000059604645 - - -0.4000000059604645 - - 0.4000000059604645 - - -0.4000000059604645 - - -0.800000011920929 - - 0.800000011920929 - - -0.800000011920929 - - 0.800000011920929 - scale: 0.5 - shape: - - 12 -articulations: - robot: - default_joint_armature: - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - default_joint_damping: - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - default_joint_friction: - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - default_joint_pos: - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.4000000059604645 - - -0.4000000059604645 - - 0.4000000059604645 - - -0.4000000059604645 - - -0.800000011920929 - - 0.800000011920929 - - -0.800000011920929 - - 0.800000011920929 - default_joint_pos_limits: - - - -0.7853984236717224 - - 0.6108654141426086 - - - -0.7853984236717224 - - 0.6108654141426086 - - - -0.6108654141426086 - - 0.7853984236717224 - - - -0.6108654141426086 - - 0.7853984236717224 - - - -9.42477798461914 - - 9.42477798461914 - - - -9.42477798461914 - - 9.42477798461914 - - - -9.42477798461914 - - 9.42477798461914 - - - -9.42477798461914 - - 9.42477798461914 - - - -9.42477798461914 - - 9.42477798461914 - - - -9.42477798461914 - - 9.42477798461914 - - - -9.42477798461914 - - 9.42477798461914 - - - -9.42477798461914 - - 9.42477798461914 - default_joint_stiffness: - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - default_joint_vel: - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - joint_names: - - LF_HAA - - LH_HAA - - RF_HAA - - RH_HAA - - LF_HFE - - LH_HFE - - RF_HFE - - RH_HFE - - LF_KFE - - LH_KFE - - RF_KFE - - RH_KFE -observations: - policy: - - dtype: torch.float32 - extras: - axes: - - X - - Y - - Z - description: Root linear velocity in the asset's root frame. - modifiers: null - units: m/s - full_path: isaaclab.envs.mdp.observations.base_lin_vel - mdp_type: Observation - name: base_lin_vel - observation_type: RootState - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 3 - - dtype: torch.float32 - extras: - axes: - - X - - Y - - Z - description: Root angular velocity in the asset's root frame. - modifiers: null - units: rad/s - full_path: isaaclab.envs.mdp.observations.base_ang_vel - mdp_type: Observation - name: base_ang_vel - observation_type: RootState - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 3 - - dtype: torch.float32 - extras: - axes: - - X - - Y - - Z - description: Gravity projection on the asset's root frame. - modifiers: null - units: m/s^2 - full_path: isaaclab.envs.mdp.observations.projected_gravity - mdp_type: Observation - name: projected_gravity - observation_type: RootState - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 3 - - dtype: torch.float32 - extras: - description: The generated command from command term in the command manager - with the given name. - modifiers: null - full_path: isaaclab.envs.mdp.observations.generated_commands - mdp_type: Observation - name: generated_commands - observation_type: Command - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 3 - - dtype: torch.float32 - extras: - description: 'The joint positions of the asset w.r.t. the default joint positions. - Note: Only the joints configured in :attr:`asset_cfg.joint_ids` will have - their positions returned.' - modifiers: null - units: rad - full_path: isaaclab.envs.mdp.observations.joint_pos_rel - joint_names: - - LF_HAA - - LH_HAA - - RF_HAA - - RH_HAA - - LF_HFE - - LH_HFE - - RF_HFE - - RH_HFE - - LF_KFE - - LH_KFE - - RF_KFE - - RH_KFE - joint_pos_offsets: - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.4000000059604645 - - -0.4000000059604645 - - 0.4000000059604645 - - -0.4000000059604645 - - -0.800000011920929 - - 0.800000011920929 - - -0.800000011920929 - - 0.800000011920929 - mdp_type: Observation - name: joint_pos_rel - observation_type: JointState - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 12 - - dtype: torch.float32 - extras: - description: 'The joint velocities of the asset w.r.t. the default joint velocities. - Note: Only the joints configured in :attr:`asset_cfg.joint_ids` will have - their velocities returned.' - modifiers: null - units: rad/s - full_path: isaaclab.envs.mdp.observations.joint_vel_rel - joint_names: - - LF_HAA - - LH_HAA - - RF_HAA - - RH_HAA - - LF_HFE - - LH_HFE - - RF_HFE - - RH_HFE - - LF_KFE - - LH_KFE - - RF_KFE - - RH_KFE - joint_vel_offsets: - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - mdp_type: Observation - name: joint_vel_rel - observation_type: JointState - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 12 - - dtype: torch.float32 - extras: - description: The last input action to the environment. The name of the action - term for which the action is required. If None, the entire action tensor is - returned. - modifiers: null - full_path: isaaclab.envs.mdp.observations.last_action - mdp_type: Observation - name: last_action - observation_type: Action - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 12 -scene: - decimation: 4 - dt: 0.02 - physics_dt: 0.005 diff --git a/docs/source/_static/policy_deployment/01_io_descriptors/isaac_velocity_flat_g1_v0_IO_descriptors.yaml b/docs/source/_static/policy_deployment/01_io_descriptors/isaac_velocity_flat_g1_v0_IO_descriptors.yaml deleted file mode 100644 index d932800eaf6e..000000000000 --- a/docs/source/_static/policy_deployment/01_io_descriptors/isaac_velocity_flat_g1_v0_IO_descriptors.yaml +++ /dev/null @@ -1,724 +0,0 @@ -# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). -# All rights reserved. -# -# SPDX-License-Identifier: BSD-3-Clause - -actions: -- action_type: JointAction - clip: null - dtype: torch.float32 - extras: - description: Joint action term that applies the processed actions to the articulation's - joints as position commands. - full_path: isaaclab.envs.mdp.actions.joint_actions.JointPositionAction - joint_names: - - left_hip_pitch_joint - - right_hip_pitch_joint - - torso_joint - - left_hip_roll_joint - - right_hip_roll_joint - - left_shoulder_pitch_joint - - right_shoulder_pitch_joint - - left_hip_yaw_joint - - right_hip_yaw_joint - - left_shoulder_roll_joint - - right_shoulder_roll_joint - - left_knee_joint - - right_knee_joint - - left_shoulder_yaw_joint - - right_shoulder_yaw_joint - - left_ankle_pitch_joint - - right_ankle_pitch_joint - - left_elbow_pitch_joint - - right_elbow_pitch_joint - - left_ankle_roll_joint - - right_ankle_roll_joint - - left_elbow_roll_joint - - right_elbow_roll_joint - - left_five_joint - - left_three_joint - - left_zero_joint - - right_five_joint - - right_three_joint - - right_zero_joint - - left_six_joint - - left_four_joint - - left_one_joint - - right_six_joint - - right_four_joint - - right_one_joint - - left_two_joint - - right_two_joint - mdp_type: Action - name: joint_position_action - offset: - - -0.20000000298023224 - - -0.20000000298023224 - - 0.0 - - 0.0 - - 0.0 - - 0.3499999940395355 - - 0.3499999940395355 - - 0.0 - - 0.0 - - 0.1599999964237213 - - -0.1599999964237213 - - 0.41999998688697815 - - 0.41999998688697815 - - 0.0 - - 0.0 - - -0.23000000417232513 - - -0.23000000417232513 - - 0.8700000047683716 - - 0.8700000047683716 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 1.0 - - 0.0 - - 0.0 - - -1.0 - - 0.5199999809265137 - - -0.5199999809265137 - scale: 0.5 - shape: - - 37 -articulations: - robot: - default_joint_armature: - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.009999999776482582 - - 0.0010000000474974513 - - 0.0010000000474974513 - - 0.0010000000474974513 - - 0.0010000000474974513 - - 0.0010000000474974513 - - 0.0010000000474974513 - - 0.0010000000474974513 - - 0.0010000000474974513 - - 0.0010000000474974513 - - 0.0010000000474974513 - - 0.0010000000474974513 - - 0.0010000000474974513 - - 0.0010000000474974513 - - 0.0010000000474974513 - default_joint_damping: - - 5.0 - - 5.0 - - 5.0 - - 5.0 - - 5.0 - - 10.0 - - 10.0 - - 5.0 - - 5.0 - - 10.0 - - 10.0 - - 5.0 - - 5.0 - - 10.0 - - 10.0 - - 2.0 - - 2.0 - - 10.0 - - 10.0 - - 2.0 - - 2.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - - 10.0 - default_joint_friction: - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - default_joint_pos: - - -0.20000000298023224 - - -0.20000000298023224 - - 0.0 - - 0.0 - - 0.0 - - 0.3499999940395355 - - 0.3499999940395355 - - 0.0 - - 0.0 - - 0.1599999964237213 - - -0.1599999964237213 - - 0.41999998688697815 - - 0.41999998688697815 - - 0.0 - - 0.0 - - -0.23000000417232513 - - -0.23000000417232513 - - 0.8700000047683716 - - 0.8700000047683716 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 1.0 - - 0.0 - - 0.0 - - -1.0 - - 0.5199999809265137 - - -0.5199999809265137 - default_joint_pos_limits: - - - -2.3499996662139893 - - 3.049999952316284 - - - -2.3499996662139893 - - 3.049999952316284 - - - -2.618000030517578 - - 2.618000030517578 - - - -0.25999996066093445 - - 2.5299997329711914 - - - -2.5299997329711914 - - 0.25999996066093445 - - - -2.967099666595459 - - 2.7924997806549072 - - - -2.967099666595459 - - 2.7924997806549072 - - - -2.749999761581421 - - 2.749999761581421 - - - -2.749999761581421 - - 2.749999761581421 - - - -1.5881999731063843 - - 2.251499652862549 - - - -2.251499652862549 - - 1.5881999731063843 - - - -0.3348899781703949 - - 2.5448997020721436 - - - -0.3348899781703949 - - 2.5448997020721436 - - - -2.618000030517578 - - 2.618000030517578 - - - -2.618000030517578 - - 2.618000030517578 - - - -0.6799999475479126 - - 0.7299999594688416 - - - -0.6799999475479126 - - 0.7299999594688416 - - - -0.22679997980594635 - - 3.420799732208252 - - - -0.22679997980594635 - - 3.420799732208252 - - - -0.26179996132850647 - - 0.26179996132850647 - - - -0.26179996132850647 - - 0.26179996132850647 - - - -2.094299793243408 - - 2.094299793243408 - - - -2.094299793243408 - - 2.094299793243408 - - - -1.8399999141693115 - - 0.30000001192092896 - - - -1.8399999141693115 - - 0.30000001192092896 - - - -0.5235979557037354 - - 0.5235979557037354 - - - -0.30000001192092896 - - 1.8399999141693115 - - - -0.30000001192092896 - - 1.8399999141693115 - - - -0.5235979557037354 - - 0.5235979557037354 - - - -1.8399999141693115 - - 0.0 - - - -1.8399999141693115 - - 0.0 - - - -0.9999999403953552 - - 1.2000000476837158 - - - 0.0 - - 1.8399999141693115 - - - 0.0 - - 1.8399999141693115 - - - -1.2000000476837158 - - 0.9999999403953552 - - - 0.0 - - 1.8399999141693115 - - - -1.8399999141693115 - - 0.0 - default_joint_stiffness: - - 200.0 - - 200.0 - - 200.0 - - 150.0 - - 150.0 - - 40.0 - - 40.0 - - 150.0 - - 150.0 - - 40.0 - - 40.0 - - 200.0 - - 200.0 - - 40.0 - - 40.0 - - 20.0 - - 20.0 - - 40.0 - - 40.0 - - 20.0 - - 20.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - - 40.0 - default_joint_vel: - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - joint_names: - - left_hip_pitch_joint - - right_hip_pitch_joint - - torso_joint - - left_hip_roll_joint - - right_hip_roll_joint - - left_shoulder_pitch_joint - - right_shoulder_pitch_joint - - left_hip_yaw_joint - - right_hip_yaw_joint - - left_shoulder_roll_joint - - right_shoulder_roll_joint - - left_knee_joint - - right_knee_joint - - left_shoulder_yaw_joint - - right_shoulder_yaw_joint - - left_ankle_pitch_joint - - right_ankle_pitch_joint - - left_elbow_pitch_joint - - right_elbow_pitch_joint - - left_ankle_roll_joint - - right_ankle_roll_joint - - left_elbow_roll_joint - - right_elbow_roll_joint - - left_five_joint - - left_three_joint - - left_zero_joint - - right_five_joint - - right_three_joint - - right_zero_joint - - left_six_joint - - left_four_joint - - left_one_joint - - right_six_joint - - right_four_joint - - right_one_joint - - left_two_joint - - right_two_joint -observations: - policy: - - dtype: torch.float32 - extras: - axes: - - X - - Y - - Z - description: Root linear velocity in the asset's root frame. - modifiers: null - units: m/s - full_path: isaaclab.envs.mdp.observations.base_lin_vel - mdp_type: Observation - name: base_lin_vel - observation_type: RootState - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 3 - - dtype: torch.float32 - extras: - axes: - - X - - Y - - Z - description: Root angular velocity in the asset's root frame. - modifiers: null - units: rad/s - full_path: isaaclab.envs.mdp.observations.base_ang_vel - mdp_type: Observation - name: base_ang_vel - observation_type: RootState - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 3 - - dtype: torch.float32 - extras: - axes: - - X - - Y - - Z - description: Gravity projection on the asset's root frame. - modifiers: null - units: m/s^2 - full_path: isaaclab.envs.mdp.observations.projected_gravity - mdp_type: Observation - name: projected_gravity - observation_type: RootState - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 3 - - dtype: torch.float32 - extras: - description: The generated command from command term in the command manager - with the given name. - modifiers: null - full_path: isaaclab.envs.mdp.observations.generated_commands - mdp_type: Observation - name: generated_commands - observation_type: Command - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 3 - - dtype: torch.float32 - extras: - description: 'The joint positions of the asset w.r.t. the default joint positions. - Note: Only the joints configured in :attr:`asset_cfg.joint_ids` will have - their positions returned.' - modifiers: null - units: rad - full_path: isaaclab.envs.mdp.observations.joint_pos_rel - joint_names: - - left_hip_pitch_joint - - right_hip_pitch_joint - - torso_joint - - left_hip_roll_joint - - right_hip_roll_joint - - left_shoulder_pitch_joint - - right_shoulder_pitch_joint - - left_hip_yaw_joint - - right_hip_yaw_joint - - left_shoulder_roll_joint - - right_shoulder_roll_joint - - left_knee_joint - - right_knee_joint - - left_shoulder_yaw_joint - - right_shoulder_yaw_joint - - left_ankle_pitch_joint - - right_ankle_pitch_joint - - left_elbow_pitch_joint - - right_elbow_pitch_joint - - left_ankle_roll_joint - - right_ankle_roll_joint - - left_elbow_roll_joint - - right_elbow_roll_joint - - left_five_joint - - left_three_joint - - left_zero_joint - - right_five_joint - - right_three_joint - - right_zero_joint - - left_six_joint - - left_four_joint - - left_one_joint - - right_six_joint - - right_four_joint - - right_one_joint - - left_two_joint - - right_two_joint - joint_pos_offsets: - - -0.20000000298023224 - - -0.20000000298023224 - - 0.0 - - 0.0 - - 0.0 - - 0.3499999940395355 - - 0.3499999940395355 - - 0.0 - - 0.0 - - 0.1599999964237213 - - -0.1599999964237213 - - 0.41999998688697815 - - 0.41999998688697815 - - 0.0 - - 0.0 - - -0.23000000417232513 - - -0.23000000417232513 - - 0.8700000047683716 - - 0.8700000047683716 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 1.0 - - 0.0 - - 0.0 - - -1.0 - - 0.5199999809265137 - - -0.5199999809265137 - mdp_type: Observation - name: joint_pos_rel - observation_type: JointState - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 37 - - dtype: torch.float32 - extras: - description: 'The joint velocities of the asset w.r.t. the default joint velocities. - Note: Only the joints configured in :attr:`asset_cfg.joint_ids` will have - their velocities returned.' - modifiers: null - units: rad/s - full_path: isaaclab.envs.mdp.observations.joint_vel_rel - joint_names: - - left_hip_pitch_joint - - right_hip_pitch_joint - - torso_joint - - left_hip_roll_joint - - right_hip_roll_joint - - left_shoulder_pitch_joint - - right_shoulder_pitch_joint - - left_hip_yaw_joint - - right_hip_yaw_joint - - left_shoulder_roll_joint - - right_shoulder_roll_joint - - left_knee_joint - - right_knee_joint - - left_shoulder_yaw_joint - - right_shoulder_yaw_joint - - left_ankle_pitch_joint - - right_ankle_pitch_joint - - left_elbow_pitch_joint - - right_elbow_pitch_joint - - left_ankle_roll_joint - - right_ankle_roll_joint - - left_elbow_roll_joint - - right_elbow_roll_joint - - left_five_joint - - left_three_joint - - left_zero_joint - - right_five_joint - - right_three_joint - - right_zero_joint - - left_six_joint - - left_four_joint - - left_one_joint - - right_six_joint - - right_four_joint - - right_one_joint - - left_two_joint - - right_two_joint - joint_vel_offsets: - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - - 0.0 - mdp_type: Observation - name: joint_vel_rel - observation_type: JointState - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 37 - - dtype: torch.float32 - extras: - description: The last input action to the environment. The name of the action - term for which the action is required. If None, the entire action tensor is - returned. - modifiers: null - full_path: isaaclab.envs.mdp.observations.last_action - mdp_type: Observation - name: last_action - observation_type: Action - overloads: - clip: null - flatten_history_dim: true - history_length: 0 - scale: null - shape: - - 37 -scene: - decimation: 4 - dt: 0.02 - physics_dt: 0.005 diff --git a/docs/source/overview/core-concepts/physical-backends/newton/warp-env-migration.rst b/docs/source/overview/core-concepts/physical-backends/newton/warp-env-migration.rst index 468ced739b4a..9ad2fbd1d8d2 100644 --- a/docs/source/overview/core-concepts/physical-backends/newton/warp-env-migration.rst +++ b/docs/source/overview/core-concepts/physical-backends/newton/warp-env-migration.rst @@ -105,6 +105,13 @@ array. This is resolved via a fallback chain (see ``ObservationManager._infer_term_dim_scalar`` in ``isaaclab_experimental/managers/observation_manager.py``): +.. warning:: + + The IO descriptor decorators are deprecated in Isaac Lab 3.0 and will be + removed in Isaac Lab 3.2. Their output-dimension metadata remains available + temporarily for Warp-first environments while a replacement runtime + configuration is developed. + 1. **Explicit ``out_dim`` in decorator** (preferred): .. code-block:: python diff --git a/docs/source/policy_deployment/01_io_descriptors/io_descriptors_101.rst b/docs/source/policy_deployment/01_io_descriptors/io_descriptors_101.rst deleted file mode 100644 index 4a302bd68910..000000000000 --- a/docs/source/policy_deployment/01_io_descriptors/io_descriptors_101.rst +++ /dev/null @@ -1,315 +0,0 @@ -IO Descriptors 101 -================== - -.. currentmodule:: isaaclab - -In this tutorial, we will learn about IO descriptors, what they are, how to export them, and how to add them to -your environments. We will use the AnymalD robot as an example to demonstrate how to export IO descriptors from -an environment, and use our own terms to demonstrate how to attach IO descriptors to custom action and observation terms. - - -What are IO Descriptors? ------------------------- - -Before we dive into IO descriptors, let's first understand what they are and how they can be useful. - -IO descriptors are a way to describe the inputs and outputs of a policy trained using the ManagerBasedRLEnv in Isaac -Lab. In other words, they describe the action and observation terms of a policy. This description is used to generate -a YAML file that can be loaded in an external tool to run the policies without having to manually input the -configuration of the action and observation terms. - -In addition to this the IO Descriptors provide the following information: -- The parameters of all the joints in the articulation. -- Some simulation parameters including the simulation time step, and the policy time step. -- For some action and observation terms, it provides the joint names or body names in the same order as they appear in the action/observation terms. -- For both the observation and action terms, it provides the terms in the exact same order as they appear in the managers. Making it easy to reconstruct them from the YAML file. - -Here is an example of what the action part of the YAML generated from the IO descriptors looks like for the AnymalD robot: - -.. literalinclude:: ../../_static/policy_deployment/01_io_descriptors/isaac_velocity_flat_anymal_d_v0_IO_descriptors.yaml - :language: yaml - :lines: 1-39 - -Here is an example of what a portion of the observation part of the YAML generated from the IO descriptors looks like for the AnymalD robot: - -.. literalinclude:: ../../_static/policy_deployment/01_io_descriptors/isaac_velocity_flat_anymal_d_v0_IO_descriptors.yaml - :language: yaml - :lines: 158-199 - -.. literalinclude:: ../../_static/policy_deployment/01_io_descriptors/isaac_velocity_flat_anymal_d_v0_IO_descriptors.yaml - :language: yaml - :lines: 236-279 - -Something to note here is that both the action and observation terms are returned as list of dictionaries, and not a dictionary of dictionaries. -This is done to ensure the order of the terms is preserved. Hence, to retrieve the action or observation term, the users need to look for the -``name`` key in the dictionaries. - -For example, in the following snippet, we are looking at the ``projected_gravity`` observation term. The ``name`` key is used to identify the term. -The ``full_path`` key is used to provide an explicit path to the function in Isaac Lab's source code that is used to compute this term. Some flags -like ``mdp_type`` and ``observation_type`` are also provided, these don't have any functional impact. They are here to inform the user that this is the -category this term belongs to. - -.. literalinclude:: ../../_static/policy_deployment/01_io_descriptors/isaac_velocity_flat_anymal_d_v0_IO_descriptors.yaml - :language: yaml - :lines: 200-219 - :emphasize-lines: 9, 11 - - -Exporting IO Descriptors from an Environment --------------------------------------------- - -In this section, we will cover how to export IO descriptors from an environment. -Keep in mind that this feature is only available to the manager based RL environments. - -If a policy has already been trained using a given configuration, then the IO descriptors can be exported using: - -.. tab-set:: - - .. tab-item:: uv (Recommended) - - .. code-block:: bash - - uv run python scripts/environments/export_io_descriptors.py --task --output_dir - - .. tab-item:: isaaclab.sh / isaaclab.bat - - .. code-block:: bash - - ./isaaclab.sh -p scripts/environments/export_io_descriptors.py --task --output_dir - -For example, if we want to export the IO descriptors for the AnymalD robot, we can run: - -.. tab-set:: - - .. tab-item:: uv (Recommended) - - .. code-block:: bash - - uv run python scripts/environments/export_io_descriptors.py --task Isaac-Velocity-Flat-AnymalD --output_dir ./io_descriptors - - .. tab-item:: isaaclab.sh / isaaclab.bat - - .. code-block:: bash - - ./isaaclab.sh -p scripts/environments/export_io_descriptors.py --task Isaac-Velocity-Flat-AnymalD --output_dir ./io_descriptors - -When training a policy, it is also possible to request the IO descriptors to be exported at the beginning of the training. -This can be done by setting the ``export_io_descriptors`` flag in the command line. - -.. tab-set:: - - .. tab-item:: uv (Recommended) - - .. code-block:: bash - - uv run isaaclab train --rl_library rsl_rl --task Isaac-Velocity-Flat-AnymalD --export_io_descriptors - uv run isaaclab train --rl_library sb3 --task Isaac-Velocity-Flat-AnymalD --export_io_descriptors - uv run isaaclab train --rl_library rl_games --task Isaac-Velocity-Flat-AnymalD --export_io_descriptors - uv run isaaclab train --rl_library skrl --task Isaac-Velocity-Flat-AnymalD --export_io_descriptors - - - .. tab-item:: isaaclab.sh / isaaclab.bat - - .. code-block:: bash - - ./isaaclab.sh train --rl_library rsl_rl --task Isaac-Velocity-Flat-AnymalD --export_io_descriptors - ./isaaclab.sh train --rl_library sb3 --task Isaac-Velocity-Flat-AnymalD --export_io_descriptors - ./isaaclab.sh train --rl_library rl_games --task Isaac-Velocity-Flat-AnymalD --export_io_descriptors - ./isaaclab.sh train --rl_library skrl --task Isaac-Velocity-Flat-AnymalD --export_io_descriptors - - -Attaching IO Descriptors to Custom Observation Terms ----------------------------------------------------- - -In this section, we will cover how to attach IO descriptors to custom observation terms. - -Let's take a look at how we can attach an IO descriptor to a simple observation term: - -.. code-block:: python - - @generic_io_descriptor( - units="m/s", axes=["X", "Y", "Z"], observation_type="RootState", on_inspect=[record_shape, record_dtype] - ) - def base_lin_vel(env: ManagerBasedEnv, asset_cfg: SceneEntityCfg = SceneEntityCfg("robot")) -> torch.Tensor: - """Root linear velocity in the asset's root frame.""" - # extract the used quantities (to enable type-hinting) - asset: RigidObject = env.scene[asset_cfg.name] - return asset.data.root_lin_vel_b - -Here, we are defining a custom observation term called ``base_lin_vel`` that computes the root linear velocity of the robot. -We are also attaching an IO descriptor to this term. The IO descriptor is defined using the ``@generic_io_descriptor`` decorator. - -The ``@generic_io_descriptor`` decorator is a special decorator that is used to attach an IO descriptor to a custom observation term. -It takes arbitrary arguments that are used to describe the observation term, in this case we provide extra information that could be -useful for the end user: - -- ``units``: The units of the observation term. -- ``axes``: The axes of the observation term. -- ``observation_type``: The type of the observation term. - -You'll also notice that there is an ``on_inspect`` argument that is provided. This is a list of functions that are used to inspect the observation term. -In this case, we are using the ``record_shape`` and ``record_dtype`` functions to record the shape and dtype of the output of the observation term. - -These functions are defined like so: - -.. code-block:: python - - def record_shape(output: torch.Tensor, descriptor: GenericObservationIODescriptor, **kwargs) -> None: - """Record the shape of the output tensor. - - Args: - output: The output tensor. - descriptor: The descriptor to record the shape to. - **kwargs: Additional keyword arguments. - """ - descriptor.shape = (output.shape[-1],) - - - def record_dtype(output: torch.Tensor, descriptor: GenericObservationIODescriptor, **kwargs) -> None: - """Record the dtype of the output tensor. - - Args: - output: The output tensor. - descriptor: The descriptor to record the dtype to. - **kwargs: Additional keyword arguments. - """ - descriptor.dtype = str(output.dtype) - -They always take the output tensor of the observation term as the first argument, and the descriptor as the second argument. -In the ``kwargs`` all the inputs of the observation term are provided. In addition to the ``on_inspect`` functions, the decorator -will also call call some functions in the background to collect the ``name``, the ``description``, and the ``full_path`` of the -observation term. Note that adding this decorator does not change the signature of the observation term, so it can be used safely -with the observation manager! - -Let us now take a look at a more complex example: getting the relative joint positions of the robot. - -.. code-block:: python - - @generic_io_descriptor( - observation_type="JointState", - on_inspect=[record_joint_names, record_dtype, record_shape, record_joint_pos_offsets], - units="rad", - ) - def joint_pos_rel(env: ManagerBasedEnv, asset_cfg: SceneEntityCfg = SceneEntityCfg("robot")) -> torch.Tensor: - """The joint positions of the asset w.r.t. the default joint positions. - - Note: Only the joints configured in :attr:`asset_cfg.joint_ids` will have their positions returned. - """ - # extract the used quantities (to enable type-hinting) - asset: Articulation = env.scene[asset_cfg.name] - return asset.data.joint_pos[:, asset_cfg.joint_ids] - asset.data.default_joint_pos[:, asset_cfg.joint_ids] - -Similarly to the previous example, we are adding an IO descriptor to a custom observation term with a set of functions that probe the observation term. - -To get the name of the joints we can write the following function: - -.. code-block:: python - - def record_joint_names(output: torch.Tensor, descriptor: GenericObservationIODescriptor, **kwargs) -> None: - """Record the joint names of the output tensor. - - Expects the `asset_cfg` keyword argument to be set. - - Args: - output: The output tensor. - descriptor: The descriptor to record the joint names to. - **kwargs: Additional keyword arguments. - """ - asset: Articulation = kwargs["env"].scene[kwargs["asset_cfg"].name] - joint_ids = kwargs["asset_cfg"].joint_ids - if joint_ids == slice(None, None, None): - joint_ids = list(range(len(asset.joint_names))) - descriptor.joint_names = [asset.joint_names[i] for i in joint_ids] - -Note that we can access all the inputs of the observation term in the ``kwargs`` dictionary. Hence we can access the ``asset_cfg``, which contains the -configuration of the articulation that the observation term is computed on. - -To get the offsets, we can write the following function: - -.. code-block:: python - - def record_joint_pos_offsets(output: torch.Tensor, descriptor: GenericObservationIODescriptor, **kwargs): - """Record the joint position offsets of the output tensor. - - Expects the `asset_cfg` keyword argument to be set. - - Args: - output: The output tensor. - descriptor: The descriptor to record the joint position offsets to. - **kwargs: Additional keyword arguments. - """ - asset: Articulation = kwargs["env"].scene[kwargs["asset_cfg"].name] - ids = kwargs["asset_cfg"].joint_ids - # Get the offsets of the joints for the first robot in the scene. - # This assumes that all robots have the same joint offsets. - descriptor.joint_pos_offsets = asset.data.default_joint_pos[:, ids][0] - -With this in mind, you should now be able to attach an IO descriptor to your own custom observation terms! However, before -we close this tutorial, let's take a look at how we can attach an IO descriptor to a custom action term. - - -Attaching IO Descriptors to Custom Action Terms ------------------------------------------------ - -In this section, we will cover how to attach IO descriptors to custom action terms. Action terms are classes that -inherit from the :class:`managers.ActionTerm` class. To add an IO descriptor to an action term, we need to expand -upon its :meth:`~managers.ActionTerm.IO_descriptor` property. - -By default, the :meth:`~managers.ActionTerm.IO_descriptor` property returns the base descriptor and fills the following fields: -- ``name``: The name of the action term. -- ``full_path``: The full path of the action term. -- ``description``: The description of the action term. -- ``export``: Whether to export the action term. - -.. code-block:: python - - @property - def IO_descriptor(self) -> GenericActionIODescriptor: - """The IO descriptor for the action term.""" - self._IO_descriptor.name = re.sub(r"([a-z])([A-Z])", r"\1_\2", self.__class__.__name__).lower() - self._IO_descriptor.full_path = f"{self.__class__.__module__}.{self.__class__.__name__}" - self._IO_descriptor.description = " ".join(self.__class__.__doc__.split()) - self._IO_descriptor.export = self.export_IO_descriptor - return self._IO_descriptor - -To add more information to the descriptor, we need to override the :meth:`~managers.ActionTerm.IO_descriptor` property. -Let's take a look at an example on how to add the joint names, scale, offset, and clip to the descriptor. - -.. code-block:: python - - @property - def IO_descriptor(self) -> GenericActionIODescriptor: - """The IO descriptor of the action term. - - This descriptor is used to describe the action term of the joint action. - It adds the following information to the base descriptor: - - joint_names: The names of the joints. - - scale: The scale of the action term. - - offset: The offset of the action term. - - clip: The clip of the action term. - - Returns: - The IO descriptor of the action term. - """ - super().IO_descriptor - self._IO_descriptor.shape = (self.action_dim,) - self._IO_descriptor.dtype = str(self.raw_actions.dtype) - self._IO_descriptor.action_type = "JointAction" - self._IO_descriptor.joint_names = self._joint_names - self._IO_descriptor.scale = self._scale - # This seems to be always [4xNum_joints] IDK why. Need to check. - if isinstance(self._offset, torch.Tensor): - self._IO_descriptor.offset = self._offset[0].detach().cpu().numpy().tolist() - else: - self._IO_descriptor.offset = self._offset - # FIXME: This is not correct. Add list support. - if self.cfg.clip is not None: - if isinstance(self._clip, torch.Tensor): - self._IO_descriptor.clip = self._clip[0].detach().cpu().numpy().tolist() - else: - self._IO_descriptor.clip = self._clip - else: - self._IO_descriptor.clip = None - return self._IO_descriptor - -This is it! You should now be able to attach an IO descriptor to your own custom action terms which concludes this tutorial. diff --git a/docs/source/policy_deployment/index.rst b/docs/source/policy_deployment/index.rst index cd89350c1773..e7c5616bd77a 100644 --- a/docs/source/policy_deployment/index.rst +++ b/docs/source/policy_deployment/index.rst @@ -8,7 +8,6 @@ Below, you'll find detailed examples of various policies for training and deploy .. toctree:: :maxdepth: 1 - 01_io_descriptors/io_descriptors_101 02_gear_assembly/gear_assembly_policy 03_compass_with_NuRec/compass_navigation_policy_with_NuRec 04_reach/reach_policy diff --git a/source/isaaclab/changelog.d/deprecate-io-descriptors.rst b/source/isaaclab/changelog.d/deprecate-io-descriptors.rst new file mode 100644 index 000000000000..057573438ab1 --- /dev/null +++ b/source/isaaclab/changelog.d/deprecate-io-descriptors.rst @@ -0,0 +1,6 @@ +Deprecated +^^^^^^^^^^ + +* Deprecated IO descriptor APIs. They remain available for compatibility and + will be removed in Isaac Lab 3.2. Use the LEAPP export workflow for supported + RSL-RL/PyTorch deployments. diff --git a/source/isaaclab/isaaclab/envs/manager_based_env.py b/source/isaaclab/isaaclab/envs/manager_based_env.py index f07bbaae257c..262573a9ff4f 100644 --- a/source/isaaclab/isaaclab/envs/manager_based_env.py +++ b/source/isaaclab/isaaclab/envs/manager_based_env.py @@ -25,7 +25,11 @@ from .common import VecEnvObs, _apply_deprecated_viewer_cfg from .manager_based_env_cfg import ManagerBasedEnvCfg -from .utils.io_descriptors import export_articulations_data, export_scene_data +from .utils.io_descriptors import ( + _warn_io_descriptors_deprecated, + export_articulations_data, + export_scene_data, +) from .utils.video_recorder import VideoRecorder # import logger @@ -287,12 +291,21 @@ def device(self): def get_IO_descriptors(self): """Get the IO descriptors for the environment. + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. Use the LEAPP + export workflow for supported RSL-RL/PyTorch deployments. + Returns: A dictionary with keys as the group names and values as the IO descriptors. """ + _warn_io_descriptors_deprecated(stacklevel=3) + return self._collect_io_descriptors() + + def _collect_io_descriptors(self): + """Collect IO descriptors without emitting a deprecation warning.""" return { - "observations": self.observation_manager.get_IO_descriptors, - "actions": self.action_manager.get_IO_descriptors, + "observations": self.observation_manager._collect_io_descriptors(), + "actions": self.action_manager._collect_io_descriptors(), "articulations": export_articulations_data(self), "scene": export_scene_data(self), } @@ -300,6 +313,10 @@ def get_IO_descriptors(self): def export_IO_descriptors(self, output_dir: str | None = None): """Export the IO descriptors for the environment. + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. Use the LEAPP + export workflow for supported RSL-RL/PyTorch deployments. + Args: output_dir: The directory to export the IO descriptors to. """ @@ -307,7 +324,8 @@ def export_IO_descriptors(self, output_dir: str | None = None): import yaml - IO_descriptors = self.get_IO_descriptors + _warn_io_descriptors_deprecated(stacklevel=3) + IO_descriptors = self._collect_io_descriptors() if output_dir is None: if self.cfg.log_dir is not None: diff --git a/source/isaaclab/isaaclab/envs/manager_based_env_cfg.py b/source/isaaclab/isaaclab/envs/manager_based_env_cfg.py index ee704f685fce..4ad1820c65cd 100644 --- a/source/isaaclab/isaaclab/envs/manager_based_env_cfg.py +++ b/source/isaaclab/isaaclab/envs/manager_based_env_cfg.py @@ -157,7 +157,12 @@ class ManagerBasedEnvCfg: """ export_io_descriptors: bool = False - """Whether to export the IO descriptors for the environment. Defaults to False.""" + """Whether to export the IO descriptors for the environment. Defaults to False. + + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. Use the LEAPP export + workflow for supported RSL-RL/PyTorch deployments. + """ log_dir: str | None = None """Directory for logging experiment artifacts. Defaults to None, in which case no specific log directory is set.""" diff --git a/source/isaaclab/isaaclab/envs/utils/io_descriptors.py b/source/isaaclab/isaaclab/envs/utils/io_descriptors.py index f14ae14e5f78..f87034a339b3 100644 --- a/source/isaaclab/isaaclab/envs/utils/io_descriptors.py +++ b/source/isaaclab/isaaclab/envs/utils/io_descriptors.py @@ -3,8 +3,16 @@ # # SPDX-License-Identifier: BSD-3-Clause +"""Deprecated IO descriptor data models and export helpers. + +.. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. Use the LEAPP export + workflow for supported RSL-RL/PyTorch deployments. +""" + from __future__ import annotations +import warnings from collections.abc import Callable from typing import TYPE_CHECKING, Any, Concatenate, ParamSpec, TypeVar @@ -21,10 +29,23 @@ import inspect +def _warn_io_descriptors_deprecated(*, stacklevel: int = 2) -> None: + """Warn that IO descriptors are deprecated.""" + warnings.warn( + "IO descriptors are deprecated and will be removed in Isaac Lab 3.2. " + "Use the LEAPP export workflow for supported RSL-RL/PyTorch deployments.", + FutureWarning, + stacklevel=stacklevel, + ) + + @configclass class GenericActionIODescriptor: """Generic action IO descriptor. + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. + This descriptor is used to describe the action space of a policy. It can be extended as needed to add more information about the action term that is being described. """ @@ -82,6 +103,9 @@ class GenericActionIODescriptor: class GenericObservationIODescriptor: """Generic observation IO descriptor. + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. + This descriptor is used to describe the observation space of a policy. It can be extended as needed to add more information about the observation term that is being described. """ @@ -123,6 +147,9 @@ def generic_io_descriptor( ) -> Callable[[Callable[Concatenate[ManagerBasedEnv, P], R]], Callable[Concatenate[ManagerBasedEnv, P], R]]: """Decorator factory for generic IO descriptors. + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. + This decorator can be used in different ways: 1. The default decorator has all the information I need for my use case: diff --git a/source/isaaclab/isaaclab/managers/action_manager.py b/source/isaaclab/isaaclab/managers/action_manager.py index d711596e5f5a..aeb3b47ffdac 100644 --- a/source/isaaclab/isaaclab/managers/action_manager.py +++ b/source/isaaclab/isaaclab/managers/action_manager.py @@ -16,7 +16,7 @@ import torch from prettytable import PrettyTable -from isaaclab.envs.utils.io_descriptors import GenericActionIODescriptor +from isaaclab.envs.utils.io_descriptors import GenericActionIODescriptor, _warn_io_descriptors_deprecated from .manager_base import ManagerBase, ManagerTermBase from .manager_term_cfg import ActionTermCfg @@ -97,7 +97,11 @@ def has_debug_vis_implementation(self) -> bool: @property def IO_descriptor(self) -> GenericActionIODescriptor: - """The IO descriptor for the action term.""" + """The IO descriptor for the action term. + + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. + """ self._IO_descriptor.name = re.sub(r"([a-z])([A-Z])", r"\1_\2", self.__class__.__name__).lower() self._IO_descriptor.full_path = f"{self.__class__.__module__}.{self.__class__.__name__}" self._IO_descriptor.description = " ".join(self.__class__.__doc__.split()) @@ -106,7 +110,11 @@ def IO_descriptor(self) -> GenericActionIODescriptor: @property def export_IO_descriptor(self) -> bool: - """Whether to export the IO descriptor for the action term.""" + """Whether to export the IO descriptor for the action term. + + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. + """ return self._export_IO_descriptor """ @@ -276,10 +284,17 @@ def has_debug_vis_implementation(self) -> bool: def get_IO_descriptors(self) -> list[dict[str, Any]]: """Get the IO descriptors for the action manager. + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. + Returns: A dictionary with keys as the term names and values as the IO descriptors. """ + _warn_io_descriptors_deprecated(stacklevel=3) + return self._collect_io_descriptors() + def _collect_io_descriptors(self) -> list[dict[str, Any]]: + """Collect IO descriptors without emitting a deprecation warning.""" data = [] for term_name, term in self._terms.items(): diff --git a/source/isaaclab/isaaclab/managers/observation_manager.py b/source/isaaclab/isaaclab/managers/observation_manager.py index 7299ff954467..778e1e73c3f3 100644 --- a/source/isaaclab/isaaclab/managers/observation_manager.py +++ b/source/isaaclab/isaaclab/managers/observation_manager.py @@ -15,6 +15,7 @@ import torch from prettytable import PrettyTable +from isaaclab.envs.utils.io_descriptors import _warn_io_descriptors_deprecated from isaaclab.utils import class_to_dict, modifiers, noise from isaaclab.utils.buffers import CircularBuffer @@ -234,10 +235,17 @@ def group_obs_concatenate(self) -> dict[str, bool]: def get_IO_descriptors(self, group_names_to_export: list[str] = ["policy"]): """Get the IO descriptors for the observation manager. + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. + Returns: A dictionary with keys as the group names and values as the IO descriptors. """ + _warn_io_descriptors_deprecated(stacklevel=3) + return self._collect_io_descriptors(group_names_to_export) + def _collect_io_descriptors(self, group_names_to_export: list[str] = ["policy"]): + """Collect IO descriptors without emitting a deprecation warning.""" group_data = {} for group_name in self._group_obs_term_names: diff --git a/source/isaaclab_experimental/changelog.d/deprecate-io-descriptors.rst b/source/isaaclab_experimental/changelog.d/deprecate-io-descriptors.rst new file mode 100644 index 000000000000..1c8d4c16d3c0 --- /dev/null +++ b/source/isaaclab_experimental/changelog.d/deprecate-io-descriptors.rst @@ -0,0 +1,7 @@ +Deprecated +^^^^^^^^^^ + +* Deprecated the Warp-specific IO descriptor APIs. They remain available for + compatibility and will be removed in Isaac Lab 3.2. LEAPP is the recommended + alternative for supported RSL-RL/PyTorch deployments but does not currently + replace Warp-first descriptor export. diff --git a/source/isaaclab_experimental/isaaclab_experimental/envs/manager_based_env_warp.py b/source/isaaclab_experimental/isaaclab_experimental/envs/manager_based_env_warp.py index ef4412c83a79..0d7659d02a26 100644 --- a/source/isaaclab_experimental/isaaclab_experimental/envs/manager_based_env_warp.py +++ b/source/isaaclab_experimental/isaaclab_experimental/envs/manager_based_env_warp.py @@ -28,7 +28,11 @@ from isaaclab.envs.common import VecEnvObs from isaaclab.envs.manager_based_env_cfg import ManagerBasedEnvCfg -from isaaclab.envs.utils.io_descriptors import export_articulations_data, export_scene_data +from isaaclab.envs.utils.io_descriptors import ( + _warn_io_descriptors_deprecated, + export_articulations_data, + export_scene_data, +) from isaaclab.sim import SimulationContext from isaaclab.sim.utils import use_stage from isaaclab.utils.seed import configure_seed @@ -297,12 +301,21 @@ def resolve_env_mask( def get_IO_descriptors(self): """Get the IO descriptors for the environment. + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. Use the LEAPP + export workflow for supported RSL-RL/PyTorch deployments. + Returns: A dictionary with keys as the group names and values as the IO descriptors. """ + _warn_io_descriptors_deprecated(stacklevel=3) + return self._collect_io_descriptors() + + def _collect_io_descriptors(self): + """Collect IO descriptors without emitting a deprecation warning.""" return { - "observations": self.observation_manager.get_IO_descriptors, - "actions": self.action_manager.get_IO_descriptors, + "observations": self.observation_manager._collect_io_descriptors(), + "actions": self.action_manager._collect_io_descriptors(), "articulations": export_articulations_data(self), "scene": export_scene_data(self), } @@ -310,6 +323,10 @@ def get_IO_descriptors(self): def export_IO_descriptors(self, output_dir: str | None = None): """Export the IO descriptors for the environment. + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. Use the LEAPP + export workflow for supported RSL-RL/PyTorch deployments. + Args: output_dir: The directory to export the IO descriptors to. """ @@ -317,7 +334,8 @@ def export_IO_descriptors(self, output_dir: str | None = None): import yaml - IO_descriptors = self.get_IO_descriptors + _warn_io_descriptors_deprecated(stacklevel=3) + IO_descriptors = self._collect_io_descriptors() if output_dir is None: if self.cfg.log_dir is not None: diff --git a/source/isaaclab_experimental/isaaclab_experimental/envs/utils/io_descriptors.py b/source/isaaclab_experimental/isaaclab_experimental/envs/utils/io_descriptors.py index 2b72dae02aa7..dc2a997a408c 100644 --- a/source/isaaclab_experimental/isaaclab_experimental/envs/utils/io_descriptors.py +++ b/source/isaaclab_experimental/isaaclab_experimental/envs/utils/io_descriptors.py @@ -5,6 +5,10 @@ """Warp-first IO descriptor decorator and inspection hooks (experimental). +.. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. Use the LEAPP export + workflow for supported RSL-RL/PyTorch deployments. + This module mirrors the stable :mod:`isaaclab.envs.utils.io_descriptors` but is designed for Warp-first observation terms whose signature is:: @@ -74,6 +78,9 @@ def generic_io_descriptor_warp( ) -> Callable[[Callable[Concatenate[ManagerBasedEnv, P], R]], Callable[Concatenate[ManagerBasedEnv, P], R]]: """IO descriptor decorator for Warp-first observation terms. + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. + Works like the stable :func:`generic_io_descriptor` but adapted to the ``func(env, out, **params) -> None`` signature: diff --git a/source/isaaclab_experimental/isaaclab_experimental/managers/action_manager.py b/source/isaaclab_experimental/isaaclab_experimental/managers/action_manager.py index 902c74d6d095..5e04c17fe132 100644 --- a/source/isaaclab_experimental/isaaclab_experimental/managers/action_manager.py +++ b/source/isaaclab_experimental/isaaclab_experimental/managers/action_manager.py @@ -19,7 +19,7 @@ from prettytable import PrettyTable from isaaclab.assets import AssetBase -from isaaclab.envs.utils.io_descriptors import GenericActionIODescriptor +from isaaclab.envs.utils.io_descriptors import GenericActionIODescriptor, _warn_io_descriptors_deprecated from isaaclab.managers.manager_term_cfg import ActionTermCfg from .manager_base import ManagerBase, ManagerTermBase @@ -100,7 +100,11 @@ def has_debug_vis_implementation(self) -> bool: @property def IO_descriptor(self) -> GenericActionIODescriptor: - """The IO descriptor for the action term.""" + """The IO descriptor for the action term. + + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. + """ self._IO_descriptor.name = re.sub(r"([a-z])([A-Z])", r"\1_\2", self.__class__.__name__).lower() self._IO_descriptor.full_path = f"{self.__class__.__module__}.{self.__class__.__name__}" self._IO_descriptor.description = " ".join((self.__class__.__doc__ or "").split()) @@ -109,7 +113,11 @@ def IO_descriptor(self) -> GenericActionIODescriptor: @property def export_IO_descriptor(self) -> bool: - """Whether to export the IO descriptor for the action term.""" + """Whether to export the IO descriptor for the action term. + + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. + """ return self._export_IO_descriptor """ @@ -291,10 +299,17 @@ def has_debug_vis_implementation(self) -> bool: def get_IO_descriptors(self) -> list[dict[str, Any]]: """Get the IO descriptors for the action manager. + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. + Returns: A dictionary with keys as the term names and values as the IO descriptors. """ + _warn_io_descriptors_deprecated(stacklevel=3) + return self._collect_io_descriptors() + def _collect_io_descriptors(self) -> list[dict[str, Any]]: + """Collect IO descriptors without emitting a deprecation warning.""" data = [] for term_name, term in self._terms.items(): diff --git a/source/isaaclab_experimental/isaaclab_experimental/managers/observation_manager.py b/source/isaaclab_experimental/isaaclab_experimental/managers/observation_manager.py index 8adb74ff8da3..672305c4f04f 100644 --- a/source/isaaclab_experimental/isaaclab_experimental/managers/observation_manager.py +++ b/source/isaaclab_experimental/isaaclab_experimental/managers/observation_manager.py @@ -55,6 +55,7 @@ import warp as wp from prettytable import PrettyTable +from isaaclab.envs.utils.io_descriptors import _warn_io_descriptors_deprecated from isaaclab.managers.manager_term_cfg import ObservationGroupCfg, ObservationTermCfg from isaaclab.utils import class_to_dict @@ -312,9 +313,17 @@ def group_obs_concatenate(self) -> dict[str, bool]: def get_IO_descriptors(self, group_names_to_export: list[str] = ["policy"]): """Get the IO descriptors for the observation manager. + .. deprecated:: 3.0 + IO descriptors will be removed in Isaac Lab 3.2. + Returns: A dictionary with keys as the group names and values as the IO descriptors. """ + _warn_io_descriptors_deprecated(stacklevel=3) + return self._collect_io_descriptors(group_names_to_export) + + def _collect_io_descriptors(self, group_names_to_export: list[str] = ["policy"]): + """Collect IO descriptors without emitting a deprecation warning.""" group_data: dict[str, list[dict[str, Any]]] = {} # Collect raw descriptor dicts (plus overloads). diff --git a/source/isaaclab_rl/changelog.d/deprecate-io-descriptors.rst b/source/isaaclab_rl/changelog.d/deprecate-io-descriptors.rst new file mode 100644 index 000000000000..024f08d6cc89 --- /dev/null +++ b/source/isaaclab_rl/changelog.d/deprecate-io-descriptors.rst @@ -0,0 +1,6 @@ +Deprecated +^^^^^^^^^^ + +* Deprecated the ``--export_io_descriptors`` training option. It remains + available for compatibility and will be removed in Isaac Lab 3.2. Use the + LEAPP export workflow for supported RSL-RL/PyTorch deployments. diff --git a/source/isaaclab_rl/isaaclab_rl/entrypoints/common.py b/source/isaaclab_rl/isaaclab_rl/entrypoints/common.py index 6d8ccff5c036..b4d9e4a90633 100644 --- a/source/isaaclab_rl/isaaclab_rl/entrypoints/common.py +++ b/source/isaaclab_rl/isaaclab_rl/entrypoints/common.py @@ -395,7 +395,12 @@ def add_common_train_args( parser.add_argument( "--max_iterations", type=max_iterations_type, default=None, help="RL Policy training iterations." ) - parser.add_argument("--export_io_descriptors", action="store_true", default=False, help="Export IO descriptors.") + parser.add_argument( + "--export_io_descriptors", + action="store_true", + default=False, + help="Deprecated: export IO descriptors (removed in Isaac Lab 3.2).", + ) parser.add_argument( "--ray-proc-id", "-rid", From b9f46e03249abfe81424f77d829f041c3db202a3 Mon Sep 17 00:00:00 2001 From: AntoineRichard Date: Fri, 14 Aug 2026 09:45:20 +0200 Subject: [PATCH 2/4] Document IO descriptor demo removal --- ...-08-14-remove-io-descriptor-demo-design.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-14-remove-io-descriptor-demo-design.md diff --git a/docs/superpowers/specs/2026-08-14-remove-io-descriptor-demo-design.md b/docs/superpowers/specs/2026-08-14-remove-io-descriptor-demo-design.md new file mode 100644 index 000000000000..52128d4d2e05 --- /dev/null +++ b/docs/superpowers/specs/2026-08-14-remove-io-descriptor-demo-design.md @@ -0,0 +1,33 @@ + + +# Remove the IO Descriptor Export Demo + +## Context + +IO descriptors are deprecated in Isaac Lab 3.0 and scheduled for removal in +Isaac Lab 3.2. The IO Descriptors 101 tutorial, its navigation entry, and its +generated YAML examples have already been removed by this branch. The remaining +`scripts/environments/export_IODescriptors.py` script still demonstrates and +invokes the deprecated `get_IO_descriptors` API. + +## Design + +Delete `scripts/environments/export_IODescriptors.py` without adding a wrapper +or compatibility stub. Users of supported RSL-RL/PyTorch deployment workflows +are directed to LEAPP by the existing changelog fragments and deprecation +warnings. + +The runtime descriptor APIs and their `FutureWarning` behavior remain +unchanged. This change only removes the obsolete standalone example script. + +## Verification + +- Search the repository for references to the deleted script and remove any + live references found. +- Run the repository pre-commit checks required for this PR. +- Review the final diff to confirm that no runtime implementation changed. From 92f15a0aa03f51158acb1858a5ce42957cdc5e12 Mon Sep 17 00:00:00 2001 From: AntoineRichard Date: Fri, 14 Aug 2026 11:16:27 +0200 Subject: [PATCH 3/4] Plan IO descriptor demo removal --- .../2026-08-14-remove-io-descriptor-demo.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-14-remove-io-descriptor-demo.md diff --git a/docs/superpowers/plans/2026-08-14-remove-io-descriptor-demo.md b/docs/superpowers/plans/2026-08-14-remove-io-descriptor-demo.md new file mode 100644 index 000000000000..85e0da050fe0 --- /dev/null +++ b/docs/superpowers/plans/2026-08-14-remove-io-descriptor-demo.md @@ -0,0 +1,91 @@ + + +# Remove the IO Descriptor Export Demo Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Remove the obsolete standalone IO-descriptor export demo while preserving all runtime deprecation warnings and compatibility APIs. + +**Architecture:** Delete only the standalone script. Validate the deletion with a file-absence check, scan tracked files for references to the removed path, and run the repository pre-commit suite. + +**Tech Stack:** Git, Bash, Isaac Lab pre-commit wrapper + +## Global Constraints + +- Do not change runtime IO-descriptor implementation or warning behavior. +- Do not add a replacement wrapper or compatibility stub. +- Do not add dependencies. +- Run `./isaaclab.sh -f` before committing. + +--- + +### Task 1: Remove the standalone export demo + +**Files:** +- Delete: `scripts/environments/export_IODescriptors.py` + +**Interfaces:** +- Consumes: The existing deprecation documentation and runtime `FutureWarning` entry points. +- Produces: A repository with no standalone IO-descriptor export demo. + +- [ ] **Step 1: Verify the desired file-absence check fails** + +Run: + +```bash +test ! -e scripts/environments/export_IODescriptors.py +``` + +Expected: exit code 1 because the obsolete script still exists. + +- [ ] **Step 2: Delete the obsolete script** + +Delete `scripts/environments/export_IODescriptors.py` without modifying runtime descriptor code. + +- [ ] **Step 3: Verify the file-absence check passes** + +Run: + +```bash +test ! -e scripts/environments/export_IODescriptors.py +``` + +Expected: exit code 0. + +- [ ] **Step 4: Scan tracked files for stale references** + +Run: + +```bash +git grep -n "export_IODescriptors.py" +``` + +Expected: exit code 1 with no matches. + +- [ ] **Step 5: Run repository checks** + +Run: + +```bash +./isaaclab.sh -f +``` + +Expected: all pre-commit hooks pass. + +- [ ] **Step 6: Review and commit the deletion** + +Run: + +```bash +git diff --check +git diff --stat HEAD^ +git add scripts/environments/export_IODescriptors.py +git commit -m "Remove IO descriptor export demo" +``` + +Expected: the implementation commit deletes only the obsolete script. From 1864ead625f36d8913372a249a00538d7636713f Mon Sep 17 00:00:00 2001 From: AntoineRichard Date: Fri, 14 Aug 2026 11:17:48 +0200 Subject: [PATCH 4/4] Remove IO descriptor export demo --- scripts/environments/export_IODescriptors.py | 105 ------------------- 1 file changed, 105 deletions(-) delete mode 100644 scripts/environments/export_IODescriptors.py diff --git a/scripts/environments/export_IODescriptors.py b/scripts/environments/export_IODescriptors.py deleted file mode 100644 index 2db02f1cc3e8..000000000000 --- a/scripts/environments/export_IODescriptors.py +++ /dev/null @@ -1,105 +0,0 @@ -# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). -# All rights reserved. -# -# SPDX-License-Identifier: BSD-3-Clause - -"""Script to an environment with random action agent.""" - -"""Launch Isaac Sim Simulator first.""" - -import argparse -import contextlib -import os - -from isaaclab.app import AppLauncher - -# add argparse arguments -parser = argparse.ArgumentParser(description="Random agent for Isaac Lab environments.") -parser.add_argument("--task", type=str, default=None, help="Name of the task.") -parser.add_argument("--output_dir", type=str, default=None, help="Path to the output directory.") -# append AppLauncher cli args -AppLauncher.add_app_launcher_args(parser) -# parse the arguments -args_cli = parser.parse_args() -args_cli.headless = True - -# launch omniverse app -app_launcher = AppLauncher(args_cli) -simulation_app = app_launcher.app - -"""Rest everything follows.""" - -import gymnasium as gym -import torch - -import isaaclab_tasks # noqa: F401 - -with contextlib.suppress(ImportError): - import isaaclab_tasks_experimental # noqa: F401 -from isaaclab_tasks.utils import parse_env_cfg - -# PLACEHOLDER: Extension template (do not remove this comment) - - -def main(): - """Random actions agent with Isaac Lab environment.""" - # create environment configuration - env_cfg = parse_env_cfg(args_cli.task, device=args_cli.device, num_envs=1, use_fabric=True) - # create environment - env = gym.make(args_cli.task, cfg=env_cfg) - - # print info (this is vectorized environment) - print(f"[INFO]: Gym observation space: {env.observation_space}") - print(f"[INFO]: Gym action space: {env.action_space}") - # reset environment - env.reset() - - outs = env.unwrapped.get_IO_descriptors - out_observations = outs["observations"] - out_actions = outs["actions"] - out_articulations = outs["articulations"] - out_scene = outs["scene"] - # Make a yaml file with the output - import yaml - - name = args_cli.task.lower().replace("-", "_") - name = name.replace(" ", "_") - - if not os.path.exists(args_cli.output_dir): - os.makedirs(args_cli.output_dir) - - with open(os.path.join(args_cli.output_dir, f"{name}_IO_descriptors.yaml"), "w") as f: - print(f"[INFO]: Exporting IO descriptors to {os.path.join(args_cli.output_dir, f'{name}_IO_descriptors.yaml')}") - yaml.safe_dump(outs, f) - - for k in out_actions: - print(f"--- Action term: {k['name']} ---") - k.pop("name") - for k1, v1 in k.items(): - print(f"{k1}: {v1}") - - for obs_group_name, obs_group in out_observations.items(): - print(f"--- Obs group: {obs_group_name} ---") - for k in obs_group: - print(f"--- Obs term: {k['name']} ---") - k.pop("name") - for k1, v1 in k.items(): - print(f"{k1}: {v1}") - - for articulation_name, articulation_data in out_articulations.items(): - print(f"--- Articulation: {articulation_name} ---") - for k1, v1 in articulation_data.items(): - print(f"{k1}: {v1}") - - for k1, v1 in out_scene.items(): - print(f"{k1}: {v1}") - - env.step(torch.zeros(env.action_space.shape, device=env.unwrapped.device)) - env.close() - - -if __name__ == "__main__": - # run the main function - main() - # close sim app - simulation_app.close()