newton.CollisionPipeline#

class newton.CollisionPipeline(model, *, reduce_contacts=True, rigid_contact_max=None, shape_pairs_filtered=None, soft_contact_max=None, soft_contact_margin=0.01, requires_grad=None, broad_phase_mode=BroadPhaseMode.EXPLICIT, sap_sort_type=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 modes: 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

__init__(model, *, reduce_contacts=True, rigid_contact_max=None, shape_pairs_filtered=None, soft_contact_max=None, soft_contact_margin=0.01, requires_grad=None, broad_phase_mode=BroadPhaseMode.EXPLICIT, sap_sort_type=None, sdf_hydroelastic_config=None)#

Initialize the CollisionPipeline.

Parameters:

  • model (Model) – The simulation model.

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

  • rigid_contact_max (int | None, optional) – Maximum number of rigid contacts to allocate. If None, estimated based on broad phase mode: - EXPLICIT: len(shape_pairs_filtered) * 10 contacts - NXN/SAP: shape_count * 20 contacts (assumes ~20 contacts per shape) For better memory efficiency, use rigid_contact_max computed from actual collision pairs.

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

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

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

  • broad_phase_mode (BroadPhaseMode, optional) – Broad phase mode for collision detection. - BroadPhaseMode.NXN: Use all-pairs AABB broad phase (O(N²), good for small scenes) - BroadPhaseMode.SAP: Use sweep-and-prune AABB broad phase (O(N log N), better for larger scenes) - BroadPhaseMode.EXPLICIT: Use precomputed shape pairs (most efficient when pairs known) Defaults to BroadPhaseMode.EXPLICIT.

  • shape_pairs_filtered (wp.array | None, optional) – Precomputed shape pairs for EXPLICIT mode. When broad_phase_mode is BroadPhaseMode.EXPLICIT, uses model.shape_contact_pairs if not provided. For NXN/SAP modes, ignored.

  • sap_sort_type (SAPSortType | None, optional) – Sorting algorithm for SAP broad phase. Only used when broad_phase_mode is BroadPhaseMode.SAP. Options: SEGMENTED or TILE. If None, uses default (SEGMENTED).

  • sdf_hydroelastic_config (SDFHydroelasticConfig | None, optional) – Configuration for SDF 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 Contacts object for this pipeline.

Returns:

A newly allocated contacts buffer sized for this pipeline.

Return type:

Contacts

get_hydro_contact_surface()#

Get hydroelastic contact surface data for visualization, if available.

Returns:

HydroelasticContactSurfaceData if sdf_hydroelastic is configured, None otherwise.

set_output_contact_surface(enabled)#

Enable or disable contact surface visualization.

Note: When output_contact_surface=True in the config, the kernel always writes debug surface data. This method is provided for API compatibility but the actual display is controlled by the viewer’s show_hydro_contact_surface flag.

Parameters:

enabled (bool) – If True, visualization is enabled (viewer will display the data). If False, visualization is disabled (viewer will hide the data).