Merge branch 'develop' into mh/new_defaults_core

# Conflicts:
#	source/isaaclab_tasks/test/core/test_environment_determinism.py

Author: StafaH

docs/index.rst

@@ -94,6 +94,13 @@ Table of Contents
    source/refs/reference_architecture/index
 
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Concepts
+
+   source/concepts/backends_and_presets
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Getting Started

docs/source/concepts/backends_and_presets.rst

@@ -0,0 +1,244 @@
+.. _backends-and-presets:
+
+Backends and Presets
+====================
+
+An Isaac Lab environment describes the robot, scene, sensors, and task. A
+**backend** supplies the physics or rendering implementation that brings that
+description to life. A **preset** is a named, tested configuration choice that
+lets you switch implementations or task modes without editing Python.
+
+In practice, the same environment can run with a different physics engine,
+renderer, or observation mode by adding a short selector:
+
+.. code-block:: bash
+
+   uv run isaaclab train --rl_library rsl_rl \
+      --task Isaac-Cartpole-Direct physics=newton_mjwarp
+
+The task stays ``Isaac-Cartpole-Direct``. The preset changes the configuration
+used to launch it.
+
+
+The mental model
+----------------
+
+Think of an environment as the experiment and presets as the knobs that select
+tested versions of its larger building blocks:
+
+.. code-block:: text
+
+   Environment
+   ├── physics=...    Which physics configuration runs the simulation?
+   ├── renderer=...   Which renderer produces camera data?
+   └── presets=...    Which task-specific mode or config bundle is used?
+
+After configuration is resolved, Isaac Lab's common asset, sensor, and scene
+APIs dispatch to the selected backend implementation. Environment code can use
+the same public API across PhysX, Newton, and OvPhysX instead of branching on
+the active engine throughout the task.
+
+Physics, rendering, and visualization are separate choices. For example, a
+camera environment can use Newton physics with the Newton Warp renderer, while
+the visualizer is selected independently with ``--viz``.
+
+
+Find what a task supports
+-------------------------
+
+Preset support is task-specific. Before choosing a name, ask the task what it
+offers:
+
+.. code-block:: bash
+
+   uv run isaaclab train --rl_library rsl_rl \
+      --task Isaac-Cartpole-Camera-Direct --help
+
+The help output groups names by ``physics=``, ``renderer=``, and ``presets=``.
+To browse all registered environments and their presets at once, run:
+
+.. code-block:: bash
+
+   uv run python scripts/environments/list_envs.py --show_presets
+
+An empty preset list is not an error. It means that the environment uses its
+registered default configuration and does not expose alternatives. Passing a
+name that a task does not list is unsupported and fails during configuration
+validation.
+
+
+Choose a selector
+-----------------
+
+.. list-table::
+   :widths: 23 32 45
+   :header-rows: 1
+
+   * - Selector
+     - Example
+     - What it changes
+   * - ``physics=NAME``
+     - ``physics=newton_mjwarp``
+     - Selects a physics configuration, including its backend and solver.
+   * - ``renderer=NAME``
+     - ``renderer=newton_renderer``
+     - Selects a renderer configuration for tasks that produce camera data.
+   * - ``presets=NAME[,NAME,...]``
+     - ``presets=rgb``
+     - Applies task-specific choices such as observation modes, camera layouts,
+       or compatible configuration bundles.
+
+These are Hydra tokens, so append them without leading dashes. They work with
+training, playback, and environment scripts that use Isaac Lab's task
+configuration launcher.
+
+Selectors can be combined. This command chooses Newton with the MuJoCo-Warp
+solver, the Newton Warp renderer, and RGB observations:
+
+.. code-block:: bash
+
+   uv run isaaclab train --rl_library rsl_rl \
+      --task Isaac-Cartpole-Camera-Direct \
+      physics=newton_mjwarp renderer=newton_renderer presets=rgb
+
+Only combine values listed for the task. Some physics, renderer, sensor, and
+observation configurations are incompatible, and the task may reject an
+invalid combination with a focused error message.
+
+
+Common backend choices
+----------------------
+
+The exact list depends on the environment, but these names follow shared
+conventions:
+
+.. list-table:: Physics presets
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Name
+     - Meaning
+   * - ``isaacsim_physx``
+     - Concrete Isaac Sim PhysX configuration. This is the default for tasks
+       whose established default is Isaac Sim PhysX.
+   * - ``physx``
+     - Automatic PhysX-family selection. Isaac Sim PhysX is used when the
+       runtime needs Kit; a configured OvPhysX alternative can be used for
+       fully kit-less runs.
+   * - ``newton_mjwarp``
+     - Newton physics with the MuJoCo-Warp solver.
+   * - ``newton_kamino``
+     - Newton physics with the Kamino solver. Support is beta and currently
+       limited to selected tasks and compatible assets.
+   * - ``ovphysx``
+     - Concrete OvPhysX configuration for supported kit-less tasks.
+
+.. list-table:: Renderer presets
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Name
+     - Meaning
+   * - ``isaacsim_rtx``
+     - Concrete Isaac Sim RTX renderer and the established default for
+       multi-backend camera tasks.
+   * - ``rtx``
+     - Automatic RTX-family selection based on the resolved runtime.
+   * - ``newton_renderer``
+     - Newton Warp renderer.
+   * - ``ovrtx``
+     - Concrete OVRTX renderer.
+
+Automatic selectors such as ``physics=physx`` and ``renderer=rtx`` are opt-in.
+Defaults are concrete so that running a task without selectors is predictable.
+A solver is not a separate backend: ``newton_mjwarp`` and ``newton_kamino``
+both use Newton but configure different solvers.
+
+
+Defaults, presets, and fine-tuning
+----------------------------------
+
+A preset replaces the complete configuration section at its location; it does
+not merge fields from two alternatives. Isaac Lab resolves configuration in
+this order:
+
+1. Apply each preset config's ``default`` choice.
+2. Apply global choices from ``presets=...``.
+3. Apply a preset targeted at a specific path, such as
+   ``env.sim.physics=newton_mjwarp``.
+4. Apply scalar Hydra overrides, such as ``env.sim.dt=0.002``.
+
+The last step makes it easy to start from a maintained preset and tune one
+value:
+
+.. code-block:: bash
+
+   uv run isaaclab train --rl_library rsl_rl \
+      --task Isaac-Cartpole-Direct \
+      physics=newton_mjwarp env.sim.dt=0.002
+
+Prefer ``physics=`` and ``renderer=`` for backend choices because they state
+intent clearly. Use ``presets=`` for task-specific modes or when one name must
+update several matching sections together. Use a path selector only when you
+intend to replace one particular section.
+
+.. important::
+
+   Keep behavior-changing presets the same when loading a checkpoint. An
+   observation preset can change tensor shapes, and a policy trained with one
+   observation mode may not load with another.
+
+
+How task authors expose choices
+-------------------------------
+
+Task authors define alternatives with
+:class:`~isaaclab_tasks.utils.hydra.PresetCfg` and choose one as the default.
+For a multi-backend task, the preset wrapper belongs in
+:class:`~isaaclab.sim.SimulationCfg`:
+
+.. code-block:: python
+
+   from isaaclab.physics import PhysxAutoCfg
+   from isaaclab.sim import SimulationCfg
+   from isaaclab.utils.configclass import configclass
+   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 PhysicsCfg(PresetCfg):
+       isaacsim_physx = PhysxCfg()
+       ovphysx = OvPhysxCfg()
+       physx = PhysxAutoCfg(
+           isaacsim_physx=isaacsim_physx,
+           ovphysx=ovphysx,
+       )
+       default = isaacsim_physx
+       newton_mjwarp = NewtonCfg(solver_cfg=MJWarpSolverCfg())
+
+
+   @configclass
+   class MyEnvCfg:
+       sim: SimulationCfg = SimulationCfg(physics=PhysicsCfg())
+
+Keep backend-specific values inside named configurations whenever possible.
+This keeps task logic shared and makes every supported choice visible from the
+command line.
+
+
+Where to go next
+----------------
+
+- :doc:`/source/overview/environments` lists environments and their supported
+  presets.
+- :doc:`/source/features/hydra` covers scalar overrides, preset authoring,
+  conflict handling, and advanced configuration behavior.
+- :doc:`/source/overview/core-concepts/multi_backend_architecture` explains how
+  factories, the physics manager, assets, and sensors dispatch across backends.
+- :doc:`/source/overview/core-concepts/physical-backends/index` compares physics
+  backend capabilities and links to backend-specific setup guides.
+- :doc:`/source/overview/core-concepts/renderers` explains renderer selection and
+  implementation details.

docs/source/features/hydra.rst

@@ -214,6 +214,10 @@ combinations early with clear error messages.
 Preset System
 -------------
 
+For a user-focused introduction to choosing physics, rendering, and task
+variants, start with :doc:`/source/concepts/backends_and_presets`. This section
+covers the complete preset definition and resolution behavior.
+
 The preset system lets you swap out entire config sections -- or individual scalar
 values -- with a single command line argument. Instead of overriding individual
 fields, you select a named preset that **completely replaces** the config section

docs/source/features/reproducibility.rst

@@ -55,6 +55,26 @@ Pass ``--deterministic`` to enable reproducible rendering from the app launcher.
         ./isaaclab.sh train --rl_library rl_games \
           --task Isaac-Cartpole-Camera --deterministic
 
+Newton physics determinism
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set :attr:`isaaclab_newton.physics.NewtonCfg.deterministic_mode` to
+``"gpu_to_gpu"`` to request reproducibility across GPU architectures, or to
+``"run_to_run"`` to request reproducibility on one GPU. Newton applies the
+selected mode to supported solver kernels and enables deterministic contact
+ordering in its collision pipeline. Deterministic execution can increase
+memory use and reduce simulation performance. MJWarp on the GPU with
+:attr:`isaaclab_newton.physics.MJWarpSolverCfg.disable_sensors` set to ``True``,
+XPBD, and Featherstone are supported; selecting an unsupported solver raises
+an error.
+
+.. warning::
+
+   Deterministic contact ordering adds sorting work and allocates buffers sized
+   for the configured maximum contact count. Runtime and memory overhead
+   therefore grow with contact capacity. Enable this mode only when its
+   reproducibility guarantee is required.
+
 For results on our determinacy testing for RL training, please check the GitHub Pull Request `#940`_.
 
 .. tip::

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

@@ -169,9 +169,9 @@ instantiations automatically use the selected backend.
 Multi-Backend Environments with Presets
 ---------------------------------------
 
-Environments can support multiple backends simultaneously using the :doc:`preset system
-</source/features/hydra>`. Each backend gets its own configuration variant. The example
-below shows only the physics-related fields:
+Environments can support multiple backends simultaneously using :doc:`backend and preset
+selectors </source/concepts/backends_and_presets>`. Each backend gets its own configuration
+variant. The example below shows only the physics-related fields:
 
 .. code-block:: python
 
@@ -470,7 +470,8 @@ See Also
 
 - :doc:`/source/migration/migrating_to_isaaclab_3-0` — migration guide from Isaac Lab 2.x to the
   multi-backend architecture
-- :doc:`/source/features/hydra` — preset system for multi-backend environment configurations
+- :doc:`/source/concepts/backends_and_presets` — user guide to backend and preset selection
+- :doc:`/source/features/hydra` — advanced configuration and preset authoring
 - :doc:`physical-backends/index` — feature matrix and per-backend guides (PhysX, Newton, OvPhysX)
 - :doc:`physical-backends/newton/index` — Newton backend guide
 - :doc:`physical-backends/newton/newton-manager-abstraction` — adding Newton solver managers and

docs/source/overview/environments.rst

@@ -116,8 +116,8 @@ preset names grouped by selector type at the command line, or run
 ``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>`
-for all available backend names and how the typed selectors work.
+See :doc:`/source/concepts/backends_and_presets` for a guided introduction to
+backend names, preset discovery, and typed selectors.
 
 .. note::
 

docs/source/overview/reinforcement-learning/rl_existing_scripts.rst

@@ -9,7 +9,8 @@ Preset Selectors
 
 All training and play commands accept ``physics=NAME``, ``renderer=NAME``, and
 ``presets=NAME[,NAME,...]`` tokens appended directly to the command (no leading dashes).
-See :doc:`/source/features/hydra` for all available names and how the selectors work.
+See :doc:`/source/concepts/backends_and_presets` for preset discovery, common backend
+names, and how the selectors work.
 
 .. tab-set::
 

docs/source/setup/quickstart.rst

@@ -176,8 +176,8 @@ Add task-specific options with ``presets=<name>``; for example:
       --task Isaac-Cartpole-Camera-Direct \
       physics=newton_mjwarp renderer=newton_renderer presets=rgb
 
-See :doc:`/source/features/hydra` for configuration overrides and
-``presets=`` in more detail.
+See :doc:`/source/concepts/backends_and_presets` for backend and preset selection,
+and :doc:`/source/features/hydra` for arbitrary configuration overrides.
 
 
 Visualize a task
@@ -259,6 +259,7 @@ Next steps
 ----------
 
 - Browse all registered environments: :doc:`/source/overview/environments`
-- Learn how task configuration works: :doc:`/source/features/hydra`
+- Learn how backends and presets fit together: :doc:`/source/concepts/backends_and_presets`
+- Learn how to override task configuration: :doc:`/source/features/hydra`
 - Follow a guided environment-building tutorial: :doc:`/source/tutorials/index`
 - Read the installation options and troubleshooting guide: :ref:`isaaclab-installation-root`