Gracefully degrade full-surface contacts

Author: mmichelis

CHANGELOG.md

@@ -49,7 +49,7 @@
 ### Changed
 
 - Decide collider visibility from USD `purpose` and visibility rather than from a bound render material. A collider whose `purpose` resolves to `default` is viewport geometry and is drawn; mark it `guide` to state that it is collision-only. Previously an unrelated visual elsewhere in the scene could make a collider vanish. `force_show_colliders` and `hide_collision_shapes` are unchanged.
-- Preserve full-surface (edge/face) soft-contact records through `SolverCoupled`'s per-entry contact filter, which previously dropped them because it keyed on a single particle id. A record is kept only when the entry owns every corner it references, so one spanning two entries is dropped by both. Coupled sub-solvers that do not consume edge/face records (`SolverXPBD`, `SolverSemiImplicit`, `SolverStyle3D`) now raise instead of silently running with those records removed; build their collision pipeline with `enable_rigid_soft_full_surface_contact=False`.
+- Preserve full-surface (edge/face) soft-contact records for capable `SolverCoupled` entries, and gracefully drop them for sub-solvers that consume only particle contacts. A record is kept only when the entry owns every corner it references, so one spanning two entries is dropped by both.
 - Disable the implicit positive Dahl-friction defaults in `SolverVBD.register_custom_attributes()` (deprecated in 1.3.0): `vbd:dahl_eps_max` and `vbd:dahl_tau` now default to zero, and Dahl cable friction is enabled only where both are authored positive. Pass `dahl_defaults_enabled=True` to temporarily restore the old defaults; the compatibility mode will be removed in a future release.
 - Keep the authored render mesh when `ModelBuilder.add_usd()` approximates a collider. `physics:approximation` is scoped to collision, so a Mesh that is both render geometry and a collider now imports as an approximated collision shape plus a visual shape carrying the original topology, instead of replacing the render mesh with the approximation. This raises `Model.shape_count` for such prims: iterate on `ShapeFlags.COLLIDE_SHAPES` rather than assuming one shape per collider prim. The visual shape adds no mass and no collision, appends after the originals so existing shape indices and `path_shape_map` entries are unchanged, and is skipped when `load_visual_shapes=False`.
 - Compile tiled camera render kernels with CUDA fast math by default for faster rendering; set `SensorTiledCamera.render_config.enable_fast_math = False` for bit-exact, IEEE-precise output.

docs/concepts/coupling.rst

@@ -377,10 +377,10 @@ The coupled-solver framework is useful today, but it is still experimental:
 - USD ownership, automatic coupled-solver construction, and high-level tuning
   guidance are not part of the experimental public API yet.
 - Full-surface (edge/face) rigid-soft contacts are consumed by
-  :class:`~newton.solvers.SolverVBD` only; other sub-solvers raise if handed
-  them. The per-entry contact filter keeps such a record only when the entry owns
-  every corner it references, so one spanning two entries is dropped by both.
-  Proxy particles do not support them at all.
+  :class:`~newton.solvers.SolverVBD` only. The per-entry contact filter drops
+  them for other sub-solvers while preserving particle contacts, and keeps them
+  for VBD only when the entry owns every referenced corner. A record spanning
+  two entries is dropped by both. Proxy particles do not support them at all.
 
 Treat coupled solvers as an advanced feature for controlled experiments and
 solver integration work. Prefer focused regression tests and explicit scene

newton/_src/solvers/coupled/interface.py

@@ -44,6 +44,9 @@ def coupling_notify_input_state_update(state, flags, *, iteration_restart=False,
     def coupling_supports_inertial_property_refresh() -> bool: ...
 
 
+    def coupling_supports_full_surface_soft_contacts() -> bool: ...
+
+
     def coupling_rewind_proxy_body(
         body_local_to_proxy_global, state, coupling_forces, body_gravity_acceleration, dt
     ) -> None: ...
@@ -252,6 +255,10 @@ def coupling_supports_inertial_property_refresh(self) -> bool:
         """
         return False
 
+    def coupling_supports_full_surface_soft_contacts(self) -> bool:
+        """Return whether the solver consumes edge and face soft contacts."""
+        return False
+
     def coupling_eval_gravity_acceleration(
         self,
         out_body_acceleration: wp.array[wp.vec3] | None,

newton/_src/solvers/coupled/solver_coupled.py

@@ -2305,6 +2305,7 @@ def _contacts_for_entry(self, entry: SolverEntry, contacts: Contacts | None) ->
             return contacts
 
         filtered = self._ensure_entry_contact_buffer(entry, contacts)
+        keep_full_surface_contacts = filtered._enable_rigid_soft_full_surface_contact
         force_contact_update = int(self._entry_contact_sources.get(entry.name) is not contacts)
         if force_contact_update:
             self._entry_contact_sources[entry.name] = contacts
@@ -2443,6 +2444,7 @@ def _contacts_for_entry(self, entry: SolverEntry, contacts: Contacts | None) ->
                     entry.view.particle_flags,
                     int(ShapeFlags.COLLIDE_PARTICLES),
                     int(ParticleFlags.ACTIVE),
+                    int(keep_full_surface_contacts),
                     filtered.soft_contact_count,
                     filtered.soft_contact_particle,
                     filtered.soft_contact_shape,
@@ -2510,9 +2512,10 @@ def _ensure_entry_contact_buffer(self, entry: SolverEntry, contacts: Contacts) -
                 dtype=wp.int32,
                 device=contacts.device,
             )
-        # Carry the capability marker: the filter now preserves edge/face records, so a sub-solver
-        # that cannot consume them must still be able to reject the buffer it is handed.
-        filtered._enable_rigid_soft_full_surface_contact = contacts._enable_rigid_soft_full_surface_contact
+        filtered._enable_rigid_soft_full_surface_contact = bool(
+            contacts._enable_rigid_soft_full_surface_contact
+            and entry.solver.coupling_supports_full_surface_soft_contacts()
+        )
         return filtered
 
     @staticmethod
@@ -3279,6 +3282,7 @@ def _filter_soft_contacts_global_shape_ids_kernel(
     particle_flags: wp.array[wp.int32],
     collide_particles_mask: int,
     active_particle_mask: int,
+    keep_full_surface_contacts: int,
     dst_count: wp.array[wp.int32],
     dst_particle: wp.array[int],
     dst_shape: wp.array[int],
@@ -3299,14 +3303,14 @@ def _filter_soft_contacts_global_shape_ids_kernel(
 
     particle = src_particle[contact_id]
     shape = src_shape[contact_id]
+    if particle < 0 and keep_full_surface_contacts == 0:
+        return
     if shape < 0 or shape >= shape_flags.shape[0]:
         return
     if (shape_flags[shape] & collide_particles_mask) == 0:
         return
 
-    # Validate every soft corner the record references: one for a particle record, two for an edge,
-    # three for a face. Requiring all of them to be owned and active keeps a record whose corners
-    # straddle two entries out of both, rather than letting one entry read a particle it does not own.
+    # Keep records only when the entry owns every referenced corner.
     corners = src_indices[contact_id]
     if corners[0] < 0:
         return
@@ -3327,8 +3331,6 @@ def _filter_soft_contacts_global_shape_ids_kernel(
     dst_body_vel[dst_id] = src_body_vel[contact_id]
     dst_normal[dst_id] = src_normal[contact_id]
     dst_tids[dst_id] = src_tids[contact_id]
-    # Carry the unified feature record too (the particle-only path writes (p, -1, -1) + (1, 0, 0)); VBD
-    # reads these fields, so dropping them delivers the contact as (-1, -1, -1) and regresses coupled
-    # VBD even with full-surface contact off (E7).
+    # VBD consumes the unified particle, edge, and face representation.
     dst_indices[dst_id] = src_indices[contact_id]
     dst_barycentric[dst_id] = src_barycentric[contact_id]

newton/_src/solvers/vbd/solver_vbd.py

@@ -867,6 +867,10 @@ def notify_model_changed(self, flags: ModelFlags | int) -> None:
     def coupling_supports_inertial_property_refresh(self) -> bool:
         return True
 
+    @override
+    def coupling_supports_full_surface_soft_contacts(self) -> bool:
+        return True
+
     def coupling_notify_input_state_update(
         self,
         state: State,
@@ -1055,7 +1059,6 @@ def coupling_harvest_proxy_particle_forces(
         if self.model.particle_count == 0 or particle_local_to_proxy_global.shape[0] == 0:
             return
 
-        # Reaching here means proxy particles exist.
         if contacts is not None:
             contacts._assert_particle_only_soft_contacts("SolverVBD proxy-particle coupling")
 

newton/tests/test_coupled_solver.py

@@ -124,6 +124,13 @@ def step(self, state_in, state_out, control, contacts, dt):
             wp.copy(state_out.joint_qd, state_in.joint_qd)
 
 
+class _FullSurfaceControlRecordingSolver(_ControlRecordingSolver):
+    """Test solver that accepts full-surface soft contacts."""
+
+    def coupling_supports_full_surface_soft_contacts(self) -> bool:
+        return True
+
+
 class _InPlaceRecordingParticleSolver(SolverBase, CouplingInterface):
     """Test solver that records whether it was stepped in-place."""
 
@@ -903,24 +910,30 @@ def test_compaction_fallback_reports_reason(self):
         self.assertEqual(coupled.view("child").body_count, model.body_count)
 
     @staticmethod
-    def _seeded_full_surface_face_contact(model, corners):
-        """A contacts buffer holding a single soft FACE record over ``corners``."""
+    def _seeded_full_surface_contacts(model, corners, particle=None):
+        """Build contacts with a face record and an optional particle record."""
         pipeline = newton.CollisionPipeline(
             model, broad_phase="nxn", soft_contact_margin=0.1, enable_rigid_soft_full_surface_contact=True
         )
         contacts = pipeline.contacts()
 
-        def _set(arr, value):
+        def _set(arr, index, value):
             a = arr.numpy()
-            a[0] = value
+            a[index] = value
             arr.assign(a)
 
-        contacts.soft_contact_count.assign([1])
-        _set(contacts.soft_contact_particle, -1)  # edge/face records carry no single particle id
-        _set(contacts.soft_contact_indices, list(corners))
-        _set(contacts.soft_contact_barycentric, [0.6, 0.3, 0.1])
-        _set(contacts.soft_contact_shape, 0)
-        _set(contacts.soft_contact_normal, [0.0, 0.0, 1.0])
+        contacts.soft_contact_count.assign([1 + int(particle is not None)])
+        _set(contacts.soft_contact_particle, 0, -1)
+        _set(contacts.soft_contact_indices, 0, list(corners))
+        _set(contacts.soft_contact_barycentric, 0, [0.6, 0.3, 0.1])
+        _set(contacts.soft_contact_shape, 0, 0)
+        _set(contacts.soft_contact_normal, 0, [0.0, 0.0, 1.0])
+        if particle is not None:
+            _set(contacts.soft_contact_particle, 1, particle)
+            _set(contacts.soft_contact_indices, 1, [particle, -1, -1])
+            _set(contacts.soft_contact_barycentric, 1, [1.0, 0.0, 0.0])
+            _set(contacts.soft_contact_shape, 1, 0)
+            _set(contacts.soft_contact_normal, 1, [0.0, 0.0, 1.0])
         return contacts
 
     @staticmethod
@@ -935,18 +948,18 @@ def _build_box_and_triangle():
         return builder.finalize(device="cpu"), body, joint, particles
 
     def test_full_surface_records_survive_the_entry_filter(self):
-        """The per-entry soft-contact filter keeps an edge/face record whose corners it owns.
-
-        The filter validates every corner the record references rather than a single particle id,
-        so a face record reaches a sub-solver that owns all three of its corners.
-        """
+        """Keep a full-surface record owned by a capable entry."""
         model, body, joint, particles = self._build_box_and_triangle()
-        contacts = self._seeded_full_surface_face_contact(model, particles)
+        contacts = self._seeded_full_surface_contacts(model, particles)
         coupled = SolverCoupled(
             model=model,
             entries=[
                 SolverCoupled.Entry(
-                    name="A", solver=_ControlRecordingSolver, bodies=[body], joints=[joint], particles=particles
+                    name="A",
+                    solver=_FullSurfaceControlRecordingSolver,
+                    bodies=[body],
+                    joints=[joint],
+                    particles=particles,
                 )
             ],
         )
@@ -959,20 +972,20 @@ def test_full_surface_records_survive_the_entry_filter(self):
         self.assertTrue(filtered._enable_rigid_soft_full_surface_contact, "capability marker must be carried over")
 
     def test_full_surface_records_straddling_entries_are_dropped(self):
-        """A record whose corners span two entries is dropped by both.
-
-        Keeping it would let an entry evaluate a contact point from a particle it does not own, so
-        the filter requires every referenced corner to be owned and active.
-        """
+        """Drop a full-surface record spanning two capable entries."""
         model, body, joint, particles = self._build_box_and_triangle()
-        contacts = self._seeded_full_surface_face_contact(model, particles)
+        contacts = self._seeded_full_surface_contacts(model, particles)
         coupled = SolverCoupled(
             model=model,
             entries=[
                 SolverCoupled.Entry(
-                    name="A", solver=_ControlRecordingSolver, bodies=[body], joints=[joint], particles=particles[:2]
+                    name="A",
+                    solver=_FullSurfaceControlRecordingSolver,
+                    bodies=[body],
+                    joints=[joint],
+                    particles=particles[:2],
                 ),
-                SolverCoupled.Entry(name="B", solver=_ControlRecordingSolver, particles=particles[2:]),
+                SolverCoupled.Entry(name="B", solver=_FullSurfaceControlRecordingSolver, particles=particles[2:]),
             ],
         )
 
@@ -982,6 +995,30 @@ def test_full_surface_records_straddling_entries_are_dropped(self):
             count = int(coupled._entry_contact_buffers[name].soft_contact_count.numpy()[0])
             self.assertEqual(count, 0, f"entry {name} owns only part of the record and must drop it")
 
+    def test_full_surface_contacts_degrade_per_entry(self):
+        """Keep only particle contacts for an unsupported entry."""
+        model, body, joint, particles = self._build_box_and_triangle()
+        contacts = self._seeded_full_surface_contacts(model, particles, particle=particles[0])
+        coupled = SolverCoupled(
+            model=model,
+            entries=[
+                SolverCoupled.Entry(
+                    name="particle_only",
+                    solver=_ControlRecordingSolver,
+                    bodies=[body],
+                    joints=[joint],
+                    particles=particles,
+                ),
+            ],
+        )
+
+        coupled.step(model.state(), model.state(), None, contacts, dt=1.0 / 60.0)
+
+        particle_only = coupled._entry_contact_buffers["particle_only"]
+        self.assertEqual(int(particle_only.soft_contact_count.numpy()[0]), 1)
+        self.assertEqual(int(particle_only.soft_contact_particle.numpy()[0]), particles[0])
+        self.assertFalse(particle_only._enable_rigid_soft_full_surface_contact)
+
     def test_entry_control_arrays_are_mapped_to_local_dofs(self):
         """Entry solvers should receive control arrays in their local DOF namespace."""
         _ControlRecordingSolver.instances.clear()
@@ -3280,6 +3317,7 @@ def _coupled_soft_contact_filter_preserves_unified_fields(test, device):
             wp.array([int(ParticleFlags.ACTIVE)], dtype=wp.int32, device=device),  # particle_flags
             int(ShapeFlags.COLLIDE_PARTICLES),
             int(ParticleFlags.ACTIVE),
+            1,  # keep_full_surface_contacts
             wp.zeros(1, dtype=wp.int32, device=device),  # dst_count
             wp.full(1, -1, dtype=wp.int32, device=device),  # dst_particle
             wp.full(1, -1, dtype=wp.int32, device=device),  # dst_shape