Skip to content

Commit 29f14e0

Browse files
AntoineRichardAntoineRichard
committed
Move Newton docs out of experimental, add backend pages
Adds a new docs/source/overview/core-concepts/backends/ hub with per-backend sub-pages and a feature-support matrix, addressing IsaacLab-Internal#876. Newton: the existing newton-physics-integration content moves wholesale from experimental-features/ to backends/newton/. The intro is reframed from "experimental feature branch" to "beta backend" and the relative literalinclude path in using-kamino.rst is fixed for the new depth. PhysX: new full page set (index, installation, configuration, supported-features) modeled on the Newton structure, covering PhysxCfg parameters and the common GPU buffer tuning knobs. OvPhysX: short stub flagged as highly experimental with pointers to the in-flight integration PRs (isaac-sim#5426, isaac-sim#5459). The page will be expanded once those land. Cross-references in features/visualization.rst, overview/reinforcement-learning/rl_existing_scripts.rst, and multi_backend_architecture.rst are updated to the new paths. The Experimental Features toctree now contains only bleeding-edge.
1 parent 88d3dda commit 29f14e0

17 files changed

Lines changed: 482 additions & 55 deletions

File tree

‎docs/index.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,6 @@ Table of Contents
142142
:caption: Experimental Features
143143

144144
source/experimental-features/bleeding-edge
145-
source/experimental-features/newton-physics-integration/index
146145

147146
.. toctree::
148147
:maxdepth: 1

‎docs/source/experimental-features/newton-physics-integration/index.rst‎

Lines changed: 0 additions & 43 deletions
This file was deleted.

‎docs/source/features/visualization.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -549,5 +549,5 @@ See Also
549549

550550
- :doc:`/source/overview/core-concepts/renderers` — renderer backends (RTX, Newton Warp, OVRTX)
551551
- :doc:`/source/overview/core-concepts/scene_data_providers` — how scene data flows from physics to visualizers
552-
- :doc:`/source/experimental-features/newton-physics-integration/index` — Newton physics integration guide
552+
- :doc:`/source/overview/core-concepts/backends/newton/index` — Newton backend guide
553553
- :doc:`/source/migration/migrating_to_isaaclab_3-0` — migration guide with ``--headless`` deprecation details

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

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
Physics Backends
2+
================
3+
4+
Isaac Lab 3.0 supports multiple physics backends through a unified API. Each backend
5+
exposes the same :class:`~isaaclab.assets.Articulation`,
6+
:class:`~isaaclab.assets.RigidObject`, sensor and renderer surfaces, while differing
7+
in solver characteristics, maturity, and feature coverage. See
8+
:doc:`../multi_backend_architecture` for how the dispatch and factory machinery work
9+
under the hood.
10+
11+
This page summarizes what each backend supports today; the sub-pages document
12+
backend-specific configuration, installation, and limitations.
13+
14+
.. toctree::
15+
:maxdepth: 2
16+
17+
physx/index
18+
newton/index
19+
ovphysx/index
20+
21+
22+
Choosing a Backend
23+
------------------
24+
25+
* **PhysX** — the historical default. Production-ready, broad coverage of Isaac Lab
26+
features, and the reference for behavior parity. Selected via
27+
:class:`~isaaclab_physx.physics.PhysxCfg`.
28+
* **Newton** — GPU-accelerated, Warp-native, and differentiable. The Newton
29+
integration ships with the MuJoCo-Warp solver and beta support for the Kamino
30+
solver. Selected via :class:`~isaaclab_newton.physics.NewtonCfg`.
31+
* **OvPhysX** — a **highly experimental** kit-less PhysX backend that reads
32+
scene-level parameters from the USD ``PhysicsScene`` prim. Selected via
33+
:class:`~isaaclab_ovphysx.physics.OvPhysxCfg`. Not recommended for general use yet.
34+
35+
The active backend is selected at simulation construction time and applies to every
36+
asset, sensor, and renderer instantiated thereafter:
37+
38+
.. code-block:: python
39+
40+
from isaaclab.sim import SimulationCfg
41+
from isaaclab_physx.physics import PhysxCfg
42+
from isaaclab_newton.physics import NewtonCfg, MJWarpSolverCfg
43+
44+
# PhysX (default)
45+
sim_cfg = SimulationCfg(physics=PhysxCfg())
46+
47+
# Newton with MuJoCo-Warp
48+
sim_cfg = SimulationCfg(physics=NewtonCfg(solver_cfg=MJWarpSolverCfg()))
49+
50+
51+
Feature Support Matrix
52+
----------------------
53+
54+
The matrix below is intentionally coarse-grained. For exhaustive per-asset and
55+
per-task support, see each backend's own ``limitations`` page.
56+
57+
.. list-table::
58+
:header-rows: 1
59+
:widths: 30 20 30 20
60+
61+
* - Feature
62+
- PhysX
63+
- Newton
64+
- OvPhysX
65+
* - Maturity
66+
- Stable
67+
- Beta
68+
- Highly experimental
69+
* - Default solver
70+
- TGS (rigid body)
71+
- MuJoCo-Warp
72+
- PhysX (TGS / PGS via USD)
73+
* - Alternative solvers
74+
- PGS
75+
- Kamino (beta), additional Newton solvers planned
76+
- —
77+
* - Differentiable
78+
- No
79+
- Yes (via Warp)
80+
- No
81+
* - Articulation API
82+
- Yes
83+
- Yes
84+
- Yes (subset)
85+
* - Rigid Object API
86+
- Yes
87+
- Yes
88+
- Yes (subset)
89+
* - Contact Sensor
90+
- Yes
91+
- Yes
92+
- Yes
93+
* - IMU / Frame Transformer / Ray Caster
94+
- Yes
95+
- Yes
96+
- Partial — see backend page
97+
* - PVA / Joint-Wrench Sensor
98+
- Yes
99+
- Yes
100+
- Partial
101+
* - Camera / Tiled Rendering
102+
- Yes (RTX)
103+
- Yes (Newton-Warp renderer)
104+
- Yes (RTX) — depends on Isaac Sim
105+
* - Requires Isaac Sim
106+
- Yes
107+
- Optional (only for the Omniverse visualizer)
108+
- Yes
109+
* - Solver configuration source
110+
- :class:`~isaaclab_physx.physics.PhysxCfg`
111+
- :class:`~isaaclab_newton.physics.NewtonCfg` + solver config
112+
- USD ``PhysicsScene`` + :class:`~isaaclab_ovphysx.physics.OvPhysxCfg`
113+
114+
115+
Selecting Backends per Task
116+
---------------------------
117+
118+
Tasks that support more than one backend define a Hydra preset on
119+
``SimulationCfg.physics``. The example below shows the cartpole task config which
120+
declares all three backends side by side:
121+
122+
.. code-block:: python
123+
124+
from isaaclab_physx.physics import PhysxCfg
125+
from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg
126+
from isaaclab_ovphysx.physics import OvPhysxCfg
127+
128+
@configclass
129+
class CartpolePhysicsCfg(PresetCfg):
130+
default: PhysxCfg = PhysxCfg()
131+
physx: PhysxCfg = PhysxCfg()
132+
newton_mjwarp: NewtonCfg = NewtonCfg(solver_cfg=MJWarpSolverCfg())
133+
ovphysx: OvPhysxCfg = OvPhysxCfg()
134+
135+
Users then select the backend at the command line via ``presets=<name>`` or by
136+
overriding the physics field directly. See :ref:`hydra-backend-solver-presets` for
137+
the full Hydra interaction.

‎docs/source/overview/core-concepts/backends/newton/index.rst‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
Newton Backend
2+
==============
3+
4+
`Newton <https://newton-physics.github.io/newton/latest/guide/overview.html>`_ is a
5+
GPU-accelerated, extensible, and differentiable physics simulation engine designed
6+
for robotics, research, and advanced simulation workflows. Built on top of
7+
`NVIDIA Warp <https://nvidia.github.io/warp/>`_ and integrating MuJoCo Warp, Newton
8+
provides high-performance simulation, modern Python APIs, and a flexible
9+
architecture for both users and developers.
10+
11+
Newton is an Open Source community-driven project with contributions from NVIDIA,
12+
Google Deep Mind, and Disney Research, managed through the Linux Foundation.
13+
14+
Newton support in Isaac Lab is in beta and under active development. Many features
15+
are still maturing, and the Isaac Lab integration ships a focused, validated set of
16+
classic RL and flat-terrain locomotion environments. We have validated Newton
17+
simulation against PhysX by transferring learned policies in both directions and
18+
have successfully deployed a Newton-trained locomotion policy to a G1 robot.
19+
20+
Newton can support `multiple solvers
21+
<https://newton-physics.github.io/newton/latest/api/newton_solvers.html>`_ for
22+
handling different types of physics simulation. The Isaac Lab integration focuses
23+
primarily on the MuJoCo-Warp solver, with beta support for the Kamino solver on
24+
selected classic tasks. See :doc:`using-kamino` for the Kamino workflow.
25+
26+
During the beta phase, breaking changes and incomplete documentation are still
27+
expected. Official support and debugging assistance will follow once the framework
28+
reaches an official release.
29+
30+
For an overview of how the multi-backend architecture works, including how to add a
31+
new backend, see :doc:`../../multi_backend_architecture`.
32+
33+
34+
.. toctree::
35+
:maxdepth: 2
36+
:titlesonly:
37+
38+
installation
39+
limitations-and-known-bugs
40+
solver-transitioning
41+
using-kamino

docs/source/experimental-features/newton-physics-integration/installation.rst renamed to docs/source/overview/core-concepts/backends/newton/installation.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Installation
22
============
33

4-
Installing the Newton physics integration requires three things:
4+
Installing the Newton backend requires three things:
55

66
1) The ``develop`` branch of Isaac Lab
77
2) Ubuntu 22.04 or 24.04

docs/source/experimental-features/newton-physics-integration/limitations-and-known-bugs.rst renamed to docs/source/overview/core-concepts/backends/newton/limitations-and-known-bugs.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
Limitations
22
===========
33

4-
During the early development phase of both Newton and this Isaac Lab integration,
5-
you are likely to encounter breaking changes as well as limited documentation.
4+
The Newton backend is in beta. Breaking changes and incomplete documentation are
5+
still expected, and official support or debugging assistance will only be
6+
available once the integration reaches an official release.
67

7-
We do not expect to be able to provide support or debugging assistance until the framework has reached an official release.
8-
9-
Here is a non-exhaustive list of capabilities currently supported in the Newton experimental feature branch grouped by extension:
8+
Here is a non-exhaustive list of capabilities currently supported by the Newton
9+
backend, grouped by extension:
1010

1111
* isaaclab:
1212
* Articulation API (supports both articulations and single-body articulations as rigid bodies)

docs/source/experimental-features/newton-physics-integration/solver-transitioning.rst renamed to docs/source/overview/core-concepts/backends/newton/solver-transitioning.rst

File renamed without changes.

docs/source/experimental-features/newton-physics-integration/using-kamino.rst renamed to docs/source/overview/core-concepts/backends/newton/using-kamino.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ solver config types used by the presets:
4949
Then add a ``newton_kamino`` entry beside the existing ``default``, ``physx``, and
5050
``newton_mjwarp`` entries:
5151

52-
.. literalinclude:: ../../../../source/isaaclab_tasks/isaaclab_tasks/direct/cartpole/cartpole_env_cfg.py
52+
.. literalinclude:: ../../../../../source/isaaclab_tasks/isaaclab_tasks/direct/cartpole/cartpole_env_cfg.py
5353
:language: python
5454
:start-at: class CartpolePhysicsCfg
5555
:end-at: ovphysx: OvPhysxCfg = OvPhysxCfg()

‎docs/source/overview/core-concepts/backends/ovphysx/index.rst‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
OvPhysX Backend
2+
===============
3+
4+
.. warning::
5+
6+
OvPhysX is **highly experimental** and is not recommended for general use yet.
7+
The public surface is changing rapidly while the backend is under active
8+
development. This page is a placeholder and will be expanded once the
9+
in-flight integration work lands on ``develop``.
10+
11+
OvPhysX is a kit-less variant of the PhysX backend. It drives PhysX directly
12+
(without the Omniverse Kit runtime) and reads scene-level solver parameters
13+
from the USD ``PhysicsScene`` prim rather than from a Python config. The Python
14+
config :class:`~isaaclab_ovphysx.physics.OvPhysxCfg` only exposes the handful of
15+
GPU buffer sizes that are not represented on the USD schema.
16+
17+
OvPhysX is selected through :class:`~isaaclab_ovphysx.physics.OvPhysxCfg`:
18+
19+
.. code-block:: python
20+
21+
from isaaclab.sim import SimulationCfg
22+
from isaaclab_ovphysx.physics import OvPhysxCfg
23+
24+
sim_cfg = SimulationCfg(physics=OvPhysxCfg())
25+
26+
Why use OvPhysX?
27+
----------------
28+
29+
* **Kit-less execution.** OvPhysX avoids Omniverse Kit, which makes it a useful
30+
experimental path for headless deployments and for backends that don't need
31+
the Kit runtime stack.
32+
* **USD-as-source-of-truth.** Solver parameters are taken from the
33+
``PhysicsScene`` USD prim, so authoring tools that already manage USD scenes
34+
do not need a parallel Python config.
35+
36+
What works today
37+
----------------
38+
39+
The asset and sensor surface tracks PhysX, but only a subset is implemented and
40+
validated at the time of writing. Articulation, Rigid Object, and Contact
41+
Sensor are the primary covered surfaces. Other sensors and renderer
42+
combinations are partial — consult the in-flight pull requests below for the
43+
current status:
44+
45+
* Articulation: `PR #5459 <https://github.com/isaac-sim/IsaacLab/pull/5459>`_
46+
* RigidObject: `PR #5426 <https://github.com/isaac-sim/IsaacLab/pull/5426>`_
47+
48+
Status and follow-up
49+
--------------------
50+
51+
This page is intentionally a stub. Once the in-flight OvPhysX work merges, this
52+
section will be expanded with full installation, configuration, and supported
53+
feature lists matching the other backends.
54+
55+
For architectural context, see :doc:`../../multi_backend_architecture`.

0 commit comments

Comments
 (0)