perf(rbd): optional GPU contact reduction (merge per-pair manifolds to ≤4 points)

[haixuanTao]

What

Opt-in narrow-phase pass (RbdPipeline::contact_reduction, default off) that compacts each batch's contacts in place after pfm_pfm: the first record of each collider pair is kept verbatim, and every later record with the same key (e.g. per-triangle trimesh manifolds under one foot) is merged into it — pool both manifolds' points (≤8), keep the deeper manifold's normal, and reuse the existing manifold_reduction deepest+spread selector down to MAX_MANIFOLD_POINTS.

Why

A convex collider resting on a trimesh emits one manifold per overlapping triangle, all sharing one colliders key and one collider-A local frame. Downstream solver kernels then pay per-point cost for near-duplicate information — on our rough-terrain RL workload the multibody contact-constraint kernels ran 4–8× their flat-ground cost (169 vs 76 µs/call). Merging to one ≤4-point manifold per pair is the standard engine remedy (PhysX/MuJoCo do the equivalent).

Measured on a 29-DOF humanoid batch (4096 envs, trimesh terrain, RTX 5090, native-CUDA backend): full training iteration 3.8 → 3.3 s (−13%), contact-constraint kernels 2–4× cheaper. Flat-ground scenes are unaffected.

Design notes

• Off = zero cost: the kernel is simply not dispatched, and init_contacts_indirect_args runs on the untouched counts.
• On, single-manifold pairs: copied verbatim → bit-identical to the unreduced path (verified on a deterministic training reference with the pass active on flat ground).
• threads(1), grid [1, num_batches, 1], two-cursor in-place compaction (write cursor ≤ read cursor); contacts_len rewritten by the single writer per batch.
• dim3-only (manifold_reduction is dim3); dim2 keeps compiling — the flag is accepted and ignored.

Documented approximations (why it's opt-in)

• One normal per merged manifold (a collider straddling a sharp edge loses the second normal — a normal-cone split would be the v2).
• Greedy pairwise merging in emission order (emission order is already nondeterministic upstream, so no new nondeterminism).
• Warm-start proximity matching can miss merged points on the first step after a merge (mild convergence cost only).

cargo check clean on nexus_rbd3d, nexus_rbd2d, and both shader crates.

🤖 Generated with Claude Code

https://claude.ai/code/session_01U2n9RqmxTJb8UG5d1Sjw4W