newton.geometry.NarrowPhase#

class newton.geometry.NarrowPhase(*, max_candidate_pairs, max_triangle_pairs=1000000, reduce_contacts=True, device=None, shape_aabb_lower=None, shape_aabb_upper=None, shape_voxel_resolution=None, contact_writer_warp_func=None, hydroelastic_sdf=None, has_meshes=True, has_heightfields=False, use_lean_gjk_mpr=False, deterministic=False, contact_max=None, verify_buffers=True)[source]#

Bases: object

Resolve broad-phase shape pairs into simulation contacts.

This class orchestrates the narrow-phase collision pipeline by launching the appropriate Warp kernels for primitive, mesh, heightfield, and SDF shape pairs. It owns the intermediate counters and pair buffers used while processing candidate pairs, then writes final contacts through a configurable contact writer function.

__init__(*, max_candidate_pairs, max_triangle_pairs=1000000, reduce_contacts=True, device=None, shape_aabb_lower=None, shape_aabb_upper=None, shape_voxel_resolution=None, contact_writer_warp_func=None, hydroelastic_sdf=None, has_meshes=True, has_heightfields=False, use_lean_gjk_mpr=False, deterministic=False, contact_max=None, verify_buffers=True)#

Initialize NarrowPhase with pre-allocated buffers.

Parameters:

  • max_candidate_pairs (int) – Maximum number of candidate pairs from broad phase

  • max_triangle_pairs (int) – Maximum number of triangle pairs for mesh and heightfield collisions (conservative estimate).

  • reduce_contacts (bool) – Whether to reduce contacts for mesh-mesh and mesh-plane collisions. When True, uses shared memory contact reduction to select representative contacts. This improves performance and stability for meshes with many vertices. Defaults to True.

  • device (Devicelike | None) – Device to allocate buffers on

  • shape_aabb_lower (wp.array[wp.vec3] | None) – Optional external AABB lower bounds array (if provided, AABBs won’t be computed internally)

  • shape_aabb_upper (wp.array[wp.vec3] | None) – Optional external AABB upper bounds array (if provided, AABBs won’t be computed internally)

  • shape_voxel_resolution (wp.array[wp.vec3i] | None) – Optional per-shape voxel resolution array used for mesh/SDF and hydroelastic contact processing.

  • contact_writer_warp_func (Any | None) – Optional custom contact writer function (first arg: ContactData, second arg: custom struct type)

  • hydroelastic_sdf (HydroelasticSDF | None) – Optional SDF hydroelastic instance. Set is_hydroelastic=True on shapes to enable hydroelastic collisions.

  • has_meshes (bool) – Whether the scene contains any mesh shapes (GeoType.MESH). When False, mesh-related kernel launches are skipped, improving performance for scenes with only primitive shapes. Defaults to True for safety. Set to False when constructing from a model with no meshes.

  • has_heightfields (bool) – Whether the scene contains any heightfield shapes (GeoType.HFIELD). When True, heightfield collision buffers and kernels are allocated. Defaults to False.

  • 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_max (int | None) – Maximum number of contacts for the deterministic sort buffer. Must match the contact_pair array size passed to launch(). Defaults to max_candidate_pairs. Set this to a larger value when a single candidate pair can emit multiple contacts (e.g. up to 4 for primitive multi-contact paths).

  • verify_buffers (bool) – When True (the default), launch a dim=[1] diagnostic kernel (verify_narrow_phase_buffers()) at the end of launch() that compares each public counter on this class (gjk_candidate_pairs_count, shape_pairs_mesh_count, triangle_pairs_count, shape_pairs_mesh_plane_count, shape_pairs_mesh_mesh_count, shape_pairs_sdf_sdf_count) and the output contact_count against the capacity of its backing array, printing wp.printf warnings on overflow. Users who want a programmatic overflow hook can disable this and read those counters themselves. Overhead is one extra kernel launch per collision pass (roughly a few µs of launch latency on CUDA; the kernel body is a handful of scalar comparisons on one thread). Disable in hot loops or CUDA graph capture once buffer sizes are known to be adequate.

launch(*, candidate_pair, candidate_pair_count, shape_types, shape_data, shape_transform, shape_source, shape_sdf_index=None, texture_sdf_data=None, shape_gap, shape_collision_radius, shape_flags, shape_collision_aabb_lower=None, shape_collision_aabb_upper=None, shape_voxel_resolution, contact_pair, contact_position, contact_normal, contact_penetration, contact_count, contact_tangent=None, device=None, **kwargs)#

Launch narrow phase collision detection on candidate pairs from broad phase.

Parameters:

  • candidate_pair (wp.array[wp.vec2i]) – Array of potentially colliding shape pairs from broad phase

  • candidate_pair_count (wp.array[wp.int32]) – Single-element array containing the number of candidate pairs

  • shape_types (wp.array[wp.int32]) – Array of geometry types for all shapes

  • shape_data (wp.array[wp.vec4]) – Array of vec4 containing scale (xyz) and margin (w) for each shape

  • shape_transform (wp.array[wp.transform]) – Array of world-space transforms for each shape

  • shape_source (wp.array[wp.uint64]) – Array of source pointers (mesh IDs, etc.) for each shape

  • shape_sdf_index (wp.array[wp.int32] | None) – Per-shape SDF table index (-1 for shapes without SDF)

  • texture_sdf_data (wp.array[TextureSDFData] | None) – Compact array of TextureSDFData structs

  • shape_gap (wp.array[wp.float32]) – Array of per-shape contact gaps (detection threshold) for each shape

  • shape_collision_radius (wp.array[wp.float32]) – Array of collision radii for each shape (for AABB fallback for planes/meshes)

  • shape_collision_aabb_lower (wp.array[wp.vec3] | None) – Local-space AABB lower bounds for each shape (for voxel binning)

  • shape_collision_aabb_upper (wp.array[wp.vec3] | None) – Local-space AABB upper bounds for each shape (for voxel binning)

  • shape_voxel_resolution (wp.array[wp.vec3i]) – Voxel grid resolution for each shape (for voxel binning)

  • contact_pair (wp.array[wp.vec2i]) – Output array for contact shape pairs

  • contact_position (wp.array[wp.vec3]) – Output array for contact positions (center point)

  • contact_normal (wp.array[wp.vec3]) – Output array for contact normals

  • contact_penetration (wp.array[float]) – Output array for penetration depths

  • contact_tangent (wp.array[wp.vec3] | None) – Output array for contact tangents, or None to disable tangent computation

  • contact_count (wp.array[int]) – Output array (single element) for contact count

  • device (Devicelike | None) – Device to launch on

launch_custom_write(*, candidate_pair, candidate_pair_count, shape_types, shape_data, shape_transform, shape_source, shape_sdf_index, shape_gap, shape_collision_radius, shape_flags, shape_collision_aabb_lower, shape_collision_aabb_upper, shape_voxel_resolution, texture_sdf_data=None, shape_heightfield_index=None, heightfield_data=None, heightfield_elevations=None, mesh_edge_indices=None, shape_edge_range=None, writer_data, device=None)#

Launch narrow phase collision detection with a custom contact writer struct.

All internal kernel launches use record_tape=False so that calls are safe inside a warp.Tape context.

Parameters:

  • candidate_pair (wp.array[wp.vec2i]) – Array of potentially colliding shape pairs from broad phase

  • candidate_pair_count (wp.array[wp.int32]) – Single-element array containing the number of candidate pairs

  • shape_types (wp.array[wp.int32]) – Array of geometry types for all shapes

  • shape_data (wp.array[wp.vec4]) – Array of vec4 containing scale (xyz) and margin (w) for each shape

  • shape_transform (wp.array[wp.transform]) – Array of world-space transforms for each shape

  • shape_source (wp.array[wp.uint64]) – Array of source pointers (mesh IDs, etc.) for each shape

  • shape_sdf_index (wp.array[wp.int32]) – Per-shape SDF table index (-1 for shapes without SDF)

  • texture_sdf_data (wp.array[TextureSDFData] | None) – Compact array of TextureSDFData structs

  • shape_gap (wp.array[wp.float32]) – Array of per-shape contact gaps (detection threshold) for each shape

  • shape_collision_radius (wp.array[wp.float32]) – Array of collision radii for each shape (for AABB fallback for planes/meshes)

  • shape_flags (wp.array[wp.int32]) – Array of shape flags for each shape (includes ShapeFlags.HYDROELASTIC)

  • shape_collision_aabb_lower (wp.array[wp.vec3]) – Local-space AABB lower bounds for each shape (for voxel binning)

  • shape_collision_aabb_upper (wp.array[wp.vec3]) – Local-space AABB upper bounds for each shape (for voxel binning)

  • shape_voxel_resolution (wp.array[wp.vec3i]) – Voxel grid resolution for each shape (for voxel binning)

  • mesh_edge_indices (wp.array[wp.vec2i] | None) – Packed array of mesh edge vertex pairs for all shapes.

  • shape_edge_range (wp.array[wp.vec2i] | None) – Per-shape (start, count) into mesh_edge_indices.

  • writer_data (Any) – Custom struct instance for contact writing (type must match the custom writer function)

  • device (Devicelike | None) – Device to launch on