Metadata-Version: 2.5
Name: ovnewton
Version: 0.2.1
Summary: Connect the Newton physics engine to ovstage / the Omniverse library ecosystem.
Project-URL: Repository, https://github.com/NVIDIA-Omniverse/ovnewton
Project-URL: Documentation, https://nvidia-omniverse.github.io/ovnewton/
Project-URL: Issues, https://github.com/NVIDIA-Omniverse/ovnewton/issues
Author: NVIDIA CORPORATION & AFFILIATES
License-Expression: Apache-2.0
License-File: LICENSE.md
License-File: THIRD_PARTY_NOTICES.md
Requires-Python: <3.15,>=3.11
Requires-Dist: coacd>=1.0.7
Requires-Dist: fast-simplification>=0.1.13
Requires-Dist: newton-usd-schemas<0.6,>=0.5.0
Requires-Dist: newton>=1.7.0
Requires-Dist: numpy>=1.26.0; python_version < '3.13'
Requires-Dist: numpy>=2.1.0; python_version == '3.13'
Requires-Dist: numpy>=2.3.2; python_version >= '3.14'
Requires-Dist: ovstage==0.3.0.1791986420
Requires-Dist: physx-usd-schemas<26,>=25.11.1
Requires-Dist: scipy>=1.11.2; python_version < '3.13'
Requires-Dist: scipy>=1.14.1; python_version == '3.13'
Requires-Dist: scipy>=1.16.1; python_version >= '3.14'
Requires-Dist: warp-lang>=1.17.0
Provides-Extra: assets-audit
Requires-Dist: gitpython>=3.2.0; extra == 'assets-audit'
Provides-Extra: dev
Requires-Dist: newton[importers]>=1.7.0; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Provides-Extra: examples
Requires-Dist: newton[sim]>=1.7.0; extra == 'examples'
Requires-Dist: ovrtx<0.7,>=0.6.0.1791947691; extra == 'examples'
Requires-Dist: pillow>=13.0.0; extra == 'examples'
Requires-Dist: pyglet>=2.1; extra == 'examples'
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

# ovnewton

`ovnewton` connects the
[Newton](https://github.com/newton-physics/newton) physics engine with the
Omniverse library ecosystem.

> **Experimental:** `ovnewton` is currently experimental. Its API and
> packaging may change before version 1.0.

## Overview

`ovnewton` builds Newton models from scenes populated in ovstage. The application owns the Newton solver and simulation loop. A binding publishes simulation state to the stage, applies sealed stage updates to Newton, or exposes selected Newton outputs without publishing.

Use `add_ovstage()` to populate an application-owned builder, or `attach_ovstage(stage)` to create and finalize the model automatically.

```text
USD ──ovpopulation──▶ ovstage ──ovnewton──▶ Newton
                          ▲                    │
                          └── simulation state ┘
```

Newton does not parse the USD file in this workflow.

## Requirements

- Python 3.11 through 3.14
- Linux on x86-64 and aarch64 for non-rendering workflows
- CPU or NVIDIA CUDA GPU for supported non-rendering workflows
- A compatible NVIDIA RTX-capable GPU and supported driver for OVRTX rendering, even when physics runs on the CPU

Package installation resolves the required dependencies. Detailed version requirements are in the [support guide](https://github.com/NVIDIA-Omniverse/ovnewton/blob/main/docs/site/support.md).

## Installation

Install the current public release of `ovnewton` and its runtime dependencies
from PyPI:

```bash
pip install ovnewton
```

Run the installed example without rendering:

```bash
python -m ovnewton.examples.example_ovnewton_basic --device cpu --no-render
```

The example loads the `scene_rigid_bodies.usda` scene included in the ovnewton wheel. Install the `examples` extra for ovrtx rendering and MuJoCo-Warp:

```bash
pip install "ovnewton[examples]"
python -m ovnewton.examples.example_ovnewton_basic
```

The same example can build the scene through ovnewton and advance it with the
MuJoCo-Warp or VBD backend on CUDA or CPU:

```bash
python -m ovnewton.examples.example_ovnewton_basic --solver mujoco
python -m ovnewton.examples.example_ovnewton_basic --solver vbd
```

The simulation runs on `cuda:0` by default. Pass `--device cpu` to simulate on the CPU. The wheel also includes a complete cartpole scene:

```bash
python -m ovnewton.examples.example_ovnewton_basic --stage scene_cartpole
```

To watch several Ant robots from Newton's installed assets fall onto a ground plane:

```bash
python -m ovnewton.examples.example_ovnewton_robot
```

## Quickstart

The USD scene in this example is supplied by the application.

`ovnewton.population_desc()` selects physics data and preserves composed schema
names. Combine it with a rendering descriptor as shown below.

```python
import newton
import ovnewton
import ovstage
from ovstage import PopulationDomain, population

scene_path = "/path/to/scene.usd"

ovnewton.register_usd_schemas()
stage = ovstage.Stage()
population.open_usd_with_desc(
    stage,
    scene_path,
    ordinal=1,
    time=population.DEFAULT_TIME,
    descs=(population.Desc(domains=PopulationDomain.RENDERING), ovnewton.population_desc()),
)
stage.advance_write_floor(1).wait()

builder = newton.ModelBuilder()
import_result = ovnewton.add_ovstage(builder, stage)
model = builder.finalize(skip_validation_joints=import_result.has_orphan_joints)
solver = newton.solvers.SolverXPBD(model)
binding = ovnewton.attach_ovstage(stage, model=model)
state_0 = model.state()
state_1 = model.state()
newton.eval_fk(model, model.joint_q, model.joint_qd, state_0)
control = model.control()
collision_pipeline = newton.CollisionPipeline(model)
contacts = collision_pipeline.contacts()

dt = 1.0 / 60.0
state_0.clear_forces()
collision_pipeline.collide(state_0, contacts)
solver.step(state_0, state_1, control, contacts, dt)

binding.update_to_ovstage(state_1, ordinal=2)
stage.advance_write_floor(2).wait()
```

Call `binding.update_from_ovstage(state, control)` when you intend to resynchronize
all supported state and drive targets from the sealed stage. This can overwrite
live simulation state with older stage values. To update only
joint targets while preserving live simulation state, pass
`attributes=("jointPositionTarget", "jointVelocityTarget")`. The same selector
supports body pose/velocity and single-DOF joint state; see the getting-started
guide for the field list and synchronization semantics. Use
`binding.query()` and `binding.read()` to expose selected read-only Newton state
without publishing it.

See the [getting-started guide](https://github.com/NVIDIA-Omniverse/ovnewton/blob/main/docs/site/getting-started.md) for the full simulation loop and MuJoCo/VBD model preparation.

## Supported features and limits

`ovnewton` supports rigid bodies, articulations, primitive and mesh colliders, physics materials, collision filtering, and a limited subset of surface-cloth inputs. Applications can synchronize state with ovstage and read selected Newton outputs on CPU or CUDA.

Physics instancing, Newton actuators, cables and volume deformables are not supported. Joint-state updates, material bindings and cloth inputs have additional restrictions; see the [support guide](https://github.com/NVIDIA-Omniverse/ovnewton/blob/main/docs/site/support.md) for the full list.

Malformed data and unsupported physics that would materially change the model raise an error. Recoverable import decisions use the standard `ovnewton` Python logger; see the [concepts guide](https://github.com/NVIDIA-Omniverse/ovnewton/blob/main/docs/site/concepts.md#diagnostics-and-observability) for details.

## License

`ovnewton` is licensed under the
[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). The complete
license text is included in the distribution.

## Contributing

This project is currently not accepting contributions.
