Rename multi-segment functions to two-concept names; polish docstrings

Naming pass: rename functions whose third+ segment is redundant or
implementation-detail, sticking to the codebase's preferred
``noun_verb`` / ``verb_noun`` two-concept idiom. Renames are atomic
across definitions, callers, and tests.

  is_penned_position        →  is_penned
  modulate_speed_near_sheep →  modulate_speed
  mecanum_kinematics_step   →  mecanum_step
  policy_forward_mean       →  forward_mean

Two-concept patterns like ``velocity_to_wheels`` / ``detections_from_scan``
/ ``make_strombom_predictor`` are left alone — they're idiomatic
converters / factories that read as a single concept, and the longer
form aids grep-ability.

Docstring polish:
* ``herding/config.py`` header drops the "previously lived as a
  module-level literal" historical framing — we ship as a single
  thing, so the refactor anecdote no longer earns its keep. The
  usage examples now mention both ``HERDING_WEBOTS`` and
  ``HERDING_MEC_WEBOTS`` presets.

126 pytest cases still pass.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

controllers/sheep/sheep.py

@@ -27,7 +27,7 @@ from herding.world.diffdrive import heading_speed_to_wheels
 from herding.world.flocking_sim import MAX_SPEED, compute_heading_speed
 from herding.world.geometry import (
     SHEEP_MAX_WHEEL_OMEGA,
-    is_penned_position,
+    is_penned,
 )
 
 
@@ -92,7 +92,7 @@ while robot.step(timestep) != -1:
     pos = gps.getValues()
     x, y = pos[0], pos[1]
 
-    if not penned and is_penned_position(x, y):
+    if not penned and is_penned(x, y):
         penned = True
         paint_pink()
 

controllers/shepherd_dog/shepherd_dog.py

@@ -85,7 +85,7 @@ import numpy as np
 from controller import Robot
 
 from herding.control.active_scan import ActiveScanTeacher
-from herding.control.modulation import modulate_speed_near_sheep
+from herding.control.modulation import modulate_speed
 from herding.control.sequential import compute_action as sequential_action
 from herding.control.strombom import compute_action as strombom_action
 from herding.control.universal import compute_action as universal_action
@@ -95,7 +95,7 @@ from herding.perception.sheep_tracker import SheepTracker
 from herding.world.diffdrive import velocity_to_mecanum_wheels, velocity_to_wheels
 from herding.world.geometry import (
     DOG_SOUTH_LIMIT,
-    PEN_ENTRY, is_penned_position,
+    PEN_ENTRY, is_penned,
 )
 from herding.config import HERDING_WEBOTS, RobotConfig
 
@@ -332,7 +332,7 @@ if MODE == "calibrate":
     _pos0 = gps.getValues(); _x0, _y0 = _pos0[0], _pos0[1]
     _n_calib = compass.getValues(); _h0 = math.atan2(_n_calib[0], _n_calib[1])
     # Gym-predicted displacement using shared kinematics.
-    from herding.world.diffdrive import velocity_to_mecanum_wheels, mecanum_kinematics_step
+    from herding.world.diffdrive import velocity_to_mecanum_wheels, mecanum_step
     from herding.world.geometry import WEBOTS_DT as _DT
     _xg, _yg, _hg = _x0, _y0, _h0
     for _ in range(_calib_n):
@@ -343,7 +343,7 @@ if MODE == "calibrate":
             max_wheel_omega=DOG_MAX_WHEEL_OMEGA, k_turn=4.0,
             wheel_base=DOG_WHEEL_BASE,
         )
-        _xg, _yg, _hg = mecanum_kinematics_step(
+        _xg, _yg, _hg = mecanum_step(
             _xg, _yg, _hg, _wfl, _wfr, _wrl, _wrr,
             DOG_WHEEL_RADIUS, DOG_WHEEL_BASE_X / 2, DOG_WHEEL_BASE_Y / 2, _DT,
         )
@@ -414,7 +414,7 @@ while robot.step(timestep) != -1:
     if USE_GT_PERCEPTION and _gt_sheep:
         # Bypass tracker: feed GT emitter positions directly to policy/teacher.
         sheep_positions = {k: v for k, v in _gt_sheep.items()
-                          if not is_penned_position(v[0], v[1])}
+                          if not is_penned(v[0], v[1])}
         tracker.update(detections)  # still advance tracker for diagnostics
     else:
         sheep_positions = tracker.update(detections)
@@ -453,7 +453,7 @@ while robot.step(timestep) != -1:
             vx, vy, _mode_str = result
 
     # Near-sheep speed modulation (shared by every mode).
-    vx, vy = modulate_speed_near_sheep(vx, vy, dog_xy, sheep_positions)
+    vx, vy = modulate_speed(vx, vy, dog_xy, sheep_positions)
 
     # EMA smoothing — kills frame-to-frame action jitter.
     if DRIVE_MODE == "mecanum":
@@ -489,7 +489,7 @@ while robot.step(timestep) != -1:
     # fire during the first few steps while the receiver fills.
     if _gt_sheep and not _run_done:
         gt_active = sum(1 for x, y in _gt_sheep.values()
-                        if not is_penned_position(x, y))
+                        if not is_penned(x, y))
         if gt_active == 0:
             os.makedirs(os.path.dirname(RUN_DONE_FILE), exist_ok=True)
             open(RUN_DONE_FILE, "w").close()
@@ -499,7 +499,7 @@ while robot.step(timestep) != -1:
 
     if step_count % 200 == 0:
         gt_penned = sum(1 for x, y in _gt_sheep.values()
-                        if is_penned_position(x, y))
+                        if is_penned(x, y))
         gt_total = len(_gt_sheep)
         common = (f"[dog mode={MODE} drive={DRIVE_MODE}] step={step_count} "
                   f"GT_penned={gt_penned}/{gt_total} "