isaaclab_newton.physics

Implementation backends for simulation interfaces.

Classes

NewtonManager	Abstract Newton physics manager for Isaac Lab.
NewtonCfg	Configuration for Newton physics manager.
NewtonSoftContactCfg	Global soft-contact parameters applied to the finalized Newton model.
NewtonCollisionPipelineCfg	Configuration for Newton collision pipeline.
NewtonFeatherstoneManager	NewtonManager specialization for the Featherstone solver.
NewtonKaminoManager	NewtonManager specialization for the Kamino solver.
NewtonMPMManager	NewtonManager specialization for Newton's implicit MPM solver.
NewtonMJWarpManager	NewtonManager specialization for the MuJoCo Warp solver.
NewtonVBDManager	Newton manager specialization for the VBD solver.
NewtonShapeCfg	Default per-shape collision properties applied to all shapes in a Newton scene.
NewtonSolverCfg	Configuration for Newton solver-related parameters.
NewtonXPBDManager	NewtonManager specialization for the XPBD solver.
MJWarpSolverCfg	Configuration for MuJoCo Warp solver-related parameters.
VBDSolverCfg	Configuration for the Vertex Block Descent solver.
XPBDSolverCfg	An implicit integrator using eXtended Position-Based Dynamics (XPBD) for rigid and soft body simulation.
FeatherstoneSolverCfg	A semi-implicit integrator using symplectic Euler.
KaminoCollisionDetectorCfg	Internal Kamino collision-detector parameters.
KaminoConstraintsCfg	Global constraint stabilization parameters for Kamino.
KaminoDVICfg	DVI forward-dynamics solver parameters for Kamino.
KaminoDVISolverCfg	Configuration for Kamino with the DVI forward-dynamics solver.
KaminoDynamicsCfg	Constrained forward-dynamics problem parameters for Kamino.
KaminoFKCfg	Forward-kinematics reset solver parameters for Kamino.
KaminoMaterialsCfg	Material mixing parameters for Kamino contacts.
KaminoPADMMCfg	P-ADMM forward-dynamics solver parameters for Kamino.
KaminoPADMMSolverCfg	Configuration for Kamino with the P-ADMM forward-dynamics solver.
MPMSolverCfg	Configuration for Newton's implicit Material Point Method (MPM) solver.
HydroelasticSDFCfg	Configuration for SDF-based hydroelastic collision handling.

Physics Manager

class isaaclab_newton.physics.NewtonManager

Bases: PhysicsManager

Abstract Newton physics manager for Isaac Lab.

Class-level (singleton-like) manager that owns simulation lifecycle, model state, contacts/collision pipeline, sensors, replication, and CUDA-graph orchestration. Concrete subclasses (one per solver) implement _build_solver() and may extend _initialize_contacts(), _prepare_builder_for_finalize(), _step_solver(), _supports_cuda_graph_capture(), _requires_initial_reset_before_graph_capture(), _reset_solver_internals(), _solver_specific_clear(), _check_solver_status(), and _log_solver_debug().

Subclasses are selected via NewtonSolverCfg.class_type, which NewtonCfg.__post_init__() propagates onto NewtonCfg.class_type so that SimulationContext resolves the matching subclass automatically.

Lifecycle: initialize() -> reset() -> step() (repeated) -> close().

Note

Shared state lives on NewtonManager (the base) by design — the framework imports NewtonManager directly and reads attributes such as _model / _state_0 / _builder from many places. Lifecycle methods therefore assign through the explicit base class (NewtonManager._foo = ...) rather than through cls so that the canonical state remains discoverable from external readers regardless of which subclass is active.

Methods:

initialize(sim_context)	Initialize the manager with simulation context.
reset([soft])	Reset physics simulation.
forward()	Update articulation kinematics without stepping physics.
video_capture_backend()	Newton GL headless perspective video capture.
pre_render()	Refresh derived Newton state before cameras and visualizers read it.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
sync_cables_to_usd()	Write Newton cable segment endpoints to Fabric curve points.
sync_particles_to_usd()	Write Newton particle positions to USD/Fabric for Kit viewport rendering.
register_particle_visual_prim(prim_path, ...)	Register a UsdGeom.Points prim whose points mirror a slice of Newton's particle state.
step()	Step the physics simulation.
close()	Clean up Newton physics resources.
get_scene_data_backend()	Return the SceneDataBackend for the SceneDataProvider.
register_callback(callback, event[, order, ...])	Register a callback.
get_physics_sim_view()	Get the list of registered views.
is_fabric_enabled()	Check if fabric interface is enabled (not applicable for Newton).
clear()	Clear all Newton-specific state (callbacks cleared by super().close()).
set_builder(builder)	Set the Newton model builder.
create_builder([up_axis])	Create a ModelBuilder configured with default settings.
cl_register_site(body_pattern, xform, *[, ...])	Register a site request for injection into prototypes before replication.
request_extended_state_attribute(attr)	Request an extended state attribute (e.g. "body_qdd").
request_extended_contact_attribute(attr)	Request an extended contact attribute (e.g. "force").
add_model_change(change)	Register a model change to notify the solver.
invalidate_fk([env_mask, env_ids, ...])	Mark environments as needing FK recomputation and solver reset.
invalidate_body_state([env_ids, env_mask])	Mark selected maximal-coordinate body state as changed without requesting FK.
start_simulation()	Start simulation by finalizing model and initializing state.
instantiate_builder_from_stage()	Create builder from USD stage.
initialize_solver()	Initialize the solver and collision pipeline.
get_model()	Get the Newton model.
get_state_0()	Get the current state.
get_state([scene_data_provider])	Get the current Newton state for visualization.
get_contacts()	Get the current Newton contact buffer, if the active solver exposes one.
get_scene_data_provider()	Return the active scene data provider.
update_visualization_state([scene_data_provider])	Refresh visualization state for the active sim backend.
get_state_1()	Get the next state.
get_control()	Get the control object.
get_dt()	Get the physics timestep.
get_solver_dt()	Get the solver substep timestep.
activate_newton_actuator_path()	Opt an articulation into the Newton actuator fast path.
register_post_actuator_callback(callback)	Append a hook to the list invoked after the actuator step on every iteration.
register_state_force_callback(callback)	Register a graph-safe callback that applies forces before every solver substep.
register_post_step_callback(callback)	Append a hook to the list invoked after the last solver substep on every step.
unregister_post_step_callback(callback)	Remove a previously registered post-step callback.
set_decimation(decimation)	Set the decimation count and re-capture the CUDA graph.
handles_decimation()	True when step() executes the full decimation loop internally.
add_contact_sensor([body_names_expr, ...])	Add a contact sensor for reporting contacts between bodies/shapes.
add_frame_transform_sensor(shapes, ...)	Add a frame transform sensor for measuring relative transforms.
after_visualizers_render()	Hook after visualizers have stepped during render().
clear_callbacks()	Remove all registered callbacks.
deregister_callback(callback_id)	Remove a registered callback.
dispatch_event(event[, payload])	Dispatch an event to all registered callbacks.
fix_articulation_root(articulation_prim[, stage])	Ensure that an articulation root has one enabled world fixed joint.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
get_device()	Get the physics simulation device.
get_physics_dt()	Get the physics timestep in seconds.
get_simulation_time()	Get the current simulation time in seconds.
pause()	Pause physics simulation.
play()	Start or resume physics simulation.
safe_callback_invoke(fn, *args[, ...])	Invoke a callback, catching exceptions that would be swallowed by external event buses.
stop()	Stop physics simulation.
wait_for_playing()	Block until the timeline is playing.
add_imu_sensor(sites)	Add an IMU sensor for measuring acceleration and angular velocity at sites.

classmethod initialize(sim_context: SimulationContext) → None

Initialize the manager with simulation context.

Parameters:

sim_context – Parent simulation context.

classmethod reset(soft: bool = False) → None

Reset physics simulation.

A hard reset (soft=False) re-finalizes the Newton model, reallocating its device arrays. The cached collision pipeline, contacts and any captured CUDA graph reference the old buffers, so they are released here and rebuilt against the re-finalized model by initialize_solver(). This avoids the illegal CUDA memory access (CUDA error 700) that would otherwise occur on the first step after a hard reset.

A soft reset (soft=True) skips this full reinitialization and reuses the existing model, solver, collision pipeline and CUDA graph.

Parameters:

soft – If True, skip full reinitialization.

classmethod forward() → None

Update articulation kinematics without stepping physics.

Update body poses from joint coordinates via the solver-specialized FK delegate (_eval_fk, bound to the active subclass’s _eval_fk_impl() in initialize_solver()). Only the articulations flagged dirty in _fk_reset_mask and _world_reset_mask (see invalidate_fk()) are updated. The masks are consumed (zeroed) afterwards so the next step() does not redundantly re-solve them.

The delegate (rather than a direct cls._eval_fk_impl call) is required because the data layer invokes NewtonManager.forward() on the base class, where cls is the base NewtonManager; the bound delegate dispatches to the concrete subclass override.

classmethod video_capture_backend() → str

Newton GL headless perspective video capture.

classmethod pre_render() → None

Refresh derived Newton state before cameras and visualizers read it.

classmethod sync_transforms_to_usd() → None

Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.

No-op when _usdrt_stage is None (i.e. Kit visualizer is not active) or when transforms have not changed since the last sync.

Called at render cadence by pre_render() (via render()). Physics stepping marks transforms dirty via _mark_transforms_dirty() so that the expensive Fabric hierarchy update only runs once per render frame rather than after every physics step.

Uses wp.fabricarray directly (no isaacsim.physics.newton extension needed). The Warp kernel reads state_0.body_q[newton_index[i]] and writes the corresponding mat44d to omni:fabric:worldMatrix for each prim.

When IFabricHierarchy.update_world_xforms_gpu_with_options is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then run the GPU hierarchy update with RIGID_BODY | FORCE_UPDATE so Newton-authored world matrices stay authoritative on rigid-body prims. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod sync_cables_to_usd() → None

Write Newton cable segment endpoints to Fabric curve points.

classmethod sync_particles_to_usd() → None

Write Newton particle positions to USD/Fabric for Kit viewport rendering.

Two prim families are synced from state_0.particle_q:

• Fabric mesh prims tagged with newton:particleOffset / newton:particleCount (deformable visual meshes) receive local-frame points on the GPU via _sync_fabric_mesh_particles().

• UsdGeom.Points prims registered through register_particle_visual_prim() (MPM particle clouds) receive world-frame points via _sync_particle_points_prims().

No-op when there is no particle state or nothing changed since the last sync.

classmethod register_particle_visual_prim(prim_path: str, particle_offset: int, particle_count: int, sync_frequency: int = 1) → None

Register a UsdGeom.Points prim whose points mirror a slice of Newton’s particle state.

Parameters:

• prim_path – Stage path of an existing UsdGeom.Points prim.

• particle_offset – First index of the prim’s slice in state.particle_q.

• particle_count – Number of particles in the slice.

• sync_frequency – Sync the prim every N dirty render frames.

classmethod step() → None

Step the physics simulation.

The stepping logic follows one of two paths depending on whether all actuators are CUDA-graph-safe:

All-graphable path (_simulate_full()):

Actuators and solver substeps are captured together in a single CUDA graph containing the full decimation x (actuators + solver substeps) loop.

Eager-actuator path (fallback, some actuators not graph-safe):

Actuators are stepped eagerly on the CPU timeline (outside the graph), then a graph containing only the solver substeps is launched via _simulate_physics_only().

In both paths the sequence within one physics step is:

zero actuated DOFs in control.joint_f
-> actuator.step (computes effort, writes to control.joint_f)
-> solver.step x num_substeps (integrates, reads control.joint_f)
-> sensors.update

classmethod close() → None

Clean up Newton physics resources.

classmethod get_scene_data_backend() → SceneDataBackend | None

Return the SceneDataBackend for the SceneDataProvider.

classmethod register_callback(callback: Callable, event: PhysicsEvent, order: int = 0, name: str | None = None, wrap_weak_ref: bool = True) → CallbackHandle

Register a callback. Passes event to parent class.

classmethod get_physics_sim_view() → list

Get the list of registered views.

Assets can append their views to this list, and sensors can access them. Returns a list that callers can append to.

Returns:

List of registered views (e.g., NewtonArticulationView instances).

classmethod is_fabric_enabled() → bool

Check if fabric interface is enabled (not applicable for Newton).

classmethod clear()

Clear all Newton-specific state (callbacks cleared by super().close()).

classmethod set_builder(builder: newton.ModelBuilder) → None

Set the Newton model builder.

classmethod create_builder(up_axis: str | None = None, **kwargs) → newton.ModelBuilder

Create a ModelBuilder configured with default settings.

Forwards NewtonShapeCfg defaults onto Newton’s upstream ModelBuilder.default_shape_cfg via checked_apply(). Falls back to wrapper defaults when no Newton config is active so rough-terrain margin/gap still apply during early construction.

Parameters:

• up_axis – Override for the up-axis. Defaults to None, which uses the manager’s _up_axis.

• **kwargs – Forwarded to ModelBuilder.

Returns:

New builder with up-axis and per-shape defaults (gap, margin) applied.

classmethod cl_register_site(body_pattern: str | None, xform: warp.transform, *, per_world: bool = False) → str

Register a site request for injection into prototypes before replication.

Sensors call this during __init__. Sites are injected into prototype builders by _cl_inject_sites() (called from newton_replicate) before add_builder, so they replicate correctly per-world.

Identical (body_pattern, per_world, transform) registrations share sites.

The body_pattern is matched against prototype-local body labels (e.g. "Robot/link.*") when replication is active, or against the flat builder’s body labels in the fallback path. Wildcard patterns that match multiple bodies create one site per matched body.

Parameters:

• body_pattern – Regex pattern matched against body labels in the prototype builder (e.g. "Robot/link0" or "Robot/finger.*" for multi-body wildcards), or None for global sites (world-origin reference, etc.).

• xform – Site transform relative to body.

• per_world – When True, body_pattern must be None and one bodyless site is created in each cloned world’s frame.

Returns:

Assigned site label suffix.

classmethod request_extended_state_attribute(attr: str) → None

Request an extended state attribute (e.g. "body_qdd").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the builder in start_simulation() so that subsequent model.state() calls allocate them.

Parameters:

attr – State attribute name (must be in State.EXTENDED_ATTRIBUTES).

classmethod request_extended_contact_attribute(attr: str) → None

Request an extended contact attribute (e.g. "force").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the model in start_simulation() so that subsequent Contacts creation includes them.

Parameters:

attr – Contact attribute name.

classmethod add_model_change(change: newton.ModelFlags) → None

Register a model change to notify the solver.

classmethod invalidate_fk(env_mask: wp.array | None = None, env_ids: wp.array | None = None, articulation_ids: wp.array | None = None) → None

Mark environments as needing FK recomputation and solver reset.

Called by asset write methods that modify joint coordinates or root transforms. The masks are consumed by the next forward, raw-state, rendering, or physics-step boundary.

Parameters:

• env_mask – Boolean mask of dirtied environments. Shape (num_envs,). Used by _mask write methods.

• env_ids – Integer indices of dirtied environments. Used by _index write methods.

• articulation_ids – Mapping from (world, arti) to model articulation index. Shape (world_count, count_per_world). Obtained from ArticulationView.articulation_ids.

classmethod invalidate_body_state(env_ids: wp.array(dtype=wp.int32) | None = None, env_mask: wp.array(dtype=wp.bool) | None = None) → None

Mark selected maximal-coordinate body state as changed without requesting FK.

Parameters:

• env_ids – Integer indices of dirtied environments. Used by index write methods.

• env_mask – Boolean mask of dirtied environments. Used by mask write methods.

classmethod start_simulation() → None

Start simulation by finalizing model and initializing state.

This function finalizes the model and initializes the simulation state. Note: Collision pipeline is initialized later in initialize_solver() after we determine whether the solver needs external collision detection.

classmethod instantiate_builder_from_stage()

Create builder from USD stage.

Detects env Xforms (e.g. /World/Env_0, /World/Env_1) and builds each as a separate Newton world via begin_world/end_world. Falls back to a flat add_usd when no env Xforms are found.

classmethod initialize_solver() → None

Initialize the solver and collision pipeline.

Thin orchestrator: delegates solver construction to _build_solver() (overridden by each solver subclass), allocates the collision pipeline (when applicable) via _initialize_contacts(), then either captures the CUDA graph immediately or defers capture until the first step() call (RTX-active path).

Warning

When using a CUDA-enabled device, the simulation is graphed. This means the function steps the simulation once to capture the graph, so it should only be called after everything else in the simulation is initialized.

classmethod get_model() → newton.Model

Get the Newton model.

When the active sim backend is Newton this returns the manager’s own authoritative model. When the active sim backend is PhysX a shadow Newton model is built lazily (from the visualizer prebuilt artifact) so renderers/visualizers that operate on Newton Model and State can still drive a PhysX-simulated scene.

classmethod get_state_0() → newton.State

Get the current state.

classmethod get_state(scene_data_provider: SceneDataProvider | None = None) → newton.State

Get the current Newton state for visualization.

Use this method from visualizers/renderers/video recorders that need a backend-agnostic Newton State. When the sim backend is PhysX this refreshes the shadow _state_0.body_q from the live PhysX scene via update_visualization_state() before returning, so callers never observe stale transforms. Under the Newton sim backend, pending forward kinematics is applied before returning the live state.

classmethod get_contacts() → Contacts | None

Get the current Newton contact buffer, if the active solver exposes one.

classmethod get_scene_data_provider() → SceneDataProvider

Return the active scene data provider.

classmethod update_visualization_state(scene_data_provider: SceneDataProvider | None = None) → None

Refresh visualization state for the active sim backend.

Newton sim backend: no-op — _state_0 is the live, authoritative state already advanced by step() / forward kinematics.

PhysX / OVPhysX sim backend: pull rigid-body transforms and deformable nodal positions from the SceneDataProvider and write them into the shadow _state_0.body_q / particle_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses and mesh points.

Calls use allow_passthrough=False so identity mappings still copy into the pre-bound shadow buffers. Passthrough would rebind the temporary SceneDataFormat fields away from _state_0, leaving OVRTX and other get_state() consumers on stale rest-pose particle / body state.

Invoked lazily from get_state() so consumers do not need to coordinate the sync explicitly.

classmethod get_state_1() → newton.State

Get the next state.

classmethod get_control() → newton.Control

Get the control object.

classmethod get_dt() → float

Get the physics timestep. Alias for get_physics_dt().

classmethod get_solver_dt() → float

Get the solver substep timestep.

classmethod activate_newton_actuator_path() → None

Opt an articulation into the Newton actuator fast path.

Idempotent — called by every Newton-fast-path articulation’s _process_actuators_cfg:

1. Sets _use_newton_actuators_active, which _is_all_graphable() checks (adapter presence alone cannot distinguish the fast path from the standard Lab path).

2. On first call, builds the single sim-level NewtonActuatorAdapter over the full flat DOF layout; later calls reuse it.

classmethod register_post_actuator_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the actuator step on every iteration.

Each callback runs inside the captured CUDA graph (when _is_all_graphable() is True) right after NewtonActuatorAdapter.step() and before the solver substeps, so kernel writes to state/control are visible to the integrator on the same iteration. Multiple articulations register their own implicit-DOF telemetry / FF-routing kernels here; all registered callbacks fire in registration order each step.

classmethod register_state_force_callback(callback: Callable[[newton.State], None]) → None

Register a graph-safe callback that applies forces before every solver substep.

Callbacks must be registered before solver initialization so they are included in CUDA graph capture.

Parameters:

callback – Function that adds forces [N, N·m] to the provided state.

classmethod register_post_step_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the last solver substep on every step.

Each callback runs inside the stepped (and, when _is_all_graphable() is True, captured) region right after the final solver substep of the decimation loop and before _update_sensors(), so the launches it issues are recorded into every captured CUDA graph and replayed on each tick. The hook fires exactly once per step() call, reflecting the state after all decimation iterations (and their solver substeps) have completed – not once per substep and not once per decimation iteration. Callbacks must be graph-safe (fixed shapes, no host branching on device data) and must be registered before capture. Articulations with non-identity ordering register their backend-to-user state republish here; all registered callbacks fire in registration order each step.

classmethod unregister_post_step_callback(callback: Callable[[], None]) → None

Remove a previously registered post-step callback.

Symmetric to register_post_step_callback(), this lets an articulation deregister its republish hook when its callbacks are cleared so the bound method does not linger on the class-level list after the articulation is gone. Removing a callback that was never registered (or was already removed) is a safe no-op, matching the tolerant deregistration of other handles.

classmethod set_decimation(decimation: int) → None

Set the decimation count and re-capture the CUDA graph.

When all actuators are graphable the entire decimation loop (actuators + solver substeps, repeated decimation times) is captured as a single CUDA graph.

If a CUDA graph was previously captured, it is automatically re-captured with the new decimation count using the same strategy as start_simulation(): standard wp.ScopedCapture when no USDRT stage is active, or deferred relaxed capture when RTX is running. Solvers with reset-dependent topology may also defer standard capture.

classmethod handles_decimation() → bool

True when step() executes the full decimation loop internally.

This is the case when all Newton actuators are CUDA-graph-safe. The full decimation loop (including the trivial decimation=1 case) is folded into a single step() call.

classmethod add_contact_sensor(body_names_expr: str | list[str] | None = None, shape_names_expr: str | list[str] | None = None, contact_partners_body_expr: str | list[str] | None = None, contact_partners_shape_expr: str | list[str] | None = None, verbose: bool = False) → tuple[str | list[str] | None, str | list[str] | None, str | list[str] | None, str | list[str] | None]

Add a contact sensor for reporting contacts between bodies/shapes.

Converts Isaac Lab pattern conventions (.* regex, full USD paths) to fnmatch globs and delegates to newton.sensors.SensorContact.

Parameters:

• body_names_expr – Expression for body names to sense.

• shape_names_expr – Expression for shape names to sense.

• contact_partners_body_expr – Expression for contact partner body names.

• contact_partners_shape_expr – Expression for contact partner shape names.

• verbose – Print verbose information.

classmethod add_frame_transform_sensor(shapes: list[int], reference_sites: list[int]) → int

Add a frame transform sensor for measuring relative transforms.

Creates a SensorFrameTransform from pre-resolved shape and reference site indices, appends it to the internal list, and returns its index.

Parameters:

• shapes – Ordered list of shape indices to measure.

• reference_sites – 1:1 list of reference site indices (same length as shapes).

Returns:

Index of the newly created sensor in _newton_frame_transform_sensors.

classmethod after_visualizers_render() → None

Hook after visualizers have stepped during render().

Use for physics-backend sync (e.g. fabric) if needed. Default is a no-op.

classmethod clear_callbacks() → None

Remove all registered callbacks.

Do NOT reset _callback_id — handle IDs must remain monotonically unique across the lifetime of the process. Resetting the counter would let a future register_callback() hand out an ID that an old, still-alive CallbackHandle (e.g. on a sensor that has not been garbage-collected yet) holds, so when the old object eventually finalizes its __del__ would deregister the new callback. This bit ovphysx’s kitless multi-context tests where two InteractiveScene``s are created in sequence: the first scene's sensor would post-GC deregister the second scene's ``_initialize_callback by ID collision, leaving the second sensor forever uninitialized.

classmethod deregister_callback(callback_id: int | CallbackHandle) → None

Remove a registered callback.

Parameters:

callback_id – The ID or CallbackHandle returned by register_callback().

classmethod dispatch_event(event: PhysicsEvent, payload: Any = None) → None

Dispatch an event to all registered callbacks.

This is the default implementation using simple callback lists. Subclasses may override or extend with platform-specific dispatch.

Parameters:

• event – The event to dispatch.

• payload – Optional data to pass to callbacks.

classmethod fix_articulation_root(articulation_prim: Any, stage: Any = None) → Any

Ensure that an articulation root has one enabled world fixed joint.

The base implementation leaves the root in place. Backends whose parser requires a different root topology may relocate it and return the resulting root prim.

Parameters:

• articulation_prim – The articulation-root prim to fix.

• stage – The stage containing the prim. Defaults to the current stage.

Returns:

The articulation-root prim after backend normalization.

Raises:

NotImplementedError – If a new joint is needed and the root is not a rigid body.

classmethod get_backend() → str

Get the tensor backend being used (“numpy” or “torch”).

classmethod get_device() → str

Get the physics simulation device.

classmethod get_physics_dt() → float

Get the physics timestep in seconds.

classmethod get_simulation_time() → float

Get the current simulation time in seconds.

classmethod pause() → None

Pause physics simulation. Default is no-op.

classmethod play() → None

Start or resume physics simulation. Default is no-op.

static safe_callback_invoke(fn: Callable, *args, physics_manager: type[PhysicsManager] | None = None) → None

Invoke a callback, catching exceptions that would be swallowed by external event buses.

Ignores ReferenceError (from garbage-collected weakref proxies). All other exceptions are forwarded to physics_manager.``store_callback_exception`` when available (see note below), or re-raised immediately otherwise.

Note (Octi):

The carb event bus used by PhysX/Omniverse silently swallows exceptions raised inside callbacks. PhysxManager works around this by storing the exception and re-raising it after event dispatch completes (in reset() / step()). Backends that dispatch events directly (e.g. Newton) don’t need this — exceptions propagate normally — so store_callback_exception is not called for them. This is a known wart; a cleaner solution is actively being explored.

classmethod stop() → None

Stop physics simulation. Default is no-op.

classmethod wait_for_playing() → None

Block until the timeline is playing. Default is no-op.

classmethod add_imu_sensor(sites: list[int]) → int

Add an IMU sensor for measuring acceleration and angular velocity at sites.

Creates a newton.sensors.SensorIMU from pre-resolved site indices, appends it to the internal list, and returns its index.

Parameters:

sites – Ordered list of site indices (one per environment).

Returns:

Index of the newly created sensor in the internal IMU sensor list.

Physics Configuration

class isaaclab_newton.physics.NewtonCfg

Bases: PhysicsCfg

Configuration for Newton physics manager.

This configuration includes Newton-specific simulation settings and solver configuration.

The active NewtonManager subclass is determined by solver_cfg.class_type, which __post_init__() propagates to class_type so that SimulationContext resolves the right manager subclass automatically. User code keeps the existing two-level shape NewtonCfg(solver_cfg=...) and does not need to set class_type explicitly.

Attributes:

class_type	The class type of the NewtonManager.
num_substeps	Number of substeps to use for the solver.
collision_decimation	Re-collide every N solver substeps within a physics tick (0 = once per tick).
debug_mode	Whether to enable debug mode for the solver.
use_cuda_graph	Whether to use CUDA graphing when simulating.
deterministic_mode	Determinism guarantee applied to the Newton solver and collision pipeline.
solver_cfg	Solver configuration.
soft_contact_cfg	Global soft-contact parameters applied after model finalization.
collision_cfg	Newton collision pipeline configuration.
default_shape_cfg	Default per-shape collision properties applied to every shape in the scene.
load_visual_shapes	Whether Newton replication imports visual-only geometry from USD.
bvh_constructor_geometry	BVH construction algorithm for mesh geometry colliders.
bvh_constructor_scene	BVH construction algorithm for the top-level scene (broad-phase) hierarchy.
bvh_constructor_gaussian	BVH construction algorithm for Gaussian-splat primitives.

class_type: type[NewtonManager] | str | None

The class type of the NewtonManager.

Auto-set in __post_init__() from solver_cfg.class_type. Users normally do not set this directly.

num_substeps: int

Number of substeps to use for the solver.

collision_decimation: int

Re-collide every N solver substeps within a physics tick (0 = once per tick).

debug_mode: bool

Whether to enable debug mode for the solver.

use_cuda_graph: bool

Whether to use CUDA graphing when simulating.

If set to False, the simulation performance will be severely degraded.

deterministic_mode: Literal['not_guaranteed', 'run_to_run', 'gpu_to_gpu']

Determinism guarantee applied to the Newton solver and collision pipeline.

The values "not_guaranteed", "run_to_run", and "gpu_to_gpu" map to the corresponding warp.DeterministicMode values. Deterministic execution increases memory use and can reduce simulation performance.

Warning

Deterministic contact ordering adds sorting work and allocates buffers sized for the configured maximum contact count. Runtime and memory overhead therefore grow with contact capacity. Enable this mode only when its reproducibility guarantee is required.

MJWarp on the GPU with disable_sensors set to True, XPBD, and Featherstone support this setting. Newton raises an error during solver initialization for unsupported solvers rather than silently running them without the requested guarantee.

solver_cfg: NewtonSolverCfg | None

Solver configuration. If None (default), MJWarpSolverCfg is used by default.

soft_contact_cfg: NewtonSoftContactCfg | None

Global soft-contact parameters applied after model finalization.

If None, Newton model defaults are preserved.

collision_cfg: NewtonCollisionPipelineCfg | None

Newton collision pipeline configuration.

Controls how Newton’s CollisionPipeline is configured when it is active. The pipeline is active when the solver delegates collision detection to Newton:

• MJWarpSolverCfg with use_mujoco_contacts=False,

• KaminoPADMMSolverCfg or KaminoDVISolverCfg with use_collision_detector=False,

• XPBDSolverCfg (always),

• VBDSolverCfg (always),

• FeatherstoneSolverCfg (always).

MPMSolverCfg does not use this pipeline; implicit MPM treats rigid geometry as colliders internally.

If None (default), a pipeline with broad_phase="explicit" is created automatically. Set this to a NewtonCollisionPipelineCfg to customize parameters such as broad phase algorithm, contact limits, or hydroelastic mode.

Note

Setting this while MJWarpSolverCfg.use_mujoco_contacts=True raises ValueError. When a Kamino solver config has use_collision_detector=True, the field is ignored because Kamino’s internal detector handles contacts.

default_shape_cfg: NewtonShapeCfg

Default per-shape collision properties applied to every shape in the scene.

Forwarded to Newton’s ModelBuilder.default_shape_cfg at builder construction via checked_apply(). See NewtonShapeCfg for the declared fields.

load_visual_shapes: bool | None

Whether Newton replication imports visual-only geometry from USD.

None imports it only when a viewer, an offscreen rgb_array capture, or a camera sensor is active, so headless training does not pay the USD parse time and memory for shapes nothing draws. Set to True to always import it, which is needed when a ray-cast sensor must hit geometry that carries no collider.

bvh_constructor_geometry: Literal['lbvh', 'sah', 'cubql']

BVH construction algorithm for mesh geometry colliders.

Selects the bounding-volume-hierarchy builder Newton uses for the triangle meshes of collision geometry, forwarded to ModelBuilder.BvhConfig. Trades build time against query (traversal) quality:

• "lbvh": linear BVH; fastest to build, lowest-quality tree.

• "sah": surface-area-heuristic BVH; slower build, tighter tree with faster ray/overlap queries.

• "cubql": cuBQL GPU builder; balances fast construction with good tree quality on the GPU (default).

bvh_constructor_scene: Literal['lbvh', 'sah']

BVH construction algorithm for the top-level scene (broad-phase) hierarchy.

Selects the builder for the BVH over all colliders used during broad-phase culling, forwarded to ModelBuilder.BvhConfig. See bvh_constructor_geometry for the "lbvh" / "sah" trade-off; "cubql" is not available for the scene hierarchy.

bvh_constructor_gaussian: Literal['lbvh', 'sah', 'cubql']

BVH construction algorithm for Gaussian-splat primitives.

Selects the builder for the BVH over 3D Gaussian primitives (used by the Gaussian renderer/collision path), forwarded to ModelBuilder.BvhConfig. See bvh_constructor_geometry for the "lbvh" / "sah" / "cubql" trade-off.

class isaaclab_newton.physics.NewtonSoftContactCfg

Bases: object

Global soft-contact parameters applied to the finalized Newton model.

Attributes:

soft_contact_ke	Body-particle and particle self-contact stiffness [N/m].
soft_contact_kd	Body-particle contact damping [N*s/m].
soft_contact_mu	Body-particle contact friction coefficient [dimensionless].

soft_contact_ke: float

Body-particle and particle self-contact stiffness [N/m].

Effective body-particle stiffness is 0.5 * (soft_contact_ke + shape_ke), where shape_ke is the rigid shape’s material stiffness.

soft_contact_kd: float

Body-particle contact damping [N*s/m].

soft_contact_mu: float

Body-particle contact friction coefficient [dimensionless].

Effective body-particle friction is sqrt(soft_contact_mu * shape_mu), where shape_mu is the rigid shape’s material friction coefficient.

class isaaclab_newton.physics.NewtonSolverCfg

Bases: object

Configuration for Newton solver-related parameters.

These parameters are used to configure the Newton solver. For more information, see the Newton documentation.

Subclasses set class_type to their matching NewtonManager subclass; NewtonCfg propagates that to its own NewtonCfg.class_type in NewtonCfg.__post_init__() so that SimulationContext resolves the correct manager via the existing dispatch path.

Attributes:

class_type	Manager class for this solver.
solver_type	Solver type metadata (deprecated).

class_type: type[NewtonManager] | str

Manager class for this solver.

Default points at the abstract NewtonManager; concrete subclasses override it.

solver_type: str

Solver type metadata (deprecated).

Deprecated since version Manager: dispatch is now driven by class_type; this field is retained as metadata for logging and debugging only. Do not branch on solver_type in new code.

class isaaclab_newton.physics.MJWarpSolverCfg

Bases: NewtonSolverCfg

Configuration for MuJoCo Warp solver-related parameters.

These parameters are used to configure the MuJoCo Warp solver. For more information, see the MuJoCo Warp documentation.

Attributes:

class_type	Manager class for the MuJoCo Warp solver.
solver_type	Solver type.
njmax	Number of constraints per environment (world).
nconmax	Number of contact points per environment (world).
iterations	Number of solver iterations.
ls_iterations	Number of line search iterations for the solver.
solver	Solver type.
integrator	Integrator type.
use_mujoco_cpu	Whether to use the pure MuJoCo backend instead of mujoco_warp.
disable_contacts	Whether to disable contact computation in MuJoCo.
disable_sensors	Whether to disable MuJoCo Warp's internal sensor computation.
default_actuator_gear	Default gear ratio for all actuators.
actuator_gears	Dictionary mapping joint names to specific gear ratios, overriding the default_actuator_gear.
update_data_interval	Frequency (in simulation steps) at which to update the MuJoCo Data object from the Newton state.
save_to_mjcf	Optional path to save the generated MJCF model file.
impratio	Frictional-to-normal constraint impedance ratio.
cone	The type of contact friction cone.
ccd_iterations	Maximum iterations for convex collision detection (GJK/EPA).
ls_parallel	Deprecated parallel line search option.
use_mujoco_contacts	Whether to use MuJoCo's internal contact solver.
tolerance	Solver convergence tolerance for the constraint residual.

class_type: type[NewtonManager] | str

Manager class for the MuJoCo Warp solver.

solver_type: str

Solver type. Can be “mujoco_warp”.

njmax: int

Number of constraints per environment (world).

nconmax: int | None

Number of contact points per environment (world).

iterations: int

Number of solver iterations.

ls_iterations: int

Number of line search iterations for the solver.

solver: str

Solver type. Can be “cg” or “newton”, or their corresponding MuJoCo integer constants.

integrator: str

Integrator type. Can be “euler”, “rk4”, or “implicitfast”, or their corresponding MuJoCo integer constants.

use_mujoco_cpu: bool

Whether to use the pure MuJoCo backend instead of mujoco_warp.

disable_contacts: bool

Whether to disable contact computation in MuJoCo.

disable_sensors: bool

Whether to disable MuJoCo Warp’s internal sensor computation.

This must be True when NewtonCfg.deterministic_mode requests a determinism guarantee. Isaac Lab sensors use Newton state directly and do not depend on MuJoCo Warp’s internal sensor data.

default_actuator_gear: float | None

Default gear ratio for all actuators.

actuator_gears: dict[str, float] | None

Dictionary mapping joint names to specific gear ratios, overriding the default_actuator_gear.

update_data_interval: int

Frequency (in simulation steps) at which to update the MuJoCo Data object from the Newton state.

If 0, Data is never updated after initialization.

save_to_mjcf: str | None

Optional path to save the generated MJCF model file.

If None, the MJCF model is not saved.

impratio: float

Frictional-to-normal constraint impedance ratio.

cone: str

The type of contact friction cone. Can be “pyramidal” or “elliptic”.

ccd_iterations: int

Maximum iterations for convex collision detection (GJK/EPA).

Increase this if you see warnings about opt.ccd_iterations needing to be increased, which typically occurs with complex collision geometries (e.g. multi-finger hands).

ls_parallel: bool

Deprecated parallel line search option.

Setting this to True emits a DeprecationWarning and is ignored. MuJoCo Warp is dropping support for parallel line search; Isaac Lab uses iterative line search for performance.

use_mujoco_contacts: bool

Whether to use MuJoCo’s internal contact solver.

If True (default), MuJoCo handles collision detection and contact resolution internally. If False, Newton’s CollisionPipeline is used instead. A default pipeline (broad_phase="explicit") is created automatically when NewtonCfg.collision_cfg is None. Set NewtonCfg.collision_cfg to a NewtonCollisionPipelineCfg to customize pipeline parameters (broad phase, contact limits, hydroelastic, etc.).

Note

Setting collision_cfg while use_mujoco_contacts=True raises ValueError because the two collision modes are mutually exclusive.

tolerance: float

Solver convergence tolerance for the constraint residual.

The solver iterates until the residual drops below this threshold or iterations is reached. Lower values give more precise constraint satisfaction at the cost of more iterations. MuJoCo default is 1e-8; Newton default is 1e-6.

class isaaclab_newton.physics.VBDSolverCfg

Bases: NewtonSolverCfg

Configuration for the Vertex Block Descent solver.

Attributes:

class_type	Manager class for the VBD solver.
iterations	Number of VBD iterations per substep.
integrate_with_external_rigid_solver	Whether an external solver integrates rigid bodies.
particle_enable_self_contact	Whether to enable particle self-contact.
particle_self_contact_radius	Particle radius used for self-contact detection [m].
particle_self_contact_margin	Self-contact detection margin [m].
solver_type	Solver type metadata (deprecated).
particle_collision_detection_interval	How often particle self-contact detection is applied.
particle_vertex_contact_buffer_size	Preallocation size for each vertex contact buffer.
particle_edge_contact_buffer_size	Preallocation size for each edge contact buffer.
particle_topological_contact_filter_threshold	Topological distance below which self-contacts are discarded.
particle_rest_shape_contact_exclusion_radius	Rest-shape separation threshold for filtering contacts [m].
rigid_contact_k_start	Initial stiffness seed for rigid-body contacts [N/m].
rigid_body_particle_contact_buffer_size	Per-body capacity of the particle, edge, and face soft-contact list.

class_type: type[NewtonManager] | str

Manager class for the VBD solver.

iterations: int

Number of VBD iterations per substep.

integrate_with_external_rigid_solver: bool

Whether an external solver integrates rigid bodies.

particle_enable_self_contact: bool

Whether to enable particle self-contact.

particle_self_contact_radius: float

Particle radius used for self-contact detection [m].

particle_self_contact_margin: float

Self-contact detection margin [m].

solver_type: str

Solver type metadata (deprecated).

Deprecated since version Manager: dispatch is now driven by class_type; this field is retained as metadata for logging and debugging only. Do not branch on solver_type in new code.

particle_collision_detection_interval: int

How often particle self-contact detection is applied.

< 0: once before initialization. 0: once before and once after initialization. k >= 1: before every k VBD iterations.

particle_vertex_contact_buffer_size: int

Preallocation size for each vertex contact buffer.

particle_edge_contact_buffer_size: int

Preallocation size for each edge contact buffer.

particle_topological_contact_filter_threshold: int

Topological distance below which self-contacts are discarded.

particle_rest_shape_contact_exclusion_radius: float

Rest-shape separation threshold for filtering contacts [m].

rigid_contact_k_start: float

Initial stiffness seed for rigid-body contacts [N/m].

rigid_body_particle_contact_buffer_size: int

Per-body capacity of the particle, edge, and face soft-contact list.

Increase this value when Newton reports a per-body particle contact buffer overflow. Only used when integrate_with_external_rigid_solver is False.

class isaaclab_newton.physics.XPBDSolverCfg

Bases: NewtonSolverCfg

An implicit integrator using eXtended Position-Based Dynamics (XPBD) for rigid and soft body simulation.

References

• Miles Macklin, Matthias Müller, and Nuttapong Chentanez. 2016. XPBD: position-based simulation of compliant constrained dynamics. In Proceedings of the 9th International Conference on Motion in Games (MIG ‘16). Association for Computing Machinery, New York, NY, USA, 49-54. https://doi.org/10.1145/2994258.2994272

• Matthias Müller, Miles Macklin, Nuttapong Chentanez, Stefan Jeschke, and Tae-Yong Kim. 2020. Detailed rigid body simulation with extended position based dynamics. In Proceedings of the ACM SIGGRAPH/Eurographics Symposium on Computer Animation (SCA ‘20). Eurographics Association, Goslar, DEU, Article 10, 1-12. https://doi.org/10.1111/cgf.14105

Attributes:

class_type	Manager class for the XPBD solver.
solver_type	Solver type.
iterations	Number of solver iterations.
soft_body_relaxation	Relaxation parameter for soft body simulation.
soft_contact_relaxation	Relaxation parameter for soft contact simulation.
joint_linear_relaxation	Relaxation parameter for joint linear simulation.
joint_angular_relaxation	Relaxation parameter for joint angular simulation.
joint_linear_compliance	Compliance parameter for joint linear simulation.
joint_angular_compliance	Compliance parameter for joint angular simulation.
rigid_contact_relaxation	Relaxation parameter for rigid contact simulation.
rigid_contact_con_weighting	Whether to use contact constraint weighting for rigid contact simulation.
angular_damping	Angular damping parameter for rigid contact simulation.
enable_restitution	Whether to enable restitution for rigid contact simulation.

class_type: type[NewtonManager] | str

Manager class for the XPBD solver.

solver_type: str

Solver type. Can be “xpbd”.

iterations: int

Number of solver iterations.

soft_body_relaxation: float

Relaxation parameter for soft body simulation.

soft_contact_relaxation: float

Relaxation parameter for soft contact simulation.

joint_linear_relaxation: float

Relaxation parameter for joint linear simulation.

joint_angular_relaxation: float

Relaxation parameter for joint angular simulation.

joint_linear_compliance: float

Compliance parameter for joint linear simulation.

joint_angular_compliance: float

Compliance parameter for joint angular simulation.

rigid_contact_relaxation: float

Relaxation parameter for rigid contact simulation.

rigid_contact_con_weighting: bool

Whether to use contact constraint weighting for rigid contact simulation.

angular_damping: float

Angular damping parameter for rigid contact simulation.

enable_restitution: bool

Whether to enable restitution for rigid contact simulation.

class isaaclab_newton.physics.FeatherstoneSolverCfg

Bases: NewtonSolverCfg

A semi-implicit integrator using symplectic Euler.

It operates on reduced (also called generalized) coordinates to simulate articulated rigid body dynamics based on Featherstone’s composite rigid body algorithm (CRBA).

See: Featherstone, Roy. Rigid Body Dynamics Algorithms. Springer US, 2014.

Semi-implicit time integration is a variational integrator that preserves energy, however it is not unconditionally stable, and requires a time-step small enough to support the required stiffness and damping forces.

See: https://en.wikipedia.org/wiki/Semi-implicit_Euler_method

Attributes:

class_type	Manager class for the Featherstone solver.
solver_type	Solver type.
angular_damping	Angular damping parameter for rigid contact simulation.
update_mass_matrix_interval	Frequency (in simulation steps) at which to update the mass matrix.
friction_smoothing	Friction smoothing parameter.
use_tile_gemm	Whether to use tile-based GEMM for the mass matrix.
fuse_cholesky	Whether to fuse the Cholesky decomposition.

class_type: type[NewtonManager] | str

Manager class for the Featherstone solver.

solver_type: str

Solver type. Can be “featherstone”.

angular_damping: float

Angular damping parameter for rigid contact simulation.

update_mass_matrix_interval: int

Frequency (in simulation steps) at which to update the mass matrix.

friction_smoothing: float

Friction smoothing parameter.

use_tile_gemm: bool

Whether to use tile-based GEMM for the mass matrix.

fuse_cholesky: bool

Whether to fuse the Cholesky decomposition.

class isaaclab_newton.physics.KaminoPADMMCfg

Bases: object

P-ADMM forward-dynamics solver parameters for Kamino.

Attributes:

max_iterations	Maximum number of P-ADMM solver iterations.
primal_tolerance	Primal residual convergence tolerance.
dual_tolerance	Dual residual convergence tolerance.
compl_tolerance	Complementarity residual convergence tolerance.
restart_tolerance	Combined primal-dual residual tolerance for acceleration restarts.
rho_0	Initial penalty parameter.
rho_min	Lower bound on the penalty parameter.
a_0	Initial acceleration parameter.
alpha	Primal-dual residual threshold for penalty updates.
tau	Penalty increase/decrease factor.
eta	Proximal regularization parameter.
penalty_update_freq	Frequency of penalty updates.
penalty_update_method	Penalty update method.
linear_solver_tolerance	Absolute tolerance for the iterative linear solver.
linear_solver_tolerance_ratio	Ratio adapting the linear solver tolerance from the ADMM primal residual.
use_acceleration	Whether to use Nesterov-type acceleration (APADMM).
use_graph_conditionals	Whether to use CUDA graph conditional nodes in the iterative solver.
warmstart_mode	Warmstart mode.
contact_warmstart_method	Contact warm-start method.

max_iterations: int

Maximum number of P-ADMM solver iterations.

primal_tolerance: float

Primal residual convergence tolerance.

dual_tolerance: float

Dual residual convergence tolerance.

compl_tolerance: float

Complementarity residual convergence tolerance.

restart_tolerance: float

Combined primal-dual residual tolerance for acceleration restarts.

rho_0: float

Initial penalty parameter.

rho_min: float

Lower bound on the penalty parameter.

a_0: float

Initial acceleration parameter.

alpha: float

Primal-dual residual threshold for penalty updates.

tau: float

Penalty increase/decrease factor.

eta: float

Proximal regularization parameter. Must be greater than zero.

penalty_update_freq: int

Frequency of penalty updates. Zero disables updates.

penalty_update_method: Literal['fixed', 'balanced']

Penalty update method.

linear_solver_tolerance: float

Absolute tolerance for the iterative linear solver. Zero leaves it unchanged.

linear_solver_tolerance_ratio: float

Ratio adapting the linear solver tolerance from the ADMM primal residual.

use_acceleration: bool

Whether to use Nesterov-type acceleration (APADMM).

use_graph_conditionals: bool

Whether to use CUDA graph conditional nodes in the iterative solver.

warmstart_mode: Literal['none', 'internal', 'containers']

Warmstart mode.

contact_warmstart_method: Literal['key_and_position', 'geom_pair_net_force', 'geom_pair_net_wrench', 'key_and_position_with_net_force_backup', 'key_and_position_with_net_wrench_backup']

Contact warm-start method.

class isaaclab_newton.physics.KaminoDVICfg

Bases: object

DVI forward-dynamics solver parameters for Kamino.

Attributes:

tolerance	Convergence tolerance on the projected update size.
regularization	Diagonal regularization added to each projected update denominator.
omega	Relaxation factor applied to projected Gauss-Seidel updates.
max_alternating_iterations	Maximum outer DVI iterations.
inequality_sweeps_per_iteration	Projected Gauss-Seidel sweeps per DVI iteration.
bilateral_solve_interval	DVI iterations between repeated direct bilateral solves.
bilateral_solver_type	Direct linear solver for the bilateral constraint block.
bilateral_solver_kwargs	Additional keyword arguments for the bilateral linear solver.
warmstart_mode	Warmstart mode.
contact_warmstart_method	Contact warm-start method when warmstart_mode is containers.

tolerance: float

Convergence tolerance on the projected update size.

regularization: float

Diagonal regularization added to each projected update denominator.

omega: float

Relaxation factor applied to projected Gauss-Seidel updates.

max_alternating_iterations: int

Maximum outer DVI iterations.

inequality_sweeps_per_iteration: int

Projected Gauss-Seidel sweeps per DVI iteration.

bilateral_solve_interval: int

DVI iterations between repeated direct bilateral solves.

bilateral_solver_type: Literal['LLTB', 'LLTBRCM']

Direct linear solver for the bilateral constraint block.

bilateral_solver_kwargs: dict[str, Any]

Additional keyword arguments for the bilateral linear solver.

warmstart_mode: Literal['none', 'internal', 'containers']

Warmstart mode.

contact_warmstart_method: Literal['key_and_position', 'geom_pair_net_force', 'key_and_position_with_net_force_backup']

Contact warm-start method when warmstart_mode is containers.

class isaaclab_newton.physics.KaminoDynamicsCfg

Bases: object

Constrained forward-dynamics problem parameters for Kamino.

Attributes:

preconditioning	Whether to precondition the dual problem.
linear_solver_type	Linear solver for the dynamics problem.
linear_solver_kwargs	Additional keyword arguments for the linear solver.

preconditioning: bool

Whether to precondition the dual problem. Must be False when using DVI.

linear_solver_type: Literal['LLTB', 'LLTBRCM', 'CR', 'CRF']

Linear solver for the dynamics problem.

linear_solver_kwargs: dict[str, Any]

Additional keyword arguments for the linear solver.

class isaaclab_newton.physics.KaminoConstraintsCfg

Bases: object

Global constraint stabilization parameters for Kamino.

Attributes:

alpha	Baumgarte stabilization for bilateral joint constraints.
beta	Baumgarte stabilization for unilateral joint-limit constraints.
gamma	Baumgarte stabilization for unilateral contact constraints.
delta	Contact penetration margin [m].

alpha: float

Baumgarte stabilization for bilateral joint constraints. Valid range is [0, 1].

beta: float

Baumgarte stabilization for unilateral joint-limit constraints. Valid range is [0, 1].

gamma: float

Baumgarte stabilization for unilateral contact constraints. Valid range is [0, 1].

delta: float

Contact penetration margin [m].

class isaaclab_newton.physics.KaminoFKCfg

Bases: object

Forward-kinematics reset solver parameters for Kamino.

Attributes:

use_regularization	Whether to regularize the FK reset solve (Tikhonov term on body poses).
regularization_weight	Weight of the FK reset regularizer when use_regularization is True.
tolerance	Convergence tolerance of the FK reset solve.

use_regularization: bool

Whether to regularize the FK reset solve (Tikhonov term on body poses).

regularization_weight: float

Weight of the FK reset regularizer when use_regularization is True.

tolerance: float

Convergence tolerance of the FK reset solve.

class isaaclab_newton.physics.KaminoCollisionDetectorCfg

Bases: object

Internal Kamino collision-detector parameters.

Attributes:

pipeline	Collision-detection pipeline.
broadphase	Broad-phase algorithm.
bvtype	Bounding-volume type.
max_contacts	Model-wide contact buffer capacity cap.
max_contacts_per_world	Per-world contact buffer capacity override.
max_contacts_per_pair	Maximum contacts generated per candidate geometry pair.
max_triangle_pairs	Maximum triangle-primitive shape pairs in narrow phase.
default_gap	Default detection gap [m] applied as a floor to per-geometry gaps.

pipeline: Literal['primitive', 'unified'] | None

Collision-detection pipeline. None uses Newton’s default (unified).

broadphase: Literal['nxn', 'sap', 'explicit'] | None

Broad-phase algorithm. None uses Newton’s default.

bvtype: Literal['aabb', 'bs'] | None

Bounding-volume type. None uses Newton’s default.

max_contacts: int | None

Model-wide contact buffer capacity cap.

max_contacts_per_world: int | None

Per-world contact buffer capacity override.

max_contacts_per_pair: int | None

Maximum contacts generated per candidate geometry pair.

max_triangle_pairs: int | None

Maximum triangle-primitive shape pairs in narrow phase.

default_gap: float | None

Default detection gap [m] applied as a floor to per-geometry gaps.

class isaaclab_newton.physics.KaminoMaterialsCfg

Bases: object

Material mixing parameters for Kamino contacts.

Attributes:

friction_mix_mode	How friction coefficients are mixed for a contact pair.
restitution_mix_mode	How restitution coefficients are mixed for a contact pair.

friction_mix_mode: Literal['average', 'multiply', 'max', 'min']

How friction coefficients are mixed for a contact pair.

restitution_mix_mode: Literal['average', 'multiply', 'max', 'min']

How restitution coefficients are mixed for a contact pair.

class isaaclab_newton.physics.KaminoPADMMSolverCfg

Bases: _KaminoSolverCfgBase

Configuration for Kamino with the P-ADMM forward-dynamics solver.

Attributes:

class_type	Manager class for the Kamino solver.
solver_type	Solver type.
integrator	Integrator type.
use_collision_detector	Whether to use Kamino's internal collision detector instead of Newton's pipeline.
use_fk_solver	Whether to enable the forward kinematics solver for state resets.
sparse_jacobian	Whether to use sparse Jacobian computation.
sparse_dynamics	Whether to use sparse dynamics computation.
rotation_correction	Rotation correction mode.
angular_velocity_damping	Angular velocity damping factor.
collect_solver_info	Whether to collect solver convergence and performance info at each step.
compute_solution_metrics	Whether to compute solution metrics at each step.
dynamics	Constrained dynamics problem parameters.
constraints	Constraint stabilization parameters.
fk	Forward-kinematics reset solver parameters.
collision_detector	Internal collision-detector parameters.
materials	Material mixing parameters.
max_contacts_per_world	Cap the per-world contact pre-allocation handed to Kamino.
dynamics_solver_cfg	P-ADMM forward-dynamics solver parameters.

class_type: type[NewtonManager] | str

Manager class for the Kamino solver.

solver_type: str

Solver type. Can be “kamino”.

integrator: Literal['euler', 'moreau']

Integrator type.

use_collision_detector: bool

Whether to use Kamino’s internal collision detector instead of Newton’s pipeline.

use_fk_solver: bool | None

Whether to enable the forward kinematics solver for state resets.

When None, Kamino will automatically determine whether to use the FK solver based on the model’s articulation structure. If the model has loop-closing joints, the FK solver will be used.

When True, NewtonKaminoManager._eval_fk_impl() reconciles body state via SolverKamino.reset() with SolverKamino.ResetConfig.from_joints. Kamino’s FK solver computes consistent body poses/velocities from the joint coordinates (including the base joint for floating bases), resolves passive / loop-closure joints, and writes back a consistent full joint state. Environment resets only need to write actuated DOFs in joint_q; passive values are filled in by FK. This is required for closed-loop systems.

When False, Newton’s articulated eval_fk is used instead over the full joint_q / joint_qd. It is then up to the user to specify constraint-consistent values. This is the faster option for purely articulated (tree-structured) systems.

sparse_jacobian: bool | None

Whether to use sparse Jacobian computation. None lets Newton pick per backend.

sparse_dynamics: bool

Whether to use sparse dynamics computation.

rotation_correction: Literal['twopi', 'continuous', 'none']

Rotation correction mode.

angular_velocity_damping: float

Angular velocity damping factor. Valid range is [0.0, 1.0].

collect_solver_info: bool

Whether to collect solver convergence and performance info at each step.

Warning

Enabling this significantly increases solver runtime and should only be used for debugging.

compute_solution_metrics: bool

Whether to compute solution metrics at each step.

Warning

Enabling this significantly increases solver runtime and should only be used for debugging.

dynamics: KaminoDynamicsCfg | None

Constrained dynamics problem parameters.

When None, Newton selects defaults appropriate to the selected dynamics solver and sparsity settings.

constraints: KaminoConstraintsCfg

Constraint stabilization parameters.

fk: KaminoFKCfg

Forward-kinematics reset solver parameters.

collision_detector: KaminoCollisionDetectorCfg

Internal collision-detector parameters.

materials: KaminoMaterialsCfg

Material mixing parameters.

max_contacts_per_world: int | None

Cap the per-world contact pre-allocation handed to Kamino.

When None, Kamino falls back to geoms.world_minimum_contacts derived from the collision pipeline, which over-allocates dramatically for contact-rich assets. Set this to bound GPU memory for multi-env training of contact-heavy tasks (e.g. legged locomotion or manipulation). The total model.rigid_contact_max is computed as max_contacts_per_world * model.world_count before solver construction.

This field is applied by NewtonKaminoManager and is not forwarded to Newton.

dynamics_solver_cfg: KaminoPADMMCfg

P-ADMM forward-dynamics solver parameters.

class isaaclab_newton.physics.KaminoDVISolverCfg

Bases: _KaminoSolverCfgBase

Configuration for Kamino with the DVI forward-dynamics solver.

Attributes:

class_type	Manager class for the Kamino solver.
solver_type	Solver type.
integrator	Integrator type.
use_collision_detector	Whether to use Kamino's internal collision detector instead of Newton's pipeline.
use_fk_solver	Whether to enable the forward kinematics solver for state resets.
sparse_jacobian	Whether to use sparse Jacobian computation.
sparse_dynamics	Whether to use sparse dynamics computation.
rotation_correction	Rotation correction mode.
angular_velocity_damping	Angular velocity damping factor.
collect_solver_info	Whether to collect solver convergence and performance info at each step.
compute_solution_metrics	Whether to compute solution metrics at each step.
dynamics	Constrained dynamics problem parameters.
constraints	Constraint stabilization parameters.
fk	Forward-kinematics reset solver parameters.
collision_detector	Internal collision-detector parameters.
materials	Material mixing parameters.
max_contacts_per_world	Cap the per-world contact pre-allocation handed to Kamino.
dynamics_solver_cfg	DVI forward-dynamics solver parameters.

class_type: type[NewtonManager] | str

Manager class for the Kamino solver.

solver_type: str

Solver type. Can be “kamino”.

integrator: Literal['euler', 'moreau']

Integrator type.

use_collision_detector: bool

Whether to use Kamino’s internal collision detector instead of Newton’s pipeline.

use_fk_solver: bool | None

Whether to enable the forward kinematics solver for state resets.

When None, Kamino will automatically determine whether to use the FK solver based on the model’s articulation structure. If the model has loop-closing joints, the FK solver will be used.

When True, NewtonKaminoManager._eval_fk_impl() reconciles body state via SolverKamino.reset() with SolverKamino.ResetConfig.from_joints. Kamino’s FK solver computes consistent body poses/velocities from the joint coordinates (including the base joint for floating bases), resolves passive / loop-closure joints, and writes back a consistent full joint state. Environment resets only need to write actuated DOFs in joint_q; passive values are filled in by FK. This is required for closed-loop systems.

When False, Newton’s articulated eval_fk is used instead over the full joint_q / joint_qd. It is then up to the user to specify constraint-consistent values. This is the faster option for purely articulated (tree-structured) systems.

sparse_jacobian: bool | None

Whether to use sparse Jacobian computation. None lets Newton pick per backend.

sparse_dynamics: bool

Whether to use sparse dynamics computation.

rotation_correction: Literal['twopi', 'continuous', 'none']

Rotation correction mode.

angular_velocity_damping: float

Angular velocity damping factor. Valid range is [0.0, 1.0].

collect_solver_info: bool

Whether to collect solver convergence and performance info at each step.

Warning

Enabling this significantly increases solver runtime and should only be used for debugging.

compute_solution_metrics: bool

Whether to compute solution metrics at each step.

Warning

Enabling this significantly increases solver runtime and should only be used for debugging.

dynamics: KaminoDynamicsCfg | None

Constrained dynamics problem parameters.

When None, Newton selects defaults appropriate to the selected dynamics solver and sparsity settings.

constraints: KaminoConstraintsCfg

Constraint stabilization parameters.

fk: KaminoFKCfg

Forward-kinematics reset solver parameters.

collision_detector: KaminoCollisionDetectorCfg

Internal collision-detector parameters.

materials: KaminoMaterialsCfg

Material mixing parameters.

max_contacts_per_world: int | None

Cap the per-world contact pre-allocation handed to Kamino.

When None, Kamino falls back to geoms.world_minimum_contacts derived from the collision pipeline, which over-allocates dramatically for contact-rich assets. Set this to bound GPU memory for multi-env training of contact-heavy tasks (e.g. legged locomotion or manipulation). The total model.rigid_contact_max is computed as max_contacts_per_world * model.world_count before solver construction.

This field is applied by NewtonKaminoManager and is not forwarded to Newton.

dynamics_solver_cfg: KaminoDVICfg

DVI forward-dynamics solver parameters.

class isaaclab_newton.physics.MPMSolverCfg

Bases: NewtonSolverCfg

Configuration for Newton’s implicit Material Point Method (MPM) solver.

The implicit MPM solver advances particle materials and treats rigid geometry as colliders. It is not a rigid-body or articulation dynamics solver.

Attributes:

class_type	Manager class for the implicit MPM solver.
solver_type	Solver type.
max_iterations	Maximum number of iterations for the rheology solver.
tolerance	Tolerance for the rheology solver.
solver	Rheology solver, or an ordered warm-start sequence of solvers.
warmstart_mode	Warm-start mode for the rheology solver.
collider_velocity_mode	Collider velocity computation mode.
voxel_size	Size of the MPM grid voxels [m].
grid_type	Type of grid to use.
grid_padding	Number of empty cells to add around particles when allocating the grid.
max_active_cell_count	Maximum active grid-cell count shared by all worlds.
max_leaf_node_count	Maximum sparse-grid leaf-node count shared by all worlds.
max_lower_node_count	Maximum sparse-grid lower internal-node count shared by all worlds.
max_upper_node_count	Maximum sparse-grid upper internal-node count shared by all worlds.
separate_worlds	Whether each Newton world uses an independent local MPM grid environment.
transfer_scheme	Particle-grid transfer scheme.
integration_scheme	Integration scheme controlling shape-function support.
critical_fraction	Dimensionless fraction under which the yield surface collapses.
air_drag	Numerical drag for background air.
collider_normal_from_sdf_gradient	Whether collider normals are computed from SDF gradients rather than closest points.
collider_basis	Collider basis function, such as "S2" or "Q1".
strain_basis	Strain basis function, such as "P0", "P1d", "Q1", or "Q1d".
velocity_basis	Velocity basis function, such as "Q1", "B2", or "B3".
project_outside_colliders	Whether to hard-project particles out of collider interiors after each substep.

class_type: type[NewtonManager] | str

Manager class for the implicit MPM solver.

solver_type: str

Solver type. Can be “implicit_mpm”.

max_iterations: int

Maximum number of iterations for the rheology solver.

tolerance: float

Tolerance for the rheology solver.

solver: str | tuple[str, ...]

Rheology solver, or an ordered warm-start sequence of solvers.

"auto" lets Newton pick the solver from the velocity basis ("gs" for Q1, "gs-batched" for B2/B3). Other accepted values include "gauss-seidel", "jacobi", "cg", "cr", and "gmres"; pass a tuple such as ("cr", "gs") to warm-start solvers left-to-right.

warmstart_mode: Literal['none', 'auto', 'particles', 'grid', 'smoothed']

Warm-start mode for the rheology solver.

collider_velocity_mode: Literal['forward', 'backward', 'instantaneous', 'finite_difference']

Collider velocity computation mode.

"instantaneous" is deprecated in favor of "forward", and "finite_difference" is deprecated in favor of "backward".

voxel_size: float

Size of the MPM grid voxels [m].

grid_type: Literal['sparse', 'dense', 'fixed']

Type of grid to use.

grid_padding: int

Number of empty cells to add around particles when allocating the grid.

max_active_cell_count: int

Maximum active grid-cell count shared by all worlds.

A positive value reserves persistent capacity for rebuildable sparse grids and bounds active subsets of dense and fixed grids. -1 keeps sparse allocation dynamic and uses exact active counts for the other grid types.

max_leaf_node_count: int

Maximum sparse-grid leaf-node count shared by all worlds.

-1 lets Newton derive the capacity from max_active_cell_count.

max_lower_node_count: int

Maximum sparse-grid lower internal-node count shared by all worlds.

-1 lets Newton derive the capacity from the initial topology.

max_upper_node_count: int

Maximum sparse-grid upper internal-node count shared by all worlds.

-1 lets Newton derive the capacity from the initial topology.

separate_worlds: bool

Whether each Newton world uses an independent local MPM grid environment.

transfer_scheme: Literal['apic', 'pic']

Particle-grid transfer scheme.

integration_scheme: Literal['pic', 'gimp']

Integration scheme controlling shape-function support.

critical_fraction: float

Dimensionless fraction under which the yield surface collapses.

air_drag: float

Numerical drag for background air.

collider_normal_from_sdf_gradient: bool

Whether collider normals are computed from SDF gradients rather than closest points.

collider_basis: str

Collider basis function, such as "S2" or "Q1".

strain_basis: str

Strain basis function, such as "P0", "P1d", "Q1", or "Q1d".

velocity_basis: str

Velocity basis function, such as "Q1", "B2", or "B3".

project_outside_colliders: bool

Whether to hard-project particles out of collider interiors after each substep.

When True, NewtonMPMManager calls SolverImplicitMPM.project_outside() immediately after every solver substep: it applies a Coulomb response and pushes particles that drifted into a collider back onto its surface. The implicit solve already resolves colliders at the grid level; this is the particle-level correction that stops material from slowly settling inside colliders, mirroring Newton’s MPM examples. Leave it False for collider-free scenes to skip a per-substep projection pass over every particle.

This is a manager-level stepping option and is intentionally not part of SolverImplicitMPM.Config.

class isaaclab_newton.physics.NewtonCollisionPipelineCfg

Bases: object

Configuration for Newton collision pipeline.

Full-featured collision pipeline with GJK/MPR narrow phase and pluggable broad phase. When this config is set on NewtonCfg.collision_cfg:

• MJWarpSolverCfg: Newton’s collision pipeline replaces MuJoCo’s internal contact solver.

• Other solvers (XPBD, Featherstone, etc.): Configures the collision pipeline parameters (these solvers always use Newton’s collision pipeline).

Key features:

• GJK/MPR algorithms for convex-convex collision detection

• Multiple broad phase options: NXN (all-pairs), SAP (sweep-and-prune), EXPLICIT (precomputed pairs)

• Mesh-mesh collision via SDF with contact reduction

• Optional hydroelastic contact model for compliant surfaces

For more details, see the Newton collision pipeline guide and CollisionPipeline API.

Attributes:

broad_phase	Broad phase algorithm for collision detection.
reduce_contacts	Whether to reduce contacts for mesh-mesh collisions.
rigid_contact_max	Maximum number of rigid contacts to allocate.
max_triangle_pairs	Maximum number of triangle pairs allocated by narrow phase for mesh and heightfield collisions.
soft_contact_max	Maximum number of soft contacts to allocate.
soft_contact_margin	Margin [m] for soft contact generation.
enable_rigid_soft_full_surface_contact	Whether to generate soft contacts against full-surface-capable rigid colliders.
requires_grad	Whether to enable gradient computation for collision.
sdf_hydroelastic_config	Configuration for SDF-based hydroelastic collision handling.

Methods:

to_pipeline_args()

Build keyword arguments for newton.CollisionPipeline.

broad_phase: Literal['explicit', 'nxn', 'sap']

Broad phase algorithm for collision detection.

Options:

• "explicit": Use precomputed shape pairs from model.shape_contact_pairs.

• "nxn": All-pairs brute force. Simple but O(n^2) complexity.

• "sap": Sweep-and-prune. Good for scenes with many dynamic objects.

Defaults to "explicit" (same as Newton’s default when broad_phase=None).

reduce_contacts: bool

Whether to reduce contacts for mesh-mesh collisions.

When True, uses shared memory contact reduction to select representative contacts. Improves performance and stability for meshes with many vertices.

Defaults to True (same as Newton’s default).

rigid_contact_max: int | None

Maximum number of rigid contacts to allocate.

Resolution order:

1. If provided, use this value.

2. Else if model.rigid_contact_max > 0, use the model value.

3. Else estimate automatically from model shape and pair metadata.

Defaults to None (auto-estimate, same as Newton’s default).

max_triangle_pairs: int

Maximum number of triangle pairs allocated by narrow phase for mesh and heightfield collisions.

Increase this when scenes with large/complex meshes or heightfields report triangle-pair overflow warnings.

Defaults to 1_000_000 (same as Newton’s default).

soft_contact_max: int | None

Maximum number of soft contacts to allocate.

If None, computed as shape_count * particle_count.

Defaults to None (auto-compute, same as Newton’s default).

soft_contact_margin: float

Margin [m] for soft contact generation.

Defaults to 0.01 (same as Newton’s default).

enable_rigid_soft_full_surface_contact: bool

Whether to generate soft contacts against full-surface-capable rigid colliders.

When True, Newton adds edge and triangle-interior soft contacts (in addition to the per-vertex particle contacts) so rigid features that pass between soft vertices are caught. Analytic shapes (boxes, capsules, spheres) are full-surface-capable without an SDF; any participating mesh/convex collider must carry a volume SDF.

Defaults to False (same as Newton’s default).

requires_grad: bool | None

Whether to enable gradient computation for collision.

If None, uses model.requires_grad.

Defaults to None (same as Newton’s default).

sdf_hydroelastic_config: HydroelasticSDFCfg | None

Configuration for SDF-based hydroelastic collision handling.

If None, hydroelastic contacts are disabled. If set, enables hydroelastic contacts with the specified parameters.

Defaults to None (hydroelastic disabled, same as Newton’s default).

to_pipeline_args() → dict[str, Any]

Build keyword arguments for newton.CollisionPipeline.

Converts this configuration into the dict expected by CollisionPipeline.__init__, handling nested config conversion (e.g. HydroelasticSDFCfg → HydroelasticSDF.Config).

Returns:

Keyword arguments suitable for CollisionPipeline(model, **args).

class isaaclab_newton.physics.HydroelasticSDFCfg

Bases: object

Configuration for SDF-based hydroelastic collision handling.

Hydroelastic contacts generate distributed contact areas instead of point contacts, providing more realistic force distribution for manipulation and compliant surfaces.

For more details, see the Newton hydroelastic contacts guide.

Attributes:

reduce_contacts	Whether to reduce contacts to a smaller representative set per shape pair.
buffer_fraction	(0, 1].
normal_matching	Whether to rotate reduced contact normals to align with aggregate force direction.
anchor_contact	Whether to add an anchor contact at the center of pressure for each normal bin.
margin_contact_area	Contact area [m^2] used for non-penetrating contacts at the margin.
output_contact_surface	Whether to output hydroelastic contact surface vertices for visualization.

reduce_contacts: bool

Whether to reduce contacts to a smaller representative set per shape pair.

When False, all generated contacts are passed through without reduction.

Defaults to True (same as Newton’s default).

buffer_fraction: float

(0, 1].

Lower values reduce memory usage but may cause overflows in dense scenes. Overflows are bounds-safe and emit warnings; increase this value when warnings appear.

Defaults to 1.0 (same as Newton’s default).

Type:

Fraction of worst-case hydroelastic buffer allocations. Range

normal_matching: bool

Whether to rotate reduced contact normals to align with aggregate force direction.

Only active when reduce_contacts is True.

Defaults to True (same as Newton’s default).

anchor_contact: bool

Whether to add an anchor contact at the center of pressure for each normal bin.

The anchor contact helps preserve moment balance. Only active when reduce_contacts is True.

Defaults to False (same as Newton’s default).

margin_contact_area: float

Contact area [m^2] used for non-penetrating contacts at the margin.

Defaults to 0.01 (same as Newton’s default).

output_contact_surface: bool

Whether to output hydroelastic contact surface vertices for visualization.

Defaults to False (same as Newton’s default).

class isaaclab_newton.physics.NewtonShapeCfg

Bases: object

Default per-shape collision properties applied to all shapes in a Newton scene.

Mirrors Newton’s ModelBuilder.default_shape_cfg. Fields that Isaac Lab overrides or exposes for user overrides are declared here; fields not represented keep Newton’s upstream defaults. The struct is forwarded onto Newton’s upstream ShapeConfig via checked_apply() at builder construction.

Attributes:

margin	Default per-shape collision margin [m].
gap	Default per-shape contact gap [m].
ke	Default per-shape normal contact stiffness [N/m].
kd	Default per-shape normal contact damping [N*s/m].
mu	Default per-shape friction coefficient [dimensionless].

margin: float

Default per-shape collision margin [m].

A nonzero margin (e.g. 0.01) is required for stable contact on triangle-mesh terrain — without it, lightweight robots fail to learn rough-terrain locomotion on Newton. Newton’s upstream default is 0.0.

gap: float

Default per-shape contact gap [m]. Newton’s upstream default is None.

ke: float

Default per-shape normal contact stiffness [N/m].

Applied to shapes that lack an explicit material; per-asset materials override it. Mirrors Newton’s ShapeConfig.ke default.

kd: float

Default per-shape normal contact damping [N*s/m].

Applied to shapes that lack an explicit material; per-asset materials override it. Mirrors Newton’s ShapeConfig.kd default.

mu: float

Default per-shape friction coefficient [dimensionless].

Applied to shapes that lack an explicit material; per-asset materials override it. Mirrors Newton’s ShapeConfig.mu default.

Solver Managers

class isaaclab_newton.physics.NewtonMJWarpManager

Bases: NewtonManager

NewtonManager specialization for the MuJoCo Warp solver.

Owns construction of SolverMuJoCo, contact-buffer allocation in both internal-MuJoCo and Newton-pipeline contact modes, and the debug convergence logging emitted from _log_solver_debug() when NewtonCfg.debug_mode is enabled.

Methods:

activate_newton_actuator_path()	Opt an articulation into the Newton actuator fast path.
add_contact_sensor([body_names_expr, ...])	Add a contact sensor for reporting contacts between bodies/shapes.
add_frame_transform_sensor(shapes, ...)	Add a frame transform sensor for measuring relative transforms.
add_imu_sensor(sites)	Add an IMU sensor for measuring acceleration and angular velocity at sites.
add_model_change(change)	Register a model change to notify the solver.
after_visualizers_render()	Hook after visualizers have stepped during render().
cl_register_site(body_pattern, xform, *[, ...])	Register a site request for injection into prototypes before replication.
clear()	Clear all Newton-specific state (callbacks cleared by super().close()).
clear_callbacks()	Remove all registered callbacks.
close()	Clean up Newton physics resources.
create_builder([up_axis])	Create a ModelBuilder configured with default settings.
deregister_callback(callback_id)	Remove a registered callback.
dispatch_event(event[, payload])	Dispatch an event to all registered callbacks.
fix_articulation_root(articulation_prim[, stage])	Ensure that an articulation root has one enabled world fixed joint.
forward()	Update articulation kinematics without stepping physics.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
get_contacts()	Get the current Newton contact buffer, if the active solver exposes one.
get_control()	Get the control object.
get_device()	Get the physics simulation device.
get_dt()	Get the physics timestep.
get_model()	Get the Newton model.
get_physics_dt()	Get the physics timestep in seconds.
get_physics_sim_view()	Get the list of registered views.
get_scene_data_backend()	Return the SceneDataBackend for the SceneDataProvider.
get_scene_data_provider()	Return the active scene data provider.
get_simulation_time()	Get the current simulation time in seconds.
get_solver_dt()	Get the solver substep timestep.
get_state([scene_data_provider])	Get the current Newton state for visualization.
get_state_0()	Get the current state.
get_state_1()	Get the next state.
handles_decimation()	True when step() executes the full decimation loop internally.
initialize(sim_context)	Initialize the manager with simulation context.
initialize_solver()	Initialize the solver and collision pipeline.
instantiate_builder_from_stage()	Create builder from USD stage.
invalidate_body_state([env_ids, env_mask])	Mark selected maximal-coordinate body state as changed without requesting FK.
invalidate_fk([env_mask, env_ids, ...])	Mark environments as needing FK recomputation and solver reset.
is_fabric_enabled()	Check if fabric interface is enabled (not applicable for Newton).
pause()	Pause physics simulation.
play()	Start or resume physics simulation.
pre_render()	Refresh derived Newton state before cameras and visualizers read it.
register_callback(callback, event[, order, ...])	Register a callback.
register_particle_visual_prim(prim_path, ...)	Register a UsdGeom.Points prim whose points mirror a slice of Newton's particle state.
register_post_actuator_callback(callback)	Append a hook to the list invoked after the actuator step on every iteration.
register_post_step_callback(callback)	Append a hook to the list invoked after the last solver substep on every step.
register_state_force_callback(callback)	Register a graph-safe callback that applies forces before every solver substep.
request_extended_contact_attribute(attr)	Request an extended contact attribute (e.g. "force").
request_extended_state_attribute(attr)	Request an extended state attribute (e.g. "body_qdd").
reset([soft])	Reset physics simulation.
safe_callback_invoke(fn, *args[, ...])	Invoke a callback, catching exceptions that would be swallowed by external event buses.
set_builder(builder)	Set the Newton model builder.
set_decimation(decimation)	Set the decimation count and re-capture the CUDA graph.
start_simulation()	Start simulation by finalizing model and initializing state.
step()	Step the physics simulation.
stop()	Stop physics simulation.
sync_cables_to_usd()	Write Newton cable segment endpoints to Fabric curve points.
sync_particles_to_usd()	Write Newton particle positions to USD/Fabric for Kit viewport rendering.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
unregister_post_step_callback(callback)	Remove a previously registered post-step callback.
update_visualization_state([scene_data_provider])	Refresh visualization state for the active sim backend.
video_capture_backend()	Newton GL headless perspective video capture.
wait_for_playing()	Block until the timeline is playing.

classmethod activate_newton_actuator_path() → None

Opt an articulation into the Newton actuator fast path.

Idempotent — called by every Newton-fast-path articulation’s _process_actuators_cfg:

1. Sets _use_newton_actuators_active, which _is_all_graphable() checks (adapter presence alone cannot distinguish the fast path from the standard Lab path).

2. On first call, builds the single sim-level NewtonActuatorAdapter over the full flat DOF layout; later calls reuse it.

classmethod add_contact_sensor(body_names_expr: str | list[str] | None = None, shape_names_expr: str | list[str] | None = None, contact_partners_body_expr: str | list[str] | None = None, contact_partners_shape_expr: str | list[str] | None = None, verbose: bool = False) → tuple[str | list[str] | None, str | list[str] | None, str | list[str] | None, str | list[str] | None]

Add a contact sensor for reporting contacts between bodies/shapes.

Converts Isaac Lab pattern conventions (.* regex, full USD paths) to fnmatch globs and delegates to newton.sensors.SensorContact.

Parameters:

• body_names_expr – Expression for body names to sense.

• shape_names_expr – Expression for shape names to sense.

• contact_partners_body_expr – Expression for contact partner body names.

• contact_partners_shape_expr – Expression for contact partner shape names.

• verbose – Print verbose information.

classmethod add_frame_transform_sensor(shapes: list[int], reference_sites: list[int]) → int

Add a frame transform sensor for measuring relative transforms.

Creates a SensorFrameTransform from pre-resolved shape and reference site indices, appends it to the internal list, and returns its index.

Parameters:

• shapes – Ordered list of shape indices to measure.

• reference_sites – 1:1 list of reference site indices (same length as shapes).

Returns:

Index of the newly created sensor in _newton_frame_transform_sensors.

classmethod add_imu_sensor(sites: list[int]) → int

Add an IMU sensor for measuring acceleration and angular velocity at sites.

Creates a newton.sensors.SensorIMU from pre-resolved site indices, appends it to the internal list, and returns its index.

Parameters:

sites – Ordered list of site indices (one per environment).

Returns:

Index of the newly created sensor in the internal IMU sensor list.

classmethod add_model_change(change: newton.ModelFlags) → None

Register a model change to notify the solver.

classmethod after_visualizers_render() → None

Hook after visualizers have stepped during render().

Use for physics-backend sync (e.g. fabric) if needed. Default is a no-op.

classmethod cl_register_site(body_pattern: str | None, xform: warp.transform, *, per_world: bool = False) → str

Register a site request for injection into prototypes before replication.

Sensors call this during __init__. Sites are injected into prototype builders by _cl_inject_sites() (called from newton_replicate) before add_builder, so they replicate correctly per-world.

Identical (body_pattern, per_world, transform) registrations share sites.

The body_pattern is matched against prototype-local body labels (e.g. "Robot/link.*") when replication is active, or against the flat builder’s body labels in the fallback path. Wildcard patterns that match multiple bodies create one site per matched body.

Parameters:

• body_pattern – Regex pattern matched against body labels in the prototype builder (e.g. "Robot/link0" or "Robot/finger.*" for multi-body wildcards), or None for global sites (world-origin reference, etc.).

• xform – Site transform relative to body.

• per_world – When True, body_pattern must be None and one bodyless site is created in each cloned world’s frame.

Returns:

Assigned site label suffix.

classmethod clear()

Clear all Newton-specific state (callbacks cleared by super().close()).

classmethod clear_callbacks() → None

Remove all registered callbacks.

Do NOT reset _callback_id — handle IDs must remain monotonically unique across the lifetime of the process. Resetting the counter would let a future register_callback() hand out an ID that an old, still-alive CallbackHandle (e.g. on a sensor that has not been garbage-collected yet) holds, so when the old object eventually finalizes its __del__ would deregister the new callback. This bit ovphysx’s kitless multi-context tests where two InteractiveScene``s are created in sequence: the first scene's sensor would post-GC deregister the second scene's ``_initialize_callback by ID collision, leaving the second sensor forever uninitialized.

classmethod close() → None

Clean up Newton physics resources.

classmethod create_builder(up_axis: str | None = None, **kwargs) → newton.ModelBuilder

Create a ModelBuilder configured with default settings.

Forwards NewtonShapeCfg defaults onto Newton’s upstream ModelBuilder.default_shape_cfg via checked_apply(). Falls back to wrapper defaults when no Newton config is active so rough-terrain margin/gap still apply during early construction.

Parameters:

• up_axis – Override for the up-axis. Defaults to None, which uses the manager’s _up_axis.

• **kwargs – Forwarded to ModelBuilder.

Returns:

New builder with up-axis and per-shape defaults (gap, margin) applied.

classmethod deregister_callback(callback_id: int | CallbackHandle) → None

Remove a registered callback.

Parameters:

callback_id – The ID or CallbackHandle returned by register_callback().

classmethod dispatch_event(event: PhysicsEvent, payload: Any = None) → None

Dispatch an event to all registered callbacks.

This is the default implementation using simple callback lists. Subclasses may override or extend with platform-specific dispatch.

Parameters:

• event – The event to dispatch.

• payload – Optional data to pass to callbacks.

classmethod fix_articulation_root(articulation_prim: Any, stage: Any = None) → Any

Ensure that an articulation root has one enabled world fixed joint.

The base implementation leaves the root in place. Backends whose parser requires a different root topology may relocate it and return the resulting root prim.

Parameters:

• articulation_prim – The articulation-root prim to fix.

• stage – The stage containing the prim. Defaults to the current stage.

Returns:

The articulation-root prim after backend normalization.

Raises:

NotImplementedError – If a new joint is needed and the root is not a rigid body.

classmethod forward() → None

Update articulation kinematics without stepping physics.

Update body poses from joint coordinates via the solver-specialized FK delegate (_eval_fk, bound to the active subclass’s _eval_fk_impl() in initialize_solver()). Only the articulations flagged dirty in _fk_reset_mask and _world_reset_mask (see invalidate_fk()) are updated. The masks are consumed (zeroed) afterwards so the next step() does not redundantly re-solve them.

The delegate (rather than a direct cls._eval_fk_impl call) is required because the data layer invokes NewtonManager.forward() on the base class, where cls is the base NewtonManager; the bound delegate dispatches to the concrete subclass override.

classmethod get_backend() → str

Get the tensor backend being used (“numpy” or “torch”).

classmethod get_contacts() → Contacts | None

Get the current Newton contact buffer, if the active solver exposes one.

classmethod get_control() → newton.Control

Get the control object.

classmethod get_device() → str

Get the physics simulation device.

classmethod get_dt() → float

Get the physics timestep. Alias for get_physics_dt().

classmethod get_model() → newton.Model

Get the Newton model.

When the active sim backend is Newton this returns the manager’s own authoritative model. When the active sim backend is PhysX a shadow Newton model is built lazily (from the visualizer prebuilt artifact) so renderers/visualizers that operate on Newton Model and State can still drive a PhysX-simulated scene.

classmethod get_physics_dt() → float

Get the physics timestep in seconds.

classmethod get_physics_sim_view() → list

Get the list of registered views.

Assets can append their views to this list, and sensors can access them. Returns a list that callers can append to.

Returns:

List of registered views (e.g., NewtonArticulationView instances).

classmethod get_scene_data_backend() → SceneDataBackend | None

Return the SceneDataBackend for the SceneDataProvider.

classmethod get_scene_data_provider() → SceneDataProvider

Return the active scene data provider.

classmethod get_simulation_time() → float

Get the current simulation time in seconds.

classmethod get_solver_dt() → float

Get the solver substep timestep.

classmethod get_state(scene_data_provider: SceneDataProvider | None = None) → newton.State

Get the current Newton state for visualization.

Use this method from visualizers/renderers/video recorders that need a backend-agnostic Newton State. When the sim backend is PhysX this refreshes the shadow _state_0.body_q from the live PhysX scene via update_visualization_state() before returning, so callers never observe stale transforms. Under the Newton sim backend, pending forward kinematics is applied before returning the live state.

classmethod get_state_0() → newton.State

Get the current state.

classmethod get_state_1() → newton.State

Get the next state.

classmethod handles_decimation() → bool

True when step() executes the full decimation loop internally.

This is the case when all Newton actuators are CUDA-graph-safe. The full decimation loop (including the trivial decimation=1 case) is folded into a single step() call.

classmethod initialize(sim_context: SimulationContext) → None

Initialize the manager with simulation context.

Parameters:

sim_context – Parent simulation context.

classmethod initialize_solver() → None

Initialize the solver and collision pipeline.

Thin orchestrator: delegates solver construction to _build_solver() (overridden by each solver subclass), allocates the collision pipeline (when applicable) via _initialize_contacts(), then either captures the CUDA graph immediately or defers capture until the first step() call (RTX-active path).

Warning

When using a CUDA-enabled device, the simulation is graphed. This means the function steps the simulation once to capture the graph, so it should only be called after everything else in the simulation is initialized.

classmethod instantiate_builder_from_stage()

Create builder from USD stage.

Detects env Xforms (e.g. /World/Env_0, /World/Env_1) and builds each as a separate Newton world via begin_world/end_world. Falls back to a flat add_usd when no env Xforms are found.

classmethod invalidate_body_state(env_ids: wp.array(dtype=wp.int32) | None = None, env_mask: wp.array(dtype=wp.bool) | None = None) → None

Mark selected maximal-coordinate body state as changed without requesting FK.

Parameters:

• env_ids – Integer indices of dirtied environments. Used by index write methods.

• env_mask – Boolean mask of dirtied environments. Used by mask write methods.

classmethod invalidate_fk(env_mask: wp.array | None = None, env_ids: wp.array | None = None, articulation_ids: wp.array | None = None) → None

Mark environments as needing FK recomputation and solver reset.

Called by asset write methods that modify joint coordinates or root transforms. The masks are consumed by the next forward, raw-state, rendering, or physics-step boundary.

Parameters:

• env_mask – Boolean mask of dirtied environments. Shape (num_envs,). Used by _mask write methods.

• env_ids – Integer indices of dirtied environments. Used by _index write methods.

• articulation_ids – Mapping from (world, arti) to model articulation index. Shape (world_count, count_per_world). Obtained from ArticulationView.articulation_ids.

classmethod is_fabric_enabled() → bool

Check if fabric interface is enabled (not applicable for Newton).

classmethod pause() → None

Pause physics simulation. Default is no-op.

classmethod play() → None

Start or resume physics simulation. Default is no-op.

classmethod pre_render() → None

Refresh derived Newton state before cameras and visualizers read it.

classmethod register_callback(callback: Callable, event: PhysicsEvent, order: int = 0, name: str | None = None, wrap_weak_ref: bool = True) → CallbackHandle

Register a callback. Passes event to parent class.

classmethod register_particle_visual_prim(prim_path: str, particle_offset: int, particle_count: int, sync_frequency: int = 1) → None

Register a UsdGeom.Points prim whose points mirror a slice of Newton’s particle state.

Parameters:

• prim_path – Stage path of an existing UsdGeom.Points prim.

• particle_offset – First index of the prim’s slice in state.particle_q.

• particle_count – Number of particles in the slice.

• sync_frequency – Sync the prim every N dirty render frames.

classmethod register_post_actuator_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the actuator step on every iteration.

Each callback runs inside the captured CUDA graph (when _is_all_graphable() is True) right after NewtonActuatorAdapter.step() and before the solver substeps, so kernel writes to state/control are visible to the integrator on the same iteration. Multiple articulations register their own implicit-DOF telemetry / FF-routing kernels here; all registered callbacks fire in registration order each step.

classmethod register_post_step_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the last solver substep on every step.

Each callback runs inside the stepped (and, when _is_all_graphable() is True, captured) region right after the final solver substep of the decimation loop and before _update_sensors(), so the launches it issues are recorded into every captured CUDA graph and replayed on each tick. The hook fires exactly once per step() call, reflecting the state after all decimation iterations (and their solver substeps) have completed – not once per substep and not once per decimation iteration. Callbacks must be graph-safe (fixed shapes, no host branching on device data) and must be registered before capture. Articulations with non-identity ordering register their backend-to-user state republish here; all registered callbacks fire in registration order each step.

classmethod register_state_force_callback(callback: Callable[[newton.State], None]) → None

Register a graph-safe callback that applies forces before every solver substep.

Callbacks must be registered before solver initialization so they are included in CUDA graph capture.

Parameters:

callback – Function that adds forces [N, N·m] to the provided state.

classmethod request_extended_contact_attribute(attr: str) → None

Request an extended contact attribute (e.g. "force").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the model in start_simulation() so that subsequent Contacts creation includes them.

Parameters:

attr – Contact attribute name.

classmethod request_extended_state_attribute(attr: str) → None

Request an extended state attribute (e.g. "body_qdd").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the builder in start_simulation() so that subsequent model.state() calls allocate them.

Parameters:

attr – State attribute name (must be in State.EXTENDED_ATTRIBUTES).

classmethod reset(soft: bool = False) → None

Reset physics simulation.

A hard reset (soft=False) re-finalizes the Newton model, reallocating its device arrays. The cached collision pipeline, contacts and any captured CUDA graph reference the old buffers, so they are released here and rebuilt against the re-finalized model by initialize_solver(). This avoids the illegal CUDA memory access (CUDA error 700) that would otherwise occur on the first step after a hard reset.

A soft reset (soft=True) skips this full reinitialization and reuses the existing model, solver, collision pipeline and CUDA graph.

Parameters:

soft – If True, skip full reinitialization.

static safe_callback_invoke(fn: Callable, *args, physics_manager: type[PhysicsManager] | None = None) → None

Invoke a callback, catching exceptions that would be swallowed by external event buses.

Ignores ReferenceError (from garbage-collected weakref proxies). All other exceptions are forwarded to physics_manager.``store_callback_exception`` when available (see note below), or re-raised immediately otherwise.

Note (Octi):

The carb event bus used by PhysX/Omniverse silently swallows exceptions raised inside callbacks. PhysxManager works around this by storing the exception and re-raising it after event dispatch completes (in reset() / step()). Backends that dispatch events directly (e.g. Newton) don’t need this — exceptions propagate normally — so store_callback_exception is not called for them. This is a known wart; a cleaner solution is actively being explored.

classmethod set_builder(builder: newton.ModelBuilder) → None

Set the Newton model builder.

classmethod set_decimation(decimation: int) → None

Set the decimation count and re-capture the CUDA graph.

When all actuators are graphable the entire decimation loop (actuators + solver substeps, repeated decimation times) is captured as a single CUDA graph.

If a CUDA graph was previously captured, it is automatically re-captured with the new decimation count using the same strategy as start_simulation(): standard wp.ScopedCapture when no USDRT stage is active, or deferred relaxed capture when RTX is running. Solvers with reset-dependent topology may also defer standard capture.

classmethod start_simulation() → None

Start simulation by finalizing model and initializing state.

This function finalizes the model and initializes the simulation state. Note: Collision pipeline is initialized later in initialize_solver() after we determine whether the solver needs external collision detection.

classmethod step() → None

Step the physics simulation.

The stepping logic follows one of two paths depending on whether all actuators are CUDA-graph-safe:

All-graphable path (_simulate_full()):

Actuators and solver substeps are captured together in a single CUDA graph containing the full decimation x (actuators + solver substeps) loop.

Eager-actuator path (fallback, some actuators not graph-safe):

Actuators are stepped eagerly on the CPU timeline (outside the graph), then a graph containing only the solver substeps is launched via _simulate_physics_only().

In both paths the sequence within one physics step is:

zero actuated DOFs in control.joint_f
-> actuator.step (computes effort, writes to control.joint_f)
-> solver.step x num_substeps (integrates, reads control.joint_f)
-> sensors.update

classmethod stop() → None

Stop physics simulation. Default is no-op.

classmethod sync_cables_to_usd() → None

Write Newton cable segment endpoints to Fabric curve points.

classmethod sync_particles_to_usd() → None

Write Newton particle positions to USD/Fabric for Kit viewport rendering.

Two prim families are synced from state_0.particle_q:

• Fabric mesh prims tagged with newton:particleOffset / newton:particleCount (deformable visual meshes) receive local-frame points on the GPU via _sync_fabric_mesh_particles().

• UsdGeom.Points prims registered through register_particle_visual_prim() (MPM particle clouds) receive world-frame points via _sync_particle_points_prims().

No-op when there is no particle state or nothing changed since the last sync.

classmethod sync_transforms_to_usd() → None

Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.

No-op when _usdrt_stage is None (i.e. Kit visualizer is not active) or when transforms have not changed since the last sync.

Called at render cadence by pre_render() (via render()). Physics stepping marks transforms dirty via _mark_transforms_dirty() so that the expensive Fabric hierarchy update only runs once per render frame rather than after every physics step.

Uses wp.fabricarray directly (no isaacsim.physics.newton extension needed). The Warp kernel reads state_0.body_q[newton_index[i]] and writes the corresponding mat44d to omni:fabric:worldMatrix for each prim.

When IFabricHierarchy.update_world_xforms_gpu_with_options is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then run the GPU hierarchy update with RIGID_BODY | FORCE_UPDATE so Newton-authored world matrices stay authoritative on rigid-body prims. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod unregister_post_step_callback(callback: Callable[[], None]) → None

Remove a previously registered post-step callback.

Symmetric to register_post_step_callback(), this lets an articulation deregister its republish hook when its callbacks are cleared so the bound method does not linger on the class-level list after the articulation is gone. Removing a callback that was never registered (or was already removed) is a safe no-op, matching the tolerant deregistration of other handles.

classmethod update_visualization_state(scene_data_provider: SceneDataProvider | None = None) → None

Refresh visualization state for the active sim backend.

Newton sim backend: no-op — _state_0 is the live, authoritative state already advanced by step() / forward kinematics.

PhysX / OVPhysX sim backend: pull rigid-body transforms and deformable nodal positions from the SceneDataProvider and write them into the shadow _state_0.body_q / particle_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses and mesh points.

Calls use allow_passthrough=False so identity mappings still copy into the pre-bound shadow buffers. Passthrough would rebind the temporary SceneDataFormat fields away from _state_0, leaving OVRTX and other get_state() consumers on stale rest-pose particle / body state.

Invoked lazily from get_state() so consumers do not need to coordinate the sync explicitly.

classmethod video_capture_backend() → str

Newton GL headless perspective video capture.

classmethod wait_for_playing() → None

Block until the timeline is playing. Default is no-op.

class isaaclab_newton.physics.NewtonVBDManager

Bases: NewtonManager

Newton manager specialization for the VBD solver.

Methods:

initialize(sim_context)	Initialize VBD deformable integration when contrib is available.
start_simulation()	Start simulation and bind registered deformables to Fabric.
instantiate_builder_from_stage()	Create and color the VBD builder from the USD stage.
activate_newton_actuator_path()	Opt an articulation into the Newton actuator fast path.
add_contact_sensor([body_names_expr, ...])	Add a contact sensor for reporting contacts between bodies/shapes.
add_frame_transform_sensor(shapes, ...)	Add a frame transform sensor for measuring relative transforms.
add_imu_sensor(sites)	Add an IMU sensor for measuring acceleration and angular velocity at sites.
add_model_change(change)	Register a model change to notify the solver.
after_visualizers_render()	Hook after visualizers have stepped during render().
cl_register_site(body_pattern, xform, *[, ...])	Register a site request for injection into prototypes before replication.
clear()	Clear all Newton-specific state (callbacks cleared by super().close()).
clear_callbacks()	Remove all registered callbacks.
close()	Clean up Newton physics resources.
create_builder([up_axis])	Create a ModelBuilder configured with default settings.
deregister_callback(callback_id)	Remove a registered callback.
dispatch_event(event[, payload])	Dispatch an event to all registered callbacks.
fix_articulation_root(articulation_prim[, stage])	Ensure that an articulation root has one enabled world fixed joint.
forward()	Update articulation kinematics without stepping physics.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
get_contacts()	Get the current Newton contact buffer, if the active solver exposes one.
get_control()	Get the control object.
get_device()	Get the physics simulation device.
get_dt()	Get the physics timestep.
get_model()	Get the Newton model.
get_physics_dt()	Get the physics timestep in seconds.
get_physics_sim_view()	Get the list of registered views.
get_scene_data_backend()	Return the SceneDataBackend for the SceneDataProvider.
get_scene_data_provider()	Return the active scene data provider.
get_simulation_time()	Get the current simulation time in seconds.
get_solver_dt()	Get the solver substep timestep.
get_state([scene_data_provider])	Get the current Newton state for visualization.
get_state_0()	Get the current state.
get_state_1()	Get the next state.
handles_decimation()	True when step() executes the full decimation loop internally.
initialize_solver()	Initialize the solver and collision pipeline.
invalidate_body_state([env_ids, env_mask])	Mark selected maximal-coordinate body state as changed without requesting FK.
invalidate_fk([env_mask, env_ids, ...])	Mark environments as needing FK recomputation and solver reset.
is_fabric_enabled()	Check if fabric interface is enabled (not applicable for Newton).
pause()	Pause physics simulation.
play()	Start or resume physics simulation.
pre_render()	Refresh derived Newton state before cameras and visualizers read it.
register_callback(callback, event[, order, ...])	Register a callback.
register_particle_visual_prim(prim_path, ...)	Register a UsdGeom.Points prim whose points mirror a slice of Newton's particle state.
register_post_actuator_callback(callback)	Append a hook to the list invoked after the actuator step on every iteration.
register_post_step_callback(callback)	Append a hook to the list invoked after the last solver substep on every step.
register_state_force_callback(callback)	Register a graph-safe callback that applies forces before every solver substep.
request_extended_contact_attribute(attr)	Request an extended contact attribute (e.g. "force").
request_extended_state_attribute(attr)	Request an extended state attribute (e.g. "body_qdd").
reset([soft])	Reset physics simulation.
safe_callback_invoke(fn, *args[, ...])	Invoke a callback, catching exceptions that would be swallowed by external event buses.
set_builder(builder)	Set the Newton model builder.
set_decimation(decimation)	Set the decimation count and re-capture the CUDA graph.
step()	Step the physics simulation.
stop()	Stop physics simulation.
sync_cables_to_usd()	Write Newton cable segment endpoints to Fabric curve points.
sync_particles_to_usd()	Write Newton particle positions to USD/Fabric for Kit viewport rendering.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
unregister_post_step_callback(callback)	Remove a previously registered post-step callback.
update_visualization_state([scene_data_provider])	Refresh visualization state for the active sim backend.
video_capture_backend()	Newton GL headless perspective video capture.
wait_for_playing()	Block until the timeline is playing.

classmethod initialize(sim_context: SimulationContext) → None

Initialize VBD deformable integration when contrib is available.

classmethod start_simulation() → None

Start simulation and bind registered deformables to Fabric.

classmethod instantiate_builder_from_stage() → None

Create and color the VBD builder from the USD stage.

classmethod activate_newton_actuator_path() → None

Opt an articulation into the Newton actuator fast path.

Idempotent — called by every Newton-fast-path articulation’s _process_actuators_cfg:

1. Sets _use_newton_actuators_active, which _is_all_graphable() checks (adapter presence alone cannot distinguish the fast path from the standard Lab path).

2. On first call, builds the single sim-level NewtonActuatorAdapter over the full flat DOF layout; later calls reuse it.

classmethod add_contact_sensor(body_names_expr: str | list[str] | None = None, shape_names_expr: str | list[str] | None = None, contact_partners_body_expr: str | list[str] | None = None, contact_partners_shape_expr: str | list[str] | None = None, verbose: bool = False) → tuple[str | list[str] | None, str | list[str] | None, str | list[str] | None, str | list[str] | None]

Add a contact sensor for reporting contacts between bodies/shapes.

Converts Isaac Lab pattern conventions (.* regex, full USD paths) to fnmatch globs and delegates to newton.sensors.SensorContact.

Parameters:

• body_names_expr – Expression for body names to sense.

• shape_names_expr – Expression for shape names to sense.

• contact_partners_body_expr – Expression for contact partner body names.

• contact_partners_shape_expr – Expression for contact partner shape names.

• verbose – Print verbose information.

classmethod add_frame_transform_sensor(shapes: list[int], reference_sites: list[int]) → int

Add a frame transform sensor for measuring relative transforms.

Creates a SensorFrameTransform from pre-resolved shape and reference site indices, appends it to the internal list, and returns its index.

Parameters:

• shapes – Ordered list of shape indices to measure.

• reference_sites – 1:1 list of reference site indices (same length as shapes).

Returns:

Index of the newly created sensor in _newton_frame_transform_sensors.

classmethod add_imu_sensor(sites: list[int]) → int

Add an IMU sensor for measuring acceleration and angular velocity at sites.

Creates a newton.sensors.SensorIMU from pre-resolved site indices, appends it to the internal list, and returns its index.

Parameters:

sites – Ordered list of site indices (one per environment).

Returns:

Index of the newly created sensor in the internal IMU sensor list.

classmethod add_model_change(change: newton.ModelFlags) → None

Register a model change to notify the solver.

classmethod after_visualizers_render() → None

Hook after visualizers have stepped during render().

Use for physics-backend sync (e.g. fabric) if needed. Default is a no-op.

classmethod cl_register_site(body_pattern: str | None, xform: warp.transform, *, per_world: bool = False) → str

Register a site request for injection into prototypes before replication.

Sensors call this during __init__. Sites are injected into prototype builders by _cl_inject_sites() (called from newton_replicate) before add_builder, so they replicate correctly per-world.

Identical (body_pattern, per_world, transform) registrations share sites.

The body_pattern is matched against prototype-local body labels (e.g. "Robot/link.*") when replication is active, or against the flat builder’s body labels in the fallback path. Wildcard patterns that match multiple bodies create one site per matched body.

Parameters:

• body_pattern – Regex pattern matched against body labels in the prototype builder (e.g. "Robot/link0" or "Robot/finger.*" for multi-body wildcards), or None for global sites (world-origin reference, etc.).

• xform – Site transform relative to body.

• per_world – When True, body_pattern must be None and one bodyless site is created in each cloned world’s frame.

Returns:

Assigned site label suffix.

classmethod clear()

Clear all Newton-specific state (callbacks cleared by super().close()).

classmethod clear_callbacks() → None

Remove all registered callbacks.

Do NOT reset _callback_id — handle IDs must remain monotonically unique across the lifetime of the process. Resetting the counter would let a future register_callback() hand out an ID that an old, still-alive CallbackHandle (e.g. on a sensor that has not been garbage-collected yet) holds, so when the old object eventually finalizes its __del__ would deregister the new callback. This bit ovphysx’s kitless multi-context tests where two InteractiveScene``s are created in sequence: the first scene's sensor would post-GC deregister the second scene's ``_initialize_callback by ID collision, leaving the second sensor forever uninitialized.

classmethod close() → None

Clean up Newton physics resources.

classmethod create_builder(up_axis: str | None = None, **kwargs) → newton.ModelBuilder

Create a ModelBuilder configured with default settings.

Forwards NewtonShapeCfg defaults onto Newton’s upstream ModelBuilder.default_shape_cfg via checked_apply(). Falls back to wrapper defaults when no Newton config is active so rough-terrain margin/gap still apply during early construction.

Parameters:

• up_axis – Override for the up-axis. Defaults to None, which uses the manager’s _up_axis.

• **kwargs – Forwarded to ModelBuilder.

Returns:

New builder with up-axis and per-shape defaults (gap, margin) applied.

classmethod deregister_callback(callback_id: int | CallbackHandle) → None

Remove a registered callback.

Parameters:

callback_id – The ID or CallbackHandle returned by register_callback().

classmethod dispatch_event(event: PhysicsEvent, payload: Any = None) → None

Dispatch an event to all registered callbacks.

This is the default implementation using simple callback lists. Subclasses may override or extend with platform-specific dispatch.

Parameters:

• event – The event to dispatch.

• payload – Optional data to pass to callbacks.

classmethod fix_articulation_root(articulation_prim: Any, stage: Any = None) → Any

Ensure that an articulation root has one enabled world fixed joint.

The base implementation leaves the root in place. Backends whose parser requires a different root topology may relocate it and return the resulting root prim.

Parameters:

• articulation_prim – The articulation-root prim to fix.

• stage – The stage containing the prim. Defaults to the current stage.

Returns:

The articulation-root prim after backend normalization.

Raises:

NotImplementedError – If a new joint is needed and the root is not a rigid body.

classmethod forward() → None

Update articulation kinematics without stepping physics.

Update body poses from joint coordinates via the solver-specialized FK delegate (_eval_fk, bound to the active subclass’s _eval_fk_impl() in initialize_solver()). Only the articulations flagged dirty in _fk_reset_mask and _world_reset_mask (see invalidate_fk()) are updated. The masks are consumed (zeroed) afterwards so the next step() does not redundantly re-solve them.

The delegate (rather than a direct cls._eval_fk_impl call) is required because the data layer invokes NewtonManager.forward() on the base class, where cls is the base NewtonManager; the bound delegate dispatches to the concrete subclass override.

classmethod get_backend() → str

Get the tensor backend being used (“numpy” or “torch”).

classmethod get_contacts() → Contacts | None

Get the current Newton contact buffer, if the active solver exposes one.

classmethod get_control() → newton.Control

Get the control object.

classmethod get_device() → str

Get the physics simulation device.

classmethod get_dt() → float

Get the physics timestep. Alias for get_physics_dt().

classmethod get_model() → newton.Model

Get the Newton model.

When the active sim backend is Newton this returns the manager’s own authoritative model. When the active sim backend is PhysX a shadow Newton model is built lazily (from the visualizer prebuilt artifact) so renderers/visualizers that operate on Newton Model and State can still drive a PhysX-simulated scene.

classmethod get_physics_dt() → float

Get the physics timestep in seconds.

classmethod get_physics_sim_view() → list

Get the list of registered views.

Assets can append their views to this list, and sensors can access them. Returns a list that callers can append to.

Returns:

List of registered views (e.g., NewtonArticulationView instances).

classmethod get_scene_data_backend() → SceneDataBackend | None

Return the SceneDataBackend for the SceneDataProvider.

classmethod get_scene_data_provider() → SceneDataProvider

Return the active scene data provider.

classmethod get_simulation_time() → float

Get the current simulation time in seconds.

classmethod get_solver_dt() → float

Get the solver substep timestep.

classmethod get_state(scene_data_provider: SceneDataProvider | None = None) → newton.State

Get the current Newton state for visualization.

Use this method from visualizers/renderers/video recorders that need a backend-agnostic Newton State. When the sim backend is PhysX this refreshes the shadow _state_0.body_q from the live PhysX scene via update_visualization_state() before returning, so callers never observe stale transforms. Under the Newton sim backend, pending forward kinematics is applied before returning the live state.

classmethod get_state_0() → newton.State

Get the current state.

classmethod get_state_1() → newton.State

Get the next state.

classmethod handles_decimation() → bool

True when step() executes the full decimation loop internally.

This is the case when all Newton actuators are CUDA-graph-safe. The full decimation loop (including the trivial decimation=1 case) is folded into a single step() call.

classmethod initialize_solver() → None

Initialize the solver and collision pipeline.

Thin orchestrator: delegates solver construction to _build_solver() (overridden by each solver subclass), allocates the collision pipeline (when applicable) via _initialize_contacts(), then either captures the CUDA graph immediately or defers capture until the first step() call (RTX-active path).

Warning

When using a CUDA-enabled device, the simulation is graphed. This means the function steps the simulation once to capture the graph, so it should only be called after everything else in the simulation is initialized.

classmethod invalidate_body_state(env_ids: wp.array(dtype=wp.int32) | None = None, env_mask: wp.array(dtype=wp.bool) | None = None) → None

Mark selected maximal-coordinate body state as changed without requesting FK.

Parameters:

• env_ids – Integer indices of dirtied environments. Used by index write methods.

• env_mask – Boolean mask of dirtied environments. Used by mask write methods.

classmethod invalidate_fk(env_mask: wp.array | None = None, env_ids: wp.array | None = None, articulation_ids: wp.array | None = None) → None

Mark environments as needing FK recomputation and solver reset.

Called by asset write methods that modify joint coordinates or root transforms. The masks are consumed by the next forward, raw-state, rendering, or physics-step boundary.

Parameters:

• env_mask – Boolean mask of dirtied environments. Shape (num_envs,). Used by _mask write methods.

• env_ids – Integer indices of dirtied environments. Used by _index write methods.

• articulation_ids – Mapping from (world, arti) to model articulation index. Shape (world_count, count_per_world). Obtained from ArticulationView.articulation_ids.

classmethod is_fabric_enabled() → bool

Check if fabric interface is enabled (not applicable for Newton).

classmethod pause() → None

Pause physics simulation. Default is no-op.

classmethod play() → None

Start or resume physics simulation. Default is no-op.

classmethod pre_render() → None

Refresh derived Newton state before cameras and visualizers read it.

classmethod register_callback(callback: Callable, event: PhysicsEvent, order: int = 0, name: str | None = None, wrap_weak_ref: bool = True) → CallbackHandle

Register a callback. Passes event to parent class.

classmethod register_particle_visual_prim(prim_path: str, particle_offset: int, particle_count: int, sync_frequency: int = 1) → None

Register a UsdGeom.Points prim whose points mirror a slice of Newton’s particle state.

Parameters:

• prim_path – Stage path of an existing UsdGeom.Points prim.

• particle_offset – First index of the prim’s slice in state.particle_q.

• particle_count – Number of particles in the slice.

• sync_frequency – Sync the prim every N dirty render frames.

classmethod register_post_actuator_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the actuator step on every iteration.

Each callback runs inside the captured CUDA graph (when _is_all_graphable() is True) right after NewtonActuatorAdapter.step() and before the solver substeps, so kernel writes to state/control are visible to the integrator on the same iteration. Multiple articulations register their own implicit-DOF telemetry / FF-routing kernels here; all registered callbacks fire in registration order each step.

classmethod register_post_step_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the last solver substep on every step.

Each callback runs inside the stepped (and, when _is_all_graphable() is True, captured) region right after the final solver substep of the decimation loop and before _update_sensors(), so the launches it issues are recorded into every captured CUDA graph and replayed on each tick. The hook fires exactly once per step() call, reflecting the state after all decimation iterations (and their solver substeps) have completed – not once per substep and not once per decimation iteration. Callbacks must be graph-safe (fixed shapes, no host branching on device data) and must be registered before capture. Articulations with non-identity ordering register their backend-to-user state republish here; all registered callbacks fire in registration order each step.

classmethod register_state_force_callback(callback: Callable[[newton.State], None]) → None

Register a graph-safe callback that applies forces before every solver substep.

Callbacks must be registered before solver initialization so they are included in CUDA graph capture.

Parameters:

callback – Function that adds forces [N, N·m] to the provided state.

classmethod request_extended_contact_attribute(attr: str) → None

Request an extended contact attribute (e.g. "force").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the model in start_simulation() so that subsequent Contacts creation includes them.

Parameters:

attr – Contact attribute name.

classmethod request_extended_state_attribute(attr: str) → None

Request an extended state attribute (e.g. "body_qdd").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the builder in start_simulation() so that subsequent model.state() calls allocate them.

Parameters:

attr – State attribute name (must be in State.EXTENDED_ATTRIBUTES).

classmethod reset(soft: bool = False) → None

Reset physics simulation.

A hard reset (soft=False) re-finalizes the Newton model, reallocating its device arrays. The cached collision pipeline, contacts and any captured CUDA graph reference the old buffers, so they are released here and rebuilt against the re-finalized model by initialize_solver(). This avoids the illegal CUDA memory access (CUDA error 700) that would otherwise occur on the first step after a hard reset.

A soft reset (soft=True) skips this full reinitialization and reuses the existing model, solver, collision pipeline and CUDA graph.

Parameters:

soft – If True, skip full reinitialization.

static safe_callback_invoke(fn: Callable, *args, physics_manager: type[PhysicsManager] | None = None) → None

Invoke a callback, catching exceptions that would be swallowed by external event buses.

Ignores ReferenceError (from garbage-collected weakref proxies). All other exceptions are forwarded to physics_manager.``store_callback_exception`` when available (see note below), or re-raised immediately otherwise.

Note (Octi):

The carb event bus used by PhysX/Omniverse silently swallows exceptions raised inside callbacks. PhysxManager works around this by storing the exception and re-raising it after event dispatch completes (in reset() / step()). Backends that dispatch events directly (e.g. Newton) don’t need this — exceptions propagate normally — so store_callback_exception is not called for them. This is a known wart; a cleaner solution is actively being explored.

classmethod set_builder(builder: newton.ModelBuilder) → None

Set the Newton model builder.

classmethod set_decimation(decimation: int) → None

Set the decimation count and re-capture the CUDA graph.

When all actuators are graphable the entire decimation loop (actuators + solver substeps, repeated decimation times) is captured as a single CUDA graph.

If a CUDA graph was previously captured, it is automatically re-captured with the new decimation count using the same strategy as start_simulation(): standard wp.ScopedCapture when no USDRT stage is active, or deferred relaxed capture when RTX is running. Solvers with reset-dependent topology may also defer standard capture.

classmethod step() → None

Step the physics simulation.

The stepping logic follows one of two paths depending on whether all actuators are CUDA-graph-safe:

All-graphable path (_simulate_full()):

Actuators and solver substeps are captured together in a single CUDA graph containing the full decimation x (actuators + solver substeps) loop.

Eager-actuator path (fallback, some actuators not graph-safe):

Actuators are stepped eagerly on the CPU timeline (outside the graph), then a graph containing only the solver substeps is launched via _simulate_physics_only().

In both paths the sequence within one physics step is:

zero actuated DOFs in control.joint_f
-> actuator.step (computes effort, writes to control.joint_f)
-> solver.step x num_substeps (integrates, reads control.joint_f)
-> sensors.update

classmethod stop() → None

Stop physics simulation. Default is no-op.

classmethod sync_cables_to_usd() → None

Write Newton cable segment endpoints to Fabric curve points.

classmethod sync_particles_to_usd() → None

Write Newton particle positions to USD/Fabric for Kit viewport rendering.

Two prim families are synced from state_0.particle_q:

• Fabric mesh prims tagged with newton:particleOffset / newton:particleCount (deformable visual meshes) receive local-frame points on the GPU via _sync_fabric_mesh_particles().

• UsdGeom.Points prims registered through register_particle_visual_prim() (MPM particle clouds) receive world-frame points via _sync_particle_points_prims().

No-op when there is no particle state or nothing changed since the last sync.

classmethod sync_transforms_to_usd() → None

Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.

No-op when _usdrt_stage is None (i.e. Kit visualizer is not active) or when transforms have not changed since the last sync.

Called at render cadence by pre_render() (via render()). Physics stepping marks transforms dirty via _mark_transforms_dirty() so that the expensive Fabric hierarchy update only runs once per render frame rather than after every physics step.

Uses wp.fabricarray directly (no isaacsim.physics.newton extension needed). The Warp kernel reads state_0.body_q[newton_index[i]] and writes the corresponding mat44d to omni:fabric:worldMatrix for each prim.

When IFabricHierarchy.update_world_xforms_gpu_with_options is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then run the GPU hierarchy update with RIGID_BODY | FORCE_UPDATE so Newton-authored world matrices stay authoritative on rigid-body prims. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod unregister_post_step_callback(callback: Callable[[], None]) → None

Remove a previously registered post-step callback.

Symmetric to register_post_step_callback(), this lets an articulation deregister its republish hook when its callbacks are cleared so the bound method does not linger on the class-level list after the articulation is gone. Removing a callback that was never registered (or was already removed) is a safe no-op, matching the tolerant deregistration of other handles.

classmethod update_visualization_state(scene_data_provider: SceneDataProvider | None = None) → None

Refresh visualization state for the active sim backend.

Newton sim backend: no-op — _state_0 is the live, authoritative state already advanced by step() / forward kinematics.

PhysX / OVPhysX sim backend: pull rigid-body transforms and deformable nodal positions from the SceneDataProvider and write them into the shadow _state_0.body_q / particle_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses and mesh points.

Calls use allow_passthrough=False so identity mappings still copy into the pre-bound shadow buffers. Passthrough would rebind the temporary SceneDataFormat fields away from _state_0, leaving OVRTX and other get_state() consumers on stale rest-pose particle / body state.

Invoked lazily from get_state() so consumers do not need to coordinate the sync explicitly.

classmethod video_capture_backend() → str

Newton GL headless perspective video capture.

classmethod wait_for_playing() → None

Block until the timeline is playing. Default is no-op.

class isaaclab_newton.physics.NewtonXPBDManager

Bases: NewtonManager

NewtonManager specialization for the XPBD solver.

Always uses Newton’s CollisionPipeline for contact handling.

Methods:

activate_newton_actuator_path()	Opt an articulation into the Newton actuator fast path.
add_contact_sensor([body_names_expr, ...])	Add a contact sensor for reporting contacts between bodies/shapes.
add_frame_transform_sensor(shapes, ...)	Add a frame transform sensor for measuring relative transforms.
add_imu_sensor(sites)	Add an IMU sensor for measuring acceleration and angular velocity at sites.
add_model_change(change)	Register a model change to notify the solver.
after_visualizers_render()	Hook after visualizers have stepped during render().
cl_register_site(body_pattern, xform, *[, ...])	Register a site request for injection into prototypes before replication.
clear()	Clear all Newton-specific state (callbacks cleared by super().close()).
clear_callbacks()	Remove all registered callbacks.
close()	Clean up Newton physics resources.
create_builder([up_axis])	Create a ModelBuilder configured with default settings.
deregister_callback(callback_id)	Remove a registered callback.
dispatch_event(event[, payload])	Dispatch an event to all registered callbacks.
fix_articulation_root(articulation_prim[, stage])	Ensure that an articulation root has one enabled world fixed joint.
forward()	Update articulation kinematics without stepping physics.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
get_contacts()	Get the current Newton contact buffer, if the active solver exposes one.
get_control()	Get the control object.
get_device()	Get the physics simulation device.
get_dt()	Get the physics timestep.
get_model()	Get the Newton model.
get_physics_dt()	Get the physics timestep in seconds.
get_physics_sim_view()	Get the list of registered views.
get_scene_data_backend()	Return the SceneDataBackend for the SceneDataProvider.
get_scene_data_provider()	Return the active scene data provider.
get_simulation_time()	Get the current simulation time in seconds.
get_solver_dt()	Get the solver substep timestep.
get_state([scene_data_provider])	Get the current Newton state for visualization.
get_state_0()	Get the current state.
get_state_1()	Get the next state.
handles_decimation()	True when step() executes the full decimation loop internally.
initialize(sim_context)	Initialize the manager with simulation context.
initialize_solver()	Initialize the solver and collision pipeline.
instantiate_builder_from_stage()	Create builder from USD stage.
invalidate_body_state([env_ids, env_mask])	Mark selected maximal-coordinate body state as changed without requesting FK.
invalidate_fk([env_mask, env_ids, ...])	Mark environments as needing FK recomputation and solver reset.
is_fabric_enabled()	Check if fabric interface is enabled (not applicable for Newton).
pause()	Pause physics simulation.
play()	Start or resume physics simulation.
pre_render()	Refresh derived Newton state before cameras and visualizers read it.
register_callback(callback, event[, order, ...])	Register a callback.
register_particle_visual_prim(prim_path, ...)	Register a UsdGeom.Points prim whose points mirror a slice of Newton's particle state.
register_post_actuator_callback(callback)	Append a hook to the list invoked after the actuator step on every iteration.
register_post_step_callback(callback)	Append a hook to the list invoked after the last solver substep on every step.
register_state_force_callback(callback)	Register a graph-safe callback that applies forces before every solver substep.
request_extended_contact_attribute(attr)	Request an extended contact attribute (e.g. "force").
request_extended_state_attribute(attr)	Request an extended state attribute (e.g. "body_qdd").
reset([soft])	Reset physics simulation.
safe_callback_invoke(fn, *args[, ...])	Invoke a callback, catching exceptions that would be swallowed by external event buses.
set_builder(builder)	Set the Newton model builder.
set_decimation(decimation)	Set the decimation count and re-capture the CUDA graph.
start_simulation()	Start simulation by finalizing model and initializing state.
step()	Step the physics simulation.
stop()	Stop physics simulation.
sync_cables_to_usd()	Write Newton cable segment endpoints to Fabric curve points.
sync_particles_to_usd()	Write Newton particle positions to USD/Fabric for Kit viewport rendering.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
unregister_post_step_callback(callback)	Remove a previously registered post-step callback.
update_visualization_state([scene_data_provider])	Refresh visualization state for the active sim backend.
video_capture_backend()	Newton GL headless perspective video capture.
wait_for_playing()	Block until the timeline is playing.

classmethod activate_newton_actuator_path() → None

Opt an articulation into the Newton actuator fast path.

Idempotent — called by every Newton-fast-path articulation’s _process_actuators_cfg:

1. Sets _use_newton_actuators_active, which _is_all_graphable() checks (adapter presence alone cannot distinguish the fast path from the standard Lab path).

2. On first call, builds the single sim-level NewtonActuatorAdapter over the full flat DOF layout; later calls reuse it.

classmethod add_contact_sensor(body_names_expr: str | list[str] | None = None, shape_names_expr: str | list[str] | None = None, contact_partners_body_expr: str | list[str] | None = None, contact_partners_shape_expr: str | list[str] | None = None, verbose: bool = False) → tuple[str | list[str] | None, str | list[str] | None, str | list[str] | None, str | list[str] | None]

Add a contact sensor for reporting contacts between bodies/shapes.

Converts Isaac Lab pattern conventions (.* regex, full USD paths) to fnmatch globs and delegates to newton.sensors.SensorContact.

Parameters:

• body_names_expr – Expression for body names to sense.

• shape_names_expr – Expression for shape names to sense.

• contact_partners_body_expr – Expression for contact partner body names.

• contact_partners_shape_expr – Expression for contact partner shape names.

• verbose – Print verbose information.

classmethod add_frame_transform_sensor(shapes: list[int], reference_sites: list[int]) → int

Add a frame transform sensor for measuring relative transforms.

Creates a SensorFrameTransform from pre-resolved shape and reference site indices, appends it to the internal list, and returns its index.

Parameters:

• shapes – Ordered list of shape indices to measure.

• reference_sites – 1:1 list of reference site indices (same length as shapes).

Returns:

Index of the newly created sensor in _newton_frame_transform_sensors.

classmethod add_imu_sensor(sites: list[int]) → int

Add an IMU sensor for measuring acceleration and angular velocity at sites.

Creates a newton.sensors.SensorIMU from pre-resolved site indices, appends it to the internal list, and returns its index.

Parameters:

sites – Ordered list of site indices (one per environment).

Returns:

Index of the newly created sensor in the internal IMU sensor list.

classmethod add_model_change(change: newton.ModelFlags) → None

Register a model change to notify the solver.

classmethod after_visualizers_render() → None

Hook after visualizers have stepped during render().

Use for physics-backend sync (e.g. fabric) if needed. Default is a no-op.

classmethod cl_register_site(body_pattern: str | None, xform: warp.transform, *, per_world: bool = False) → str

Register a site request for injection into prototypes before replication.

Sensors call this during __init__. Sites are injected into prototype builders by _cl_inject_sites() (called from newton_replicate) before add_builder, so they replicate correctly per-world.

Identical (body_pattern, per_world, transform) registrations share sites.

The body_pattern is matched against prototype-local body labels (e.g. "Robot/link.*") when replication is active, or against the flat builder’s body labels in the fallback path. Wildcard patterns that match multiple bodies create one site per matched body.

Parameters:

• body_pattern – Regex pattern matched against body labels in the prototype builder (e.g. "Robot/link0" or "Robot/finger.*" for multi-body wildcards), or None for global sites (world-origin reference, etc.).

• xform – Site transform relative to body.

• per_world – When True, body_pattern must be None and one bodyless site is created in each cloned world’s frame.

Returns:

Assigned site label suffix.

classmethod clear()

Clear all Newton-specific state (callbacks cleared by super().close()).

classmethod clear_callbacks() → None

Remove all registered callbacks.

Do NOT reset _callback_id — handle IDs must remain monotonically unique across the lifetime of the process. Resetting the counter would let a future register_callback() hand out an ID that an old, still-alive CallbackHandle (e.g. on a sensor that has not been garbage-collected yet) holds, so when the old object eventually finalizes its __del__ would deregister the new callback. This bit ovphysx’s kitless multi-context tests where two InteractiveScene``s are created in sequence: the first scene's sensor would post-GC deregister the second scene's ``_initialize_callback by ID collision, leaving the second sensor forever uninitialized.

classmethod close() → None

Clean up Newton physics resources.

classmethod create_builder(up_axis: str | None = None, **kwargs) → newton.ModelBuilder

Create a ModelBuilder configured with default settings.

Forwards NewtonShapeCfg defaults onto Newton’s upstream ModelBuilder.default_shape_cfg via checked_apply(). Falls back to wrapper defaults when no Newton config is active so rough-terrain margin/gap still apply during early construction.

Parameters:

• up_axis – Override for the up-axis. Defaults to None, which uses the manager’s _up_axis.

• **kwargs – Forwarded to ModelBuilder.

Returns:

New builder with up-axis and per-shape defaults (gap, margin) applied.

classmethod deregister_callback(callback_id: int | CallbackHandle) → None

Remove a registered callback.

Parameters:

callback_id – The ID or CallbackHandle returned by register_callback().

classmethod dispatch_event(event: PhysicsEvent, payload: Any = None) → None

Dispatch an event to all registered callbacks.

This is the default implementation using simple callback lists. Subclasses may override or extend with platform-specific dispatch.

Parameters:

• event – The event to dispatch.

• payload – Optional data to pass to callbacks.

classmethod fix_articulation_root(articulation_prim: Any, stage: Any = None) → Any

Ensure that an articulation root has one enabled world fixed joint.

The base implementation leaves the root in place. Backends whose parser requires a different root topology may relocate it and return the resulting root prim.

Parameters:

• articulation_prim – The articulation-root prim to fix.

• stage – The stage containing the prim. Defaults to the current stage.

Returns:

The articulation-root prim after backend normalization.

Raises:

NotImplementedError – If a new joint is needed and the root is not a rigid body.

classmethod forward() → None

Update articulation kinematics without stepping physics.

Update body poses from joint coordinates via the solver-specialized FK delegate (_eval_fk, bound to the active subclass’s _eval_fk_impl() in initialize_solver()). Only the articulations flagged dirty in _fk_reset_mask and _world_reset_mask (see invalidate_fk()) are updated. The masks are consumed (zeroed) afterwards so the next step() does not redundantly re-solve them.

The delegate (rather than a direct cls._eval_fk_impl call) is required because the data layer invokes NewtonManager.forward() on the base class, where cls is the base NewtonManager; the bound delegate dispatches to the concrete subclass override.

classmethod get_backend() → str

Get the tensor backend being used (“numpy” or “torch”).

classmethod get_contacts() → Contacts | None

Get the current Newton contact buffer, if the active solver exposes one.

classmethod get_control() → newton.Control

Get the control object.

classmethod get_device() → str

Get the physics simulation device.

classmethod get_dt() → float

Get the physics timestep. Alias for get_physics_dt().

classmethod get_model() → newton.Model

Get the Newton model.

When the active sim backend is Newton this returns the manager’s own authoritative model. When the active sim backend is PhysX a shadow Newton model is built lazily (from the visualizer prebuilt artifact) so renderers/visualizers that operate on Newton Model and State can still drive a PhysX-simulated scene.

classmethod get_physics_dt() → float

Get the physics timestep in seconds.

classmethod get_physics_sim_view() → list

Get the list of registered views.

Assets can append their views to this list, and sensors can access them. Returns a list that callers can append to.

Returns:

List of registered views (e.g., NewtonArticulationView instances).

classmethod get_scene_data_backend() → SceneDataBackend | None

Return the SceneDataBackend for the SceneDataProvider.

classmethod get_scene_data_provider() → SceneDataProvider

Return the active scene data provider.

classmethod get_simulation_time() → float

Get the current simulation time in seconds.

classmethod get_solver_dt() → float

Get the solver substep timestep.

classmethod get_state(scene_data_provider: SceneDataProvider | None = None) → newton.State

Get the current Newton state for visualization.

Use this method from visualizers/renderers/video recorders that need a backend-agnostic Newton State. When the sim backend is PhysX this refreshes the shadow _state_0.body_q from the live PhysX scene via update_visualization_state() before returning, so callers never observe stale transforms. Under the Newton sim backend, pending forward kinematics is applied before returning the live state.

classmethod get_state_0() → newton.State

Get the current state.

classmethod get_state_1() → newton.State

Get the next state.

classmethod handles_decimation() → bool

True when step() executes the full decimation loop internally.

This is the case when all Newton actuators are CUDA-graph-safe. The full decimation loop (including the trivial decimation=1 case) is folded into a single step() call.

classmethod initialize(sim_context: SimulationContext) → None

Initialize the manager with simulation context.

Parameters:

sim_context – Parent simulation context.

classmethod initialize_solver() → None

Initialize the solver and collision pipeline.

Thin orchestrator: delegates solver construction to _build_solver() (overridden by each solver subclass), allocates the collision pipeline (when applicable) via _initialize_contacts(), then either captures the CUDA graph immediately or defers capture until the first step() call (RTX-active path).

Warning

When using a CUDA-enabled device, the simulation is graphed. This means the function steps the simulation once to capture the graph, so it should only be called after everything else in the simulation is initialized.

classmethod instantiate_builder_from_stage()

Create builder from USD stage.

Detects env Xforms (e.g. /World/Env_0, /World/Env_1) and builds each as a separate Newton world via begin_world/end_world. Falls back to a flat add_usd when no env Xforms are found.

classmethod invalidate_body_state(env_ids: wp.array(dtype=wp.int32) | None = None, env_mask: wp.array(dtype=wp.bool) | None = None) → None

Mark selected maximal-coordinate body state as changed without requesting FK.

Parameters:

• env_ids – Integer indices of dirtied environments. Used by index write methods.

• env_mask – Boolean mask of dirtied environments. Used by mask write methods.

classmethod invalidate_fk(env_mask: wp.array | None = None, env_ids: wp.array | None = None, articulation_ids: wp.array | None = None) → None

Mark environments as needing FK recomputation and solver reset.

Called by asset write methods that modify joint coordinates or root transforms. The masks are consumed by the next forward, raw-state, rendering, or physics-step boundary.

Parameters:

• env_mask – Boolean mask of dirtied environments. Shape (num_envs,). Used by _mask write methods.

• env_ids – Integer indices of dirtied environments. Used by _index write methods.

• articulation_ids – Mapping from (world, arti) to model articulation index. Shape (world_count, count_per_world). Obtained from ArticulationView.articulation_ids.

classmethod is_fabric_enabled() → bool

Check if fabric interface is enabled (not applicable for Newton).

classmethod pause() → None

Pause physics simulation. Default is no-op.

classmethod play() → None

Start or resume physics simulation. Default is no-op.

classmethod pre_render() → None

Refresh derived Newton state before cameras and visualizers read it.

classmethod register_callback(callback: Callable, event: PhysicsEvent, order: int = 0, name: str | None = None, wrap_weak_ref: bool = True) → CallbackHandle

Register a callback. Passes event to parent class.

classmethod register_particle_visual_prim(prim_path: str, particle_offset: int, particle_count: int, sync_frequency: int = 1) → None

Register a UsdGeom.Points prim whose points mirror a slice of Newton’s particle state.

Parameters:

• prim_path – Stage path of an existing UsdGeom.Points prim.

• particle_offset – First index of the prim’s slice in state.particle_q.

• particle_count – Number of particles in the slice.

• sync_frequency – Sync the prim every N dirty render frames.

classmethod register_post_actuator_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the actuator step on every iteration.

Each callback runs inside the captured CUDA graph (when _is_all_graphable() is True) right after NewtonActuatorAdapter.step() and before the solver substeps, so kernel writes to state/control are visible to the integrator on the same iteration. Multiple articulations register their own implicit-DOF telemetry / FF-routing kernels here; all registered callbacks fire in registration order each step.

classmethod register_post_step_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the last solver substep on every step.

Each callback runs inside the stepped (and, when _is_all_graphable() is True, captured) region right after the final solver substep of the decimation loop and before _update_sensors(), so the launches it issues are recorded into every captured CUDA graph and replayed on each tick. The hook fires exactly once per step() call, reflecting the state after all decimation iterations (and their solver substeps) have completed – not once per substep and not once per decimation iteration. Callbacks must be graph-safe (fixed shapes, no host branching on device data) and must be registered before capture. Articulations with non-identity ordering register their backend-to-user state republish here; all registered callbacks fire in registration order each step.

classmethod register_state_force_callback(callback: Callable[[newton.State], None]) → None

Register a graph-safe callback that applies forces before every solver substep.

Callbacks must be registered before solver initialization so they are included in CUDA graph capture.

Parameters:

callback – Function that adds forces [N, N·m] to the provided state.

classmethod request_extended_contact_attribute(attr: str) → None

Request an extended contact attribute (e.g. "force").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the model in start_simulation() so that subsequent Contacts creation includes them.

Parameters:

attr – Contact attribute name.

classmethod request_extended_state_attribute(attr: str) → None

Request an extended state attribute (e.g. "body_qdd").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the builder in start_simulation() so that subsequent model.state() calls allocate them.

Parameters:

attr – State attribute name (must be in State.EXTENDED_ATTRIBUTES).

classmethod reset(soft: bool = False) → None

Reset physics simulation.

A hard reset (soft=False) re-finalizes the Newton model, reallocating its device arrays. The cached collision pipeline, contacts and any captured CUDA graph reference the old buffers, so they are released here and rebuilt against the re-finalized model by initialize_solver(). This avoids the illegal CUDA memory access (CUDA error 700) that would otherwise occur on the first step after a hard reset.

A soft reset (soft=True) skips this full reinitialization and reuses the existing model, solver, collision pipeline and CUDA graph.

Parameters:

soft – If True, skip full reinitialization.

static safe_callback_invoke(fn: Callable, *args, physics_manager: type[PhysicsManager] | None = None) → None

Invoke a callback, catching exceptions that would be swallowed by external event buses.

Ignores ReferenceError (from garbage-collected weakref proxies). All other exceptions are forwarded to physics_manager.``store_callback_exception`` when available (see note below), or re-raised immediately otherwise.

Note (Octi):

The carb event bus used by PhysX/Omniverse silently swallows exceptions raised inside callbacks. PhysxManager works around this by storing the exception and re-raising it after event dispatch completes (in reset() / step()). Backends that dispatch events directly (e.g. Newton) don’t need this — exceptions propagate normally — so store_callback_exception is not called for them. This is a known wart; a cleaner solution is actively being explored.

classmethod set_builder(builder: newton.ModelBuilder) → None

Set the Newton model builder.

classmethod set_decimation(decimation: int) → None

Set the decimation count and re-capture the CUDA graph.

When all actuators are graphable the entire decimation loop (actuators + solver substeps, repeated decimation times) is captured as a single CUDA graph.

If a CUDA graph was previously captured, it is automatically re-captured with the new decimation count using the same strategy as start_simulation(): standard wp.ScopedCapture when no USDRT stage is active, or deferred relaxed capture when RTX is running. Solvers with reset-dependent topology may also defer standard capture.

classmethod start_simulation() → None

Start simulation by finalizing model and initializing state.

This function finalizes the model and initializes the simulation state. Note: Collision pipeline is initialized later in initialize_solver() after we determine whether the solver needs external collision detection.

classmethod step() → None

Step the physics simulation.

The stepping logic follows one of two paths depending on whether all actuators are CUDA-graph-safe:

All-graphable path (_simulate_full()):

Actuators and solver substeps are captured together in a single CUDA graph containing the full decimation x (actuators + solver substeps) loop.

Eager-actuator path (fallback, some actuators not graph-safe):

Actuators are stepped eagerly on the CPU timeline (outside the graph), then a graph containing only the solver substeps is launched via _simulate_physics_only().

In both paths the sequence within one physics step is:

zero actuated DOFs in control.joint_f
-> actuator.step (computes effort, writes to control.joint_f)
-> solver.step x num_substeps (integrates, reads control.joint_f)
-> sensors.update

classmethod stop() → None

Stop physics simulation. Default is no-op.

classmethod sync_cables_to_usd() → None

Write Newton cable segment endpoints to Fabric curve points.

classmethod sync_particles_to_usd() → None

Write Newton particle positions to USD/Fabric for Kit viewport rendering.

Two prim families are synced from state_0.particle_q:

• Fabric mesh prims tagged with newton:particleOffset / newton:particleCount (deformable visual meshes) receive local-frame points on the GPU via _sync_fabric_mesh_particles().

• UsdGeom.Points prims registered through register_particle_visual_prim() (MPM particle clouds) receive world-frame points via _sync_particle_points_prims().

No-op when there is no particle state or nothing changed since the last sync.

classmethod sync_transforms_to_usd() → None

Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.

No-op when _usdrt_stage is None (i.e. Kit visualizer is not active) or when transforms have not changed since the last sync.

Called at render cadence by pre_render() (via render()). Physics stepping marks transforms dirty via _mark_transforms_dirty() so that the expensive Fabric hierarchy update only runs once per render frame rather than after every physics step.

Uses wp.fabricarray directly (no isaacsim.physics.newton extension needed). The Warp kernel reads state_0.body_q[newton_index[i]] and writes the corresponding mat44d to omni:fabric:worldMatrix for each prim.

When IFabricHierarchy.update_world_xforms_gpu_with_options is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then run the GPU hierarchy update with RIGID_BODY | FORCE_UPDATE so Newton-authored world matrices stay authoritative on rigid-body prims. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod unregister_post_step_callback(callback: Callable[[], None]) → None

Remove a previously registered post-step callback.

Symmetric to register_post_step_callback(), this lets an articulation deregister its republish hook when its callbacks are cleared so the bound method does not linger on the class-level list after the articulation is gone. Removing a callback that was never registered (or was already removed) is a safe no-op, matching the tolerant deregistration of other handles.

classmethod update_visualization_state(scene_data_provider: SceneDataProvider | None = None) → None

Refresh visualization state for the active sim backend.

Newton sim backend: no-op — _state_0 is the live, authoritative state already advanced by step() / forward kinematics.

PhysX / OVPhysX sim backend: pull rigid-body transforms and deformable nodal positions from the SceneDataProvider and write them into the shadow _state_0.body_q / particle_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses and mesh points.

Calls use allow_passthrough=False so identity mappings still copy into the pre-bound shadow buffers. Passthrough would rebind the temporary SceneDataFormat fields away from _state_0, leaving OVRTX and other get_state() consumers on stale rest-pose particle / body state.

Invoked lazily from get_state() so consumers do not need to coordinate the sync explicitly.

classmethod video_capture_backend() → str

Newton GL headless perspective video capture.

classmethod wait_for_playing() → None

Block until the timeline is playing. Default is no-op.

class isaaclab_newton.physics.NewtonFeatherstoneManager

Bases: NewtonManager

NewtonManager specialization for the Featherstone solver.

Always uses Newton’s CollisionPipeline for contact handling.

Methods:

activate_newton_actuator_path()	Opt an articulation into the Newton actuator fast path.
add_contact_sensor([body_names_expr, ...])	Add a contact sensor for reporting contacts between bodies/shapes.
add_frame_transform_sensor(shapes, ...)	Add a frame transform sensor for measuring relative transforms.
add_imu_sensor(sites)	Add an IMU sensor for measuring acceleration and angular velocity at sites.
add_model_change(change)	Register a model change to notify the solver.
after_visualizers_render()	Hook after visualizers have stepped during render().
cl_register_site(body_pattern, xform, *[, ...])	Register a site request for injection into prototypes before replication.
clear()	Clear all Newton-specific state (callbacks cleared by super().close()).
clear_callbacks()	Remove all registered callbacks.
close()	Clean up Newton physics resources.
create_builder([up_axis])	Create a ModelBuilder configured with default settings.
deregister_callback(callback_id)	Remove a registered callback.
dispatch_event(event[, payload])	Dispatch an event to all registered callbacks.
fix_articulation_root(articulation_prim[, stage])	Ensure that an articulation root has one enabled world fixed joint.
forward()	Update articulation kinematics without stepping physics.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
get_contacts()	Get the current Newton contact buffer, if the active solver exposes one.
get_control()	Get the control object.
get_device()	Get the physics simulation device.
get_dt()	Get the physics timestep.
get_model()	Get the Newton model.
get_physics_dt()	Get the physics timestep in seconds.
get_physics_sim_view()	Get the list of registered views.
get_scene_data_backend()	Return the SceneDataBackend for the SceneDataProvider.
get_scene_data_provider()	Return the active scene data provider.
get_simulation_time()	Get the current simulation time in seconds.
get_solver_dt()	Get the solver substep timestep.
get_state([scene_data_provider])	Get the current Newton state for visualization.
get_state_0()	Get the current state.
get_state_1()	Get the next state.
handles_decimation()	True when step() executes the full decimation loop internally.
initialize(sim_context)	Initialize the manager with simulation context.
initialize_solver()	Initialize the solver and collision pipeline.
instantiate_builder_from_stage()	Create builder from USD stage.
invalidate_body_state([env_ids, env_mask])	Mark selected maximal-coordinate body state as changed without requesting FK.
invalidate_fk([env_mask, env_ids, ...])	Mark environments as needing FK recomputation and solver reset.
is_fabric_enabled()	Check if fabric interface is enabled (not applicable for Newton).
pause()	Pause physics simulation.
play()	Start or resume physics simulation.
pre_render()	Refresh derived Newton state before cameras and visualizers read it.
register_callback(callback, event[, order, ...])	Register a callback.
register_particle_visual_prim(prim_path, ...)	Register a UsdGeom.Points prim whose points mirror a slice of Newton's particle state.
register_post_actuator_callback(callback)	Append a hook to the list invoked after the actuator step on every iteration.
register_post_step_callback(callback)	Append a hook to the list invoked after the last solver substep on every step.
register_state_force_callback(callback)	Register a graph-safe callback that applies forces before every solver substep.
request_extended_contact_attribute(attr)	Request an extended contact attribute (e.g. "force").
request_extended_state_attribute(attr)	Request an extended state attribute (e.g. "body_qdd").
reset([soft])	Reset physics simulation.
safe_callback_invoke(fn, *args[, ...])	Invoke a callback, catching exceptions that would be swallowed by external event buses.
set_builder(builder)	Set the Newton model builder.
set_decimation(decimation)	Set the decimation count and re-capture the CUDA graph.
start_simulation()	Start simulation by finalizing model and initializing state.
step()	Step the physics simulation.
stop()	Stop physics simulation.
sync_cables_to_usd()	Write Newton cable segment endpoints to Fabric curve points.
sync_particles_to_usd()	Write Newton particle positions to USD/Fabric for Kit viewport rendering.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
unregister_post_step_callback(callback)	Remove a previously registered post-step callback.
update_visualization_state([scene_data_provider])	Refresh visualization state for the active sim backend.
video_capture_backend()	Newton GL headless perspective video capture.
wait_for_playing()	Block until the timeline is playing.

classmethod activate_newton_actuator_path() → None

Opt an articulation into the Newton actuator fast path.

Idempotent — called by every Newton-fast-path articulation’s _process_actuators_cfg:

1. Sets _use_newton_actuators_active, which _is_all_graphable() checks (adapter presence alone cannot distinguish the fast path from the standard Lab path).

2. On first call, builds the single sim-level NewtonActuatorAdapter over the full flat DOF layout; later calls reuse it.

classmethod add_contact_sensor(body_names_expr: str | list[str] | None = None, shape_names_expr: str | list[str] | None = None, contact_partners_body_expr: str | list[str] | None = None, contact_partners_shape_expr: str | list[str] | None = None, verbose: bool = False) → tuple[str | list[str] | None, str | list[str] | None, str | list[str] | None, str | list[str] | None]

Add a contact sensor for reporting contacts between bodies/shapes.

Converts Isaac Lab pattern conventions (.* regex, full USD paths) to fnmatch globs and delegates to newton.sensors.SensorContact.

Parameters:

• body_names_expr – Expression for body names to sense.

• shape_names_expr – Expression for shape names to sense.

• contact_partners_body_expr – Expression for contact partner body names.

• contact_partners_shape_expr – Expression for contact partner shape names.

• verbose – Print verbose information.

classmethod add_frame_transform_sensor(shapes: list[int], reference_sites: list[int]) → int

Add a frame transform sensor for measuring relative transforms.

Creates a SensorFrameTransform from pre-resolved shape and reference site indices, appends it to the internal list, and returns its index.

Parameters:

• shapes – Ordered list of shape indices to measure.

• reference_sites – 1:1 list of reference site indices (same length as shapes).

Returns:

Index of the newly created sensor in _newton_frame_transform_sensors.

classmethod add_imu_sensor(sites: list[int]) → int

Add an IMU sensor for measuring acceleration and angular velocity at sites.

Creates a newton.sensors.SensorIMU from pre-resolved site indices, appends it to the internal list, and returns its index.

Parameters:

sites – Ordered list of site indices (one per environment).

Returns:

Index of the newly created sensor in the internal IMU sensor list.

classmethod add_model_change(change: newton.ModelFlags) → None

Register a model change to notify the solver.

classmethod after_visualizers_render() → None

Hook after visualizers have stepped during render().

Use for physics-backend sync (e.g. fabric) if needed. Default is a no-op.

classmethod cl_register_site(body_pattern: str | None, xform: warp.transform, *, per_world: bool = False) → str

Register a site request for injection into prototypes before replication.

Sensors call this during __init__. Sites are injected into prototype builders by _cl_inject_sites() (called from newton_replicate) before add_builder, so they replicate correctly per-world.

Identical (body_pattern, per_world, transform) registrations share sites.

The body_pattern is matched against prototype-local body labels (e.g. "Robot/link.*") when replication is active, or against the flat builder’s body labels in the fallback path. Wildcard patterns that match multiple bodies create one site per matched body.

Parameters:

• body_pattern – Regex pattern matched against body labels in the prototype builder (e.g. "Robot/link0" or "Robot/finger.*" for multi-body wildcards), or None for global sites (world-origin reference, etc.).

• xform – Site transform relative to body.

• per_world – When True, body_pattern must be None and one bodyless site is created in each cloned world’s frame.

Returns:

Assigned site label suffix.

classmethod clear()

Clear all Newton-specific state (callbacks cleared by super().close()).

classmethod clear_callbacks() → None

Remove all registered callbacks.

Do NOT reset _callback_id — handle IDs must remain monotonically unique across the lifetime of the process. Resetting the counter would let a future register_callback() hand out an ID that an old, still-alive CallbackHandle (e.g. on a sensor that has not been garbage-collected yet) holds, so when the old object eventually finalizes its __del__ would deregister the new callback. This bit ovphysx’s kitless multi-context tests where two InteractiveScene``s are created in sequence: the first scene's sensor would post-GC deregister the second scene's ``_initialize_callback by ID collision, leaving the second sensor forever uninitialized.

classmethod close() → None

Clean up Newton physics resources.

classmethod create_builder(up_axis: str | None = None, **kwargs) → newton.ModelBuilder

Create a ModelBuilder configured with default settings.

Forwards NewtonShapeCfg defaults onto Newton’s upstream ModelBuilder.default_shape_cfg via checked_apply(). Falls back to wrapper defaults when no Newton config is active so rough-terrain margin/gap still apply during early construction.

Parameters:

• up_axis – Override for the up-axis. Defaults to None, which uses the manager’s _up_axis.

• **kwargs – Forwarded to ModelBuilder.

Returns:

New builder with up-axis and per-shape defaults (gap, margin) applied.

classmethod deregister_callback(callback_id: int | CallbackHandle) → None

Remove a registered callback.

Parameters:

callback_id – The ID or CallbackHandle returned by register_callback().

classmethod dispatch_event(event: PhysicsEvent, payload: Any = None) → None

Dispatch an event to all registered callbacks.

This is the default implementation using simple callback lists. Subclasses may override or extend with platform-specific dispatch.

Parameters:

• event – The event to dispatch.

• payload – Optional data to pass to callbacks.

classmethod fix_articulation_root(articulation_prim: Any, stage: Any = None) → Any

Ensure that an articulation root has one enabled world fixed joint.

The base implementation leaves the root in place. Backends whose parser requires a different root topology may relocate it and return the resulting root prim.

Parameters:

• articulation_prim – The articulation-root prim to fix.

• stage – The stage containing the prim. Defaults to the current stage.

Returns:

The articulation-root prim after backend normalization.

Raises:

NotImplementedError – If a new joint is needed and the root is not a rigid body.

classmethod forward() → None

Update articulation kinematics without stepping physics.

Update body poses from joint coordinates via the solver-specialized FK delegate (_eval_fk, bound to the active subclass’s _eval_fk_impl() in initialize_solver()). Only the articulations flagged dirty in _fk_reset_mask and _world_reset_mask (see invalidate_fk()) are updated. The masks are consumed (zeroed) afterwards so the next step() does not redundantly re-solve them.

The delegate (rather than a direct cls._eval_fk_impl call) is required because the data layer invokes NewtonManager.forward() on the base class, where cls is the base NewtonManager; the bound delegate dispatches to the concrete subclass override.

classmethod get_backend() → str

Get the tensor backend being used (“numpy” or “torch”).

classmethod get_contacts() → Contacts | None

Get the current Newton contact buffer, if the active solver exposes one.

classmethod get_control() → newton.Control

Get the control object.

classmethod get_device() → str

Get the physics simulation device.

classmethod get_dt() → float

Get the physics timestep. Alias for get_physics_dt().

classmethod get_model() → newton.Model

Get the Newton model.

When the active sim backend is Newton this returns the manager’s own authoritative model. When the active sim backend is PhysX a shadow Newton model is built lazily (from the visualizer prebuilt artifact) so renderers/visualizers that operate on Newton Model and State can still drive a PhysX-simulated scene.

classmethod get_physics_dt() → float

Get the physics timestep in seconds.

classmethod get_physics_sim_view() → list

Get the list of registered views.

Assets can append their views to this list, and sensors can access them. Returns a list that callers can append to.

Returns:

List of registered views (e.g., NewtonArticulationView instances).

classmethod get_scene_data_backend() → SceneDataBackend | None

Return the SceneDataBackend for the SceneDataProvider.

classmethod get_scene_data_provider() → SceneDataProvider

Return the active scene data provider.

classmethod get_simulation_time() → float

Get the current simulation time in seconds.

classmethod get_solver_dt() → float

Get the solver substep timestep.

classmethod get_state(scene_data_provider: SceneDataProvider | None = None) → newton.State

Get the current Newton state for visualization.

Use this method from visualizers/renderers/video recorders that need a backend-agnostic Newton State. When the sim backend is PhysX this refreshes the shadow _state_0.body_q from the live PhysX scene via update_visualization_state() before returning, so callers never observe stale transforms. Under the Newton sim backend, pending forward kinematics is applied before returning the live state.

classmethod get_state_0() → newton.State

Get the current state.

classmethod get_state_1() → newton.State

Get the next state.

classmethod handles_decimation() → bool

True when step() executes the full decimation loop internally.

This is the case when all Newton actuators are CUDA-graph-safe. The full decimation loop (including the trivial decimation=1 case) is folded into a single step() call.

classmethod initialize(sim_context: SimulationContext) → None

Initialize the manager with simulation context.

Parameters:

sim_context – Parent simulation context.

classmethod initialize_solver() → None

Initialize the solver and collision pipeline.

Thin orchestrator: delegates solver construction to _build_solver() (overridden by each solver subclass), allocates the collision pipeline (when applicable) via _initialize_contacts(), then either captures the CUDA graph immediately or defers capture until the first step() call (RTX-active path).

Warning

When using a CUDA-enabled device, the simulation is graphed. This means the function steps the simulation once to capture the graph, so it should only be called after everything else in the simulation is initialized.

classmethod instantiate_builder_from_stage()

Create builder from USD stage.

Detects env Xforms (e.g. /World/Env_0, /World/Env_1) and builds each as a separate Newton world via begin_world/end_world. Falls back to a flat add_usd when no env Xforms are found.

classmethod invalidate_body_state(env_ids: wp.array(dtype=wp.int32) | None = None, env_mask: wp.array(dtype=wp.bool) | None = None) → None

Mark selected maximal-coordinate body state as changed without requesting FK.

Parameters:

• env_ids – Integer indices of dirtied environments. Used by index write methods.

• env_mask – Boolean mask of dirtied environments. Used by mask write methods.

classmethod invalidate_fk(env_mask: wp.array | None = None, env_ids: wp.array | None = None, articulation_ids: wp.array | None = None) → None

Mark environments as needing FK recomputation and solver reset.

Called by asset write methods that modify joint coordinates or root transforms. The masks are consumed by the next forward, raw-state, rendering, or physics-step boundary.

Parameters:

• env_mask – Boolean mask of dirtied environments. Shape (num_envs,). Used by _mask write methods.

• env_ids – Integer indices of dirtied environments. Used by _index write methods.

• articulation_ids – Mapping from (world, arti) to model articulation index. Shape (world_count, count_per_world). Obtained from ArticulationView.articulation_ids.

classmethod is_fabric_enabled() → bool

Check if fabric interface is enabled (not applicable for Newton).

classmethod pause() → None

Pause physics simulation. Default is no-op.

classmethod play() → None

Start or resume physics simulation. Default is no-op.

classmethod pre_render() → None

Refresh derived Newton state before cameras and visualizers read it.

classmethod register_callback(callback: Callable, event: PhysicsEvent, order: int = 0, name: str | None = None, wrap_weak_ref: bool = True) → CallbackHandle

Register a callback. Passes event to parent class.

classmethod register_particle_visual_prim(prim_path: str, particle_offset: int, particle_count: int, sync_frequency: int = 1) → None

Register a UsdGeom.Points prim whose points mirror a slice of Newton’s particle state.

Parameters:

• prim_path – Stage path of an existing UsdGeom.Points prim.

• particle_offset – First index of the prim’s slice in state.particle_q.

• particle_count – Number of particles in the slice.

• sync_frequency – Sync the prim every N dirty render frames.

classmethod register_post_actuator_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the actuator step on every iteration.

Each callback runs inside the captured CUDA graph (when _is_all_graphable() is True) right after NewtonActuatorAdapter.step() and before the solver substeps, so kernel writes to state/control are visible to the integrator on the same iteration. Multiple articulations register their own implicit-DOF telemetry / FF-routing kernels here; all registered callbacks fire in registration order each step.

classmethod register_post_step_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the last solver substep on every step.

Each callback runs inside the stepped (and, when _is_all_graphable() is True, captured) region right after the final solver substep of the decimation loop and before _update_sensors(), so the launches it issues are recorded into every captured CUDA graph and replayed on each tick. The hook fires exactly once per step() call, reflecting the state after all decimation iterations (and their solver substeps) have completed – not once per substep and not once per decimation iteration. Callbacks must be graph-safe (fixed shapes, no host branching on device data) and must be registered before capture. Articulations with non-identity ordering register their backend-to-user state republish here; all registered callbacks fire in registration order each step.

classmethod register_state_force_callback(callback: Callable[[newton.State], None]) → None

Register a graph-safe callback that applies forces before every solver substep.

Callbacks must be registered before solver initialization so they are included in CUDA graph capture.

Parameters:

callback – Function that adds forces [N, N·m] to the provided state.

classmethod request_extended_contact_attribute(attr: str) → None

Request an extended contact attribute (e.g. "force").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the model in start_simulation() so that subsequent Contacts creation includes them.

Parameters:

attr – Contact attribute name.

classmethod request_extended_state_attribute(attr: str) → None

Request an extended state attribute (e.g. "body_qdd").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the builder in start_simulation() so that subsequent model.state() calls allocate them.

Parameters:

attr – State attribute name (must be in State.EXTENDED_ATTRIBUTES).

classmethod reset(soft: bool = False) → None

Reset physics simulation.

A hard reset (soft=False) re-finalizes the Newton model, reallocating its device arrays. The cached collision pipeline, contacts and any captured CUDA graph reference the old buffers, so they are released here and rebuilt against the re-finalized model by initialize_solver(). This avoids the illegal CUDA memory access (CUDA error 700) that would otherwise occur on the first step after a hard reset.

A soft reset (soft=True) skips this full reinitialization and reuses the existing model, solver, collision pipeline and CUDA graph.

Parameters:

soft – If True, skip full reinitialization.

static safe_callback_invoke(fn: Callable, *args, physics_manager: type[PhysicsManager] | None = None) → None

Invoke a callback, catching exceptions that would be swallowed by external event buses.

Ignores ReferenceError (from garbage-collected weakref proxies). All other exceptions are forwarded to physics_manager.``store_callback_exception`` when available (see note below), or re-raised immediately otherwise.

Note (Octi):

The carb event bus used by PhysX/Omniverse silently swallows exceptions raised inside callbacks. PhysxManager works around this by storing the exception and re-raising it after event dispatch completes (in reset() / step()). Backends that dispatch events directly (e.g. Newton) don’t need this — exceptions propagate normally — so store_callback_exception is not called for them. This is a known wart; a cleaner solution is actively being explored.

classmethod set_builder(builder: newton.ModelBuilder) → None

Set the Newton model builder.

classmethod set_decimation(decimation: int) → None

Set the decimation count and re-capture the CUDA graph.

When all actuators are graphable the entire decimation loop (actuators + solver substeps, repeated decimation times) is captured as a single CUDA graph.

If a CUDA graph was previously captured, it is automatically re-captured with the new decimation count using the same strategy as start_simulation(): standard wp.ScopedCapture when no USDRT stage is active, or deferred relaxed capture when RTX is running. Solvers with reset-dependent topology may also defer standard capture.

classmethod start_simulation() → None

Start simulation by finalizing model and initializing state.

This function finalizes the model and initializes the simulation state. Note: Collision pipeline is initialized later in initialize_solver() after we determine whether the solver needs external collision detection.

classmethod step() → None

Step the physics simulation.

The stepping logic follows one of two paths depending on whether all actuators are CUDA-graph-safe:

All-graphable path (_simulate_full()):

Actuators and solver substeps are captured together in a single CUDA graph containing the full decimation x (actuators + solver substeps) loop.

Eager-actuator path (fallback, some actuators not graph-safe):

Actuators are stepped eagerly on the CPU timeline (outside the graph), then a graph containing only the solver substeps is launched via _simulate_physics_only().

In both paths the sequence within one physics step is:

zero actuated DOFs in control.joint_f
-> actuator.step (computes effort, writes to control.joint_f)
-> solver.step x num_substeps (integrates, reads control.joint_f)
-> sensors.update

classmethod stop() → None

Stop physics simulation. Default is no-op.

classmethod sync_cables_to_usd() → None

Write Newton cable segment endpoints to Fabric curve points.

classmethod sync_particles_to_usd() → None

Write Newton particle positions to USD/Fabric for Kit viewport rendering.

Two prim families are synced from state_0.particle_q:

• Fabric mesh prims tagged with newton:particleOffset / newton:particleCount (deformable visual meshes) receive local-frame points on the GPU via _sync_fabric_mesh_particles().

• UsdGeom.Points prims registered through register_particle_visual_prim() (MPM particle clouds) receive world-frame points via _sync_particle_points_prims().

No-op when there is no particle state or nothing changed since the last sync.

classmethod sync_transforms_to_usd() → None

Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.

No-op when _usdrt_stage is None (i.e. Kit visualizer is not active) or when transforms have not changed since the last sync.

Called at render cadence by pre_render() (via render()). Physics stepping marks transforms dirty via _mark_transforms_dirty() so that the expensive Fabric hierarchy update only runs once per render frame rather than after every physics step.

Uses wp.fabricarray directly (no isaacsim.physics.newton extension needed). The Warp kernel reads state_0.body_q[newton_index[i]] and writes the corresponding mat44d to omni:fabric:worldMatrix for each prim.

When IFabricHierarchy.update_world_xforms_gpu_with_options is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then run the GPU hierarchy update with RIGID_BODY | FORCE_UPDATE so Newton-authored world matrices stay authoritative on rigid-body prims. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod unregister_post_step_callback(callback: Callable[[], None]) → None

Remove a previously registered post-step callback.

Symmetric to register_post_step_callback(), this lets an articulation deregister its republish hook when its callbacks are cleared so the bound method does not linger on the class-level list after the articulation is gone. Removing a callback that was never registered (or was already removed) is a safe no-op, matching the tolerant deregistration of other handles.

classmethod update_visualization_state(scene_data_provider: SceneDataProvider | None = None) → None

Refresh visualization state for the active sim backend.

Newton sim backend: no-op — _state_0 is the live, authoritative state already advanced by step() / forward kinematics.

PhysX / OVPhysX sim backend: pull rigid-body transforms and deformable nodal positions from the SceneDataProvider and write them into the shadow _state_0.body_q / particle_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses and mesh points.

Calls use allow_passthrough=False so identity mappings still copy into the pre-bound shadow buffers. Passthrough would rebind the temporary SceneDataFormat fields away from _state_0, leaving OVRTX and other get_state() consumers on stale rest-pose particle / body state.

Invoked lazily from get_state() so consumers do not need to coordinate the sync explicitly.

classmethod video_capture_backend() → str

Newton GL headless perspective video capture.

classmethod wait_for_playing() → None

Block until the timeline is playing. Default is no-op.

class isaaclab_newton.physics.NewtonKaminoManager

Bases: NewtonManager

NewtonManager specialization for the Kamino solver.

Uses Newton’s CollisionPipeline unless its use_collision_detector field is True, in which case Kamino’s internal collision detector handles contact generation.

Methods:

activate_newton_actuator_path()	Opt an articulation into the Newton actuator fast path.
add_contact_sensor([body_names_expr, ...])	Add a contact sensor for reporting contacts between bodies/shapes.
add_frame_transform_sensor(shapes, ...)	Add a frame transform sensor for measuring relative transforms.
add_imu_sensor(sites)	Add an IMU sensor for measuring acceleration and angular velocity at sites.
add_model_change(change)	Register a model change to notify the solver.
after_visualizers_render()	Hook after visualizers have stepped during render().
cl_register_site(body_pattern, xform, *[, ...])	Register a site request for injection into prototypes before replication.
clear()	Clear all Newton-specific state (callbacks cleared by super().close()).
clear_callbacks()	Remove all registered callbacks.
close()	Clean up Newton physics resources.
create_builder([up_axis])	Create a ModelBuilder configured with default settings.
deregister_callback(callback_id)	Remove a registered callback.
dispatch_event(event[, payload])	Dispatch an event to all registered callbacks.
fix_articulation_root(articulation_prim[, stage])	Ensure that an articulation root has one enabled world fixed joint.
forward()	Update articulation kinematics without stepping physics.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
get_contacts()	Get the current Newton contact buffer, if the active solver exposes one.
get_control()	Get the control object.
get_device()	Get the physics simulation device.
get_dt()	Get the physics timestep.
get_model()	Get the Newton model.
get_physics_dt()	Get the physics timestep in seconds.
get_physics_sim_view()	Get the list of registered views.
get_scene_data_backend()	Return the SceneDataBackend for the SceneDataProvider.
get_scene_data_provider()	Return the active scene data provider.
get_simulation_time()	Get the current simulation time in seconds.
get_solver_dt()	Get the solver substep timestep.
get_state([scene_data_provider])	Get the current Newton state for visualization.
get_state_0()	Get the current state.
get_state_1()	Get the next state.
handles_decimation()	True when step() executes the full decimation loop internally.
initialize(sim_context)	Initialize the manager with simulation context.
initialize_solver()	Initialize the solver and collision pipeline.
instantiate_builder_from_stage()	Create builder from USD stage.
invalidate_body_state([env_ids, env_mask])	Mark selected maximal-coordinate body state as changed without requesting FK.
invalidate_fk([env_mask, env_ids, ...])	Mark environments as needing FK recomputation and solver reset.
is_fabric_enabled()	Check if fabric interface is enabled (not applicable for Newton).
pause()	Pause physics simulation.
play()	Start or resume physics simulation.
pre_render()	Refresh derived Newton state before cameras and visualizers read it.
register_callback(callback, event[, order, ...])	Register a callback.
register_particle_visual_prim(prim_path, ...)	Register a UsdGeom.Points prim whose points mirror a slice of Newton's particle state.
register_post_actuator_callback(callback)	Append a hook to the list invoked after the actuator step on every iteration.
register_post_step_callback(callback)	Append a hook to the list invoked after the last solver substep on every step.
register_state_force_callback(callback)	Register a graph-safe callback that applies forces before every solver substep.
request_extended_contact_attribute(attr)	Request an extended contact attribute (e.g. "force").
request_extended_state_attribute(attr)	Request an extended state attribute (e.g. "body_qdd").
reset([soft])	Reset physics simulation.
safe_callback_invoke(fn, *args[, ...])	Invoke a callback, catching exceptions that would be swallowed by external event buses.
set_builder(builder)	Set the Newton model builder.
set_decimation(decimation)	Set the decimation count and re-capture the CUDA graph.
start_simulation()	Start simulation by finalizing model and initializing state.
step()	Step the physics simulation.
stop()	Stop physics simulation.
sync_cables_to_usd()	Write Newton cable segment endpoints to Fabric curve points.
sync_particles_to_usd()	Write Newton particle positions to USD/Fabric for Kit viewport rendering.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
unregister_post_step_callback(callback)	Remove a previously registered post-step callback.
update_visualization_state([scene_data_provider])	Refresh visualization state for the active sim backend.
video_capture_backend()	Newton GL headless perspective video capture.
wait_for_playing()	Block until the timeline is playing.

classmethod activate_newton_actuator_path() → None

Opt an articulation into the Newton actuator fast path.

Idempotent — called by every Newton-fast-path articulation’s _process_actuators_cfg:

1. Sets _use_newton_actuators_active, which _is_all_graphable() checks (adapter presence alone cannot distinguish the fast path from the standard Lab path).

2. On first call, builds the single sim-level NewtonActuatorAdapter over the full flat DOF layout; later calls reuse it.

classmethod add_contact_sensor(body_names_expr: str | list[str] | None = None, shape_names_expr: str | list[str] | None = None, contact_partners_body_expr: str | list[str] | None = None, contact_partners_shape_expr: str | list[str] | None = None, verbose: bool = False) → tuple[str | list[str] | None, str | list[str] | None, str | list[str] | None, str | list[str] | None]

Add a contact sensor for reporting contacts between bodies/shapes.

Converts Isaac Lab pattern conventions (.* regex, full USD paths) to fnmatch globs and delegates to newton.sensors.SensorContact.

Parameters:

• body_names_expr – Expression for body names to sense.

• shape_names_expr – Expression for shape names to sense.

• contact_partners_body_expr – Expression for contact partner body names.

• contact_partners_shape_expr – Expression for contact partner shape names.

• verbose – Print verbose information.

classmethod add_frame_transform_sensor(shapes: list[int], reference_sites: list[int]) → int

Add a frame transform sensor for measuring relative transforms.

Creates a SensorFrameTransform from pre-resolved shape and reference site indices, appends it to the internal list, and returns its index.

Parameters:

• shapes – Ordered list of shape indices to measure.

• reference_sites – 1:1 list of reference site indices (same length as shapes).

Returns:

Index of the newly created sensor in _newton_frame_transform_sensors.

classmethod add_imu_sensor(sites: list[int]) → int

Add an IMU sensor for measuring acceleration and angular velocity at sites.

Creates a newton.sensors.SensorIMU from pre-resolved site indices, appends it to the internal list, and returns its index.

Parameters:

sites – Ordered list of site indices (one per environment).

Returns:

Index of the newly created sensor in the internal IMU sensor list.

classmethod add_model_change(change: newton.ModelFlags) → None

Register a model change to notify the solver.

classmethod after_visualizers_render() → None

Hook after visualizers have stepped during render().

Use for physics-backend sync (e.g. fabric) if needed. Default is a no-op.

classmethod cl_register_site(body_pattern: str | None, xform: warp.transform, *, per_world: bool = False) → str

Register a site request for injection into prototypes before replication.

Sensors call this during __init__. Sites are injected into prototype builders by _cl_inject_sites() (called from newton_replicate) before add_builder, so they replicate correctly per-world.

Identical (body_pattern, per_world, transform) registrations share sites.

The body_pattern is matched against prototype-local body labels (e.g. "Robot/link.*") when replication is active, or against the flat builder’s body labels in the fallback path. Wildcard patterns that match multiple bodies create one site per matched body.

Parameters:

• body_pattern – Regex pattern matched against body labels in the prototype builder (e.g. "Robot/link0" or "Robot/finger.*" for multi-body wildcards), or None for global sites (world-origin reference, etc.).

• xform – Site transform relative to body.

• per_world – When True, body_pattern must be None and one bodyless site is created in each cloned world’s frame.

Returns:

Assigned site label suffix.

classmethod clear()

Clear all Newton-specific state (callbacks cleared by super().close()).

classmethod clear_callbacks() → None

Remove all registered callbacks.

Do NOT reset _callback_id — handle IDs must remain monotonically unique across the lifetime of the process. Resetting the counter would let a future register_callback() hand out an ID that an old, still-alive CallbackHandle (e.g. on a sensor that has not been garbage-collected yet) holds, so when the old object eventually finalizes its __del__ would deregister the new callback. This bit ovphysx’s kitless multi-context tests where two InteractiveScene``s are created in sequence: the first scene's sensor would post-GC deregister the second scene's ``_initialize_callback by ID collision, leaving the second sensor forever uninitialized.

classmethod close() → None

Clean up Newton physics resources.

classmethod create_builder(up_axis: str | None = None, **kwargs) → newton.ModelBuilder

Create a ModelBuilder configured with default settings.

Forwards NewtonShapeCfg defaults onto Newton’s upstream ModelBuilder.default_shape_cfg via checked_apply(). Falls back to wrapper defaults when no Newton config is active so rough-terrain margin/gap still apply during early construction.

Parameters:

• up_axis – Override for the up-axis. Defaults to None, which uses the manager’s _up_axis.

• **kwargs – Forwarded to ModelBuilder.

Returns:

New builder with up-axis and per-shape defaults (gap, margin) applied.

classmethod deregister_callback(callback_id: int | CallbackHandle) → None

Remove a registered callback.

Parameters:

callback_id – The ID or CallbackHandle returned by register_callback().

classmethod dispatch_event(event: PhysicsEvent, payload: Any = None) → None

Dispatch an event to all registered callbacks.

This is the default implementation using simple callback lists. Subclasses may override or extend with platform-specific dispatch.

Parameters:

• event – The event to dispatch.

• payload – Optional data to pass to callbacks.

classmethod fix_articulation_root(articulation_prim: Any, stage: Any = None) → Any

Ensure that an articulation root has one enabled world fixed joint.

The base implementation leaves the root in place. Backends whose parser requires a different root topology may relocate it and return the resulting root prim.

Parameters:

• articulation_prim – The articulation-root prim to fix.

• stage – The stage containing the prim. Defaults to the current stage.

Returns:

The articulation-root prim after backend normalization.

Raises:

NotImplementedError – If a new joint is needed and the root is not a rigid body.

classmethod forward() → None

Update articulation kinematics without stepping physics.

Update body poses from joint coordinates via the solver-specialized FK delegate (_eval_fk, bound to the active subclass’s _eval_fk_impl() in initialize_solver()). Only the articulations flagged dirty in _fk_reset_mask and _world_reset_mask (see invalidate_fk()) are updated. The masks are consumed (zeroed) afterwards so the next step() does not redundantly re-solve them.

The delegate (rather than a direct cls._eval_fk_impl call) is required because the data layer invokes NewtonManager.forward() on the base class, where cls is the base NewtonManager; the bound delegate dispatches to the concrete subclass override.

classmethod get_backend() → str

Get the tensor backend being used (“numpy” or “torch”).

classmethod get_contacts() → Contacts | None

Get the current Newton contact buffer, if the active solver exposes one.

classmethod get_control() → newton.Control

Get the control object.

classmethod get_device() → str

Get the physics simulation device.

classmethod get_dt() → float

Get the physics timestep. Alias for get_physics_dt().

classmethod get_model() → newton.Model

Get the Newton model.

When the active sim backend is Newton this returns the manager’s own authoritative model. When the active sim backend is PhysX a shadow Newton model is built lazily (from the visualizer prebuilt artifact) so renderers/visualizers that operate on Newton Model and State can still drive a PhysX-simulated scene.

classmethod get_physics_dt() → float

Get the physics timestep in seconds.

classmethod get_physics_sim_view() → list

Get the list of registered views.

Assets can append their views to this list, and sensors can access them. Returns a list that callers can append to.

Returns:

List of registered views (e.g., NewtonArticulationView instances).

classmethod get_scene_data_backend() → SceneDataBackend | None

Return the SceneDataBackend for the SceneDataProvider.

classmethod get_scene_data_provider() → SceneDataProvider

Return the active scene data provider.

classmethod get_simulation_time() → float

Get the current simulation time in seconds.

classmethod get_solver_dt() → float

Get the solver substep timestep.

classmethod get_state(scene_data_provider: SceneDataProvider | None = None) → newton.State

Get the current Newton state for visualization.

Use this method from visualizers/renderers/video recorders that need a backend-agnostic Newton State. When the sim backend is PhysX this refreshes the shadow _state_0.body_q from the live PhysX scene via update_visualization_state() before returning, so callers never observe stale transforms. Under the Newton sim backend, pending forward kinematics is applied before returning the live state.

classmethod get_state_0() → newton.State

Get the current state.

classmethod get_state_1() → newton.State

Get the next state.

classmethod handles_decimation() → bool

True when step() executes the full decimation loop internally.

This is the case when all Newton actuators are CUDA-graph-safe. The full decimation loop (including the trivial decimation=1 case) is folded into a single step() call.

classmethod initialize(sim_context: SimulationContext) → None

Initialize the manager with simulation context.

Parameters:

sim_context – Parent simulation context.

classmethod initialize_solver() → None

Initialize the solver and collision pipeline.

Thin orchestrator: delegates solver construction to _build_solver() (overridden by each solver subclass), allocates the collision pipeline (when applicable) via _initialize_contacts(), then either captures the CUDA graph immediately or defers capture until the first step() call (RTX-active path).

Warning

When using a CUDA-enabled device, the simulation is graphed. This means the function steps the simulation once to capture the graph, so it should only be called after everything else in the simulation is initialized.

classmethod instantiate_builder_from_stage()

Create builder from USD stage.

Detects env Xforms (e.g. /World/Env_0, /World/Env_1) and builds each as a separate Newton world via begin_world/end_world. Falls back to a flat add_usd when no env Xforms are found.

classmethod invalidate_body_state(env_ids: wp.array(dtype=wp.int32) | None = None, env_mask: wp.array(dtype=wp.bool) | None = None) → None

Mark selected maximal-coordinate body state as changed without requesting FK.

Parameters:

• env_ids – Integer indices of dirtied environments. Used by index write methods.

• env_mask – Boolean mask of dirtied environments. Used by mask write methods.

classmethod invalidate_fk(env_mask: wp.array | None = None, env_ids: wp.array | None = None, articulation_ids: wp.array | None = None) → None

Mark environments as needing FK recomputation and solver reset.

Called by asset write methods that modify joint coordinates or root transforms. The masks are consumed by the next forward, raw-state, rendering, or physics-step boundary.

Parameters:

• env_mask – Boolean mask of dirtied environments. Shape (num_envs,). Used by _mask write methods.

• env_ids – Integer indices of dirtied environments. Used by _index write methods.

• articulation_ids – Mapping from (world, arti) to model articulation index. Shape (world_count, count_per_world). Obtained from ArticulationView.articulation_ids.

classmethod is_fabric_enabled() → bool

Check if fabric interface is enabled (not applicable for Newton).

classmethod pause() → None

Pause physics simulation. Default is no-op.

classmethod play() → None

Start or resume physics simulation. Default is no-op.

classmethod pre_render() → None

Refresh derived Newton state before cameras and visualizers read it.

classmethod register_callback(callback: Callable, event: PhysicsEvent, order: int = 0, name: str | None = None, wrap_weak_ref: bool = True) → CallbackHandle

Register a callback. Passes event to parent class.

classmethod register_particle_visual_prim(prim_path: str, particle_offset: int, particle_count: int, sync_frequency: int = 1) → None

Register a UsdGeom.Points prim whose points mirror a slice of Newton’s particle state.

Parameters:

• prim_path – Stage path of an existing UsdGeom.Points prim.

• particle_offset – First index of the prim’s slice in state.particle_q.

• particle_count – Number of particles in the slice.

• sync_frequency – Sync the prim every N dirty render frames.

classmethod register_post_actuator_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the actuator step on every iteration.

Each callback runs inside the captured CUDA graph (when _is_all_graphable() is True) right after NewtonActuatorAdapter.step() and before the solver substeps, so kernel writes to state/control are visible to the integrator on the same iteration. Multiple articulations register their own implicit-DOF telemetry / FF-routing kernels here; all registered callbacks fire in registration order each step.

classmethod register_post_step_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the last solver substep on every step.

Each callback runs inside the stepped (and, when _is_all_graphable() is True, captured) region right after the final solver substep of the decimation loop and before _update_sensors(), so the launches it issues are recorded into every captured CUDA graph and replayed on each tick. The hook fires exactly once per step() call, reflecting the state after all decimation iterations (and their solver substeps) have completed – not once per substep and not once per decimation iteration. Callbacks must be graph-safe (fixed shapes, no host branching on device data) and must be registered before capture. Articulations with non-identity ordering register their backend-to-user state republish here; all registered callbacks fire in registration order each step.

classmethod register_state_force_callback(callback: Callable[[newton.State], None]) → None

Register a graph-safe callback that applies forces before every solver substep.

Callbacks must be registered before solver initialization so they are included in CUDA graph capture.

Parameters:

callback – Function that adds forces [N, N·m] to the provided state.

classmethod request_extended_contact_attribute(attr: str) → None

Request an extended contact attribute (e.g. "force").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the model in start_simulation() so that subsequent Contacts creation includes them.

Parameters:

attr – Contact attribute name.

classmethod request_extended_state_attribute(attr: str) → None

Request an extended state attribute (e.g. "body_qdd").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the builder in start_simulation() so that subsequent model.state() calls allocate them.

Parameters:

attr – State attribute name (must be in State.EXTENDED_ATTRIBUTES).

classmethod reset(soft: bool = False) → None

Reset physics simulation.

A hard reset (soft=False) re-finalizes the Newton model, reallocating its device arrays. The cached collision pipeline, contacts and any captured CUDA graph reference the old buffers, so they are released here and rebuilt against the re-finalized model by initialize_solver(). This avoids the illegal CUDA memory access (CUDA error 700) that would otherwise occur on the first step after a hard reset.

A soft reset (soft=True) skips this full reinitialization and reuses the existing model, solver, collision pipeline and CUDA graph.

Parameters:

soft – If True, skip full reinitialization.

static safe_callback_invoke(fn: Callable, *args, physics_manager: type[PhysicsManager] | None = None) → None

Invoke a callback, catching exceptions that would be swallowed by external event buses.

Ignores ReferenceError (from garbage-collected weakref proxies). All other exceptions are forwarded to physics_manager.``store_callback_exception`` when available (see note below), or re-raised immediately otherwise.

Note (Octi):

The carb event bus used by PhysX/Omniverse silently swallows exceptions raised inside callbacks. PhysxManager works around this by storing the exception and re-raising it after event dispatch completes (in reset() / step()). Backends that dispatch events directly (e.g. Newton) don’t need this — exceptions propagate normally — so store_callback_exception is not called for them. This is a known wart; a cleaner solution is actively being explored.

classmethod set_builder(builder: newton.ModelBuilder) → None

Set the Newton model builder.

classmethod set_decimation(decimation: int) → None

Set the decimation count and re-capture the CUDA graph.

When all actuators are graphable the entire decimation loop (actuators + solver substeps, repeated decimation times) is captured as a single CUDA graph.

If a CUDA graph was previously captured, it is automatically re-captured with the new decimation count using the same strategy as start_simulation(): standard wp.ScopedCapture when no USDRT stage is active, or deferred relaxed capture when RTX is running. Solvers with reset-dependent topology may also defer standard capture.

classmethod start_simulation() → None

Start simulation by finalizing model and initializing state.

This function finalizes the model and initializes the simulation state. Note: Collision pipeline is initialized later in initialize_solver() after we determine whether the solver needs external collision detection.

classmethod step() → None

Step the physics simulation.

The stepping logic follows one of two paths depending on whether all actuators are CUDA-graph-safe:

All-graphable path (_simulate_full()):

Actuators and solver substeps are captured together in a single CUDA graph containing the full decimation x (actuators + solver substeps) loop.

Eager-actuator path (fallback, some actuators not graph-safe):

Actuators are stepped eagerly on the CPU timeline (outside the graph), then a graph containing only the solver substeps is launched via _simulate_physics_only().

In both paths the sequence within one physics step is:

zero actuated DOFs in control.joint_f
-> actuator.step (computes effort, writes to control.joint_f)
-> solver.step x num_substeps (integrates, reads control.joint_f)
-> sensors.update

classmethod stop() → None

Stop physics simulation. Default is no-op.

classmethod sync_cables_to_usd() → None

Write Newton cable segment endpoints to Fabric curve points.

classmethod sync_particles_to_usd() → None

Write Newton particle positions to USD/Fabric for Kit viewport rendering.

Two prim families are synced from state_0.particle_q:

• Fabric mesh prims tagged with newton:particleOffset / newton:particleCount (deformable visual meshes) receive local-frame points on the GPU via _sync_fabric_mesh_particles().

• UsdGeom.Points prims registered through register_particle_visual_prim() (MPM particle clouds) receive world-frame points via _sync_particle_points_prims().

No-op when there is no particle state or nothing changed since the last sync.

classmethod sync_transforms_to_usd() → None

Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.

No-op when _usdrt_stage is None (i.e. Kit visualizer is not active) or when transforms have not changed since the last sync.

Called at render cadence by pre_render() (via render()). Physics stepping marks transforms dirty via _mark_transforms_dirty() so that the expensive Fabric hierarchy update only runs once per render frame rather than after every physics step.

Uses wp.fabricarray directly (no isaacsim.physics.newton extension needed). The Warp kernel reads state_0.body_q[newton_index[i]] and writes the corresponding mat44d to omni:fabric:worldMatrix for each prim.

When IFabricHierarchy.update_world_xforms_gpu_with_options is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then run the GPU hierarchy update with RIGID_BODY | FORCE_UPDATE so Newton-authored world matrices stay authoritative on rigid-body prims. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod unregister_post_step_callback(callback: Callable[[], None]) → None

Remove a previously registered post-step callback.

Symmetric to register_post_step_callback(), this lets an articulation deregister its republish hook when its callbacks are cleared so the bound method does not linger on the class-level list after the articulation is gone. Removing a callback that was never registered (or was already removed) is a safe no-op, matching the tolerant deregistration of other handles.

classmethod update_visualization_state(scene_data_provider: SceneDataProvider | None = None) → None

Refresh visualization state for the active sim backend.

Newton sim backend: no-op — _state_0 is the live, authoritative state already advanced by step() / forward kinematics.

PhysX / OVPhysX sim backend: pull rigid-body transforms and deformable nodal positions from the SceneDataProvider and write them into the shadow _state_0.body_q / particle_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses and mesh points.

Calls use allow_passthrough=False so identity mappings still copy into the pre-bound shadow buffers. Passthrough would rebind the temporary SceneDataFormat fields away from _state_0, leaving OVRTX and other get_state() consumers on stale rest-pose particle / body state.

Invoked lazily from get_state() so consumers do not need to coordinate the sync explicitly.

classmethod video_capture_backend() → str

Newton GL headless perspective video capture.

classmethod wait_for_playing() → None

Block until the timeline is playing. Default is no-op.

class isaaclab_newton.physics.NewtonMPMManager

Bases: NewtonManager

NewtonManager specialization for Newton’s implicit MPM solver.

MPM advances particle materials in-place and treats rigid geometry as colliders, so it does not consume Newton’s rigid-body collision pipeline and steps with a single State.

Methods:

reset_solver_state([state, world_mask, flags])	Reset MPM and coupled-solver history after task state is rewritten.
activate_newton_actuator_path()	Opt an articulation into the Newton actuator fast path.
add_contact_sensor([body_names_expr, ...])	Add a contact sensor for reporting contacts between bodies/shapes.
add_frame_transform_sensor(shapes, ...)	Add a frame transform sensor for measuring relative transforms.
add_imu_sensor(sites)	Add an IMU sensor for measuring acceleration and angular velocity at sites.
add_model_change(change)	Register a model change to notify the solver.
after_visualizers_render()	Hook after visualizers have stepped during render().
cl_register_site(body_pattern, xform, *[, ...])	Register a site request for injection into prototypes before replication.
clear()	Clear all Newton-specific state (callbacks cleared by super().close()).
clear_callbacks()	Remove all registered callbacks.
close()	Clean up Newton physics resources.
create_builder([up_axis])	Create a ModelBuilder configured with default settings.
deregister_callback(callback_id)	Remove a registered callback.
dispatch_event(event[, payload])	Dispatch an event to all registered callbacks.
fix_articulation_root(articulation_prim[, stage])	Ensure that an articulation root has one enabled world fixed joint.
forward()	Update articulation kinematics without stepping physics.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
get_contacts()	Get the current Newton contact buffer, if the active solver exposes one.
get_control()	Get the control object.
get_device()	Get the physics simulation device.
get_dt()	Get the physics timestep.
get_model()	Get the Newton model.
get_physics_dt()	Get the physics timestep in seconds.
get_physics_sim_view()	Get the list of registered views.
get_scene_data_backend()	Return the SceneDataBackend for the SceneDataProvider.
get_scene_data_provider()	Return the active scene data provider.
get_simulation_time()	Get the current simulation time in seconds.
get_solver_dt()	Get the solver substep timestep.
get_state([scene_data_provider])	Get the current Newton state for visualization.
get_state_0()	Get the current state.
get_state_1()	Get the next state.
handles_decimation()	True when step() executes the full decimation loop internally.
initialize(sim_context)	Initialize the manager with simulation context.
initialize_solver()	Initialize the solver and collision pipeline.
instantiate_builder_from_stage()	Create builder from USD stage.
invalidate_body_state([env_ids, env_mask])	Mark selected maximal-coordinate body state as changed without requesting FK.
invalidate_fk([env_mask, env_ids, ...])	Mark environments as needing FK recomputation and solver reset.
is_fabric_enabled()	Check if fabric interface is enabled (not applicable for Newton).
pause()	Pause physics simulation.
play()	Start or resume physics simulation.
pre_render()	Refresh derived Newton state before cameras and visualizers read it.
register_callback(callback, event[, order, ...])	Register a callback.
register_particle_visual_prim(prim_path, ...)	Register a UsdGeom.Points prim whose points mirror a slice of Newton's particle state.
register_post_actuator_callback(callback)	Append a hook to the list invoked after the actuator step on every iteration.
register_post_step_callback(callback)	Append a hook to the list invoked after the last solver substep on every step.
register_state_force_callback(callback)	Register a graph-safe callback that applies forces before every solver substep.
request_extended_contact_attribute(attr)	Request an extended contact attribute (e.g. "force").
request_extended_state_attribute(attr)	Request an extended state attribute (e.g. "body_qdd").
reset([soft])	Reset physics simulation.
safe_callback_invoke(fn, *args[, ...])	Invoke a callback, catching exceptions that would be swallowed by external event buses.
set_builder(builder)	Set the Newton model builder.
set_decimation(decimation)	Set the decimation count and re-capture the CUDA graph.
start_simulation()	Start simulation by finalizing model and initializing state.
step()	Step the physics simulation.
stop()	Stop physics simulation.
sync_cables_to_usd()	Write Newton cable segment endpoints to Fabric curve points.
sync_particles_to_usd()	Write Newton particle positions to USD/Fabric for Kit viewport rendering.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
unregister_post_step_callback(callback)	Remove a previously registered post-step callback.
update_visualization_state([scene_data_provider])	Refresh visualization state for the active sim backend.
video_capture_backend()	Newton GL headless perspective video capture.
wait_for_playing()	Block until the timeline is playing.

classmethod reset_solver_state(state: State | None = None, world_mask: wp.array(dtype=wp.bool) | None = None, flags: StateFlags | int | None = None) → None

Reset MPM and coupled-solver history after task state is rewritten.

When state is omitted, both distinct manager state buffers are reset so a later buffer swap cannot restore stale history. A mask follows Newton’s canonical world_count + 1 contract, where the last entry selects global entities in world -1. A selected single local world is promoted to a full reset because a one-world MPM grid has no environment offsets.

Parameters:

• state – State whose solver-owned history should be reset. If omitted, reset both manager states.

• world_mask – Canonical per-world mask, including the final global-world entry.

• flags – State components whose solver-owned history should reset.

Raises:

• RuntimeError – If the MPM solver or a usable state is not initialized.

• ValueError – If world_mask does not use Newton’s canonical shape.

classmethod activate_newton_actuator_path() → None

Opt an articulation into the Newton actuator fast path.

Idempotent — called by every Newton-fast-path articulation’s _process_actuators_cfg:

1. Sets _use_newton_actuators_active, which _is_all_graphable() checks (adapter presence alone cannot distinguish the fast path from the standard Lab path).

2. On first call, builds the single sim-level NewtonActuatorAdapter over the full flat DOF layout; later calls reuse it.

classmethod add_contact_sensor(body_names_expr: str | list[str] | None = None, shape_names_expr: str | list[str] | None = None, contact_partners_body_expr: str | list[str] | None = None, contact_partners_shape_expr: str | list[str] | None = None, verbose: bool = False) → tuple[str | list[str] | None, str | list[str] | None, str | list[str] | None, str | list[str] | None]

Add a contact sensor for reporting contacts between bodies/shapes.

Converts Isaac Lab pattern conventions (.* regex, full USD paths) to fnmatch globs and delegates to newton.sensors.SensorContact.

Parameters:

• body_names_expr – Expression for body names to sense.

• shape_names_expr – Expression for shape names to sense.

• contact_partners_body_expr – Expression for contact partner body names.

• contact_partners_shape_expr – Expression for contact partner shape names.

• verbose – Print verbose information.

classmethod add_frame_transform_sensor(shapes: list[int], reference_sites: list[int]) → int

Add a frame transform sensor for measuring relative transforms.

Creates a SensorFrameTransform from pre-resolved shape and reference site indices, appends it to the internal list, and returns its index.

Parameters:

• shapes – Ordered list of shape indices to measure.

• reference_sites – 1:1 list of reference site indices (same length as shapes).

Returns:

Index of the newly created sensor in _newton_frame_transform_sensors.

classmethod add_imu_sensor(sites: list[int]) → int

Add an IMU sensor for measuring acceleration and angular velocity at sites.

Creates a newton.sensors.SensorIMU from pre-resolved site indices, appends it to the internal list, and returns its index.

Parameters:

sites – Ordered list of site indices (one per environment).

Returns:

Index of the newly created sensor in the internal IMU sensor list.

classmethod add_model_change(change: newton.ModelFlags) → None

Register a model change to notify the solver.

classmethod after_visualizers_render() → None

Hook after visualizers have stepped during render().

Use for physics-backend sync (e.g. fabric) if needed. Default is a no-op.

classmethod cl_register_site(body_pattern: str | None, xform: warp.transform, *, per_world: bool = False) → str

Register a site request for injection into prototypes before replication.

Sensors call this during __init__. Sites are injected into prototype builders by _cl_inject_sites() (called from newton_replicate) before add_builder, so they replicate correctly per-world.

Identical (body_pattern, per_world, transform) registrations share sites.

The body_pattern is matched against prototype-local body labels (e.g. "Robot/link.*") when replication is active, or against the flat builder’s body labels in the fallback path. Wildcard patterns that match multiple bodies create one site per matched body.

Parameters:

• body_pattern – Regex pattern matched against body labels in the prototype builder (e.g. "Robot/link0" or "Robot/finger.*" for multi-body wildcards), or None for global sites (world-origin reference, etc.).

• xform – Site transform relative to body.

• per_world – When True, body_pattern must be None and one bodyless site is created in each cloned world’s frame.

Returns:

Assigned site label suffix.

classmethod clear()

Clear all Newton-specific state (callbacks cleared by super().close()).

classmethod clear_callbacks() → None

Remove all registered callbacks.

Do NOT reset _callback_id — handle IDs must remain monotonically unique across the lifetime of the process. Resetting the counter would let a future register_callback() hand out an ID that an old, still-alive CallbackHandle (e.g. on a sensor that has not been garbage-collected yet) holds, so when the old object eventually finalizes its __del__ would deregister the new callback. This bit ovphysx’s kitless multi-context tests where two InteractiveScene``s are created in sequence: the first scene's sensor would post-GC deregister the second scene's ``_initialize_callback by ID collision, leaving the second sensor forever uninitialized.

classmethod close() → None

Clean up Newton physics resources.

classmethod create_builder(up_axis: str | None = None, **kwargs) → newton.ModelBuilder

Create a ModelBuilder configured with default settings.

Forwards NewtonShapeCfg defaults onto Newton’s upstream ModelBuilder.default_shape_cfg via checked_apply(). Falls back to wrapper defaults when no Newton config is active so rough-terrain margin/gap still apply during early construction.

Parameters:

• up_axis – Override for the up-axis. Defaults to None, which uses the manager’s _up_axis.

• **kwargs – Forwarded to ModelBuilder.

Returns:

New builder with up-axis and per-shape defaults (gap, margin) applied.

classmethod deregister_callback(callback_id: int | CallbackHandle) → None

Remove a registered callback.

Parameters:

callback_id – The ID or CallbackHandle returned by register_callback().

classmethod dispatch_event(event: PhysicsEvent, payload: Any = None) → None

Dispatch an event to all registered callbacks.

This is the default implementation using simple callback lists. Subclasses may override or extend with platform-specific dispatch.

Parameters:

• event – The event to dispatch.

• payload – Optional data to pass to callbacks.

classmethod fix_articulation_root(articulation_prim: Any, stage: Any = None) → Any

Ensure that an articulation root has one enabled world fixed joint.

The base implementation leaves the root in place. Backends whose parser requires a different root topology may relocate it and return the resulting root prim.

Parameters:

• articulation_prim – The articulation-root prim to fix.

• stage – The stage containing the prim. Defaults to the current stage.

Returns:

The articulation-root prim after backend normalization.

Raises:

NotImplementedError – If a new joint is needed and the root is not a rigid body.

classmethod forward() → None

Update articulation kinematics without stepping physics.

Update body poses from joint coordinates via the solver-specialized FK delegate (_eval_fk, bound to the active subclass’s _eval_fk_impl() in initialize_solver()). Only the articulations flagged dirty in _fk_reset_mask and _world_reset_mask (see invalidate_fk()) are updated. The masks are consumed (zeroed) afterwards so the next step() does not redundantly re-solve them.

The delegate (rather than a direct cls._eval_fk_impl call) is required because the data layer invokes NewtonManager.forward() on the base class, where cls is the base NewtonManager; the bound delegate dispatches to the concrete subclass override.

classmethod get_backend() → str

Get the tensor backend being used (“numpy” or “torch”).

classmethod get_contacts() → Contacts | None

Get the current Newton contact buffer, if the active solver exposes one.

classmethod get_control() → newton.Control

Get the control object.

classmethod get_device() → str

Get the physics simulation device.

classmethod get_dt() → float

Get the physics timestep. Alias for get_physics_dt().

classmethod get_model() → newton.Model

Get the Newton model.

When the active sim backend is Newton this returns the manager’s own authoritative model. When the active sim backend is PhysX a shadow Newton model is built lazily (from the visualizer prebuilt artifact) so renderers/visualizers that operate on Newton Model and State can still drive a PhysX-simulated scene.

classmethod get_physics_dt() → float

Get the physics timestep in seconds.

classmethod get_physics_sim_view() → list

Get the list of registered views.

Assets can append their views to this list, and sensors can access them. Returns a list that callers can append to.

Returns:

List of registered views (e.g., NewtonArticulationView instances).

classmethod get_scene_data_backend() → SceneDataBackend | None

Return the SceneDataBackend for the SceneDataProvider.

classmethod get_scene_data_provider() → SceneDataProvider

Return the active scene data provider.

classmethod get_simulation_time() → float

Get the current simulation time in seconds.

classmethod get_solver_dt() → float

Get the solver substep timestep.

classmethod get_state(scene_data_provider: SceneDataProvider | None = None) → newton.State

Get the current Newton state for visualization.

Use this method from visualizers/renderers/video recorders that need a backend-agnostic Newton State. When the sim backend is PhysX this refreshes the shadow _state_0.body_q from the live PhysX scene via update_visualization_state() before returning, so callers never observe stale transforms. Under the Newton sim backend, pending forward kinematics is applied before returning the live state.

classmethod get_state_0() → newton.State

Get the current state.

classmethod get_state_1() → newton.State

Get the next state.

classmethod handles_decimation() → bool

True when step() executes the full decimation loop internally.

This is the case when all Newton actuators are CUDA-graph-safe. The full decimation loop (including the trivial decimation=1 case) is folded into a single step() call.

classmethod initialize(sim_context: SimulationContext) → None

Initialize the manager with simulation context.

Parameters:

sim_context – Parent simulation context.

classmethod initialize_solver() → None

Initialize the solver and collision pipeline.

Thin orchestrator: delegates solver construction to _build_solver() (overridden by each solver subclass), allocates the collision pipeline (when applicable) via _initialize_contacts(), then either captures the CUDA graph immediately or defers capture until the first step() call (RTX-active path).

Warning

When using a CUDA-enabled device, the simulation is graphed. This means the function steps the simulation once to capture the graph, so it should only be called after everything else in the simulation is initialized.

classmethod instantiate_builder_from_stage()

Create builder from USD stage.

Detects env Xforms (e.g. /World/Env_0, /World/Env_1) and builds each as a separate Newton world via begin_world/end_world. Falls back to a flat add_usd when no env Xforms are found.

classmethod invalidate_body_state(env_ids: wp.array(dtype=wp.int32) | None = None, env_mask: wp.array(dtype=wp.bool) | None = None) → None

Mark selected maximal-coordinate body state as changed without requesting FK.

Parameters:

• env_ids – Integer indices of dirtied environments. Used by index write methods.

• env_mask – Boolean mask of dirtied environments. Used by mask write methods.

classmethod invalidate_fk(env_mask: wp.array | None = None, env_ids: wp.array | None = None, articulation_ids: wp.array | None = None) → None

Mark environments as needing FK recomputation and solver reset.

Called by asset write methods that modify joint coordinates or root transforms. The masks are consumed by the next forward, raw-state, rendering, or physics-step boundary.

Parameters:

• env_mask – Boolean mask of dirtied environments. Shape (num_envs,). Used by _mask write methods.

• env_ids – Integer indices of dirtied environments. Used by _index write methods.

• articulation_ids – Mapping from (world, arti) to model articulation index. Shape (world_count, count_per_world). Obtained from ArticulationView.articulation_ids.

classmethod is_fabric_enabled() → bool

Check if fabric interface is enabled (not applicable for Newton).

classmethod pause() → None

Pause physics simulation. Default is no-op.

classmethod play() → None

Start or resume physics simulation. Default is no-op.

classmethod pre_render() → None

Refresh derived Newton state before cameras and visualizers read it.

classmethod register_callback(callback: Callable, event: PhysicsEvent, order: int = 0, name: str | None = None, wrap_weak_ref: bool = True) → CallbackHandle

Register a callback. Passes event to parent class.

classmethod register_particle_visual_prim(prim_path: str, particle_offset: int, particle_count: int, sync_frequency: int = 1) → None

Register a UsdGeom.Points prim whose points mirror a slice of Newton’s particle state.

Parameters:

• prim_path – Stage path of an existing UsdGeom.Points prim.

• particle_offset – First index of the prim’s slice in state.particle_q.

• particle_count – Number of particles in the slice.

• sync_frequency – Sync the prim every N dirty render frames.

classmethod register_post_actuator_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the actuator step on every iteration.

Each callback runs inside the captured CUDA graph (when _is_all_graphable() is True) right after NewtonActuatorAdapter.step() and before the solver substeps, so kernel writes to state/control are visible to the integrator on the same iteration. Multiple articulations register their own implicit-DOF telemetry / FF-routing kernels here; all registered callbacks fire in registration order each step.

classmethod register_post_step_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the last solver substep on every step.

Each callback runs inside the stepped (and, when _is_all_graphable() is True, captured) region right after the final solver substep of the decimation loop and before _update_sensors(), so the launches it issues are recorded into every captured CUDA graph and replayed on each tick. The hook fires exactly once per step() call, reflecting the state after all decimation iterations (and their solver substeps) have completed – not once per substep and not once per decimation iteration. Callbacks must be graph-safe (fixed shapes, no host branching on device data) and must be registered before capture. Articulations with non-identity ordering register their backend-to-user state republish here; all registered callbacks fire in registration order each step.

classmethod register_state_force_callback(callback: Callable[[newton.State], None]) → None

Register a graph-safe callback that applies forces before every solver substep.

Callbacks must be registered before solver initialization so they are included in CUDA graph capture.

Parameters:

callback – Function that adds forces [N, N·m] to the provided state.

classmethod request_extended_contact_attribute(attr: str) → None

Request an extended contact attribute (e.g. "force").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the model in start_simulation() so that subsequent Contacts creation includes them.

Parameters:

attr – Contact attribute name.

classmethod request_extended_state_attribute(attr: str) → None

Request an extended state attribute (e.g. "body_qdd").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the builder in start_simulation() so that subsequent model.state() calls allocate them.

Parameters:

attr – State attribute name (must be in State.EXTENDED_ATTRIBUTES).

classmethod reset(soft: bool = False) → None

Reset physics simulation.

A hard reset (soft=False) re-finalizes the Newton model, reallocating its device arrays. The cached collision pipeline, contacts and any captured CUDA graph reference the old buffers, so they are released here and rebuilt against the re-finalized model by initialize_solver(). This avoids the illegal CUDA memory access (CUDA error 700) that would otherwise occur on the first step after a hard reset.

A soft reset (soft=True) skips this full reinitialization and reuses the existing model, solver, collision pipeline and CUDA graph.

Parameters:

soft – If True, skip full reinitialization.

static safe_callback_invoke(fn: Callable, *args, physics_manager: type[PhysicsManager] | None = None) → None

Invoke a callback, catching exceptions that would be swallowed by external event buses.

Ignores ReferenceError (from garbage-collected weakref proxies). All other exceptions are forwarded to physics_manager.``store_callback_exception`` when available (see note below), or re-raised immediately otherwise.

Note (Octi):

The carb event bus used by PhysX/Omniverse silently swallows exceptions raised inside callbacks. PhysxManager works around this by storing the exception and re-raising it after event dispatch completes (in reset() / step()). Backends that dispatch events directly (e.g. Newton) don’t need this — exceptions propagate normally — so store_callback_exception is not called for them. This is a known wart; a cleaner solution is actively being explored.

classmethod set_builder(builder: newton.ModelBuilder) → None

Set the Newton model builder.

classmethod set_decimation(decimation: int) → None

Set the decimation count and re-capture the CUDA graph.

When all actuators are graphable the entire decimation loop (actuators + solver substeps, repeated decimation times) is captured as a single CUDA graph.

If a CUDA graph was previously captured, it is automatically re-captured with the new decimation count using the same strategy as start_simulation(): standard wp.ScopedCapture when no USDRT stage is active, or deferred relaxed capture when RTX is running. Solvers with reset-dependent topology may also defer standard capture.

classmethod start_simulation() → None

Start simulation by finalizing model and initializing state.

This function finalizes the model and initializes the simulation state. Note: Collision pipeline is initialized later in initialize_solver() after we determine whether the solver needs external collision detection.

classmethod step() → None

Step the physics simulation.

The stepping logic follows one of two paths depending on whether all actuators are CUDA-graph-safe:

All-graphable path (_simulate_full()):

Actuators and solver substeps are captured together in a single CUDA graph containing the full decimation x (actuators + solver substeps) loop.

Eager-actuator path (fallback, some actuators not graph-safe):

Actuators are stepped eagerly on the CPU timeline (outside the graph), then a graph containing only the solver substeps is launched via _simulate_physics_only().

In both paths the sequence within one physics step is:

zero actuated DOFs in control.joint_f
-> actuator.step (computes effort, writes to control.joint_f)
-> solver.step x num_substeps (integrates, reads control.joint_f)
-> sensors.update

classmethod stop() → None

Stop physics simulation. Default is no-op.

classmethod sync_cables_to_usd() → None

Write Newton cable segment endpoints to Fabric curve points.

classmethod sync_particles_to_usd() → None

Write Newton particle positions to USD/Fabric for Kit viewport rendering.

Two prim families are synced from state_0.particle_q:

• Fabric mesh prims tagged with newton:particleOffset / newton:particleCount (deformable visual meshes) receive local-frame points on the GPU via _sync_fabric_mesh_particles().

• UsdGeom.Points prims registered through register_particle_visual_prim() (MPM particle clouds) receive world-frame points via _sync_particle_points_prims().

No-op when there is no particle state or nothing changed since the last sync.

classmethod sync_transforms_to_usd() → None

Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.

No-op when _usdrt_stage is None (i.e. Kit visualizer is not active) or when transforms have not changed since the last sync.

Called at render cadence by pre_render() (via render()). Physics stepping marks transforms dirty via _mark_transforms_dirty() so that the expensive Fabric hierarchy update only runs once per render frame rather than after every physics step.

Uses wp.fabricarray directly (no isaacsim.physics.newton extension needed). The Warp kernel reads state_0.body_q[newton_index[i]] and writes the corresponding mat44d to omni:fabric:worldMatrix for each prim.

When IFabricHierarchy.update_world_xforms_gpu_with_options is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then run the GPU hierarchy update with RIGID_BODY | FORCE_UPDATE so Newton-authored world matrices stay authoritative on rigid-body prims. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod unregister_post_step_callback(callback: Callable[[], None]) → None

Remove a previously registered post-step callback.

Symmetric to register_post_step_callback(), this lets an articulation deregister its republish hook when its callbacks are cleared so the bound method does not linger on the class-level list after the articulation is gone. Removing a callback that was never registered (or was already removed) is a safe no-op, matching the tolerant deregistration of other handles.

classmethod update_visualization_state(scene_data_provider: SceneDataProvider | None = None) → None

Refresh visualization state for the active sim backend.

Newton sim backend: no-op — _state_0 is the live, authoritative state already advanced by step() / forward kinematics.

PhysX / OVPhysX sim backend: pull rigid-body transforms and deformable nodal positions from the SceneDataProvider and write them into the shadow _state_0.body_q / particle_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses and mesh points.

Calls use allow_passthrough=False so identity mappings still copy into the pre-bound shadow buffers. Passthrough would rebind the temporary SceneDataFormat fields away from _state_0, leaving OVRTX and other get_state() consumers on stale rest-pose particle / body state.

Invoked lazily from get_state() so consumers do not need to coordinate the sync explicitly.

classmethod video_capture_backend() → str

Newton GL headless perspective video capture.

classmethod wait_for_playing() → None

Block until the timeline is playing. Default is no-op.