Add tendon activation tolerance

Delay inactive dynamic-roller activation by a configurable fraction of the roller radius while preserving zero-clearance deactivation. This prevents route-state chatter near the switching boundary.

Author: vreutskyy

newton/_src/solvers/tendon_kernels.py

@@ -137,6 +137,7 @@ def update_tendon_link_active(
     tendon_link_orientation: wp.array[int],
     tendon_link_offset: wp.array[wp.vec3],
     tendon_link_axis: wp.array[wp.vec3],
+    tendon_activation_tol: float,
     tendon_link_active: wp.array[bool],
 ):
     """Update dynamic rolling links from oriented distance to their bypass span."""
@@ -232,7 +233,10 @@ def update_tendon_link_active(
             distance = wp.dot(candidate_offset - closest_offset, span_normal)
             if tendon_link_orientation[link_idx] <= 0:
                 distance = -distance
-            if alpha > 0.0 and alpha < 1.0 and distance <= tendon_link_radius[link_idx]:
+            activation_radius = tendon_link_radius[link_idx]
+            if not tendon_link_active[link_idx]:
+                activation_radius = activation_radius * (1.0 - tendon_activation_tol)
+            if alpha > 0.0 and alpha < 1.0 and distance <= activation_radius:
                 active = True
         tendon_link_active[link_idx] = active
 

newton/_src/solvers/tendon_state.py

@@ -105,10 +105,17 @@ def _init_tendon_state(self, model: Model, allocate_xpbd_lambdas: bool = True) -
             self.tendon_max_sweeps = 256
         if not hasattr(self, "tendon_settle_tol"):
             self.tendon_settle_tol = 1.0e-3
+        if not hasattr(self, "tendon_activation_tol"):
+            self.tendon_activation_tol = 2.0e-3
         if not 1 <= self.tendon_max_sweeps <= 256:
             raise ValueError(f"tendon_max_sweeps must be between 1 and 256, got {self.tendon_max_sweeps}")
         if self.tendon_settle_tol < 0.0:
             raise ValueError(f"tendon_settle_tol must be non-negative, got {self.tendon_settle_tol}")
+        if not 0.0 <= self.tendon_activation_tol < 1.0:
+            raise ValueError(
+                f"tendon_activation_tol must be between 0 (inclusive) and 1 (exclusive), "
+                f"got {self.tendon_activation_tol}"
+            )
         if model.tendon_segment_count == 0:
             self.tendon_seg_rest_length = None
             self.tendon_seg_rest_length_step = None
@@ -248,6 +255,7 @@ def _update_tendon_link_active(self, model: Model, body_q: wp.array[wp.transform
                 model.tendon_link_orientation,
                 model.tendon_link_offset,
                 model.tendon_link_axis,
+                self.tendon_activation_tol,
                 self.tendon_link_active,
             ],
             device=model.device,

newton/_src/solvers/xpbd/solver_xpbd.py

@@ -117,6 +117,7 @@ def __init__(
         enable_restitution: bool = False,
         tendon_max_sweeps: int = 256,
         tendon_settle_tol: float = 1.0e-3,
+        tendon_activation_tol: float = 2.0e-3,
     ):
         super().__init__(model=model)
         self.iterations = iterations
@@ -126,6 +127,9 @@ def __init__(
         # cables stop almost immediately; stiff/transient ones run up to the cap.
         self.tendon_max_sweeps = tendon_max_sweeps
         self.tendon_settle_tol = tendon_settle_tol
+        # Inactive dynamic rollers activate only after entering this fraction of their radius.
+        # Active rollers still deactivate at zero clearance.
+        self.tendon_activation_tol = tendon_activation_tol
 
         self.soft_body_relaxation = soft_body_relaxation
         self.soft_contact_relaxation = soft_contact_relaxation

newton/tests/test_tendon_capstan.py

@@ -1345,6 +1345,35 @@ def test_dynamic_route_uses_oriented_signed_distance(test, device):
             )
 
 
+def test_dynamic_route_activation_tolerance_preserves_boundary_state(test, device):
+    """Dynamic routing should not chatter inside the activation tolerance."""
+    with wp.ScopedDevice(device):
+        radius = 0.1
+        activation_tol = 1.0e-3
+        activation_gap = activation_tol * radius
+        for orientation in (-1, 1):
+            model, candidate, candidate_link = build_oriented_dynamic_route(orientation, device)
+            solver = newton.solvers.SolverXPBD(
+                model,
+                iterations=1,
+                tendon_activation_tol=activation_tol,
+            )
+            body_q = model.body_q.numpy()
+
+            transitions = (
+                (radius - 0.5 * activation_gap, False),
+                (radius - 1.5 * activation_gap, True),
+                (radius - 0.5 * activation_gap, True),
+                (radius + 0.5 * activation_gap, False),
+            )
+            for distance, expected_active in transitions:
+                body_q[candidate, :3] = (distance * orientation, 0.0, 0.0)
+                model.body_q.assign(body_q)
+                solver._update_tendon_link_active(model, model.body_q)
+                actual_active = bool(solver.tendon_link_active.numpy()[candidate_link])
+                test.assertEqual(actual_active, expected_active)
+
+
 def test_dynamic_route_requires_projection_on_bypass_span(test, device):
     """A roller beyond either neighboring site should remain inactive."""
     with wp.ScopedDevice(device):
@@ -2566,6 +2595,12 @@ def run(settle_tol, max_sweeps):
     devices,
     test_dynamic_route_uses_oriented_signed_distance,
 )
+add_test(
+    TestTendonCapstan,
+    "dynamic_route_activation_tolerance_preserves_boundary_state",
+    devices,
+    test_dynamic_route_activation_tolerance_preserves_boundary_state,
+)
 add_test(
     TestTendonCapstan,
     "dynamic_route_requires_projection_on_bypass_span",