newton.CollisionPipeline#

class newton.CollisionPipeline(model, *, reduce_contacts=True, rigid_contact_max=None, max_triangle_pairs=1000000, shape_pairs_filtered=None, soft_contact_max=None, soft_contact_margin=0.01, requires_grad=None, broad_phase=None, narrow_phase=None, sdf_hydroelastic_config=None, shape_pairs_max=None, deterministic=False, contact_matching='disabled', contact_matching_pos_threshold=0.0005, contact_matching_normal_dot_threshold=0.995, contact_report=False, verify_buffers=True)[source]#

Bases: object

Full-featured collision pipeline with GJK/MPR narrow phase and pluggable broad phase.

Key features:

  • GJK/MPR algorithms for convex-convex collision detection

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

  • Mesh-mesh collision via SDF with contact reduction

  • Optional hydroelastic contact model for compliant surfaces

For most users, construct with CollisionPipeline(model, ...).

Note

Differentiable rigid contacts (the rigid_contact_diff_* arrays when requires_grad is enabled) are experimental. The narrow phase stays frozen and gradients are a tangent approximation; validate accuracy and usefulness on your workflow before relying on them in optimization loops.

__init__(model, *, reduce_contacts=True, rigid_contact_max=None, max_triangle_pairs=1000000, shape_pairs_filtered=None, soft_contact_max=None, soft_contact_margin=0.01, requires_grad=None, broad_phase=None, narrow_phase=None, sdf_hydroelastic_config=None, shape_pairs_max=None, deterministic=False, contact_matching='disabled', contact_matching_pos_threshold=0.0005, contact_matching_normal_dot_threshold=0.995, contact_report=False, verify_buffers=True)#

Initialize the CollisionPipeline (expert API).

Parameters:

  • model (Model) – The simulation model.

  • reduce_contacts (bool) – Whether to reduce contacts for mesh-mesh collisions. Defaults to True.

  • rigid_contact_max (int | None) – Maximum number of rigid contacts to allocate. Resolution order: - If provided, use this value. - Else if model.rigid_contact_max > 0, use the model value. - Else estimate automatically from model shape and pair metadata.

  • max_triangle_pairs (int) – Maximum number of triangle pairs allocated by narrow phase for mesh and heightfield collisions. Increase this when scenes with large/complex meshes or heightfields report triangle-pair overflow warnings.

  • soft_contact_max (int | None) – Maximum number of soft contacts to allocate. If None, computed as shape_count * particle_count.

  • soft_contact_margin (float) – Margin for soft contact generation. Defaults to 0.01.

  • requires_grad (bool | None) – Whether to enable gradient computation. If None, uses model.requires_grad.

  • broad_phase (Literal['nxn', 'sap', 'explicit'] | BroadPhaseAllPairs | BroadPhaseSAP | BroadPhaseExplicit | None) – Either a broad phase mode string (“explicit”, “nxn”, “sap”) or a prebuilt broad phase instance for expert usage.

  • narrow_phase (NarrowPhase | None) – Optional prebuilt narrow phase instance. Must be provided together with a broad phase instance for expert usage.

  • shape_pairs_filtered (wp.array[wp.vec2i] | None) – Precomputed shape pairs for EXPLICIT mode. When broad_phase is “explicit”, uses model.shape_contact_pairs if not provided. For “nxn”/”sap” modes, ignored.

  • sdf_hydroelastic_config (HydroelasticSDF.Config | None) – Configuration for hydroelastic collision handling. Defaults to None.

  • shape_pairs_max (int | None) – Override for the broad-phase candidate-pair buffer capacity used by the "nxn" and "sap" modes. Defaults to the worst-case N*(N-1)/2 per-world bound, which is rarely hit by either "nxn" or "sap" in practice – "nxn" still applies AABB overlap, group, and excluded-pair filtering inside BroadPhaseAllPairs before writing, and "sap" is sparse by design – so the default sizing is typically 10-100x larger than what gets emitted on real scenes. Set this to a tighter value (e.g. measured peak with ~25% headroom) to avoid multi-GB allocations on large scenes; a too-small value triggers a buffer overflow warning at runtime. Ignored for the "explicit" mode (which uses the filtered pair list length directly) and for expert paths that pass a pre-built narrow_phase.

  • deterministic (bool) – Sort contacts after the narrow phase so that results are independent of GPU thread scheduling. Adds a radix sort + gather pass. Hydroelastic contacts are not yet covered.

  • contact_matching (Literal['disabled', 'latest', 'sticky']) – Frame-to-frame contact matching mode. One of "disabled", "latest", or "sticky". Any non-disabled mode implies deterministic=True and populates Contacts.rigid_contact_match_index. Defaults to "disabled".

  • contact_matching_pos_threshold (float) – World-space distance threshold [m] between the previous and current contact midpoints 0.5 * (world(point0) + world(point1)). Contacts whose midpoint moves more than this are considered broken. Defaults to 0.0005.

  • contact_matching_normal_dot_threshold (float) – Minimum dot product between old and new contact normals for a match.

  • contact_report (bool) – Allocate rigid_contact_new_indices / rigid_contact_new_count / rigid_contact_broken_indices / rigid_contact_broken_count on the Contacts container, populated each frame. Requires a non-disabled contact_matching mode.

  • verify_buffers (bool) – Run a dim=[1] diagnostic kernel at the end of the narrow phase that prints warnings on any intermediate candidate-pair or final rigid contact buffer overflow; see NarrowPhase for the full counter list. Defaults to True. Overhead is one extra kernel launch per collision pass; disable in hot loops or CUDA graph capture once buffer sizes are known to be adequate.

Note

When requires_grad is true (explicitly or via model.requires_grad), rigid-contact autodiff via rigid_contact_diff_* is experimental; see collide().

collide(state, contacts, *, soft_contact_margin=None)#

Run the collision pipeline using NarrowPhase.

Safe to call inside a wp.Tape context. The non-differentiable broad-phase and narrow-phase kernels are launched with tape recording hardcoded record_tape=False internally. The differentiable kernels (soft-contact generation and rigid-contact augmentation) are recorded on the tape so that gradients flow through state.body_q and state.particle_q.

When requires_grad=True, the differentiable rigid-contact arrays (contacts.rigid_contact_diff_*) are populated by a lightweight augmentation kernel that reconstructs world-space contact points from the frozen narrow-phase output through the body transforms.

Note

This rigid-contact gradient path is experimental: usefulness and numerical behaviour are still being assessed across real-world scenarios.

Parameters:

  • state (newton.State) – The current simulation state.

  • contacts (Contacts) – The contacts buffer to populate (will be cleared first).

  • soft_contact_margin (float | None) – Margin for soft contact generation. If None, uses the value from construction.

contacts()#

Allocate and return a new newton.Contacts object for this pipeline.

The returned buffer uses this pipeline’s requires_grad flag (resolved at construction from the argument or model.requires_grad).

Returns:

A newly allocated contacts buffer sized for this pipeline.

Return type:

Contacts

Note

If requires_grad is true, rigid_contact_diff_* arrays may be allocated; rigid-contact differentiability is experimental (see collide()).

property rigid_contact_max: int#

Maximum rigid contact buffer capacity used by this pipeline.

property soft_contact_max: int#

Maximum soft contact buffer capacity used by this pipeline.