Make automatic PhysX defaults concrete and fix install hints

docs/source/features/hydra.rst

@@ -252,7 +252,7 @@ override is given:
     class PhysicsCfg(PresetCfg):
         isaacsim_physx: PhysxCfg = PhysxCfg()
         physx: PhysxAutoCfg = PhysxAutoCfg(isaacsim_physx=isaacsim_physx)
-        default: PhysxAutoCfg = physx
+        default: PhysxCfg = isaacsim_physx
         newton_mjwarp: NewtonCfg = NewtonCfg()
 
     @configclass
@@ -264,11 +264,15 @@ override is given:
     # Use Newton physics backend
     python train.py --task=Isaac-Reach-Franka env.physics=newton_mjwarp
 
-For tasks that expose automatic PhysX-family selection, ``physics=physx`` is
-resolved at launch time: Isaac Sim PhysX is used when a Kit renderer or Kit viewer
-is requested. For fully kit-less runs, OvPhysX is used when the task configures
-an OvPhysX alternative; otherwise selection falls back to Isaac Sim PhysX and
-requires Kit. Use ``physics=isaacsim_physx`` to force Isaac Sim PhysX.
+Tasks that previously used automatic ``PhysxAutoCfg`` selection by default now
+use the concrete ``isaacsim_physx`` variant by default. Existing explicit
+defaults, such as Newton, remain unchanged. The explicit ``physics=physx``
+selector opts into automatic PhysX-family selection at launch time: Isaac Sim
+PhysX is used when a Kit renderer or Kit viewer is requested. For fully kit-less
+runs, OvPhysX is used when the task configures an OvPhysX alternative; otherwise
+selection falls back to Isaac Sim PhysX and requires Kit. This matches renderer
+selection, where ``isaacsim_rtx`` is the concrete default and ``renderer=rtx``
+is automatic.
 
 The ``default`` field can be set to ``None`` to make an optional feature that is
 disabled unless explicitly selected:
@@ -321,7 +325,7 @@ Physics backend selection uses the same preset system. A task can define a
             isaacsim_physx=isaacsim_physx,
             ovphysx=ovphysx,
         )
-        default = physx
+        default: PhysxCfg = isaacsim_physx
         newton_mjwarp: NewtonCfg = NewtonCfg(
             solver_cfg=MJWarpSolverCfg(njmax=5, nconmax=3),
             num_substeps=1,

docs/source/migration/migrating_to_isaaclab_3-0.rst

@@ -652,28 +652,33 @@ when no CLI override is given. Other fields are named presets selectable with
 
 .. code-block:: python
 
-   from isaaclab_tasks.utils import PresetCfg
+   from isaaclab.physics import PhysxAutoCfg
    from isaaclab.utils.configclass import configclass
+   from isaaclab_ovphysx.physics import OvPhysxCfg
+   from isaaclab_tasks.utils import PresetCfg
 
    @configclass
    class MyPhysicsCfg(PresetCfg):
-       default: PhysxCfg = PhysxCfg(...)   # used when no override is given
-       physx:   PhysxCfg = PhysxCfg(...)   # selected by physics=physx
+       isaacsim_physx: PhysxCfg = PhysxCfg(...)
+       ovphysx: OvPhysxCfg = OvPhysxCfg()
+       physx: PhysxAutoCfg = PhysxAutoCfg(isaacsim_physx=isaacsim_physx, ovphysx=ovphysx)
+       default: PhysxCfg = isaacsim_physx  # used when no override is given
        newton_mjwarp:  NewtonCfg = NewtonCfg(...)  # selected by physics=newton_mjwarp
 
 Selecting a preset at launch
 -----------------------------
 
-Pass ``physics=newton_mjwarp`` (or ``physics=physx``) on the CLI to swap the entire config section.
-The legacy ``presets=NAME`` form still works for the same values.
+Pass ``physics=newton_mjwarp`` on the CLI to swap the entire config section.
+Use ``physics=physx`` to opt into automatic PhysX-family selection. The legacy
+``presets=NAME`` form still works for the same values.
 
 .. code-block:: bash
 
    # Run with Newton backend
    uv run --extra isaacsim isaaclab train --rl_library rsl_rl \
        --task Isaac-Open-Drawer-Franka-Direct physics=newton_mjwarp
 
-   # Run with default (PhysX) backend
+   # Run with default (concrete Isaac Sim PhysX) backend
    uv run --extra isaacsim isaaclab train --rl_library rsl_rl \
        --task Isaac-Open-Drawer-Franka-Direct
 
@@ -693,18 +698,30 @@ subclass that carries both a PhysX and a Newton variant.
        self.sim.dt = 1 / 60
        self.sim.physics = PhysxCfg(bounce_threshold_velocity=0.2)
 
+.. important::
+
+   The ``After`` example below mirrors the current Reach task, which intentionally
+   uses Newton/MJWarp as its default. The ``Before`` snippet only illustrates the
+   older single-backend form, so the default differs between the two snippets.
+   When migrating a task that should retain PhysX by default, use
+   ``default: PhysxCfg = isaacsim_physx`` instead. Adding backend variants should
+   not silently change a task's established default.
+
 *After:*
 
 .. code-block:: python
 
+   from isaaclab.physics import PhysxAutoCfg
    from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg
+   from isaaclab_ovphysx.physics import OvPhysxCfg
    from isaaclab_physx.physics import PhysxCfg
    from isaaclab_tasks.utils import PresetCfg
 
    @configclass
    class ReachPhysicsCfg(PresetCfg):
-       default: PhysxCfg = PhysxCfg(bounce_threshold_velocity=0.2)
-       physx:   PhysxCfg = PhysxCfg(bounce_threshold_velocity=0.2)
+       isaacsim_physx: PhysxCfg = PhysxCfg(bounce_threshold_velocity=0.2)
+       ovphysx: OvPhysxCfg = OvPhysxCfg()
+       physx: PhysxAutoCfg = PhysxAutoCfg(isaacsim_physx=isaacsim_physx, ovphysx=ovphysx)
        newton_mjwarp:  NewtonCfg = NewtonCfg(
            solver_cfg=MJWarpSolverCfg(
                njmax=20, nconmax=20, ls_iterations=20,
@@ -714,6 +731,7 @@ subclass that carries both a PhysX and a Newton variant.
            num_substeps=1,
            debug_mode=False,
        )
+       default: NewtonCfg = newton_mjwarp
 
    # In the env cfg __post_init__:
    def __post_init__(self):

docs/source/overview/core-concepts/multi_backend_architecture.rst

@@ -171,6 +171,7 @@ below shows only the physics-related fields:
 .. code-block:: python
 
     from isaaclab.envs import DirectRLEnvCfg
+    from isaaclab.physics import PhysxAutoCfg
     from isaaclab.sim import SimulationCfg
     from isaaclab.utils.configclass import configclass
     from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg
@@ -180,12 +181,16 @@ below shows only the physics-related fields:
 
     @configclass
     class CartpolePhysicsCfg(PresetCfg):
-        default: PhysxCfg = PhysxCfg()
-        physx: PhysxCfg = PhysxCfg()
+        isaacsim_physx: PhysxCfg = PhysxCfg()
+        ovphysx: OvPhysxCfg = OvPhysxCfg()
+        physx: PhysxAutoCfg = PhysxAutoCfg(
+            isaacsim_physx=isaacsim_physx,
+            ovphysx=ovphysx,
+        )
+        default: PhysxCfg = isaacsim_physx
         newton_mjwarp: NewtonCfg = NewtonCfg(
             solver_cfg=MJWarpSolverCfg(njmax=5, nconmax=3)
         )
-        ovphysx: OvPhysxCfg = OvPhysxCfg()
 
     @configclass
     class CartpoleEnvCfg(DirectRLEnvCfg):
@@ -199,9 +204,12 @@ Users then select a physics backend at the command line:
 
       .. code-block:: bash
 
-          # Default (PhysX)
+          # Default (concrete Isaac Sim PhysX)
           uv run isaaclab train --rl_library rsl_rl --task Isaac-Cartpole-Direct
 
+          # Automatic PhysX-family selection
+          uv run isaaclab train --rl_library rsl_rl --task Isaac-Cartpole-Direct physics=physx
+
           # MJWarp (Newton backend)
           uv run isaaclab train --rl_library rsl_rl --task Isaac-Cartpole-Direct physics=newton_mjwarp
 
@@ -212,15 +220,26 @@ Users then select a physics backend at the command line:
 
       .. code-block:: bash
 
-          # Default (PhysX)
+          # Default (concrete Isaac Sim PhysX)
           ./isaaclab.sh train --rl_library rsl_rl --task Isaac-Cartpole-Direct
 
+          # Automatic PhysX-family selection
+          ./isaaclab.sh train --rl_library rsl_rl --task Isaac-Cartpole-Direct physics=physx
+
           # MJWarp (Newton backend)
           ./isaaclab.sh train --rl_library rsl_rl --task Isaac-Cartpole-Direct physics=newton_mjwarp
 
           # OvPhysX backend
           ./isaaclab.sh train --rl_library rsl_rl --task Isaac-Cartpole-Direct physics=ovphysx
 
+When a task's default would otherwise be automatic ``PhysxAutoCfg`` selection,
+its ``default`` variant is the concrete ``isaacsim_physx`` configuration.
+Explicit defaults such as Newton remain unchanged. The ``physics=physx``
+selector is opt-in and chooses between Isaac Sim PhysX and OvPhysX at launch
+time according to whether the resolved runtime requires Kit. This mirrors
+renderer presets: the default is concrete ``isaacsim_rtx``, while
+``renderer=rtx`` opts into automatic selection.
+
 The Physics Manager
 -------------------
 

docs/source/overview/core-concepts/physical-backends/index.rst

@@ -131,17 +131,23 @@ declares all three backends side by side:
 
 .. code-block:: python
 
-    from isaaclab_physx.physics import PhysxCfg
+    from isaaclab.physics import PhysxAutoCfg
     from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg
     from isaaclab_ovphysx.physics import OvPhysxCfg
+    from isaaclab_physx.physics import PhysxCfg
 
     @configclass
     class CartpolePhysicsCfg(PresetCfg):
-        default: PhysxCfg = PhysxCfg()
-        physx: PhysxCfg = PhysxCfg()
-        newton_mjwarp: NewtonCfg = NewtonCfg(solver_cfg=MJWarpSolverCfg())
+        isaacsim_physx: PhysxCfg = PhysxCfg()
         ovphysx: OvPhysxCfg = OvPhysxCfg()
+        physx: PhysxAutoCfg = PhysxAutoCfg(
+            isaacsim_physx=isaacsim_physx,
+            ovphysx=ovphysx,
+        )
+        default: PhysxCfg = isaacsim_physx
+        newton_mjwarp: NewtonCfg = NewtonCfg(solver_cfg=MJWarpSolverCfg())
 
-Users then select the backend at the command line via ``presets=<name>`` or by
-overriding the physics field directly. See :ref:`hydra-backend-solver-presets` for
-the full Hydra interaction.
+With no selector, the task uses concrete Isaac Sim PhysX. Users can select a
+backend with ``physics=<name>``; ``physics=physx`` explicitly opts into automatic
+selection between the configured PhysX-family implementations. See
+:ref:`hydra-backend-solver-presets` for the full Hydra interaction.

docs/source/overview/core-concepts/physical-backends/physx/installation.rst

@@ -37,5 +37,8 @@ default preset:
 
           ./isaaclab.sh -p scripts/environments/zero_agent.py --task Isaac-Cartpole --num_envs 128
 
-The ``default`` preset on most tasks resolves to PhysX. You can also pass
-``physics=physx`` explicitly on tasks that declare multi-backend physics presets.
+Environments whose previous default was automatic PhysX selection now use the
+concrete ``isaacsim_physx`` variant by default. Existing explicit defaults, such
+as Newton, remain unchanged. Pass ``physics=physx`` explicitly to opt into
+automatic PhysX-family selection between Isaac Sim PhysX and OvPhysX on tasks
+that support both.

docs/source/overview/core-concepts/physical-backends/physx/supported-features.rst

@@ -3,8 +3,10 @@ Supported Features
 
 PhysX is the broadest backend in Isaac Lab. It is the reference for behaviour
 parity and supports every public asset, sensor, and renderer surface in the
-framework. Tasks built before Isaac Lab 3.0 ran on PhysX, and the bulk of the
-shipped tasks still default to the PhysX preset.
+framework. Tasks built before Isaac Lab 3.0 ran on PhysX. Environments whose
+previous default was automatic PhysX selection now use the concrete
+``isaacsim_physx`` preset by default; explicit backend defaults remain
+unchanged.
 
 The summary below is intentionally coarse; consult each component's API
 documentation for fine-grained capability details.
@@ -51,8 +53,9 @@ Tasks and Workflows
 -------------------
 
 * Direct and Manager-based workflows
-* All ``isaaclab_tasks`` environments default to the PhysX preset unless the
-  task explicitly opts in to a different backend
+* ``isaaclab_tasks`` environments that previously defaulted to automatic PhysX
+  selection now default to concrete Isaac Sim PhysX. Environments with an
+  explicit backend default, including Newton tasks, retain that default.
 * Imitation learning and motion-generation pipelines (Mimic, motion generators)
 
 

docs/source/overview/environments.rst

@@ -90,13 +90,17 @@ modes. The **Presets** column in each table below is divided into three labeled
 
 * **physics=** — physics-backend name passed as ``physics=NAME``
   (e.g. ``physx``, ``isaacsim_physx``, ``newton_mjwarp``,
-  ``newton_kamino``, ``ovphysx``, ``newton_mjwarp_vbd_proxy``). On tasks that
-  expose automatic PhysX-family selection, ``physx`` uses Isaac Sim PhysX when
-  Kit is required and OvPhysX otherwise when the task supports it. Tasks
-  without an OvPhysX alternative fall back to Isaac Sim PhysX; use
-  ``isaacsim_physx`` to force Isaac Sim PhysX directly.
+  ``newton_kamino``, ``ovphysx``, ``newton_mjwarp_vbd_proxy``). Environments
+  whose previous default was automatic PhysX selection use the concrete
+  ``isaacsim_physx`` variant by default; explicit backend defaults such as
+  Newton remain unchanged. Select ``physics=physx`` to opt into automatic
+  PhysX-family selection: it uses Isaac Sim PhysX when Kit is required and
+  OvPhysX otherwise when the task supports it. Tasks without an OvPhysX
+  alternative fall back to Isaac Sim PhysX.
 * **renderer=** — renderer-backend name passed as ``renderer=NAME``
-  (e.g. ``isaacsim_rtx``, ``newton_renderer``, ``ovrtx``, ``rtx``)
+  (e.g. ``isaacsim_rtx``, ``newton_renderer``, ``ovrtx``, ``rtx``). Cameras
+  using the multi-backend renderer config default to concrete ``isaacsim_rtx``;
+  select ``renderer=rtx`` to opt into automatic RTX-family selection.
 * **presets=** — environment-specific (domain) preset name passed as
   ``presets=NAME[,NAME,...]``
   (e.g. ``rgb``, ``depth``, ``single_camera``, ``duo_camera``)
@@ -109,7 +113,7 @@ supported and causes configuration validation to fail.
 
 Pass ``--task=<task-name> --help`` to a training script to see all available
 preset names grouped by selector type at the command line, or run
-``./isaaclab.sh -p scripts/environments/list_envs.py --show_presets``
+``uv run python scripts/environments/list_envs.py --show_presets``
 to list presets for every registered environment.
 
 See the :doc:`Hydra preset system documentation </source/features/hydra>`

docs/source/overview/imitation-learning/augmented_imitation.rst

@@ -311,8 +311,11 @@ To install the robomimic framework, use the following commands:
 
    # install the dependencies
    sudo apt install cmake build-essential
-   # install python module (for robomimic)
-   ./isaaclab.sh -i robomimic
+   # resolve and verify Robomimic in the uv-managed environment
+   uv run --extra mimic python -c "import robomimic"
+
+For a legacy environment, install the same dependencies with
+``./isaaclab.sh -i mimic``.
 
 Training an agent
 ^^^^^^^^^^^^^^^^^
@@ -325,7 +328,7 @@ Using the generated data, we can now train a visuomotor BC agent for ``IsaacCont
 
       .. code:: bash
 
-          uv run python scripts/imitation_learning/robomimic/train.py \
+          uv run --extra mimic python scripts/imitation_learning/robomimic/train.py \
           --task IsaacContrib-Stack-Cube-Franka-IK-Rel-Visuomotor-Cosmos --algo bc \
           --dataset ./datasets/mimic_cosmos_dataset.hdf5 \
           --name bc_rnn_image_franka_stack_mimic_cosmos
@@ -417,7 +420,7 @@ Example usage for the cube stacking task:
 
       .. code:: bash
 
-          uv run python scripts/imitation_learning/robomimic/robust_eval.py \
+          uv run --extra mimic python scripts/imitation_learning/robomimic/robust_eval.py \
           --task IsaacContrib-Stack-Cube-Franka-IK-Rel-Visuomotor-Cosmos \
           --input_dir logs/robomimic/IsaacContrib-Stack-Cube-Franka-IK-Rel-Visuomotor-Cosmos/bc_rnn_image_franka_stack_mimic_cosmos/*/models \
           --log_dir robust_results/bc_rnn_image_franka_stack_mimic_cosmos \

docs/source/overview/imitation-learning/teleop_imitation.rst

@@ -459,9 +459,11 @@ Install the Robomimic framework using the following command:
 
    # install the dependencies
    sudo apt install cmake build-essential
-   # install python module (for robomimic)
-   ./isaaclab.sh -i robomimic
+   # resolve and verify Robomimic in the uv-managed environment
+   uv run --extra mimic python -c "import robomimic"
 
+For a legacy environment, install the same dependencies with
+``./isaaclab.sh -i mimic``.
 
 
 Train an Agent
@@ -479,7 +481,7 @@ Using the Isaac Lab Mimic generated data we can now train a state-based BC RNN a
 
       .. code:: bash
 
-         uv run python scripts/imitation_learning/robomimic/train.py \
+         uv run --extra mimic python scripts/imitation_learning/robomimic/train.py \
          --task IsaacContrib-Stack-Cube-Franka-IK-Rel \
          --algo bc \
          --dataset ./datasets/generated_dataset.hdf5
@@ -489,7 +491,7 @@ Using the Isaac Lab Mimic generated data we can now train a state-based BC RNN a
 
       .. code:: bash
 
-         uv run python scripts/imitation_learning/robomimic/train.py \
+         uv run --extra mimic python scripts/imitation_learning/robomimic/train.py \
          --task IsaacContrib-Stack-Cube-Franka-IK-Rel-Visuomotor \
          --algo bc \
          --dataset ./datasets/generated_dataset.hdf5
@@ -512,7 +514,7 @@ Run the trained policy to visualize the results:
 
       .. code:: bash
 
-         uv run python scripts/imitation_learning/robomimic/play.py \
+         uv run --extra mimic python scripts/imitation_learning/robomimic/play.py \
          --task IsaacContrib-Stack-Cube-Franka-IK-Rel \
          --viz kit \
          --num_rollouts 50 \
@@ -523,7 +525,7 @@ Run the trained policy to visualize the results:
 
       .. code:: bash
 
-         uv run python scripts/imitation_learning/robomimic/play.py \
+         uv run --extra mimic python scripts/imitation_learning/robomimic/play.py \
          --task IsaacContrib-Stack-Cube-Franka-IK-Rel-Visuomotor \
          --viz kit \
          --num_rollouts 50 \