Checkpoint 4

herding/flocking_sim.py

@@ -1,25 +1,51 @@
-"""Reynolds-style sheep flocking dynamics.
+"""Sheep flocking dynamics — Strömbom 2014 / Reynolds 1987 hybrid.
 
 This is the per-sheep behavioural step used both by the Webots sheep
 controller (scalar, one sheep at a time) and by the training environment
-(loop over sheep). The numerics are adapted from the original
-``controllers/sheep/flocking.py`` and retuned for the new external-pen
-layout: the south stone wall is intact except in the gate column, so
-sheep can only reach the pen by walking through that 3-m corridor.
+(loop over sheep).
+
+Model
+-----
+The force stack each step (summed → heading + speed):
 
-Force stack each step (summed → heading + speed):
     flee       — quadratic ramp away from dog within FLEE_DIST
-    cohesion   — drift toward flock centre, halved while fleeing
-    separation — inverse-distance push from peers
-    walls      — soft repulsion + hard escape band against field walls,
-                 except inside the gate column where the south wall is
-                 absent
+                 (Strömbom 2014 §2.1, term ρa)
+    cohesion   — drift toward local centre of mass of peers within
+                 COHESION_DIST (Strömbom 2014 §2.1, term c).
+                 Weight is **higher when fleeing** — modelling the
+                 "safety in numbers" / predator-confusion effect
+                 Strömbom 2014 describes as fear-induced cohesion.
+    separation — short-range inverse-distance repulsion from peers
+                 (Strömbom 2014 §2.1, term α; Reynolds 1987)
     wander     — small persistent drift for natural idle motion
+                 (Strömbom 2014 §2.1, noise term ε)
 
-A sheep latches to ``penned`` the first time it crosses the gate plane
-into the gate column (handled by callers via ``geometry.is_penned_position``);
-once latched, ``penned=True`` is passed in here and the force stack
-switches to in-pen containment + jitter.
+References
+----------
+- Strömbom et al. (2014). "Solving the shepherding problem: heuristics
+  for herding autonomous, interacting agents." J R Soc Interface 11.
+- Reynolds (1987). "Flocks, herds and schools: A distributed
+  behavioural model." SIGGRAPH '87.
+
+Environment-specific adaptations
+--------------------------------
+The original Strömbom model assumes an open field. Our scenario adds:
+
+* Field walls — soft repulsion within ``WALL_MARGIN`` plus a hard
+  escape band when inside ``WALL_HARD_MARGIN``. Necessary because the
+  Webots field is fenced (30 m square enclosure).
+* Gate column — the south wall has a 3 m gap at x ∈ [10, 13]; sheep
+  pass through it freely (no wall force inside the column).
+* Penned containment — once a sheep crosses the gate plane south
+  (``geometry.is_penned_position``), the caller flags ``penned=True``
+  and we switch to in-pen wall-bounce + jitter. Sheep do not exit the
+  pen on their own. This is a hard sim constraint, not a behavioural
+  claim about real sheep.
+
+Parameter tuning (cohesion weight 3× while fleeing) was chosen so the
+flock survives passage through the 3 m gate without fragmenting — this
+is a defensible engineering adaptation of Strömbom's qualitative
+"fear-induced cohesion" to our gate width.
 """
 
 import math