[Backport release/3.0.0] Bundle #7272, #7121, #7183, #7306, #7305, and #7303 (#7313)

# Description

Backports six merged PRs to `release/3.0.0` as separate
provenance-preserving cherry-picks:

| Source PR | Source commit | Backport commit | Scope |
| --- | --- | --- | --- |
| #7272 | `0081477fea2` | `c9fc1997476` | Fix scene-wide gravity
distributions for PhysX and OvPhysX. |
| #7121 | `9f65e3d4fd2` | `cce8acd84e1` | Fix backend-factory fallback
before simulator initialization. |
| #7183 | `3fcc9c6b824` | `99d58d3d3c4` | Streamline the getting-started
documentation. |
| #7306 | `6aad90be0ae` | `9a786cc028a` | Optimize Newton test runtime.
|
| #7305 | `1c9ba908cf1` | `a2dc8ce948e` | Disable Warp autodiff in the
test suite. |
| #7303 | `393fc37d2b0` | `249a5cb97d8` | Remove post-Hydra preset
resolution. |

#7272 forwards the validated `uniform`, `log_uniform`, or `gaussian`
distribution through both scene-wide backend paths. Newton behavior is
unchanged.

#7121 makes factory resolution fall back to Newton when no
`SimulationContext` exists while retaining the visualizer contract of
reporting no active backend before context creation.

#7183 is documentation-only. #7306 and #7305 change test infrastructure
only; they do not change runtime behavior.

#7303 makes `resolve_task_config` and `parse_env_cfg` the
task-composition boundary. Runtime consumers now require concrete
physics, renderer, and camera configurations and no longer attempt late
preset fallback after Hydra composition.

The branch was synchronized with the current `release/3.0.0` tip
containing #7301 before #7303 was applied. All six source cherry-picks
applied without conflicts. A file-by-file existence, mode, and blob
audit confirmed that every #7303 path matches its merged source commit
exactly.

## Validation

### #7272

- Regression verification against the unpatched `release/3.0.0` tip —
both PhysX and OvPhysX cases failed as expected.
- `uv run --extra test --frozen python -m pytest -q
source/isaaclab/test/envs/test_gravity_randomization.py
source/isaaclab/test/envs/test_mdp_event_selectors.py` — 7 passed.
- `uv run --extra test --extra ovphysx --frozen python -m pytest -q
source/isaaclab_ov/test/physics/test_ovphysx_gravity.py` — 1 passed.

### #7121

- Regression verification before the #7121 cherry-pick reproduced the
original `NoneType.physics_manager` failure.
- `uv run --extra test --frozen python -m pytest -q
source/isaaclab/test/utils/test_backend_utils.py
source/isaaclab/test/visualizers/test_visualizer.py` — 18 passed.

### #7183

- `uv run --frozen --extra test python -m pytest --noconftest -q
tools/test/test_environ_docs.py` — 26 passed.

### #7306

- All 9 affected paths match the merged source PR exactly.
- The full simulator-backed Newton suite is left to backport CI because
this local worktree does not include the full Isaac Sim runtime.

### #7305

- Loaded the root `conftest.py` successfully with Warp unavailable.
- Loaded it with Warp installed and confirmed `wp.config.enable_backward
is False`.

### #7303

- Hydra and Shadow Hand camera suites — 129 passed.
- Benchmark capture and RL entrypoint suites — 31 passed.
- Experimental frontend and custom-coupling suites — 74 passed, 1
skipped.
- Ruff and Ruff-format passed for every changed Python path.
- Source/backport audit — 54 paths checked, 0 mismatches.
- The Isaac Sim-backed integration case is left to CI because this local
worktree is kitless.

### Repository gates

- `git diff --check upstream/release/3.0.0...HEAD` — passed.

---------

Signed-off-by: Sylvester Kaczmarek <16242628+sylvesterkaczmarek@users.noreply.github.com>
Co-authored-by: Antoine RICHARD <antoiner@nvidia.com>
Co-authored-by: Sylvester Kaczmarek <16242628+sylvesterkaczmarek@users.noreply.github.com>
Co-authored-by: Mustafa H <34825877+StafaH@users.noreply.github.com>

Author: 4 people

.github/workflows/build.yaml

@@ -103,6 +103,7 @@ jobs:
           ^apps/ :: Standalone apps
           ^scripts/ :: Standalone scripts
           ^\.dockerignore$ :: Docker build context filter
+          ^conftest\.py$ :: Root pytest configuration
           ^pyproject\.toml$ :: Root Python project (Docker copy)
           ^environment\.yml$ :: Conda env (Docker copy)
           ^isaaclab\. :: isaaclab.sh/.bat entrypoints (Docker copy)

conftest.py

@@ -27,6 +27,14 @@
 import json
 import os
 
+try:
+    import warp as wp
+except ModuleNotFoundError as exc:
+    if exc.name != "warp":
+        raise
+else:
+    wp.config.enable_backward = False
+
 pytest_plugins = ["tools.ovrtx_log"]
 
 JOURNAL_ENV_VAR = "ISAACLAB_TEST_JOURNAL"

docs/index.rst

@@ -29,7 +29,8 @@ adaptability, and support for running in the cloud.
 
 Additionally, Isaac Lab provides a variety of environments, and we are actively working on adding more environments
 to the list. These include classic control tasks, fixed-arm and dexterous manipulation tasks, legged locomotion tasks,
-and navigation tasks. A complete list is available in the `environments <source/overview/environments>`_ section.
+and navigation tasks. Browse the registered tasks and build a command in the
+`environment browser <source/setup/environments>`_.
 
 Isaac lab is developed with specific robot assets that are now **Batteries-included** as part of the platform and are ready to learn! These robots include...
 
@@ -122,11 +123,9 @@ Table of Contents
 
 
    source/overview/core-concepts/index
-   source/overview/environments
    source/overview/reinforcement-learning/index
    source/overview/imitation-learning/index
    source/overview/showroom
-   source/overview/simple_agents
 
 
 .. toctree::

docs/source/_static/css/environment-browser.js

@@ -9,7 +9,7 @@
     "use strict";
 
     const initializeEnvironmentBrowser = () => {
-        // Generated from the task rows in source/overview/environments.rst.
+        // Generated from the core and contributed Gym registry entries.
         // START-AUTO-GENERATED: environment-browser-task-rows
         const taskRows = [
             ["Isaac-Ant-Direct", "rl_games,rsl_rl,skrl", "isaacsim_physx,newton_kamino,newton_mjwarp,ovphysx", "", "", {}, "tasks/classic/ant.jpg", true],
@@ -23,15 +23,15 @@
             ["Isaac-Humanoid", "rl_games,rsl_rl,skrl,sb3", "isaacsim_physx,newton_mjwarp,ovphysx", "", "", {}, "tasks/classic/humanoid.jpg", true],
             ["Isaac-Lift-Cable-Franka", "rsl_rl", "newton_mjwarp_vbd_proxy", "", "ik,joint", {}, "tasks/manipulation/franka_lift_cable.jpg"],
             ["Isaac-Lift-Cable-Franka-Camera", "rsl_rl", "newton_mjwarp_vbd_proxy", "isaacsim_rtx,newton_renderer,ovrtx", "ik,joint", {}, "tasks/manipulation/franka_lift_cable.jpg"],
-            ["Isaac-Lift-Cloth-Franka", "rsl_rl", "isaacsim_physx,newton_mjwarp_vbd_proxy", "", "ik,joint", {}, "tasks/manipulation/franka_lift_cloth.jpg"],
-            ["Isaac-Lift-Cloth-Franka-Camera", "rsl_rl", "isaacsim_physx,newton_mjwarp_vbd_proxy", "isaacsim_rtx,newton_renderer,ovrtx", "ik,joint", {}, "tasks/manipulation/franka_lift_cloth.jpg"],
+            ["Isaac-Lift-Cloth-Franka", "rsl_rl", "isaacsim_physx,newton_mjwarp_vbd_proxy,ovphysx", "", "ik,joint", {}, "tasks/manipulation/franka_lift_cloth.jpg"],
+            ["Isaac-Lift-Cloth-Franka-Camera", "rsl_rl", "isaacsim_physx,newton_mjwarp_vbd_proxy,ovphysx", "isaacsim_rtx,newton_renderer,ovrtx", "ik,joint", {}, "tasks/manipulation/franka_lift_cloth.jpg"],
             ["Isaac-Lift-Franka", "rsl_rl", "isaacsim_physx,newton_mjwarp", "", "cube,shapes"],
             ["Isaac-Lift-KukaAllegro", "rsl_rl", "isaacsim_physx,newton_mjwarp,ovphysx", "", "cube,shapes", {}, "tasks/manipulation/kuka_allegro_lift.jpg"],
             ["Isaac-Lift-KukaAllegro-Camera", "rsl_rl", "isaacsim_physx,newton_mjwarp,ovphysx", "isaacsim_rtx,newton_renderer,ovrtx", "albedo128,albedo256,albedo64,cube,depth128,depth256,depth64,duo_camera,raycaster_depth128,raycaster_depth256,raycaster_depth64,rgb128,rgb256,rgb64,semantic_segmentation128,semantic_segmentation256,semantic_segmentation64,shapes,simple_shading_constant_diffuse128,simple_shading_constant_diffuse256,simple_shading_constant_diffuse64,simple_shading_diffuse_mdl128,simple_shading_diffuse_mdl256,simple_shading_diffuse_mdl64,simple_shading_full_mdl128,simple_shading_full_mdl256,simple_shading_full_mdl64,single_camera", {}, "tasks/manipulation/kuka_allegro_lift.jpg"],
-            ["Isaac-Lift-Soft-Franka", "rsl_rl", "isaacsim_physx,newton_mjwarp_vbd_proxy", "", "ik,joint", {}, "newton/franka-mjwarp-vbd-coupling.png"],
-            ["Isaac-Lift-Soft-Franka-Camera", "rsl_rl", "isaacsim_physx,newton_mjwarp_vbd_proxy", "isaacsim_rtx,newton_renderer,ovrtx", "ik,joint", {}, "newton/franka-mjwarp-vbd-coupling.png"],
-            ["Isaac-Open-Drawer-Franka-Direct", "rl_games,rsl_rl,skrl", "", "", "", {}, "tasks/manipulation/franka_open_drawer.jpg"],
-            ["Isaac-Open-Drawer-Franka", "rl_games,rsl_rl,skrl", "", "", "", {}, "tasks/manipulation/franka_open_drawer.jpg"],
+            ["Isaac-Lift-Soft-Franka", "rsl_rl", "isaacsim_physx,newton_mjwarp_vbd_proxy,ovphysx", "", "ik,joint", {}, "newton/franka-mjwarp-vbd-coupling.png"],
+            ["Isaac-Lift-Soft-Franka-Camera", "rsl_rl", "isaacsim_physx,newton_mjwarp_vbd_proxy,ovphysx", "isaacsim_rtx,newton_renderer,ovrtx", "ik,joint", {}, "newton/franka-mjwarp-vbd-coupling.png"],
+            ["Isaac-Open-Drawer-Franka-Direct", "rl_games,rsl_rl,skrl", "isaacsim_physx,newton_mjwarp,ovphysx", "", "", {}, "tasks/manipulation/franka_open_drawer.jpg"],
+            ["Isaac-Open-Drawer-Franka", "rl_games,rsl_rl,skrl", "isaacsim_physx,newton_mjwarp,ovphysx", "", "", {}, "tasks/manipulation/franka_open_drawer.jpg"],
             ["Isaac-Pendulum-MARL-Direct", "rl_games,skrl", "isaacsim_physx,newton_kamino,newton_mjwarp,ovphysx", "", ""],
             ["Isaac-Reach-Franka", "rl_games,rsl_rl,skrl", "isaacsim_physx,newton_mjwarp,ovphysx", "", "diffik,diffik_abs,joint_pos,newton_ik", {}, "tasks/manipulation/franka_reach.jpg", true],
             ["Isaac-Reach-Franka-OSC", "rsl_rl", "isaacsim_physx,newton_mjwarp,ovphysx", "", "diffik_abs", {}, "tasks/manipulation/franka_reach.jpg"],
@@ -94,8 +94,8 @@
             ["IsaacContrib-Navigation-3DObstacles-ARL-Robot-1", "rl_games,rsl_rl,skrl", "", "", "", {}, "tasks/drone_arl/arl_robot_1_navigation.jpg"],
             ["IsaacContrib-Navigation-Flat-AnymalC", "rsl_rl,skrl", "", "", "", {}, "tasks/navigation/anymal_c_nav.jpg"],
             ["IsaacContrib-NutPour-GR1T2-Pink-IK-Abs", "", "", "", ""],
-            ["IsaacContrib-Open-Drawer-Franka-IK-Abs", "rsl_rl", "", "", ""],
-            ["IsaacContrib-Open-Drawer-Franka-IK-Rel", "rsl_rl", "", "", ""],
+            ["IsaacContrib-Open-Drawer-Franka-IK-Abs", "rsl_rl", "isaacsim_physx,newton_mjwarp,ovphysx", "", ""],
+            ["IsaacContrib-Open-Drawer-Franka-IK-Rel", "rsl_rl", "isaacsim_physx,newton_mjwarp,ovphysx", "", ""],
             ["IsaacContrib-Open-Drawer-OpenArm", "rl_games,rsl_rl", "", "", "", {}, "tasks/manipulation/openarm_uni_open_drawer.jpg"],
             ["IsaacContrib-PickPlace-FixedBaseUpperBodyIK-G1-Abs", "", "", "", "", {}, "tasks/manipulation/g1_pick_place_fixed_base.jpg"],
             ["IsaacContrib-PickPlace-G1-InspireFTP-Abs", "", "", "", "", {}, "tasks/manipulation/g1_pick_place.jpg"],

docs/source/_static/quickstart/agent-comparison.gif

@@ -96,7 +96,7 @@ isaaclab_tasks extension
 ------------------------
 
 This package ``isaaclab_tasks`` contains the tasks that are available in the Isaac Lab.
-For more information, please refer to the :ref:`environments`.
+For more information, browse the registered tasks in :doc:`/source/setup/environments`.
 
 It includes the following modules:
 
@@ -227,7 +227,7 @@ isaaclab_tasks_experimental extension
 
 The package ``isaaclab_tasks_experimental`` contains experimental task implementations
 under active development, not yet part of the stable task suite.
-For the list of available environments, please refer to the :ref:`environments`.
+For the list of available environments, please refer to :doc:`/source/setup/environments`.
 
 
 Additional public API modules

docs/source/_static/quickstart/task-sampler.gif

@@ -239,7 +239,7 @@ alternatives. The ``physics=`` selector recognizes these bundles from their
 Where to go next
 ----------------
 
-- :doc:`/source/overview/environments` lists environments and their supported
+- :doc:`/source/setup/environments` lists environments and their supported
   presets.
 - :doc:`/source/features/hydra` covers scalar overrides, preset authoring,
   conflict handling, and advanced configuration behavior.

docs/source/api/index.rst

@@ -134,6 +134,7 @@ These guides explain how to interface with reinforcement learning environments i
 
     wrap_rl_env
     add_own_library
+    run_state_machines
 
 
 Transferring Policies Between Physics Backends

docs/source/concepts/backends_and_presets.rst

@@ -0,0 +1,50 @@
+.. _run-scripted-state-machines:
+
+Run Scripted State Machines
+===========================
+
+Isaac Lab includes hand-written state-machine examples for inspecting an
+environment's observations and action interface without training a policy. The
+state transitions run in parallel across environments as Warp kernels, which
+keeps the examples efficient at larger environment counts.
+
+Run these commands from the Isaac Lab repository root. Use ``--num_envs`` to
+change the number of parallel environments and ``--viz`` to select a
+visualizer.
+
+Pick and lift a rigid cube
+--------------------------
+
+This example approaches a cube, closes the gripper, and lifts the cube to its
+goal pose:
+
+.. code-block:: bash
+
+   uv run python scripts/environments/state_machine/lift_cube_sm.py \
+      --num_envs 32 --viz kit
+
+Lift a deformable object
+------------------------
+
+This example uses the Newton backend to grasp and lift a soft object. The
+Newton visualizer opens by default:
+
+.. code-block:: bash
+
+   uv run python scripts/environments/state_machine/lift_franka_soft.py \
+      --num_envs 1
+
+Open a cabinet drawer
+---------------------
+
+This example approaches the drawer handle, grasps it, pulls the drawer open,
+and releases it:
+
+.. code-block:: bash
+
+   uv run python scripts/environments/state_machine/open_cabinet_sm.py \
+      --num_envs 32 --viz kit
+
+Each script defines its states, wait times, transition kernel, and action loop
+in one file. Start with ``lift_cube_sm.py`` when adapting the pattern to a new
+manipulation task.