isaaclab_contrib.coupling

Named Newton couplers and their configurations.

This package contains contributed coupled-solver support (proxy and ADMM based rigid-deformable coupling) that wraps Newton’s experimental coupled solvers. Each sub-solver declares its model ownership as a named entry, and coupling interfaces refer to those entries by name.

Classes

CouplerEntryCfg	Configuration for one named sub-solver and its model ownership.
CouplerCfg	Base configuration for a Newton experimental coupled solver.
CouplerProxyMappingCfg	Configuration for one directed virtual-proxy mapping.
CouplerProxyCfg	Configuration for Newton's lagged-impulse virtual-proxy coupling.
CouplerAdmmCfg	Configuration for Newton's linearized ADMM coupling.
NewtonCouplerManager	Couple named Newton solver entries through proxy or ADMM interfaces.

Coupler Configurations

class isaaclab_contrib.coupling.CouplerEntryCfg

Bases: object

Configuration for one named sub-solver and its model ownership.

Bodies are selected by full Newton body-label regex. Joints and shapes attached to selected bodies are included by default; additional shapes can be selected directly by their full labels.

Attributes:

name	Unique name used by coupling mappings to reference this entry.
solver_cfg	Configuration used to construct this entry's Newton solver.
bodies	Bodies owned by this entry.
particles	Parent-model particle indices owned by this entry.
all_particles	Whether this entry owns every particle in the parent model.
include_child_joints	Whether fully selected child joints are owned by this entry.
include_body_shapes	Whether shapes attached to selected bodies are owned by this entry.
include_static_shapes	Whether this entry owns all shapes whose body index is -1.
shape_label_patterns	Regexes matched against full Newton shape labels for additional ownership.
substeps	Number of equal substeps this entry runs inside one coupled step.
in_place	Whether this entry steps in-place instead of using a second state buffer.

name: str

Unique name used by coupling mappings to reference this entry.

solver_cfg: NewtonSolverCfg

Configuration used to construct this entry’s Newton solver.

bodies: list[str]

Bodies owned by this entry.

Each string is treated as a regex matched against full Newton body labels, including all descendant body labels below the matched path.

particles: list[int]

Parent-model particle indices owned by this entry.

all_particles: bool

Whether this entry owns every particle in the parent model.

include_child_joints: bool

Whether fully selected child joints are owned by this entry.

A joint is owned when its child body is selected and its parent is either the world or selected by the same entry.

include_body_shapes: bool

Whether shapes attached to selected bodies are owned by this entry.

include_static_shapes: bool

Whether this entry owns all shapes whose body index is -1.

shape_label_patterns: list[str]

Regexes matched against full Newton shape labels for additional ownership.

substeps: int

Number of equal substeps this entry runs inside one coupled step.

in_place: bool

Whether this entry steps in-place instead of using a second state buffer.

Use this only for solvers, such as implicit MPM, whose public stepping contract explicitly supports identical input and output states. Coupled MPM entries require this field to be True.

class isaaclab_contrib.coupling.CouplerCfg

Bases: NewtonSolverCfg

Base configuration for a Newton experimental coupled solver.

Bodies, particles, joints, and shapes may be assigned to at most one entry. Unassigned model elements remain outside the nested solvers. Use a concrete subclass to configure the coupling interfaces.

Attributes:

class_type	Coupler implementation class.
entries	Ordered named sub-solver entries and their ownership selectors.
solver_type	Solver type metadata (deprecated).

class_type: type[NewtonManager] | str

Coupler implementation class.

entries: list[CouplerEntryCfg]

Ordered named sub-solver entries and their ownership selectors.

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_contrib.coupling.CouplerProxyMappingCfg

Bases: object

Configuration for one directed virtual-proxy mapping.

Attributes:

source	Name of the entry that owns the source bodies.
destination	Name of the entry that receives the proxy bodies.
bodies	Source bodies exposed as proxies in the destination entry.
particles	Source particle indices exposed as proxies in the destination entry.
mode	Proxy transfer mode passed to Newton's coupled-proxy solver.
mass_scale	Scale applied to proxy body mass/inertia and particle mass in the destination view.
collide_interval	Proxy-local collision refresh interval.
collision_pipeline	Configuration or factory for the proxy destination collision pipeline.

source: str

Name of the entry that owns the source bodies.

destination: str

Name of the entry that receives the proxy bodies.

bodies: list[str | int]

Source bodies exposed as proxies in the destination entry.

String selectors use the full-label-regex semantics of CouplerEntryCfg.bodies. Raw Newton body ids may be given directly as integers. The coupler resolves selectors to body ids in place, so after build this list holds only integers.

particles: list[int]

Source particle indices exposed as proxies in the destination entry.

mode: Literal['lagged', 'staggered']

Proxy transfer mode passed to Newton’s coupled-proxy solver.

mass_scale: float

Scale applied to proxy body mass/inertia and particle mass in the destination view.

collide_interval: int | None

Proxy-local collision refresh interval.

None refreshes contacts on every proxy pass. Explicit values must be positive integers and require collision_pipeline to be a factory.

collision_pipeline: NewtonCollisionPipelineCfg | Callable[[ModelView], CollisionPipeline | None] | None

Configuration or factory for the proxy destination collision pipeline.

Setting the field or returning None from the factory passes shared outer contacts to the destination.

class isaaclab_contrib.coupling.CouplerProxyCfg

Bases: CouplerCfg

Configuration for Newton’s lagged-impulse virtual-proxy coupling.

Newton’s proxy coupler currently supports at most two solver entries.

Attributes:

class_type	Coupler implementation class.
solver_type	Solver type metadata (deprecated).
entries	Ordered named sub-solver entries and their ownership selectors.
proxies	Directed proxy mappings between named solver entries.
iterations	Number of proxy relaxation passes per coupled step.

class_type: type[NewtonManager] | str

Coupler implementation class.

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.

entries: list[CouplerEntryCfg]

Ordered named sub-solver entries and their ownership selectors.

proxies: list[CouplerProxyMappingCfg]

Directed proxy mappings between named solver entries.

iterations: int

Number of proxy relaxation passes per coupled step.

class isaaclab_contrib.coupling.CouplerAdmmCfg

Bases: CouplerCfg

Configuration for Newton’s linearized ADMM coupling.

Attributes:

class_type	Coupler implementation class.
solver_type	Solver type metadata (deprecated).
entries	Ordered named sub-solver entries and their ownership selectors.
contact_max_triangle_pairs	Internal ADMM triangle-pair capacity across all environments in one process.
contact_reduction_hashtable_size_factor	Contact-reduction hash table size relative to the internal triangle-pair capacity.
contact_pairs	Symmetric contact interfaces as (entry_name, entry_name) pairs.
iterations	Number of ADMM dual iterations per coupled step.
rho	ADMM penalty parameter [dimensionless].
gamma	Proximal mass scaling parameter [dimensionless].
baumgarte	Position-error correction fraction [dimensionless].
joint_stiffness	Translational cross-solver joint stiffness [N/m].
joint_damping	Translational cross-solver joint damping [N*s/m].
joint_angular_stiffness	Angular cross-solver joint stiffness [N*m/rad].
joint_angular_damping	Angular cross-solver joint damping [N*m*s/rad].
joint_proximal_bodies	Whether cross-solver joint neighbors remain visible as inertial proxies.
joint_proximal_destination_entries	Optional entries that receive cross-solver joint proximal bodies.
joint_proximal_mass_scale	Mass scale applied to cross-solver joint proximal bodies.
rigid_contact_matching	Frame-to-frame matching mode for collision-detected rigid contacts.
contact_matching_pos_threshold	Maximum midpoint distance for matching rigid contacts [m].
contact_matching_normal_dot_threshold	Minimum normal dot product for matching rigid contacts.
contact_matching_force_scale	Scale applied to the previous ADMM dual when a rigid contact matches.

class_type: type[NewtonManager] | str

Coupler implementation class.

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.

entries: list[CouplerEntryCfg]

Ordered named sub-solver entries and their ownership selectors.

contact_max_triangle_pairs: int | None

Internal ADMM triangle-pair capacity across all environments in one process.

None uses Newton’s default. Must be less than 2**20 with rigid_contact_matching set to "latest" or "sticky"; larger capacities require "disabled".

contact_reduction_hashtable_size_factor: float | None

Contact-reduction hash table size relative to the internal triangle-pair capacity.

None uses Newton’s default. Increase it for hash table fill or insertion warnings.

contact_pairs: list[tuple[str, str]] | None

Symmetric contact interfaces as (entry_name, entry_name) pairs.

None asks Newton to detect every distinct entry pair automatically. An empty list disables ADMM contact coupling.

iterations: int

Number of ADMM dual iterations per coupled step.

rho: float

ADMM penalty parameter [dimensionless].

gamma: float

Proximal mass scaling parameter [dimensionless].

baumgarte: float

Position-error correction fraction [dimensionless].

joint_stiffness: float

Translational cross-solver joint stiffness [N/m].

joint_damping: float

Translational cross-solver joint damping [N*s/m].

joint_angular_stiffness: float

Angular cross-solver joint stiffness [N*m/rad].

joint_angular_damping: float

Angular cross-solver joint damping [N*m*s/rad].

joint_proximal_bodies: bool

Whether cross-solver joint neighbors remain visible as inertial proxies.

joint_proximal_destination_entries: list[str] | None

Optional entries that receive cross-solver joint proximal bodies.

joint_proximal_mass_scale: float

Mass scale applied to cross-solver joint proximal bodies.

rigid_contact_matching: Literal['disabled', 'latest', 'sticky']

Frame-to-frame matching mode for collision-detected rigid contacts.

contact_matching_pos_threshold: float | None

Maximum midpoint distance for matching rigid contacts [m].

contact_matching_normal_dot_threshold: float | None

Minimum normal dot product for matching rigid contacts.

contact_matching_force_scale: float

Scale applied to the previous ADMM dual when a rigid contact matches.

Newton Coupler

class isaaclab_contrib.coupling.NewtonCouplerManager

Bases: NewtonVBDManager

Couple named Newton solver entries through proxy or ADMM interfaces.

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, physics_cfg])	Create a ModelBuilder configured with default settings.
create_fixed_tendon_control(articulation)	Build the solver's fixed-tendon command adapter for articulation.
create_visual_material_writer(batches)	Compile material-to-shape addresses for the active Newton model.
create_visual_shape_color_writer(asset, ...)	Compile selected articulation-body shape addresses for the active Newton model.
deregister_callback(callback_id)	Remove a registered callback.
dispatch_event(event[, payload])	Dispatch an event to all registered callbacks.
fix_articulation_root(articulation_prim[, stage])	Ensure that an articulation root has one enabled world fixed joint.
forward()	Update articulation kinematics without stepping physics.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
get_contacts()	Get the current Newton contact buffer, if the active solver exposes one.
get_control()	Get the control object.
get_device()	Get the physics simulation device.
get_dt()	Get the physics timestep.
get_model()	Return the active physics model.
get_physics_dt()	Get the physics timestep in seconds.
get_physics_sim_view()	Return the registered articulation views.
get_scene_data_backend()	Return the SceneDataBackend for the SceneDataProvider.
get_scene_data_provider()	Return the active scene data provider.
get_simulation_time()	Get the current simulation time in seconds.
get_solver_dt()	Get the solver substep timestep.
get_state_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()	Import the explicitly declared clone plan into the Newton builder.
invalidate_body_state([env_ids, env_mask])	Mark selected maximal-coordinate body state as changed without requesting FK.
invalidate_fk([env_mask, env_ids, ...])	Mark environments as needing FK recomputation and solver reset.
is_fabric_enabled()	Check if fabric interface is enabled (not applicable for Newton).
pause()	Pause physics simulation.
play()	Start or resume physics simulation.
pre_render()	Sync deferred physics state to the rendering backend.
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.
register_post_step_callback(callback)	Append a hook to the list invoked after the last solver substep on every step.
register_state_force_callback(callback)	Register a graph-safe callback that applies forces before every solver substep.
request_extended_contact_attribute(attr)	Request an extended contact attribute (e.g. "force").
request_extended_state_attribute(attr)	Request an extended state attribute (e.g. "body_qdd").
reset([soft])	Reset physics simulation.
safe_callback_invoke(fn, *args[, ...])	Invoke a callback, catching exceptions that would be swallowed by external event buses.
set_decimation(decimation)	Set the decimation count and re-capture the CUDA graph.
setup_deformable_body(prim, deformable_type, ...)	Apply Newton's token deformable anchor schemas and sync the visual mesh geometry.
start_simulation()	Start simulation by finalizing model and initializing state.
step()	Step the physics simulation.
stop()	Stop physics simulation.
unregister_post_step_callback(callback)	Remove a previously registered post-step callback.
video_capture_backend()	Newton GL headless perspective video capture.
wait_for_playing()	Block until the timeline is playing.

Attributes:

backend	Borrowed native resource shared by physics and scene consumers; the simulation registry owns it.
supports_anim_recording	Whether this backend can service --anim_recording_enabled (OVD Recorder).

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.

Compiles the Isaac Lab regular expressions and delegates to newton.sensors.SensorContact, which full-matches compiled patterns against model labels.

Parameters:

• body_names_expr – Expression for body names to sense.

• shape_names_expr – Expression for shape names to sense.

• contact_partners_body_expr – Expression for contact partner body names.

• contact_partners_shape_expr – Expression for contact partner shape names.

• verbose – Print verbose information.

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

Add a frame transform sensor for measuring relative transforms.

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

Parameters:

• shapes – Ordered list of shape indices to measure.

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

Returns:

Index of the newly created sensor in _newton_frame_transform_sensors.

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

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

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

Parameters:

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

Returns:

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

classmethod add_model_change(change: newton.ModelFlags) → None

Register a model change to notify the solver.

classmethod after_visualizers_render() → None

Hook after visualizers have stepped during render().

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

backend: ClassVar[NewtonBackend | None] = None

Borrowed native resource shared by physics and scene consumers; the simulation registry owns it.

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

Register a site request for injection into prototypes before replication.

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

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

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

Parameters:

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

• xform – Site transform relative to body.

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

Returns:

Assigned site label suffix.

classmethod clear()

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

classmethod clear_callbacks() → None

Remove all registered callbacks.

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

classmethod close() → None

Clean up Newton physics resources.

classmethod create_builder(up_axis: str | None = None, *, physics_cfg: NewtonCfg | 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.

• physics_cfg – Explicit builder settings; None uses the active physics configuration.

• **kwargs – Forwarded to ModelBuilder.

Returns:

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

classmethod create_fixed_tendon_control(articulation)

Build the solver’s fixed-tendon command adapter for articulation.

Tendon state is backend-neutral and lives on the articulation; how a target reaches the solver is not. MuJoCo drives tendons through actuator controls, so only the MJWarp manager implements this. The articulation stores what it gets, the way it stores its actuator control, and never needs to know which solver is active.

Only the MuJoCo solver registers the mujoco:tendon frequency, so an articulation reports tendons under MJWarp alone and this base is unreachable through the normal path. Reaching it means a solver gained tendons with no way to command them, which is worth saying rather than returning nothing – None already means “this asset’s tendons are all passive”.

Parameters:

articulation – Newton articulation to drive.

Raises:

NotImplementedError – Always – this solver has no fixed-tendon transmission.

classmethod create_visual_material_writer(batches: tuple[VisualMaterialBatch, ...]) → VisualMaterialWriter

Compile material-to-shape addresses for the active Newton model.

classmethod create_visual_shape_color_writer(asset: BaseArticulation, body_names: tuple[str, ...]) → VisualShapeColorWriter

Compile selected articulation-body shape addresses for the active Newton model.

classmethod deregister_callback(callback_id: int | CallbackHandle) → None

Remove a registered callback.

Parameters:

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

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

Dispatch an event to all registered callbacks.

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

Parameters:

• event – The event to dispatch.

• payload – Optional data to pass to callbacks.

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

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

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

Parameters:

• articulation_prim – The articulation-root prim to fix.

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

Returns:

The articulation-root prim after backend normalization.

Raises:

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

classmethod forward() → None

Update articulation kinematics without stepping physics.

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

Asset and scene-data reads share the same pending work. The bound delegate dispatches calls on NewtonManager to the active solver’s implementation.

classmethod get_backend() → str

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

classmethod get_contacts() → Contacts | None

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

classmethod get_control() → newton.Control

Get the control object.

classmethod get_device() → str

Get the physics simulation device.

classmethod get_dt() → float

Get the physics timestep. Alias for get_physics_dt().

classmethod get_model() → newton.Model

Return the active physics model. Render consumers acquire their backend from the registry.

classmethod get_physics_dt() → float

Get the physics timestep in seconds.

classmethod get_physics_sim_view() → list

Return the registered articulation views.

classmethod get_scene_data_backend() → SceneDataBackend | None

Return the SceneDataBackend for the SceneDataProvider.

classmethod get_scene_data_provider() → SceneDataProvider

Return the active scene data provider.

classmethod get_simulation_time() → float

Get the current simulation time in seconds.

classmethod get_solver_dt() → float

Get the solver substep timestep.

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

Construct the solver and contacts, establish the initial body state, and schedule graph capture for the first step after the environment has authored its initial state. Initialization and capture do not advance physics.

classmethod instantiate_builder_from_stage()

Import the explicitly declared clone plan into the Newton builder.

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

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

Parameters:

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

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

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

Mark environments as needing FK recomputation and solver reset.

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

Parameters:

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

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

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

classmethod is_fabric_enabled() → bool

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

classmethod pause() → None

Pause physics simulation. Default is no-op.

classmethod play() → None

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

classmethod pre_render() → None

Sync deferred physics state to the rendering backend.

Called by render() before cameras and visualizers read scene data. The default implementation is a no-op. Backends that defer transform writes (e.g. Newton’s dirty-flag pattern) should override this to flush pending updates.

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 register_post_step_callback(callback: Callable[[], None]) → None

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

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

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

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

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

Parameters:

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

classmethod request_extended_contact_attribute(attr: str) → None

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

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

Parameters:

attr – Contact attribute name.

classmethod request_extended_state_attribute(attr: str) → None

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

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

Parameters:

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

classmethod reset(soft: bool = False) → None

Reset physics simulation.

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

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

Parameters:

soft – If True, skip full reinitialization.

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

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

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

Note (Octi):

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

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

Invalidate the existing graph when the loop changes. Its replacement is captured immediately before the next requested step, after authored state is reconciled.

classmethod setup_deformable_body(prim: Any, deformable_type: str, sim_mesh_prim: Any, vis_mesh_prim: Any) → None

Apply Newton’s token deformable anchor schemas and sync the visual mesh geometry.

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.

supports_anim_recording: ClassVar[bool] = False

Whether this backend can service --anim_recording_enabled (OVD Recorder).

Overridden by backends that implement the recorder (currently PhysX-only).

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

Remove a previously registered post-step callback.

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

classmethod video_capture_backend() → str

Newton GL headless perspective video capture.

classmethod wait_for_playing() → None

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