Checkpoint 7

herding/control/sequential.py

@@ -1,25 +1,9 @@
-"""Sequential single-target shepherd dog algorithm.
+"""Sequential "pin-and-push" shepherd-dog controller.
 
-Strömbom drives the flock's centre of mass; with N sheep and a narrow
-3 m gate, this fails because the flock is wider than the gate and CoM
-driving abandons stragglers. Real sheepdogs solve this differently:
-they pick *one* sheep at a time, drive it through, return for the next.
-
-This module implements that "pin-and-push" approach.
-
-Algorithm (one step):
-1. Active sheep = those still in the field (not yet penned).
-2. Target = the active sheep currently closest to the pen entry.
-3. Drive position = ``target + Δ · unit(target − pen_entry)`` —
-   directly behind the target relative to the goal.
-4. Output unit vector pointing the dog at the drive position.
-
-Once the target crosses the gate it latches as penned and is removed
-from the active set; the next-closest unpenned sheep becomes the
-target. The algorithm naturally "queues" sheep through the gate.
-
-Empirically (with our flocking dynamics) this scales linearly with
-flock size and works up to at least n=10 within a 15 000-step budget.
+Single-target alternative to Strömbom: each step, target the sheep
+closest to the pen, park behind it, drive it through; once it latches
+penned the next-closest sheep becomes the target. Naturally queues
+the flock through a narrow gate.
 """
 
 import math
@@ -43,25 +27,17 @@ def _is_active(x, y) -> bool:
 
 
 def compute_action(dog_xy, sheep_positions, pen_target=PEN_ENTRY):
-    """Return ``(vx, vy, mode)`` where mode encodes the current target.
-
-    Compatible with the Strömbom call signature so it can be drop-in
-    swapped in the dog controller and the env's imitation reward.
-    """
+    """Return ``(vx, vy, mode)`` — same call signature as Strömbom."""
     active = [(name, x, y) for name, (x, y) in sheep_positions.items()
               if _is_active(x, y)]
     if not active:
         return 0.0, 0.0, "idle"
 
-    # Pick target = sheep closest to pen entry. Stable choice: as one
-    # sheep approaches and crosses the gate it stays the target until
-    # latched; then the next-closest takes over.
     name, sx, sy = min(
         active,
         key=lambda s: math.hypot(s[1] - pen_target[0], s[2] - pen_target[1]),
     )
 
-    # Drive position behind the target along the (target → pen) line.
     ux, uy = _unit(sx - pen_target[0], sy - pen_target[1])
     tx = sx + DELTA_DRIVE * ux
     ty = sy + DELTA_DRIVE * uy
@@ -71,7 +47,7 @@ def compute_action(dog_xy, sheep_positions, pen_target=PEN_ENTRY):
 
 
 def compute_action_debug(dog_xy, sheep_positions, pen_target=PEN_ENTRY):
-    """Debug variant returning ``(vx, vy, mode, debug_dict)``."""
+    """``compute_action`` plus a debug dict (target, drive point)."""
     active = [(name, x, y) for name, (x, y) in sheep_positions.items()
               if _is_active(x, y)]
     if not active: