> This page is for version Release 3.0 (default).
> For other versions, use one of these documentation indexes:
> - Release 3.0 (default): https://docs.nvidia.com/isaaclab/3.0/llms.txt
> - Release 2.3: https://docs.nvidia.com/isaaclab/2.3/llms.txt
> - Release 2.2: https://docs.nvidia.com/isaaclab/2.2/llms.txt
> - Release 2.1: https://docs.nvidia.com/isaaclab/2.1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/isaaclab/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/isaaclab/_mcp/server.

# OvPhysX

> **Warning**
>
> Do not combine OvPhysX with the Kit visualizer. Commands such as
> `physics=ovphysx --visualizer kit` are unsupported because ovphysx
> loads USD-dependent PhysX plugins from its own package, while Kit already
> owns a separate USD/plugin stack in the same process. Use
> `--visualizer newton_gl`, `--visualizer rerun`, `--visualizer viser`,
> or omit `--visualizer` for headless execution.

OvPhysX runs PhysX without Omniverse Kit. It reads scene-level solver settings
from the USD `PhysicsScene` prim. [OvPhysxCfg](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/api/lab_ov/isaaclab_ov.physics.html#isaaclab_ov.physics.OvPhysxCfg) holds
GPU buffer settings that USD does not represent.

OvPhysX is selected through [OvPhysxCfg](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/api/lab_ov/isaaclab_ov.physics.html#isaaclab_ov.physics.OvPhysxCfg):

```python
from isaaclab.sim import SimulationCfg
from isaaclab_ov.physics import OvPhysxCfg

sim_cfg = SimulationCfg(physics=OvPhysxCfg())
```

## Why use OvPhysX?

* **No Kit runtime.** Run headless simulations without Isaac Sim.
* **USD configuration.** Scene-authoring tools can set solver parameters directly
  on the `PhysicsScene` prim.

## What works today

OvPhysX supports the following components. The notes describe requirements and
limits to consider when configuring a task.

| Component                       | Coverage and limits                                                                                                              |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Rigid objects and articulations | Rigid objects, rigid-object collections, and articulations.                                                                      |
| Contact sensing                 | Aggregate and filtered forces, contact points, and contact timing. Pose tracking requires one sensor body per environment.       |
| Motion and frame sensing        | IMU, PVA, and frame transforms. Joint-wrench readings include the root body and use the child-side joint frame.                  |
| Ray casting                     | Ray casters and ray-cast cameras using Warp meshes. The standard ray caster requires static target meshes.                       |
| Rendering and scene data        | Scene-data and frame-view implementations support kit-less consumers, including OVRTX. Isaac Sim / Kit cannot share the process. |
| Deformables                     | Volume and surface deformables on CUDA. Bodies in one view need matching node counts; see `Deformable limitations`\_.            |
| Heterogeneous cloning           | Geometry variants with matching body, joint, and tendon layouts; see `Heterogeneous cloning`\_.                                  |

See [/source/concepts/sensors/index](/isaaclab/3.0/concepts/sensors) for sensor configuration and
[/source/concepts/renderers](/isaaclab/3.0/concepts/renderers) for renderer choices.

Implementation history: rigid objects #5426, articulations #5459,
rigid-object collections #5570, contacts #5422, scene data #5589,
and frame views #5678 in [https://github.com/isaac-sim/IsaacLab/pulls](https://github.com/isaac-sim/IsaacLab/pulls).
Broader integration work was tracked in issue #5634.
Check isaaclab_ov implementations and tests when updating this table.

## Installation

The `ovphysx` extra requires OvPhysX 0.6.4.72118723. Install it from the repository root with:

```bash
uv sync --inexact --extra ovphysx
```

The `--inexact` flag preserves packages installed through other extras.
Use `--extra ov` to install both public OvPhysX and OVRTX runtimes. The combined
extra pairs OVRTX 0.5.1.385782 with OVStage 0.2.1; OVRTX 0.4.1 is not compatible
with this runtime combination. The legacy
Isaac Lab installer also supports `./isaaclab.sh -i 'ov[ovphysx]'` and
`./isaaclab.sh -i 'ov[all]'`.

## Testing the Installation

First check that the Python package and runtime wheel import correctly:

#### uv (Recommended)

```bash
uv run --extra ovphysx --extra test python -c "import ovphysx.types; from isaaclab_ov.physics import OvPhysxCfg; print('OvPhysX runtime OK')"
```

#### isaaclab.sh / isaaclab.bat

```bash
./isaaclab.sh -p -c "import ovphysx.types; from isaaclab_ov.physics import OvPhysxCfg; print('OvPhysX runtime OK')"
```

Then run a small backend smoke test:

#### uv (Recommended)

```bash
uv run --extra ovphysx --extra test python -m pytest source/isaaclab_ov/test/assets/test_rigid_object.py::test_initialization -k cpu
```

#### isaaclab.sh / isaaclab.bat

```bash
./isaaclab.sh -p -m pytest source/isaaclab_ov/test/assets/test_rigid_object.py::test_initialization -k cpu
```

To try a task that declares an OvPhysX physics preset, use the same preset CLI
syntax as the other backends:

#### uv (Recommended)

```bash
uv run --extra ovphysx isaaclab zero_agent --task Isaac-Cartpole-Direct \
    --num_envs 128 --max_steps 64 --viz none physics=ovphysx
```

#### isaaclab.sh / isaaclab.bat

```bash
./isaaclab.sh -p scripts/environments/zero_agent.py --task Isaac-Cartpole-Direct \
    --num_envs 128 --max_steps 64 --viz none physics=ovphysx
```

This command runs a 64-step headless zero-action rollout and then exits.

## Supported locomotion environments

Use the [environment browser ](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/isaaclab/environments.html) or task help
for the available `physics=` presets. To list launchable combinations:

```bash
uv run --extra ovphysx isaaclab list_envs --show_presets --keyword Velocity
```

Playback uses the same `physics=ovphysx` selector as training.

#### Locomotion task examples

* `Isaac-Ant-Direct`
* `Isaac-Humanoid-Direct`
* `IsaacContrib-Velocity-Rough-AnymalB`
* `IsaacContrib-Velocity-Rough-AnymalC`
* `Isaac-Velocity-Flat-AnymalD`
* `Isaac-Velocity-Rough-AnymalD`
* `IsaacContrib-Velocity-Rough-UnitreeA1`
* `IsaacContrib-Velocity-Rough-UnitreeGo1`
* `Isaac-Velocity-Rough-UnitreeGo2`
* `Isaac-Velocity-Rough-Cassie`
* `Isaac-Velocity-Rough-G1`
* `Isaac-Velocity-Rough-H1`

## Heterogeneous cloning

OvPhysX 0.6.3 is required for heterogeneous runtime cloning. Tensor bindings use
numeric environment order so indexed resets, actions and observations address
the correct variant. Variants may differ in geometry but must preserve body,
joint and tendon layout. Isaac Lab checks prototype rotation axes and tendon layouts;
OVPhysX checks body and joint metadata when binding articulations.

The clone context compiles the plan's prototypes and world assignments once.
The physics manager attaches one exported stage, replays the native copies, and
warms the runtime before assets and sensors bind. Hard reset reuses the same
declarations; there is no separate consumable queue. Binding paths come from the
plan's world layout and environment template, not from native clone order.

Authored sources all receive native environment ID zero. Every world containing
a source or USD-only physics therefore imports all its declared assets as originals. Other worlds
clone their assets from a complete original world of the same composition,
using one native environment ID per destination world. This keeps a robot,
table and object able to contact one another without destination placeholders.
Only declared asset subtrees are copied; unrelated authored assets are retained.

Keep [filter_collisions](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/api/lab/isaaclab.scene.html#isaaclab.scene.InteractiveSceneCfg.filter_collisions) enabled to
isolate original worlds with USD collision groups. GPU copies additionally use
native environment-ID filtering. CPU has no native environment-ID filtering
in OvPhysX 0.6.3, so it imports all declared USD copies and uses collision groups.
Large overlapping original layouts can still exhaust broadphase pair capacity;
use spatially separated environments.

## Deformable limitations

OvPhysX deformables currently require every body matched by one
[DeformableObject](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/api/lab/isaaclab.assets.html#isaaclab.assets.DeformableObject) to have the same number of simulation
nodes. Initialization raises an error for mixed node counts instead of exposing
padded state that would produce incorrect reductions.

Deformable scenes also require full-stage materialization. Startup cost therefore
grows with the number of authored environments. Use this path for small validation
scenes; training-scale workloads with thousands of environments are not currently
supported. Deformable bodies are not supported by the heterogeneous fast-path
cloner.

## Native access

Use native access when the shared asset and sensor APIs do not expose the data
or operation you need. Reuse an Isaac Lab-owned handle when its selection matches;
create raw access only for additional capabilities. Native writes can bypass Isaac
Lab's caches and validation, so follow the ownership and synchronization rules below.

### Mental model

OvPhysX exposes generic `TensorBinding` objects. A binding combines a prim
selection with one installed `TensorType`; it is not an asset-specific native
storage object. Callers explicitly pull values into their own buffer with
`read()` and push a buffer back with `write()`. Isaac Lab optionally wraps
these bindings in [OvPhysxView](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/api/lab_ov/isaaclab_ov.sim.views.html#isaaclab_ov.sim.views.OvPhysxView) for a
string-keyed, guarded convenience surface.

### Lifecycle prerequisite

Create bindings only after the OvPhysX simulation has initialized and reset,
when its native runtime is live. A stage reload, a reset path that rebuilds the
stage or runtime, and manager teardown invalidate all existing bindings and
views. Reacquire them afterwards.

Get the active OvPhysX handle from the manager after the lifecycle prerequisite:

```python
from isaaclab_ov.physics import OvPhysxManager

physx = OvPhysxManager.get_physx_instance()
if physx is None:
    raise RuntimeError("OvPhysX has not been constructed; initialize and reset the simulation first.")
```

A non-`None` handle proves only that the manager constructed an OvPhysX instance; it is not a
readiness predicate for the current simulation context. Manager teardown releases the instance
and clears this handle. Initialize and reset the current context before access, and always
reacquire the handle before creating new bindings or views.

### Reuse Isaac Lab-owned access

Reuse the convenience view already owned by an Isaac Lab asset when its
selection matches:

```python
object_view = scene["object"].root_view
poses = object_view.get_attribute("rigid_body_pose")
```

### Create raw access

Create a raw binding when the desired selection is not already owned by an
Isaac Lab asset. The following representative pose binding is float32 and
uses the simulation device; it is not a generic allocator for every tensor
type:

```python
import warp as wp
from isaaclab.physics import PhysicsManager
from ovphysx.types import TensorType

binding = physx.create_tensor_binding(
    pattern="/World/envs/env_*/Object",
    tensor_type=TensorType.RIGID_BODY_POSE,
)
try:
    poses = wp.empty(
        tuple(binding.shape),
        dtype=wp.float32,
        device=PhysicsManager.get_device(),
    )
    binding.read(poses)
    binding.write(poses)
finally:
    binding.destroy()
```

Before allocating a buffer, inspect `binding.shape`, `binding.dtype`, the
binding's count, and its path metadata. Match the binding shape and DLPack scalar
metadata exactly, and respect the binding's native device and access mode.
`RIGID_BODY_POSE` has the float32 layout used above, but another tensor type
can have a different scalar dtype, shape, native device, or write permission.

For a new selection, construct [OvPhysxView](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/api/lab_ov/isaaclab_ov.sim.views.html#isaaclab_ov.sim.views.OvPhysxView)
with the native runtime and a Tensor API pattern:

```python
from isaaclab.physics import PhysicsManager
from isaaclab_ov.sim.views import OvPhysxView

view = OvPhysxView(
    physx,
    pattern="/World/envs/env_*/Object",
    device=PhysicsManager.get_device(),
)
try:
    if view.try_binding_for("rigid_body_pose") is not None:
        poses = view.get_attribute("rigid_body_pose")
        view.set_attribute("rigid_body_pose", poses)
        view.read_into("rigid_body_pose", poses)
finally:
    view.close()
```

`try_binding_for` attempts to create a binding for this selection and returns
`None` when a valid type is unavailable. `binding_for` returns a raw binding
and bypasses the view's device, dtype, shape, and read-only guards.

### Read/write semantics

Raw `binding.read(buffer)` calls pull values into caller-owned buffers, while
`binding.write(buffer)` calls push values to the simulation. Editing a local
buffer alone does not change the simulation. The guarded
[get_attribute](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/api/lab_ov/isaaclab_ov.sim.views.html#isaaclab_ov.sim.views.OvPhysxView.get_attribute),
[read_into](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/api/lab_ov/isaaclab_ov.sim.views.html#isaaclab_ov.sim.views.OvPhysxView.read_into), and
[set_attribute](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/api/lab_ov/isaaclab_ov.sim.views.html#isaaclab_ov.sim.views.OvPhysxView.set_attribute) paths provide the
same pull/push boundary while validating the binding's shape, scalar dtype,
native device, and writable access.

### Ownership, synchronization, and invalidation

Allocate buffers on the binding's required device and match its shape and
DLPack scalar metadata. State tensors normally use the simulation device, while
some property tensors are CPU-only. [OvPhysxView](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/api/lab_ov/isaaclab_ov.sim.views.html#isaaclab_ov.sim.views.OvPhysxView)
validates these requirements and can reinterpret supported flat scalar layouts
as structured Warp values, but it does not move data between CPU and GPU.

Use `try_binding_for` when a tensor type might not apply to the selected
prims. Reacquire raw bindings and convenience views after reset paths that
rebuild the stage or runtime, or after teardown. Destroy raw bindings and close
custom views before they are no longer needed. Manager teardown closes tracked
`OvPhysxView` instances before releasing the runtime, but explicit cleanup
avoids retaining their bindings for the rest of a long-lived simulation.

### Authoritative references

The generated Isaac Lab reference for
[OvPhysxView](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/api/lab_ov/isaaclab_ov.sim.views.html#isaaclab_ov.sim.views.OvPhysxView) documents the convenience
view. The repository metadata pins OvPhysX to a version but does not provide
a versioned official OvPhysX documentation URL, so inspect the installed
`TensorType` and binding metadata at runtime.

## Where to go next

* [/source/isaaclab/environments](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/isaaclab/environments.html) — tasks and backend presets.
* [Backend architecture](/isaaclab/3.0/concepts/backends-and-presets#backend-architecture) — shared factories and resource ownership.
* [/source/concepts/scene_data_providers](/isaaclab/3.0/concepts/scene-data-provider) — shared scene data for renderers and visualizers.