using-ovnewton

name: using-ovnewtondescription: Connect the Newton physics engine to an Omniverse simulation or ovstage with ovnewton. Use when importing a populated ovstage into Newton, stepping its physics, synchronizing stage edits, or publishing simulation state for Omniverse rendering.license: Apache-2.0metadata:   author: Jan Carius <jcarius@nvidia.com>

Using ovnewton

Use ovnewton for the Newton ↔ ovstage bridge. The application owns model finalization, the solver, controls, collision handling, and the simulation loop. ovnewton reads a populated ovstage; Newton does not parse USD in this workflow. Standalone Newton simulations and generic Omniverse authoring do not need this skill.

Start from the supported examples

Install ovnewton in the application's environment. This workflow requires Newton 1.7 or newer, OVStage 0.3, and OVRTX 0.6 when rendering. Let its package metadata select compatible dependencies; do not replace the qualified ovstage dependency with an arbitrary build.

pip install ovnewton
python -m ovnewton.examples.example_ovnewton_basic --device cpu --no-render --num-frames 8

For rendering or MuJoCo-Warp, install "ovnewton[examples]". The basic example accepts --solver mujoco or --solver vbd; VBD also supports CPU simulation. Rendering needs a supported NVIDIA GPU and its own device selection.

Read the getting-started guide and adapt the basic example. For multiple robots, use the robot example. Use documentation and examples corresponding to the installed ovnewton release; repository main may describe a newer API.

Construct and bind the simulation

1. Call ovnewton.register_usd_schemas() before the first USD schema read. Create an ovstage.Stage() and populate the application-supplied USD with population.open_usd_with_desc(stage, scene_path, ordinal=1, time=population.DEFAULT_TIME, descs=(ovnewton.population_desc(),)). Add a population.Desc(domains=PopulationDomain.RENDERING) descriptor when rendering. ovnewton.population_desc() preserves composed schema names so unsupported physics remains detectable even without its schema plugin. Seal population with stage.advance_write_floor(1).wait() before importing. For rendering, create stages with ovstage.StageConfig selecting runtime_default_hierarchy_computation_model=ovstage.HierarchyComputationModel.GPU_INCREMENTAL, including CPU physics with a GPU renderer. This setting is process-wide; coexisting stages must use a consistent configuration. CPU-only runs do not need this setting. An existing populated stage must preserve the same composed schema metadata; attachment cannot recover schema names discarded during population. If the application already supplies a populated stage, reuse it and its sealed ordinal; do not reload the scene or assume its ordinal is 1.
2. Create an empty newton.ModelBuilder(). Configure defaults and register any solver-owned custom attributes before calling ovnewton.add_ovstage(builder, stage, ordinal=population_ordinal). Compose all scene assets into one ovstage first: this entry point currently requires a builder without model entities and supports one stage per builder.
3. For MuJoCo, register SolverMuJoCo.register_custom_attributes(builder) before calling ovnewton.add_ovstage(). For rigid-body VBD, register SolverVBD.register_custom_attributes(builder) before ovnewton.add_ovstage() and call builder.color() after that import, before finalization. Use SolverVBD(model, rigid_compliant_alm=True) for compliant rigid-body contacts, following the example's solver settings and contact-material tuning.
4. Finalize with builder.finalize(skip_validation_joints=import_result.has_orphan_joints), where import_result is the result of add_ovstage. Construct the solver and bind with ovnewton.attach_ovstage(stage, model=model, ordinal=population_ordinal). attach_ovstage(stage) is the convenience path when no builder customization is needed. When binding an existing model, body and joint labels must match stage paths.

Step and synchronize

Allocate two model states, controls, and contacts. Each substep clears forces, computes contacts, calls the solver, and swaps the states. Start from the example's collision pipeline and solver configuration rather than assuming every solver has identical preparation requirements.

After stepping, publish the current state with binding.update_to_ovstage(state, ordinal=output_ordinal), then seal it with stage.advance_write_floor(output_ordinal).wait(). Coordinate increasing write ordinals with the application's other stage writers.

To consume application edits, seal them first and call binding.update_from_ovstage(state, control) before stepping, using the same control passed to the solver. This reads the latest sealed supported state and drive-target fields. An explicit read ordinal is a consistency ceiling, not historical playback. Selected Newton-native output can instead be read through binding.query() and binding.read() without stage publication.

For rendering, publish and seal Newton output before the renderer consumes the stage. Newton's simulation device and OVRTX's rendering device are independent; follow the example's synchronization and device-selection options.

Check the support guide before promising support for authored physics. Unsupported physics may fail attachment; do not silently replace it with a different physical model. See the concepts guide and output-read guide for synchronization, diagnostics, read layouts, and lifetimes.