isaaclab_newton.physics

Implementation backends for simulation interfaces.

Classes

NewtonManager	Abstract Newton physics manager for Isaac Lab.
NewtonCfg	Configuration for Newton physics manager.
NewtonSolverCfg	Configuration for Newton solver-related parameters.
MJWarpSolverCfg	Configuration for MuJoCo Warp solver-related parameters.
XPBDSolverCfg	An implicit integrator using eXtended Position-Based Dynamics (XPBD) for rigid and soft body simulation.
FeatherstoneSolverCfg	A semi-implicit integrator using symplectic Euler.
KaminoSolverCfg	Configuration for Kamino solver-related parameters.
NewtonCollisionPipelineCfg	Configuration for Newton collision pipeline.
HydroelasticSDFCfg	Configuration for SDF-based hydroelastic collision handling.
NewtonShapeCfg	Default per-shape collision properties applied to all shapes in a Newton scene.
NewtonMJWarpManager	NewtonManager specialization for the MuJoCo Warp solver.
NewtonXPBDManager	NewtonManager specialization for the XPBD solver.
NewtonFeatherstoneManager	NewtonManager specialization for the Featherstone solver.
NewtonKaminoManager	NewtonManager specialization for the Kamino solver.

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(), _step_solver(), _solver_specific_clear(), 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.
pre_render()	Flush deferred Fabric writes before cameras/visualizers read the scene.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
sync_particles_to_usd()	Write Newton particle_q to Fabric mesh point arrays for Kit viewport rendering.
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.
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.
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.
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.
add_imu_sensor(sites)	Add an IMU sensor for measuring acceleration and angular velocity at sites.
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.
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.

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.

Parameters:

soft – If True, skip full reinitialization.

classmethod forward() → None

Update articulation kinematics without stepping physics.

Runs Newton’s generic forward kinematics (eval_fk) over all articulations to compute body poses from joint coordinates. This is the full (unmasked) FK path used during initial setup. For incremental per-environment updates after resets, see invalidate_fk() which accumulates masks consumed by step().

classmethod pre_render() → None

Flush deferred Fabric writes before cameras/visualizers read the scene.

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 cubric is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then call IAdapter::compute on the GPU to propagate the hierarchy and notify the Fabric Scene Delegate. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod sync_particles_to_usd() → None

Write Newton particle_q to Fabric mesh point arrays for Kit viewport rendering.

For each deformable body whose mesh prim carries a newton:particleOffset attribute, this function copies the corresponding slice of state_0.particle_q into the Fabric points array so the Kit viewport reflects the current deformation.

No-op when there is no _usdrt_stage, no simulation state, or no deformable bodies registered.

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

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) → 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, 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.

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.solvers.SolverNotifyFlags) → 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 in step() before physics stepping.

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 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 sets up cubric bindings and 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=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 update_visualization_state() is a no-op and this is equivalent to get_state_0().

classmethod update_visualization_state(scene_data_provider=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 sim backend: pull rigid-body transforms from the SceneDataProvider and write them into the shadow _state_0.body_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses.

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 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.

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 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 after_visualizers_render() → None

Hook after visualizers have stepped during render().

Use for physics-backend sync (e.g. fabric) if needed. Recording pipelines (Kit/RTX, Newton GL video, etc.) run from isaaclab.envs.utils.recording_hooks so they are not tied to a specific physics manager. 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 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.

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.
debug_mode	Whether to enable debug mode for the solver.
use_cuda_graph	Whether to use CUDA graphing when simulating.
solver_cfg	Solver configuration.
collision_cfg	Newton collision pipeline configuration.
default_shape_cfg	Default per-shape collision properties applied to every shape in the scene.

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.

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.

solver_cfg: NewtonSolverCfg | None

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

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,

• KaminoSolverCfg with use_collision_detector=False,

• XPBDSolverCfg (always),

• FeatherstoneSolverCfg (always).

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 KaminoSolverCfg.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.

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.
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	Whether to use parallel line search.
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.

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

Whether to use parallel line search.

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.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.KaminoSolverCfg

Bases: NewtonSolverCfg

Configuration for Kamino solver-related parameters.

Kamino is a Proximal Alternating Direction Method of Multipliers (P-ADMM) based solver for constrained multi-body dynamics. It operates in maximal coordinates and supports rigid bodies and articulations with hard frictional contacts.

Note

This solver is currently in Beta. Its API and behavior may change in future releases.

For more information, see the Newton Kamino documentation.

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.
constraints_alpha	Baumgarte stabilization parameter for bilateral joint constraints.
constraints_beta	Baumgarte stabilization parameter for unilateral joint-limit constraints.
constraints_gamma	Baumgarte stabilization parameter for unilateral contact constraints.
constraints_delta	Contact penetration margin [m].
padmm_max_iterations	Maximum number of P-ADMM solver iterations.
padmm_primal_tolerance	Primal residual convergence tolerance for P-ADMM.
padmm_dual_tolerance	Dual residual convergence tolerance for P-ADMM.
padmm_compl_tolerance	Complementarity residual convergence tolerance for P-ADMM.
padmm_rho_0	Initial penalty parameter for P-ADMM.
padmm_use_acceleration	Whether to use acceleration in the P-ADMM solver.
padmm_warmstart_mode	Warmstart mode for P-ADMM.
padmm_eta	Proximal regularization parameter for P-ADMM.
padmm_contact_warmstart_method	Contact warm-start method for P-ADMM.
padmm_use_graph_conditionals	Whether to use CUDA graph conditional nodes in the P-ADMM iterative solver.
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.
collision_detector_pipeline	Collision detection pipeline type.
collision_detector_max_contacts_per_pair	Maximum number of contacts to generate per candidate geometry pair.
dynamics_preconditioning	Whether to use preconditioning in the constrained dynamics solver.

Methods:

to_solver_config()

Build a SolverKamino.Config from this configuration.

class_type: type[NewtonManager] | str

Manager class for the Kamino solver.

solver_type: str

Solver type. Can be “kamino”.

integrator: str

Integrator type. Can be “euler” or “moreau”.

use_collision_detector: bool

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

use_fk_solver: bool

Whether to enable the forward kinematics solver for state resets.

Required for proper environment resets. The FK solver computes consistent body poses from joint angles after state writes, which is essential for maximal-coordinate solvers.

sparse_jacobian: bool

Whether to use sparse Jacobian computation.

sparse_dynamics: bool

Whether to use sparse dynamics computation.

rotation_correction: str

Rotation correction mode. Can be “twopi”, “continuous”, or “none”.

angular_velocity_damping: float

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

constraints_alpha: float

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

constraints_beta: float

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

constraints_gamma: float

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

constraints_delta: float

Contact penetration margin [m].

padmm_max_iterations: int

Maximum number of P-ADMM solver iterations.

padmm_primal_tolerance: float

Primal residual convergence tolerance for P-ADMM.

padmm_dual_tolerance: float

Dual residual convergence tolerance for P-ADMM.

padmm_compl_tolerance: float

Complementarity residual convergence tolerance for P-ADMM.

padmm_rho_0: float

Initial penalty parameter for P-ADMM.

padmm_use_acceleration: bool

Whether to use acceleration in the P-ADMM solver.

padmm_warmstart_mode: str

Warmstart mode for P-ADMM. Can be “none”, “internal”, or “containers”.

padmm_eta: float

Proximal regularization parameter for P-ADMM. Must be greater than zero.

padmm_contact_warmstart_method: str

Contact warm-start method for P-ADMM.

Can be “key_and_position”, “geom_pair_net_force”, “geom_pair_net_wrench”, “key_and_position_with_net_force_backup”, or “key_and_position_with_net_wrench_backup”.

padmm_use_graph_conditionals: bool

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

When False, replaces wp.capture_while with unrolled for-loops over max iterations.

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.

collision_detector_pipeline: str | None

Collision detection pipeline type. Can be “primitive” or “unified”.

Only used when use_collision_detector is True. If None, Newton’s default ("unified") is used.

collision_detector_max_contacts_per_pair: int | None

Maximum number of contacts to generate per candidate geometry pair.

Only used when use_collision_detector is True. If None, Newton’s default is used.

dynamics_preconditioning: bool

Whether to use preconditioning in the constrained dynamics solver.

Preconditioning improves convergence of the PADMM solver by rescaling the problem. Disabling may be useful for debugging or profiling solver behavior.

to_solver_config() → SolverKamino.Config

Build a SolverKamino.Config from this configuration.

Converts the flat field layout of KaminoSolverCfg into the nested dataclass hierarchy expected by SolverKamino.

Returns:

A SolverKamino.Config instance ready for solver construction.

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.
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).

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. Only fields Isaac Lab actually overrides are declared here; unspecified fields keep Newton’s upstream default. 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].

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.

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.
forward()	Update articulation kinematics without stepping physics.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
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_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_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()	Flush deferred Fabric writes before cameras/visualizers read the scene.
register_callback(callback, event[, order, ...])	Register a callback.
register_post_actuator_callback(callback)	Append a hook to the list invoked after the actuator step on every iteration.
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_particles_to_usd()	Write Newton particle_q to Fabric mesh point arrays for Kit viewport rendering.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
update_visualization_state([scene_data_provider])	Refresh visualization state for the active sim backend.
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.solvers.SolverNotifyFlags) → 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. Recording pipelines (Kit/RTX, Newton GL video, etc.) run from isaaclab.envs.utils.recording_hooks so they are not tied to a specific physics manager. Default is a no-op.

classmethod cl_register_site(body_pattern: str | None, xform: warp.transform) → 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, 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.

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 forward() → None

Update articulation kinematics without stepping physics.

Runs Newton’s generic forward kinematics (eval_fk) over all articulations to compute body poses from joint coordinates. This is the full (unmasked) FK path used during initial setup. For incremental per-environment updates after resets, see invalidate_fk() which accumulates masks consumed by step().

classmethod get_backend() → str

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

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

Return the SceneDataBackend for the SceneDataProvider.

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=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 update_visualization_state() is a no-op and this is equivalent to get_state_0().

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 sets up cubric bindings and 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_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 in step() before physics stepping.

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

Flush deferred Fabric writes before cameras/visualizers read the scene.

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_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 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.

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.

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_particles_to_usd() → None

Write Newton particle_q to Fabric mesh point arrays for Kit viewport rendering.

For each deformable body whose mesh prim carries a newton:particleOffset attribute, this function copies the corresponding slice of state_0.particle_q into the Fabric points array so the Kit viewport reflects the current deformation.

No-op when there is no _usdrt_stage, no simulation state, or no deformable bodies registered.

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 cubric is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then call IAdapter::compute on the GPU to propagate the hierarchy and notify the Fabric Scene Delegate. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod update_visualization_state(scene_data_provider=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 sim backend: pull rigid-body transforms from the SceneDataProvider and write them into the shadow _state_0.body_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses.

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

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.
forward()	Update articulation kinematics without stepping physics.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
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_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_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()	Flush deferred Fabric writes before cameras/visualizers read the scene.
register_callback(callback, event[, order, ...])	Register a callback.
register_post_actuator_callback(callback)	Append a hook to the list invoked after the actuator step on every iteration.
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_particles_to_usd()	Write Newton particle_q to Fabric mesh point arrays for Kit viewport rendering.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
update_visualization_state([scene_data_provider])	Refresh visualization state for the active sim backend.
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.solvers.SolverNotifyFlags) → 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. Recording pipelines (Kit/RTX, Newton GL video, etc.) run from isaaclab.envs.utils.recording_hooks so they are not tied to a specific physics manager. Default is a no-op.

classmethod cl_register_site(body_pattern: str | None, xform: warp.transform) → 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, 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.

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 forward() → None

Update articulation kinematics without stepping physics.

Runs Newton’s generic forward kinematics (eval_fk) over all articulations to compute body poses from joint coordinates. This is the full (unmasked) FK path used during initial setup. For incremental per-environment updates after resets, see invalidate_fk() which accumulates masks consumed by step().

classmethod get_backend() → str

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

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

Return the SceneDataBackend for the SceneDataProvider.

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=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 update_visualization_state() is a no-op and this is equivalent to get_state_0().

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 sets up cubric bindings and 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_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 in step() before physics stepping.

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

Flush deferred Fabric writes before cameras/visualizers read the scene.

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_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 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.

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.

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_particles_to_usd() → None

Write Newton particle_q to Fabric mesh point arrays for Kit viewport rendering.

For each deformable body whose mesh prim carries a newton:particleOffset attribute, this function copies the corresponding slice of state_0.particle_q into the Fabric points array so the Kit viewport reflects the current deformation.

No-op when there is no _usdrt_stage, no simulation state, or no deformable bodies registered.

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 cubric is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then call IAdapter::compute on the GPU to propagate the hierarchy and notify the Fabric Scene Delegate. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod update_visualization_state(scene_data_provider=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 sim backend: pull rigid-body transforms from the SceneDataProvider and write them into the shadow _state_0.body_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses.

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

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.
forward()	Update articulation kinematics without stepping physics.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
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_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_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()	Flush deferred Fabric writes before cameras/visualizers read the scene.
register_callback(callback, event[, order, ...])	Register a callback.
register_post_actuator_callback(callback)	Append a hook to the list invoked after the actuator step on every iteration.
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_particles_to_usd()	Write Newton particle_q to Fabric mesh point arrays for Kit viewport rendering.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
update_visualization_state([scene_data_provider])	Refresh visualization state for the active sim backend.
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.solvers.SolverNotifyFlags) → 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. Recording pipelines (Kit/RTX, Newton GL video, etc.) run from isaaclab.envs.utils.recording_hooks so they are not tied to a specific physics manager. Default is a no-op.

classmethod cl_register_site(body_pattern: str | None, xform: warp.transform) → 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, 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.

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 forward() → None

Update articulation kinematics without stepping physics.

Runs Newton’s generic forward kinematics (eval_fk) over all articulations to compute body poses from joint coordinates. This is the full (unmasked) FK path used during initial setup. For incremental per-environment updates after resets, see invalidate_fk() which accumulates masks consumed by step().

classmethod get_backend() → str

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

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

Return the SceneDataBackend for the SceneDataProvider.

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=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 update_visualization_state() is a no-op and this is equivalent to get_state_0().

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 sets up cubric bindings and 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_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 in step() before physics stepping.

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

Flush deferred Fabric writes before cameras/visualizers read the scene.

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_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 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.

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.

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_particles_to_usd() → None

Write Newton particle_q to Fabric mesh point arrays for Kit viewport rendering.

For each deformable body whose mesh prim carries a newton:particleOffset attribute, this function copies the corresponding slice of state_0.particle_q into the Fabric points array so the Kit viewport reflects the current deformation.

No-op when there is no _usdrt_stage, no simulation state, or no deformable bodies registered.

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 cubric is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then call IAdapter::compute on the GPU to propagate the hierarchy and notify the Fabric Scene Delegate. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod update_visualization_state(scene_data_provider=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 sim backend: pull rigid-body transforms from the SceneDataProvider and write them into the shadow _state_0.body_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses.

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

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 KaminoSolverCfg.use_collision_detector is True, in which case Kamino’s internal collision detector handles contact generation.

Methods:

step()	Step the physics simulation.
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.
forward()	Update articulation kinematics without stepping physics.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
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_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_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()	Flush deferred Fabric writes before cameras/visualizers read the scene.
register_callback(callback, event[, order, ...])	Register a callback.
register_post_actuator_callback(callback)	Append a hook to the list invoked after the actuator step on every iteration.
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.
stop()	Stop physics simulation.
sync_particles_to_usd()	Write Newton particle_q to Fabric mesh point arrays for Kit viewport rendering.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
update_visualization_state([scene_data_provider])	Refresh visualization state for the active sim backend.
wait_for_playing()	Block until the timeline is playing.

classmethod step() → None

Step the physics simulation.

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.solvers.SolverNotifyFlags) → 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. Recording pipelines (Kit/RTX, Newton GL video, etc.) run from isaaclab.envs.utils.recording_hooks so they are not tied to a specific physics manager. Default is a no-op.

classmethod cl_register_site(body_pattern: str | None, xform: warp.transform) → 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, 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.

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 forward() → None

Update articulation kinematics without stepping physics.

Runs Newton’s generic forward kinematics (eval_fk) over all articulations to compute body poses from joint coordinates. This is the full (unmasked) FK path used during initial setup. For incremental per-environment updates after resets, see invalidate_fk() which accumulates masks consumed by step().

classmethod get_backend() → str

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

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

Return the SceneDataBackend for the SceneDataProvider.

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=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 update_visualization_state() is a no-op and this is equivalent to get_state_0().

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 sets up cubric bindings and 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_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 in step() before physics stepping.

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

Flush deferred Fabric writes before cameras/visualizers read the scene.

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_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 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.

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.

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 stop() → None

Stop physics simulation. Default is no-op.

classmethod sync_particles_to_usd() → None

Write Newton particle_q to Fabric mesh point arrays for Kit viewport rendering.

For each deformable body whose mesh prim carries a newton:particleOffset attribute, this function copies the corresponding slice of state_0.particle_q into the Fabric points array so the Kit viewport reflects the current deformation.

No-op when there is no _usdrt_stage, no simulation state, or no deformable bodies registered.

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 cubric is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then call IAdapter::compute on the GPU to propagate the hierarchy and notify the Fabric Scene Delegate. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod update_visualization_state(scene_data_provider=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 sim backend: pull rigid-body transforms from the SceneDataProvider and write them into the shadow _state_0.body_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses.

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

classmethod wait_for_playing() → None

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