newton.CollisionPipeline#

class newton.CollisionPipeline(model, *, reduce_contacts=True, rigid_contact_max=None, max_triangle_pairs=1000000, max_heightfield_cell_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, ...).

__init__(model, *, reduce_contacts=True, rigid_contact_max=None, max_triangle_pairs=1000000, max_heightfield_cell_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 mesh-triangle pairs allocated by narrow phase. Increase this when scenes with large/complex meshes report triangle-pair overflow warnings.

  • max_heightfield_cell_pairs (int) – Maximum number of heightfield cell pairs allocated by narrow phase. Increase this when scenes with large/complex heightfields report heightfield-cell-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.

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

Run the collision pipeline using NarrowPhase.

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.

Returns:

A newly allocated contacts buffer sized for this pipeline.

Return type:

Contacts

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.