Checkpoint 7

herding/control/modulation.py

@@ -1,8 +1,8 @@
-"""Shared low-level control helpers used by every dog mode.
+"""Shared action post-processing.
 
-Centralised here so the BC student, Strömbom, Sequential, and the DAgger
-teacher all apply identical post-processing to their action outputs.
-The downstream wheel-velocity layer (``herding.diffdrive``) is unchanged.
+Every dog mode routes its action through ``modulate_speed_near_sheep``
+so the magnitude is reduced near sheep — direction (intent) is
+preserved.
 """
 
 from __future__ import annotations
@@ -10,12 +10,8 @@ from __future__ import annotations
 import math
 
 
-# Speed-modulation: scale action magnitude down when close to the
-# nearest sheep. Stops the dog from charging in at full speed and
-# scattering the flock. Action norm linearly ramps from MIN_SPEED at
-# distance 0 to 1.0 at SLOW_NEAR_SHEEP.
-SLOW_NEAR_SHEEP = 2.5
-MIN_SPEED = 0.30
+SLOW_NEAR_SHEEP = 2.5  # m — distance below which action norm is scaled down
+MIN_SPEED = 0.30       # action norm at zero distance
 
 
 def modulate_speed_near_sheep(
@@ -25,16 +21,9 @@ def modulate_speed_near_sheep(
     slow_dist: float = SLOW_NEAR_SHEEP,
     min_scale: float = MIN_SPEED,
 ) -> tuple[float, float]:
-    """Scale (vx, vy) magnitude down when close to the nearest sheep.
-
-    ``sheep_positions`` accepts either a ``{name: (x, y)}`` dict
-    (matching what the trackers emit) or an iterable of ``(x, y)``
-    tuples. Empty input → action returned unchanged.
-
-    The intent direction is preserved; only magnitude is reduced. With
-    ``slow_dist=2.5`` and ``min_scale=0.3``, an action that started at
-    norm 1 is multiplied by 0.3 right next to a sheep, by 0.65 at 1 m
-    away, and by 1.0 once the nearest sheep is ≥ 2.5 m off.
+    """Linearly ramp action magnitude from ``min_scale`` at distance 0
+    to 1.0 at ``slow_dist``. ``sheep_positions`` may be a
+    ``{name: (x, y)}`` dict or an iterable of ``(x, y)`` tuples.
     """
     if not sheep_positions:
         return vx, vy