Opt-in support for contact matching - simplifies solver warm starting

CHANGELOG.md

@@ -79,6 +79,11 @@
 - Export `ViewerBase` from `newton.viewer` public API
 - Add `custom_attributes` argument to `ModelBuilder.add_shape_convex_hull()`
 - Add RJ45 plug-socket insertion example with SDF contacts, latch joint, and interactive gizmo
+- Add `TRIANGLE_PRISM` support-function type for heightfield triangles, extruding 1 m along the heightfield's local -Z so GJK/MPR naturally resolves shapes on the back side
+- Add `ViewerGL.log_scalar()` for live scalar time-series plots in the viewer
+- Add `deterministic` flag to `CollisionPipeline` and `NarrowPhase` for GPU-thread-scheduling-independent contact ordering via radix sort and deterministic fingerprint tiebreaking in contact reduction
+- Add `ViewerBase.log_arrows()` for arrow rendering (wide line + arrowhead) in the GL viewer with a dedicated geometry shader
+- Add frame-to-frame contact matching via `CollisionPipeline(contact_matching=True)` with configurable position and normal thresholds. With `contact_report=True`, new and broken contact index lists are exposed as `contacts.rigid_contact_new_indices` / `rigid_contact_new_count` / `rigid_contact_broken_indices` / `rigid_contact_broken_count`
 
 ### Changed
 

docs/concepts/collisions.rst

@@ -1253,6 +1253,18 @@ and is consumed by the solver :meth:`~solvers.SolverBase.step` method for contac
      - Contact normal, pointing from shape 0 toward shape 1 (world frame).
    * - ``rigid_contact_margin0``, ``rigid_contact_margin1``
      - Per-shape thickness: effective radius + margin (scalar).
+   * - ``rigid_contact_match_index``
+     - Per-contact frame-to-frame match result (int32). ``>= 0``: matched old
+       index, ``-1``: new, ``-2``: broken.  Only allocated when
+       ``contact_matching=True``. See :ref:`Contact Matching`.
+   * - ``rigid_contact_new_indices``, ``rigid_contact_new_count``
+     - Compact index list of new contacts in the current sorted buffer (where
+       ``match_index < 0``). Only allocated when ``contact_report=True``.
+       See :ref:`Contact Reports`.
+   * - ``rigid_contact_broken_indices``, ``rigid_contact_broken_count``
+     - Compact index list of contacts from the previous frame that no current
+       contact matched. Only allocated when ``contact_report=True``.
+       See :ref:`Contact Reports`.
 
 **Soft contacts (particle-shape):**
 
@@ -1669,6 +1681,89 @@ fully CUDA-graph-capturable.
 
    Hydroelastic contacts are not yet covered by deterministic ordering.
 
+.. _Contact Matching:
+
+Contact Matching
+----------------
+
+Contact matching tracks contacts across frames, identifying which contacts
+persist, which are new, and which have broken.  Enable it with
+``contact_matching=True`` on :class:`~CollisionPipeline` (this implies
+``deterministic=True``):
+
+.. testsetup:: contact-matching
+
+    import warp as wp
+    import newton
+
+    builder = newton.ModelBuilder()
+    builder.add_ground_plane()
+    body = builder.add_body(xform=wp.transform((0.0, 0.0, 2.0), wp.quat_identity()))
+    builder.add_shape_sphere(body, radius=0.5)
+    model = builder.finalize()
+    state = model.state()
+
+.. testcode:: contact-matching
+
+    pipeline = newton.CollisionPipeline(
+        model,
+        contact_matching=True,
+        contact_matching_pos_threshold=0.02,       # metres
+        contact_matching_normal_dot_threshold=0.9,  # cos(~25°)
+    )
+    contacts = pipeline.contacts()
+
+    pipeline.collide(state, contacts)
+
+    # Per-contact match index (int32):
+    #   >= 0 : index of the matched contact in the previous frame
+    #     -1 : new contact (no match found)
+    #     -2 : key matched but position/normal thresholds exceeded (broken)
+    match_idx = contacts.rigid_contact_match_index.numpy()
+
+Each frame, the matcher binary-searches the current contacts against the
+previous frame's sorted keys, then verifies candidates against a world-space
+position distance threshold and a normal dot-product threshold.  The sort key
+encodes ``(shape_a, shape_b, sub_key)`` so only contacts between the same shape
+pair are compared.
+
+**Thresholds**
+
+- ``contact_matching_pos_threshold`` — maximum world-space distance [m] a
+  contact may move between frames and still be considered the same contact.
+- ``contact_matching_normal_dot_threshold`` — minimum dot product between old
+  and new contact normals.  Below this the contact is reported as broken even
+  if the key and position match.
+
+.. _Contact Reports:
+
+Contact Reports
+^^^^^^^^^^^^^^^
+
+Pass ``contact_report=True`` to also collect compact index lists of new and
+broken contacts each frame:
+
+.. testcode:: contact-matching
+
+    pipeline = newton.CollisionPipeline(
+        model,
+        contact_matching=True,
+        contact_report=True,
+    )
+    contacts = pipeline.contacts()
+    pipeline.collide(state, contacts)
+
+    n_new = contacts.rigid_contact_new_count.numpy()[0]
+    new_indices = contacts.rigid_contact_new_indices.numpy()[:n_new]
+
+    n_broken = contacts.rigid_contact_broken_count.numpy()[0]
+    broken_indices = contacts.rigid_contact_broken_indices.numpy()[:n_broken]
+
+``rigid_contact_new_indices`` holds indices into the current frame's sorted
+contact buffer where ``match_index < 0``.  ``rigid_contact_broken_indices``
+holds indices into the *previous* frame's sorted buffer for contacts that no
+current contact matched.
+
 .. _Performance:
 
 Performance