isaaclab_contrib.deformable

isaaclab_contrib.deformable#

Sub-package for externally contributed assets.

This package contains contributed code that depends on Isaac Lab’s public API but is not required for core functionality. This includes implementations of Newton solvers for deformables.

Classes

`deformable_object.DeformableObject`	A deformable object asset class (Newton backend).
`deformable_object_data.DeformableObjectData`	Data container for a deformable object (Newton backend).
`newton_manager_cfg.VBDSolverCfg`	Configuration for the Vertex Block Descent (VBD) solver.
`newton_manager_cfg.CoupledMJWarpVBDSolverCfg`	Configuration for the coupled rigid-body MJWarp + VBD solver.
`newton_manager_cfg.CoupledFeatherstoneVBDSolverCfg`	Configuration for the coupled rigid-body Featherstone + VBD solver.
`newton_manager_cfg.NewtonModelCfg`	Global Newton model parameters.
`vbd_manager.NewtonVBDManager`	`NewtonManager` specialization for the VBD solver.
`coupled_mjwarp_vbd_manager.NewtonCoupledMJWarpVBDManager`	`NewtonManager` specialization for the coupled MJWarp + VBD solver.
`coupled_featherstone_vbd_manager.NewtonCoupledFeatherstoneVBDManager`	`NewtonManager` specialization for the coupled Featherstone + VBD solver.

Deformable Object#

class isaaclab_contrib.deformable.deformable_object.DeformableObject[source]#

Bases: BaseDeformableObject

A deformable object asset class (Newton backend).

This class manages cloth/deformable bodies in the Newton physics engine. Newton stores all particles in flat arrays (state.particle_q, state.particle_qd). This class builds a per-instance indexing layer on top of those flat arrays, enabling the standard BaseDeformableObject interface for reading/writing nodal state.

The cloth mesh is added to the Newton ModelBuilder during the MODEL_INIT phase. The mesh data is read from the USD prim at cfg.prim_path, and cloth simulation parameters (density, stiffness, etc.) come from DeformableObjectCfg.

Attributes:

`cfg`	Configuration instance for the deformable object.
`data`	Data container for the deformable object.
`num_instances`	Number of instances of the asset.
`num_bodies`	Number of bodies in the asset.
`max_sim_vertices_per_body`	The maximum number of simulation mesh vertices per deformable body.
`device`	Memory device for computation.
`has_debug_vis_implementation`	Whether the asset has a debug visualization implemented.
`is_initialized`	Whether the asset is initialized.

Methods:

`__init__`(cfg)	Initialize the deformable object.
`reset`([env_ids, env_mask])	Reset the deformable object.
`write_data_to_sim`()	Apply kinematic targets to the Newton simulation.
`update`(dt)	Update the internal buffers.
`write_nodal_pos_to_sim_index`(nodal_pos[, ...])	Set the nodal positions over selected environment indices into the simulation.
`write_nodal_velocity_to_sim_index`(nodal_vel)	Set the nodal velocity over selected environment indices into the simulation.
`write_nodal_kinematic_target_to_sim_index`(targets)	Set the kinematic targets of the simulation mesh for the deformable bodies.
`write_nodal_state_to_sim_mask`(nodal_state[, ...])	Set the nodal state over selected environment mask into the simulation.
`write_nodal_pos_to_sim_mask`(nodal_pos[, ...])	Set the nodal positions over selected environment mask into the simulation.
`write_nodal_velocity_to_sim_mask`(nodal_vel)	Set the nodal velocity over selected environment mask into the simulation.
`write_nodal_kinematic_target_to_sim_mask`(targets)	Set the kinematic targets over selected environment mask into the target buffer.
`assert_shape_and_dtype`(tensor, shape, dtype)	Assert the shape and dtype of a tensor or warp array.
`assert_shape_and_dtype_mask`(tensor, masks, dtype)	Assert the shape of a tensor or warp array against mask dimensions.
`set_debug_vis`(debug_vis)	Sets whether to visualize the asset data.
`set_visibility`(visible[, env_ids])	Set the visibility of the prims corresponding to the asset.
`transform_nodal_pos`(nodal_pos[, pos, quat])	Transform the nodal positions based on the pose transformation.
`write_nodal_kinematic_target_to_sim`(targets)	Deprecated.
`write_nodal_pos_to_sim`(nodal_pos[, env_ids])	Deprecated.
`write_nodal_state_to_sim`(nodal_state[, env_ids])	Deprecated.
`write_nodal_state_to_sim_index`(nodal_state)	Set the nodal state over selected environment indices into the simulation.
`write_nodal_velocity_to_sim`(nodal_vel[, env_ids])	Deprecated.

cfg: DeformableObjectCfg#: Configuration instance for the deformable object.

__init__(cfg: DeformableObjectCfg)[source]#

Initialize the deformable object.

Parameters:: cfg – A configuration instance.

property data: DeformableObjectData#: Data container for the deformable object.

property num_instances: int#: Number of instances of the asset.

property num_bodies: int#

Number of bodies in the asset.

This is always 1 since each object is a single deformable body.

property max_sim_vertices_per_body: int#: The maximum number of simulation mesh vertices per deformable body.

reset(env_ids: Sequence[int] | None = None, env_mask: wp.array | None = None) → None[source]#

Reset the deformable object.

No-op to match the PhysX deformable object convention.

Parameters:

env_ids – Environment indices. If None, then all indices are used.
env_mask – Environment mask. If None, then all the instances are updated. Shape is (num_instances,).

write_data_to_sim()[source]#

Apply kinematic targets to the Newton simulation.

Reads the stored kinematic target buffer and enforces it on particles: kinematic particles (flag=0) get inv_mass=0, particle_flags=0, target position, and zero velocity; free particles (flag=1) get their original inv_mass and particle_flags=1 (ACTIVE) restored.

Writes to both state_0 and state_1 so kinematic positions survive the state swaps that happen between substeps.

update(dt: float)[source]#

Update the internal buffers.

Parameters:: dt – The amount of time passed from last update() call [s].

Set the nodal positions over selected environment indices into the simulation.

Parameters:

nodal_pos – Nodal positions in simulation frame [m]. Shape is (len(env_ids), max_sim_vertices_per_body, 3) or (num_instances, max_sim_vertices_per_body, 3).
env_ids – Environment indices. If None, then all indices are used.
full_data – Whether to expect full data. Defaults to False.

Set the nodal velocity over selected environment indices into the simulation.

Parameters:

nodal_vel – Nodal velocities in simulation frame [m/s]. Shape is (len(env_ids), max_sim_vertices_per_body, 3) or (num_instances, max_sim_vertices_per_body, 3).
env_ids – Environment indices. If None, then all indices are used.
full_data – Whether to expect full data. Defaults to False.

Set the kinematic targets of the simulation mesh for the deformable bodies.

Newton has no native kinematic target API. Instead: - Kinematic (flag=0.0): set particle_inv_mass to 0, write target pos, zero vel - Free (flag=1.0): restore original particle_inv_mass

Parameters:

targets – The kinematic targets comprising of nodal positions and flags [m]. Shape is (len(env_ids), max_sim_vertices_per_body, 4) or (num_instances, max_sim_vertices_per_body, 4).
env_ids – Environment indices. If None, then all indices are used.
full_data – Whether to expect full data. Defaults to False.

write_nodal_state_to_sim_mask(nodal_state: torch.Tensor | wp.array | ProxyArray, env_mask: wp.array | torch.Tensor | None = None) → None[source]#

Set the nodal state over selected environment mask into the simulation.

Parameters:

nodal_state – Nodal state in simulation frame [m, m/s]. Shape is (num_instances, max_sim_vertices_per_body, 6).
env_mask – Environment mask. If None, then all indices are used. Shape is (num_instances,).

write_nodal_pos_to_sim_mask(nodal_pos: torch.Tensor | wp.array | ProxyArray, env_mask: wp.array | torch.Tensor | None = None) → None[source]#

Set the nodal positions over selected environment mask into the simulation.

Parameters:

nodal_pos – Nodal positions in simulation frame [m]. Shape is (num_instances, max_sim_vertices_per_body, 3).
env_mask – Environment mask. If None, then all indices are used. Shape is (num_instances,).

write_nodal_velocity_to_sim_mask(nodal_vel: torch.Tensor | wp.array | ProxyArray, env_mask: wp.array | torch.Tensor | None = None) → None[source]#

Set the nodal velocity over selected environment mask into the simulation.

Parameters:

nodal_vel – Nodal velocities in simulation frame [m/s]. Shape is (num_instances, max_sim_vertices_per_body, 3).
env_mask – Environment mask. If None, then all indices are used. Shape is (num_instances,).

write_nodal_kinematic_target_to_sim_mask(targets: torch.Tensor | wp.array | ProxyArray, env_mask: wp.array | torch.Tensor | None = None) → None[source]#

Set the kinematic targets over selected environment mask into the target buffer.

Parameters:

targets – The kinematic targets comprising of nodal positions and flags [m]. Shape is (num_instances, max_sim_vertices_per_body, 4).
env_mask – Environment mask. If None, then all indices are used. Shape is (num_instances,).

assert_shape_and_dtype(tensor: float | torch.Tensor | wp.array, shape: tuple[int, ...], dtype: type, name: str = '') → None#

Assert the shape and dtype of a tensor or warp array.

Controlled by AssetBaseCfg.disable_shape_checks. When checks are disabled this method is a no-op.

Parameters:

tensor – The tensor or warp array to assert the shape of. Floats are skipped.
shape – The expected leading dimensions (e.g. (num_envs, num_joints)).
dtype – The expected warp dtype.
name – Optional parameter name for error messages.

assert_shape_and_dtype_mask(tensor: float | torch.Tensor | wp.array, masks: tuple[wp.array, ...], dtype: type, name: str = '', trailing_dims: tuple[int, ...] = ()) → None#

Assert the shape of a tensor or warp array against mask dimensions.

Mask-based write methods expect full-sized data — one element per entry in each mask dimension, regardless of how many entries are True. The expected leading shape is therefore (mask_0.shape[0], mask_1.shape[0], ...) (i.e. the total size of each dimension, not the number of selected entries).

Controlled by AssetBaseCfg.disable_shape_checks. When checks are disabled this method is a no-op.

Parameters:

tensor – The tensor or warp array to assert the shape of. Floats are skipped.
masks – Tuple of mask arrays whose shape[0] dimensions form the expected leading shape.
dtype – The expected warp dtype.
name – Optional parameter name for error messages.
trailing_dims – Extra trailing dimensions to append (e.g. (9,) for inertias with wp.float32).

property device: str#: Memory device for computation.

property has_debug_vis_implementation: bool#: Whether the asset has a debug visualization implemented.

property is_initialized: bool#

Whether the asset is initialized.

Returns True if the asset is initialized, False otherwise.

set_debug_vis(debug_vis: bool) → bool#

Sets whether to visualize the asset data.

Parameters:: debug_vis – Whether to visualize the asset data.
Returns:: Whether the debug visualization was successfully set. False if the asset does not support debug visualization.

set_visibility(visible: bool, env_ids: Sequence[int] | None = None)#

Set the visibility of the prims corresponding to the asset.

This operation affects the visibility of the prims corresponding to the asset in the USD stage. It is useful for toggling the visibility of the asset in the simulator. For instance, one can hide the asset when it is not being used to reduce the rendering overhead.

Note

This operation uses the PXR API to set the visibility of the prims. Thus, the operation may have an overhead if the number of prims is large.

Parameters:

visible – Whether to make the prims visible or not.
env_ids – The indices of the object to set visibility. Defaults to None (all instances).

transform_nodal_pos(nodal_pos: torch.Tensor, pos: torch.Tensor | None = None, quat: torch.Tensor | None = None) → torch.Tensor#

Transform the nodal positions based on the pose transformation.

This function computes the transformation of the nodal positions based on the pose transformation. It multiplies the nodal positions with the rotation matrix of the pose and adds the translation. Internally, it calls the isaaclab.utils.math.transform_points() function.

Parameters:

nodal_pos – The nodal positions in the simulation frame [m]. Shape is (N, max_sim_vertices_per_body, 3).
pos – The position transformation [m]. Shape is (N, 3). Defaults to None, in which case the position is assumed to be zero.
quat – The orientation transformation as quaternion (x, y, z, w). Shape is (N, 4). Defaults to None, in which case the orientation is assumed to be identity.

Returns:

The transformed nodal positions [m]. Shape is (N, max_sim_vertices_per_body, 3).

write_nodal_kinematic_target_to_sim(targets: torch.Tensor | wp.array | ProxyArray, env_ids: Sequence[int] | torch.Tensor | wp.array | None = None) → None#: Deprecated. Please use write_nodal_kinematic_target_to_sim_index() instead.

write_nodal_pos_to_sim(nodal_pos: torch.Tensor | wp.array | ProxyArray, env_ids: Sequence[int] | torch.Tensor | wp.array | None = None) → None#: Deprecated. Please use write_nodal_pos_to_sim_index() instead.

write_nodal_state_to_sim(nodal_state: torch.Tensor | wp.array | ProxyArray, env_ids: Sequence[int] | torch.Tensor | wp.array | None = None) → None#: Deprecated. Please use write_nodal_state_to_sim_index() instead.

Set the nodal state over selected environment indices into the simulation.

The nodal state comprises of the nodal positions and velocities. Since these are nodes, the velocity only has a translational component. All the quantities are in the simulation frame.

Parameters:

nodal_state – Nodal state in simulation frame [m, m/s]. Shape is (len(env_ids), max_sim_vertices_per_body, 6) or (num_instances, max_sim_vertices_per_body, 6).
env_ids – Environment indices. If None, then all indices are used.
full_data – Whether to expect full data. Defaults to False.

write_nodal_velocity_to_sim(nodal_vel: torch.Tensor | wp.array | ProxyArray, env_ids: Sequence[int] | torch.Tensor | wp.array | None = None) → None#: Deprecated. Please use write_nodal_velocity_to_sim_index() instead.

class isaaclab_contrib.deformable.deformable_object_data.DeformableObjectData[source]#

Bases: BaseDeformableObjectData

Data container for a deformable object (Newton backend).

Newton stores all particles in flat arrays (model.particle_q, state.particle_qd). This data class builds a per-instance view by gathering from the flat arrays using precomputed offsets.

The data is lazily updated, meaning that the data is only updated when it is accessed.

Attributes:

`default_nodal_state_w`	Default nodal state `[nodal_pos, nodal_vel]` in simulation world frame.
`nodal_kinematic_target`	Simulation mesh kinematic targets for the deformable bodies.
`nodal_pos_w`	Nodal positions in simulation world frame [m].
`nodal_vel_w`	Nodal velocities in simulation world frame [m/s].
`nodal_state_w`	Nodal state `[nodal_pos, nodal_vel]` in simulation world frame [m, m/s].
`root_pos_w`	Root position from nodal positions [m].
`root_vel_w`	Root velocity from nodal velocities [m/s].

Methods:

update(dt)

Update the data for the deformable object.

default_nodal_state_w: ProxyArray = None#: Default nodal state [nodal_pos, nodal_vel] in simulation world frame. Shape is (num_instances, particles_per_body) with dtype vec6f.

nodal_kinematic_target: ProxyArray = None#: Simulation mesh kinematic targets for the deformable bodies. Shape is (num_instances, particles_per_body) with dtype vec4f.

property nodal_pos_w: ProxyArray#: Nodal positions in simulation world frame [m]. Shape is (num_instances, particles_per_body) vec3f.

property nodal_vel_w: ProxyArray#: Nodal velocities in simulation world frame [m/s]. Shape is (num_instances, particles_per_body) vec3f.

property nodal_state_w: ProxyArray#

Nodal state [nodal_pos, nodal_vel] in simulation world frame [m, m/s].

Shape is (num_instances, particles_per_body) vec6f.

property root_pos_w: ProxyArray#

Root position from nodal positions [m]. Shape is (num_instances,) vec3f.

This quantity is computed as the mean of the nodal positions.

update(dt: float)#

Update the data for the deformable object.

Parameters:: dt – The time step for the update [s]. This must be a positive value.

property root_vel_w: ProxyArray#

Root velocity from nodal velocities [m/s]. Shape is (num_instances,) vec3f.

This quantity is computed as the mean of the nodal velocities.

Newton Solver Configurations#

class isaaclab_contrib.deformable.newton_manager_cfg.VBDSolverCfg[source]#

Bases: NewtonSolverCfg

Configuration for the Vertex Block Descent (VBD) solver.

Supports particle simulation (cloth, soft bodies) and coupled rigid-body systems. Requires ModelBuilder.color() to be called before finalize() to build the parallel vertex colouring needed by the solver.

Attributes:

`class_type`	Manager class for the VBD solver.
`solver_type`	Solver type metadata (deprecated).
`iterations`	Number of VBD iterations per substep.
`integrate_with_external_rigid_solver`	Whether rigid bodies are integrated by an external solver (one-way coupling).
`particle_enable_self_contact`	Whether to enable VBD deformable's self-contact.
`particle_self_contact_radius`	Particle radius used for self-contact detection [m].
`particle_self_contact_margin`	Self-contact detection margin [m].
`particle_collision_detection_interval`	Controls how frequently particle self-contact detection is applied.
`particle_vertex_contact_buffer_size`	Preallocation size for each vertex's vertex-triangle collision buffer.
`particle_edge_contact_buffer_size`	Preallocation size for each edge's edge-edge collision buffer.
`particle_topological_contact_filter_threshold`	Maximum topological distance (in rings) below which self-contacts are discarded.
`particle_rest_shape_contact_exclusion_radius`	World-space distance threshold for filtering topologically close primitives [m].
`rigid_contact_k_start`	Initial stiffness seed for all rigid body contacts (body-body and body-particle) [N/m].

class_type: type[NewtonManager] | str#: Manager class for the VBD solver.

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.

iterations: int#: Number of VBD iterations per substep.

integrate_with_external_rigid_solver: bool#

Whether rigid bodies are integrated by an external solver (one-way coupling).

Set to True when coupling cloth with a separate rigid-body solver (e.g. SolverFeatherstone) so that VBD only integrates the cloth particles.

particle_enable_self_contact: bool#: Whether to enable VBD deformable’s self-contact.

particle_self_contact_radius: float#: Particle radius used for self-contact detection [m].

particle_self_contact_margin: float#: Self-contact detection margin [m]. Should be >= particle_self_contact_radius.

particle_collision_detection_interval: int#

Controls how frequently particle self-contact detection is applied.

If set to a value < 0, collision detection is only performed once before the initialization step. If set to 0, collision detection is applied twice: once before and once immediately after initialization. If set to a value k >= 1, collision detection is applied before every k VBD iterations.

particle_vertex_contact_buffer_size: int#: Preallocation size for each vertex’s vertex-triangle collision buffer.

particle_edge_contact_buffer_size: int#: Preallocation size for each edge’s edge-edge collision buffer.

particle_topological_contact_filter_threshold: int#

Maximum topological distance (in rings) below which self-contacts are discarded.

Only used when particle_enable_self_contact is True. Increase to suppress contacts between closely connected mesh elements. Values > 3 significantly increase computation time.

particle_rest_shape_contact_exclusion_radius: float#

World-space distance threshold for filtering topologically close primitives [m].

Candidate self-contacts whose rest-configuration separation is shorter than this value are ignored. Only used when particle_enable_self_contact is True.

rigid_contact_k_start: float#

Initial stiffness seed for all rigid body contacts (body-body and body-particle) [N/m].

Used by the AVBD rigid contact solver. Increase to make rigid contacts stiffer.

class isaaclab_contrib.deformable.newton_manager_cfg.CoupledMJWarpVBDSolverCfg[source]#

Bases: NewtonSolverCfg

Configuration for the coupled rigid-body MJWarp + VBD solver.

Alternates a rigid-body solver (MJWarpSolverCfg) and a soft-body solver (SolverVBD) per substep. The coupling direction is controlled by coupling_mode:

"one_way" (default): Rigid solver advances first, then VBD reads the updated body poses. The rigid solver does not feel particle contacts.
"two_way": Same-substep two-way coupling with normal + Coulomb friction. Contact detection runs first, reaction forces are injected into body_f, then the rigid solver reads body_f and feels resistance from the deformable object. The friction reaction lets actuators carry the object against gravity during a lift.

Attributes:

`class_type`	Manager class for the VBD solver.
`solver_type`	Solver type metadata (deprecated).
`rigid_solver_cfg`	Rigid-body sub-solver configuration for `MJWarpSolverCfg`.
`soft_solver_cfg`	VBD sub-solver configuration for cloth/particle dynamics.
`coupling_mode`	Coupling direction between the rigid and VBD solvers.

class_type: type[NewtonManager] | str#: Manager class for the VBD solver.

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.

rigid_solver_cfg: MJWarpSolverCfg#: Rigid-body sub-solver configuration for MJWarpSolverCfg.

soft_solver_cfg: VBDSolverCfg#: VBD sub-solver configuration for cloth/particle dynamics.

coupling_mode: str#

Coupling direction between the rigid and VBD solvers.

"one_way": Rigid -> soft only (default, existing behavior).
"two_way": Same-substep two-way coupling with normal + Coulomb friction.

class isaaclab_contrib.deformable.newton_manager_cfg.CoupledFeatherstoneVBDSolverCfg[source]#

Bases: NewtonSolverCfg

Configuration for the coupled rigid-body Featherstone + VBD solver.

Alternates a rigid-body solver (FeatherstoneSolverCfg) and a soft-body solver (SolverVBD) per substep. The coupling direction is controlled by coupling_mode:

"kinematic" (default): Rigid -> soft only. Rigid bodies are kinematically updated by the rigid solver, then VBD reads the updated body poses and reacts to them. The rigid solver does not feel particle contacts.
"one_way": Rigid solver advances first, then VBD reads the updated body poses. The rigid solver does not feel particle contacts.
"two_way": Same-substep two-way coupling with normal + Coulomb friction. Contact detection runs first, reaction forces are injected into body_f, then the rigid solver reads body_f and feels resistance from the deformable object. The friction reaction lets actuators carry the object against gravity during a lift.

Attributes:

`class_type`	Manager class for the VBD solver.
`solver_type`	Solver type metadata (deprecated).
`rigid_solver_cfg`	Rigid-body sub-solver configuration for `FeatherstoneSolverCfg`.
`soft_solver_cfg`	VBD sub-solver configuration for cloth/particle dynamics.
`coupling_mode`	Coupling direction between the rigid and VBD solvers.

class_type: type[NewtonManager] | str#: Manager class for the VBD solver.

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.

rigid_solver_cfg: FeatherstoneSolverCfg#: Rigid-body sub-solver configuration for FeatherstoneSolverCfg.

soft_solver_cfg: VBDSolverCfg#: VBD sub-solver configuration for cloth/particle dynamics.

coupling_mode: str#

Coupling direction between the rigid and VBD solvers.

"kinematic": Rigid -> soft only (default)
"one_way": Rigid -> soft only (existing behavior).
"two_way": Same-substep two-way coupling with normal + Coulomb friction.

class isaaclab_contrib.deformable.newton_manager_cfg.NewtonModelCfg[source]#

Bases: object

Global Newton model parameters.

These parameters are applied to the newton.Model after finalization. They control model-level contact behavior shared across all objects.

Attributes:

`soft_contact_ke`	Body-particle contact stiffness [N/m].
`soft_contact_kd`	Body-particle contact damping [N*s/m].
`soft_contact_mu`	Body-particle contact friction coefficient.
`shape_material_ke`	Per-shape contact stiffness override [N/m].
`shape_material_kd`	Per-shape contact damping override [N*s/m].
`shape_material_mu`	Per-shape friction coefficient override [dimensionless].

soft_contact_ke: float#

Body-particle contact stiffness [N/m].

Controls the stiffness of the penalty force of contacts between cloth/soft-body particles and rigid body shapes, and self-contacts of cloth/soft-body particles. The effective stiffness per contact is the average of this value and the rigid shape’s material stiffness.

soft_contact_kd: float#: Body-particle contact damping [N*s/m].

soft_contact_mu: float#

Body-particle contact friction coefficient.

The effective friction per contact is sqrt(soft_contact_mu * shape_material_mu). Increase for better grip (e.g. gripper picking up cloth).

shape_material_ke: float | None#

Per-shape contact stiffness override [N/m].

When set, all collision shapes in the model will have their contact stiffness overwritten to this value. If None (default), the per-shape values parsed from USD/MJCF are kept.

shape_material_kd: float | None#

Per-shape contact damping override [N*s/m].

When set, all collision shapes in the model will have their contact damping overwritten to this value. If None (default), the per-shape values parsed from USD/MJCF are kept.

shape_material_mu: float | None#

Per-shape friction coefficient override [dimensionless].

When set, all collision shapes in the model will have their friction coefficient overwritten to this value. If None (default), the per-shape values parsed from USD/MJCF are kept.

Newton Solver Managers#

class isaaclab_contrib.deformable.vbd_manager.NewtonVBDManager[source]#

Bases: NewtonManager

NewtonManager specialization for the VBD solver.

Always uses Newton’s CollisionPipeline for contact handling.

Methods:

`initialize`(sim_context)	Initialize the manager with simulation context.
`start_simulation`()	Start simulation by finalizing model and initializing state.
`instantiate_builder_from_stage`()	Create builder from USD stage with special treatment for deformable bodies, as these are not read from USD yet.
`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_solver`()	Initialize the solver and collision pipeline.
`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.
`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 initialize(sim_context: SimulationContext) → None[source]#

Initialize the manager with simulation context.

Parameters:: sim_context – Parent simulation context.

TODO: Subclass should not override this method, once deformables supported on Newton import_usd, this can be unified with NewtonManager’s implementation.

classmethod start_simulation() → None[source]#

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.

TODO: Subclass should not override this method, missing piece is having Newton bind a surface mesh to volume deformable tetrahedral mesh in addition to removing the deformable_registry data structure.

classmethod instantiate_builder_from_stage()[source]#

Create builder from USD stage with special treatment for deformable bodies, as these are not read from USD yet.

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.

TODO: Subclass should not override this method, once deformables supported on Newton import_usd, this can be unified with NewtonManager’s implementation.

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:

Sets _use_newton_actuators_active, which _is_all_graphable() checks (adapter presence alone cannot distinguish the fast path from the standard Lab path).
On first call, builds the single sim-level NewtonActuatorAdapter over the full flat DOF layout; later calls reuse it.

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_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 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 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_contrib.deformable.coupled_mjwarp_vbd_manager.NewtonCoupledMJWarpVBDManager[source]#

Bases: NewtonManager

NewtonManager specialization for the coupled MJWarp + VBD solver. Due to Newton deformables not being properly integrated yet, this manager uses the same temporary solutions from VBD Manager.

Always uses Newton’s CollisionPipeline for contact handling.

Methods:

`initialize`(sim_context)	Initialize the manager with simulation context.
`step`()	Step the physics simulation.
`start_simulation`()	Start simulation by finalizing model and initializing state.
`instantiate_builder_from_stage`()	Create builder from USD stage with special treatment for deformable bodies, as these are not read from USD yet.
`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_solver`()	Initialize the solver and collision pipeline.
`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.
`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 initialize(sim_context: SimulationContext) → None[source]#

Initialize the manager with simulation context.

Parameters:: sim_context – Parent simulation context.

TODO: Subclass should not override this method, once deformables supported on Newton import_usd, this can be unified with NewtonManager’s implementation.

classmethod step() → None[source]#: Step the physics simulation.

classmethod start_simulation() → None[source]#

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.

TODO: Subclass should not override this method, missing piece is having Newton bind a surface mesh to volume deformable tetrahedral mesh in addition to removing the deformable_registry data structure.

classmethod instantiate_builder_from_stage()[source]#

Create builder from USD stage with special treatment for deformable bodies, as these are not read from USD yet.

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.

TODO: Subclass should not override this method, once deformables supported on Newton import_usd, this can be unified with NewtonManager’s implementation.

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:

Sets _use_newton_actuators_active, which _is_all_graphable() checks (adapter presence alone cannot distinguish the fast path from the standard Lab path).
On first call, builds the single sim-level NewtonActuatorAdapter over the full flat DOF layout; later calls reuse it.

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_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 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 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_contrib.deformable.coupled_featherstone_vbd_manager.NewtonCoupledFeatherstoneVBDManager[source]#

Bases: NewtonManager

NewtonManager specialization for the coupled Featherstone + VBD solver. Due to Newton deformables not being properly integrated yet, this manager uses the same temporary solutions from VBD Manager.

Always uses Newton’s CollisionPipeline for contact handling.

Methods:

`initialize`(sim_context)	Initialize the manager with simulation context.
`step`()	Step the physics simulation.
`start_simulation`()	Start simulation by finalizing model and initializing state.
`instantiate_builder_from_stage`()	Create builder from USD stage with special treatment for deformable bodies, as these are not read from USD yet.
`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_solver`()	Initialize the solver and collision pipeline.
`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.
`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 initialize(sim_context: SimulationContext) → None[source]#

Initialize the manager with simulation context.

Parameters:: sim_context – Parent simulation context.

TODO: Subclass should not override this method, once deformables supported on Newton import_usd, this can be unified with NewtonManager’s implementation.

classmethod step() → None[source]#: Step the physics simulation.

classmethod start_simulation() → None[source]#

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.

TODO: Subclass should not override this method, missing piece is having Newton bind a surface mesh to volume deformable tetrahedral mesh in addition to removing the deformable_registry data structure.

classmethod instantiate_builder_from_stage()[source]#

Create builder from USD stage with special treatment for deformable bodies, as these are not read from USD yet.

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.

TODO: Subclass should not override this method, once deformables supported on Newton import_usd, this can be unified with NewtonManager’s implementation.

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:

Sets _use_newton_actuators_active, which _is_all_graphable() checks (adapter presence alone cannot distinguish the fast path from the standard Lab path).
On first call, builds the single sim-level NewtonActuatorAdapter over the full flat DOF layout; later calls reuse it.

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

isaaclab_contrib.deformable

Contents

isaaclab_contrib.deformable#

Deformable Object#

Newton Solver Configurations#

Newton Solver Managers#