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)[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)#

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(dtype=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.

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