Python guide and API reference#

class isaacsim.physics_engines.ovnewton.NewtonConfig(
use_cuda_graph: bool = True,
auto_switch_on_startup: bool = True,
default_steps_per_second: int = 60,
solver: SolverConfig | None = None,
device: str | None = None,
)#

Configure the Newton physics backend.

Only default_steps_per_second and device affect backend behavior. The remaining integration options do not affect stage construction or stepping.

Parameters:
  • use_cuda_graph – Whether an integration should request CUDA-graph capture.

  • auto_switch_on_startup – Whether a carrier application should request Newton activation after registration.

  • default_steps_per_second – Simulation frequency reported through the registration callbacks.

  • solver – Requested solver settings, or None to create the default settings.

  • device – Warp device used while ovnewton finalizes the Newton model, or None to use Newton’s process default.

auto_switch_on_startup: bool = True#
default_steps_per_second: int = 60#
device: str | None = None#
solver: SolverConfig | None = None#
use_cuda_graph: bool = True#
class isaacsim.physics_engines.ovnewton.NewtonSimulationRegistry(
config: NewtonConfig | None = None,
simulation_name: str | None = None,
)#

Manage a Newton stage and its registered simulation callbacks.

Parameters:
  • config – Newton backend configuration. Defaults are used when omitted.

  • simulation_name – Name used to register the simulation.

register() → SimulationId#

Register the Newton simulation callbacks.

Returns:

The assigned simulation identifier.

Raises:

RuntimeError – If the registration API rejects the simulation.

unregister() → None#

Unregister the simulation if it is registered.

class isaacsim.physics_engines.ovnewton.NewtonStage(
config: NewtonConfig | None = None,
)#

Manage Newton-engine state for a single attached ovstage.

Parameters:

config – Backend configuration, or None to use the default configuration.

Lifecycle:
  1. Constructor receives an optional NewtonConfig.

  2. initialize() borrows a caller-owned ovstage, builds a Newton model via ovnewton.attach_ovstage, and creates solver state.

  3. Subsequent calls to simulate() advance time.

  4. on_detach() / close() clear the attachment and mark the stage uninitialized.

check_results() → bool#

Check whether synchronous simulation results are ready.

Returns:

Always True because the backend completes work synchronously.

close() → None#

Detach the stage and mark the simulation uninitialized.

fetch_results() → None#

Dispatch an empty compatibility contact report to subscribers.

Newton tensor views expose contact data directly. This callback notifies subscribers with empty header, contact-data, and friction-anchor collections.

flush_changes() → None#

Accept a request to flush pending changes.

The Newton backend applies no deferred modifications.

force_load_physics_from_usd() → None#

Rebuild physics state from the currently borrowed ovstage.

get_attached_stage() → int#

Get the attached USD stage identifier.

Returns:

Attached stage identifier, or zero when no stage is attached.

get_body_position(
prim_path: str,
) → tuple[float, float, float] | None#

Get the latest position of a Newton rigid body.

Parameters:

prim_path – USD prim path used to identify the body.

Returns:

World-space position when the body and current state are available, otherwise None.

has_attached_stage() → bool#

Report whether a caller-owned ovstage is still borrowed.

Distinguishes a retained ovstage (including StageCache id 0) from a fully detached backend. Required after a failed initialize that keeps _ovstage so start_simulation can retry: the manager uses this signal for InitializeResult::eFailedDirty and owner keepalive.

Returns:

True when a borrowed ovstage reference is held, otherwise False.

initialize(
ovstage_obj: Any | None,
stage_id: int = 0,
) → bool#

Borrow an ovstage and build the Newton model through ovnewton.

Parameters:
  • ovstage_obj – Caller-owned ovstage.Stage, or None for an empty scene.

  • stage_id – Numeric identifier republished through get_attached_stage().

Returns:

True when initialization completes, including an empty stage or unavailable optional dependencies. Returns False when model construction raises an exception or a required Stage object is missing.

is_capable_of_simulating(
schema_names: list[str],
) → tuple[bool, list[bool]]#

Check support for requested USD physics schemas.

Newton advertises rigid-body and articulation support. Soft-body, fluid, cloth, and vehicle schemas are unsupported.

Parameters:

schema_names – Schema type names to query.

Returns:

A successful-query flag and one support flag per requested schema.

is_change_tracking_paused() → bool#

Check whether change tracking is paused.

Returns:

True when change tracking is paused.

list_body_paths() → list[str]#

Get the USD prim paths parsed as Newton bodies.

Returns:

Body prim paths in parser-defined order.

on_attach(stage_id: int) → bool#

Record the USD identifier republished for get_attached_stage.

Parameters:

stage_id – Numeric identifier supplied by the physics manager.

Returns:

True when the nonzero identifier is accepted, otherwise False.

on_detach() → None#

Detach the backend from its current ovstage.

on_pause() → None#

Record a simulation-pause event.

on_reset() → None#

Reset the simulation timestamp and step count.

on_resume(current_time: float) → None#

Record a simulation-resume event.

Parameters:

current_time – Simulation time at resume.

on_update(
current_time: float,
elapsed_secs: float,
enable_update: bool,
) → None#

Advance the backend for an enabled update.

Parameters:
  • current_time – Current simulation time.

  • elapsed_secs – Duration of the update in seconds.

  • enable_update – Whether this update should advance simulation.

pause_change_tracking(pause: bool) → None#

Set whether change tracking is paused.

Parameters:

pause – True to pause change tracking, or False to resume it.

release_physics_objects() → None#

Drop the ovnewton binding and derived Newton simulation objects.

reset_simulation() → None#

Clear physics objects, counters, and initialization state.

simulate(elapsed_time: float, current_time: float) → None#

Advance the simulation and fetch synchronous results.

Parameters:
  • elapsed_time – Duration of the simulation step in seconds.

  • current_time – Current simulation time supplied to the backend.

simulate_async(
elapsed_time: float,
current_time: float,
) → None#

Advance the simulation and notify pre-step and post-step subscribers.

Pre-step subscribers run before the solver and post-step subscribers run afterward. Subscribers within each phase run by ascending order value. A solver failure leaves the step counters unchanged.

Parameters:
  • elapsed_time – Duration of the simulation step in seconds.

  • current_time – Current simulation time supplied to the backend.

start_simulation() → None#

Initialize the attached ovstage when simulation has not started.

subscribe_contact_report(
callback: Callable[[Any, Any, Any], Any],
) → int#

Subscribe to contact-report notifications.

Parameters:

callback – Function invoked with contact headers, contact data, and friction-anchor data.

Returns:

Identifier used to remove the subscription.

subscribe_step_event(
pre_step: bool,
order: int,
callback: Callable[[float, Any], Any],
) → int#

Subscribe to simulation-step notifications.

Parameters:
  • pre_step – True to invoke the callback before the solver step, or False to invoke it afterward.

  • order – Ordering value within the selected step phase.

  • callback – Function invoked with the step duration and physics-step context.

Returns:

Identifier used to remove the subscription.

unsubscribe_contact_report(subscription_id: int) → None#

Remove a contact-report subscription.

Parameters:

subscription_id – Identifier returned by subscribe_contact_report().

unsubscribe_step_event(subscription_id: int) → None#

Remove a simulation-step subscription.

Parameters:

subscription_id – Identifier returned by subscribe_step_event().

property binding: Any | None#

Get the ovnewton stage binding.

Returns:

Active ovnewton.StageBinding, or None before construction or for an empty stage.

property contacts: Any | None#

Get the Newton contact buffer.

Returns:

Contact buffer after successful model construction, or None when no model is available.

property control: Any | None#

Get the Newton control buffer.

Returns:

Control buffer after successful model construction, or None when no model is available.

property device: Any#

Get the device used by the Newton model.

Returns:

Model device when available, otherwise the Warp CPU device. If Warp is unavailable, returns "cpu".

property initialized: bool#

Check whether initialization has completed.

Returns:

True after an initialization attempt completes, including an empty-stage initialization.

property last_step_failed: bool#

Check whether the most recent solver step failed.

Returns:

True when the most recent attempted solver step raised an exception.

property model: Any | None#

Get the Newton model.

Returns:

Newton model after successful model construction, or None before construction or for an empty stage.

property ovstage: Any | None#

Get the borrowed caller-owned ovstage.

Returns:

Attached ovstage Stage, or None when no stage is attached.

property solver: Any | None#

Get the Newton solver.

Returns:

Solver after successful model construction, or None when no model is available.

property solver_is_maximal: bool#

Check whether the active solver uses maximal coordinates.

Returns:

True when the active solver advances maximal-coordinate state.

property state_0: Any | None#

Get the current Newton simulation state.

Returns:

Current Newton state after successful model construction, or None when no model is available.

property state_1: Any | None#

Get the scratch Newton simulation state.

Returns:

Scratch Newton state after successful model construction, or None when no model is available.

property step_count: int#

Get the number of completed simulation steps.

Returns:

Number of initialized step callbacks that did not encounter a solver error since attachment or reset.

property timestamp: int#

Get the simulation timestamp.

Returns:

Backend timestamp incremented once per initialized step callback that does not encounter a solver error.

property usd_stage: Any | None#

Get an optional pxr USD stage for tensor path queries.

When usd_identifier resolves through the StageCache, tensor views use this stage for prim-path pattern matching. Physics model construction always comes from the borrowed ovstage.

Returns:

Cached USD stage, or None when no StageCache entry is available.

isaacsim.physics_engines.ovnewton.get_registry(
simulation_id: SimulationId | int,
) → NewtonSimulationRegistry | None#

Look up an active Newton registry by simulation identifier.

Parameters:

simulation_id – Registered simulation identifier or its integer payload.

Returns:

Active registry for the identifier, or None when the simulation is not registered.

isaacsim.physics_engines.ovnewton.register(
config: NewtonConfig | None = None,
simulation_name: str | None = None,
) → SimulationId#

Create and register a Newton simulation.

Parameters:
  • config – Newton backend configuration.

  • simulation_name – Name to register the simulation and its tensor factories under. Pass a distinct name per simulation to run several at once; omit it for a single simulation under the default name.

Returns:

The assigned simulation identifier. Pass it to unregister().

Raises:

RuntimeError – If the physics registration API rejects the simulation.

isaacsim.physics_engines.ovnewton.unregister(
simulation_id: SimulationId | int,
) → None#

Unregister a Newton simulation.

Parameters:

simulation_id – Registered simulation identifier or its integer payload.