neckcompass 1.0.0__py3-none-any.whl

neckcompass/__init__.py

@@ -0,0 +1,22 @@
+"""NeckCompass: Drosophila Central Complex ring-attractor compass & GPS-denied path integrator."""
+
+from .path_integrator import FanBodyNavigator
+from .ring_attractor import (
+    CompassDiagnostics,
+    PlasticLandmarkRing,
+    RingCompass,
+    circular_error_rad,
+    wrap_angle,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    "CompassDiagnostics",
+    "FanBodyNavigator",
+    "PlasticLandmarkRing",
+    "RingCompass",
+    "circular_error_rad",
+    "wrap_angle",
+]

neckcompass/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m neckcompass` execution."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

neckcompass/cli.py

@@ -0,0 +1,281 @@
+"""Command-line interface for NeckCompass (`neckcompass demo`, `neckcompass benchmark-quick`)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+from typing import Optional, Sequence
+
+import numpy as np
+
+from . import __version__
+from .path_integrator import FanBodyNavigator
+from .ring_attractor import RingCompass, circular_error_rad, wrap_angle
+
+
+class _CircularEKF2State:
+    """Optimal 2-state Circular Extended Kalman Filter [heading_rad, gyro_bias_rad_s]."""
+
+    def __init__(
+        self,
+        init_heading_rad: float,
+        gyro_std_rad_s: float = math.radians(1.5),
+        bias_rw_rad_s_rt_s: float = math.radians(0.08),
+        mag_std_rad: float = math.radians(3.0),
+    ) -> None:
+        self.psi = float(wrap_angle(init_heading_rad))
+        self.bias = 0.0
+        r_mag = float(mag_std_rad) ** 2
+        self.P = np.diag([r_mag, (math.radians(1.5)) ** 2]).astype(np.float64)
+        self.gyro_var = float(gyro_std_rad_s) ** 2
+        self.bias_rw_var = float(bias_rw_rad_s_rt_s) ** 2
+        self.r_mag = r_mag
+
+    def update(self, omega_meas: float, dt: float, mag_rad: float) -> float:
+        psi_pred = float(wrap_angle(self.psi + (omega_meas - self.bias) * dt))
+        p00, p01, p10, p11 = self.P[0, 0], self.P[0, 1], self.P[1, 0], self.P[1, 1]
+        # Exact discrete-time covariance propagation: F = [[1, -dt], [0, 1]]
+        q00 = self.gyro_var * (dt * dt)
+        q11 = self.bias_rw_var * dt
+        pp00 = p00 - dt * (p10 + p01) + (dt * dt) * p11 + q00
+        pp01 = p01 - dt * p11
+        pp10 = p10 - dt * p11
+        pp11 = p11 + q11
+
+        innov = float(wrap_angle(mag_rad - psi_pred))
+        s_cov = pp00 + self.r_mag
+        k0 = pp00 / s_cov
+        k1 = pp10 / s_cov
+
+        self.psi = float(wrap_angle(psi_pred + k0 * innov))
+        self.bias = float(self.bias + k1 * innov)
+        self.P[0, 0] = (1.0 - k0) * pp00
+        self.P[0, 1] = (1.0 - k0) * pp01
+        self.P[1, 0] = pp10 - k1 * pp00
+        self.P[1, 1] = pp11 - k1 * pp01
+        return self.psi
+
+
+def _run_demo(seed: int = 42, n_wedges: int = 16, as_json: bool = False) -> dict:
+    rng = np.random.default_rng(seed)
+    dt = 0.02
+    speed = 1.6  # m/s
+    gyro_bias = math.radians(1.0)  # 1.0 deg/s steady MEMS drift
+
+    compass = RingCompass(n_wedges=n_wedges)
+    nav = FanBodyNavigator(n_columns=16, compass=compass)
+
+    true_x, true_y, true_psi = 0.0, 0.0, 0.35
+    compass.reset(true_psi + rng.normal(0.0, math.radians(2.0)))
+
+    outbound_steps = int(90.0 / dt)  # 90 s outbound survey (~144 m path)
+    spike_errs_deg: list[float] = []
+
+    for k in range(outbound_steps):
+        t = k * dt
+        omega_true = 0.22 * math.sin(0.11 * t) + 0.14 * math.cos(0.07 * t)
+        true_psi = float(wrap_angle(true_psi + omega_true * dt))
+        true_x += speed * math.cos(true_psi) * dt
+        true_y += speed * math.sin(true_psi) * dt
+
+        omega_meas = omega_true + gyro_bias + rng.normal(0.0, math.radians(1.2))
+        spike = 0.0
+        if 25.0 <= t <= 26.6:
+            spike = math.radians(118.0) * math.sin(math.pi * (t - 25.0) / 1.6)
+        elif 58.0 <= t <= 59.8:
+            spike = -math.radians(136.0) * math.sin(math.pi * (t - 58.0) / 1.8)
+        mag_meas = float(wrap_angle(true_psi + spike + rng.normal(0.0, math.radians(2.5))))
+
+        est_psi, _, _ = nav.step_with_compass(omega_meas, speed, dt, mag_heading_rad=mag_meas)
+        if abs(spike) > math.radians(60.0):
+            spike_errs_deg.append(abs(math.degrees(float(circular_error_rad(est_psi, true_psi)))))
+
+    outbound_dist = math.hypot(true_x, true_y)
+
+    # Engage blind GPS-denied return-to-home via PFL3 steering
+    max_return_steps = int(130.0 / dt)
+    for k in range(max_return_steps):
+        t = 90.0 + k * dt
+        est_dist, _ = nav.home_vector()
+        if est_dist < 0.6:
+            break
+        omega_cmd = nav.steering_cmd(max_turn_rate=0.9)
+        true_psi = float(wrap_angle(true_psi + omega_cmd * dt))
+        step_v = speed * min(1.0, max(0.25, est_dist / 3.0))
+        true_x += step_v * math.cos(true_psi) * dt
+        true_y += step_v * math.sin(true_psi) * dt
+
+        omega_meas = omega_cmd + gyro_bias + rng.normal(0.0, math.radians(1.2))
+        spike = (
+            math.radians(125.0) * math.sin(math.pi * (t - 115.0) / 1.5)
+            if 115.0 <= t <= 116.5
+            else 0.0
+        )
+        mag_meas = float(wrap_angle(true_psi + spike + rng.normal(0.0, math.radians(2.5))))
+        nav.step_with_compass(omega_meas, step_v, dt, mag_heading_rad=mag_meas)
+
+    miss_m = math.hypot(true_x, true_y)
+    summary = {
+        "version": __version__,
+        "n_wedges": n_wedges,
+        "outbound_distance_from_origin_m": round(outbound_dist, 2),
+        "max_error_during_136deg_spike_deg": round(max(spike_errs_deg) if spike_errs_deg else 0.0, 2),
+        "estimated_gyro_bias_deg_s": round(math.degrees(compass.estimated_gyro_bias_rad_s), 3),
+        "final_return_miss_m": round(miss_m, 2),
+    }
+
+    if as_json:
+        print(json.dumps(summary, indent=2))
+    else:
+        print(f"NeckCompass v{__version__} -- Central Complex Ring Attractor & Path Integrator Demo")
+        print("-" * 74)
+        print(f"  E-PG Ring Wedges               : {summary['n_wedges']}")
+        print(f"  Outbound Survey Displacement   : {summary['outbound_distance_from_origin_m']:.2f} m (GPS blackout)")
+        print(f"  Max Error in 118-136 deg Spikes: {summary['max_error_during_136deg_spike_deg']:.2f} deg")
+        print(f"  Learned P-EN Gyro Bias Trim    : {summary['estimated_gyro_bias_deg_s']:.3f} deg/s (true: 1.000 deg/s)")
+        print(f"  Final PFL3 Return-to-Home Miss : {summary['final_return_miss_m']:.2f} m")
+    return summary
+
+
+def _run_quick_benchmark(seed: int = 101, as_json: bool = False) -> dict:
+    rng = np.random.default_rng(seed)
+    dt = 0.02
+    steps = int(120.0 / dt)
+    gyro_bias_init = math.radians(0.9)
+    bias_rw_std = math.radians(0.08)
+    gyro_std = math.radians(1.5)
+    mag_std = math.radians(3.0)
+
+    def eval_heading(spiky: bool) -> dict[str, dict[str, float]]:
+        local_rng = np.random.default_rng(seed + (17 if spiky else 0))
+        psi_true = 0.2
+        gyro_bias = gyro_bias_init
+        init_mag = float(wrap_angle(psi_true + local_rng.normal(0.0, mag_std)))
+
+        nc = RingCompass(n_wedges=16, initial_heading_rad=init_mag)
+        ekf = _CircularEKF2State(
+            init_mag,
+            gyro_std_rad_s=gyro_std,
+            bias_rw_rad_s_rt_s=bias_rw_std,
+            mag_std_rad=mag_std,
+        )
+        psi_gyro = init_mag
+        psi_comp = init_mag
+        tau_comp = 2.5
+        alpha_comp = dt / (tau_comp + dt)
+
+        errs = {"neckcompass": [], "ekf": [], "complementary": [], "gyro_dr": []}
+        for k in range(steps):
+            t = k * dt
+            omega_true = 0.30 * math.sin(0.15 * t) + 0.18 * math.cos(0.09 * t)
+            psi_true = float(wrap_angle(psi_true + omega_true * dt))
+            gyro_bias += local_rng.normal(0.0, bias_rw_std * math.sqrt(dt))
+            omega_meas = omega_true + gyro_bias + local_rng.normal(0.0, gyro_std)
+
+            anom = 0.0
+            if spiky:
+                # Periodic 1.4 s ferromagnetic hull/cable spikes every 15 s
+                phase = t % 15.0
+                if 6.0 <= phase <= 7.4:
+                    sign = 1.0 if (int(t // 15.0) % 2 == 0) else -1.0
+                    amp = math.radians(115.0 if sign > 0 else 135.0)
+                    anom = sign * amp * math.sin(math.pi * (phase - 6.0) / 1.4)
+
+            mag_meas = float(wrap_angle(psi_true + anom + local_rng.normal(0.0, mag_std)))
+
+            psi_nc = nc.update(omega_meas, dt, mag_heading_rad=mag_meas)
+            psi_ekf = ekf.update(omega_meas, dt, mag_meas)
+            psi_gyro = float(wrap_angle(psi_gyro + omega_meas * dt))
+            pred_c = float(wrap_angle(psi_comp + omega_meas * dt))
+            psi_comp = float(wrap_angle(pred_c + alpha_comp * float(wrap_angle(mag_meas - pred_c))))
+
+            if k >= int(15.0 / dt):  # Steady-state window after 15 s warmup
+                errs["neckcompass"].append(abs(math.degrees(float(circular_error_rad(psi_nc, psi_true)))))
+                errs["ekf"].append(abs(math.degrees(float(circular_error_rad(psi_ekf, psi_true)))))
+                errs["complementary"].append(abs(math.degrees(float(circular_error_rad(psi_comp, psi_true)))))
+                errs["gyro_dr"].append(abs(math.degrees(float(circular_error_rad(psi_gyro, psi_true)))))
+
+        out: dict[str, dict[str, float]] = {}
+        for name, vals in errs.items():
+            arr = np.asarray(vals, dtype=np.float64)
+            out[name] = {
+                "rmse_deg": round(float(np.sqrt(np.mean(arr * arr))), 2),
+                "p95_deg": round(float(np.percentile(arr, 95)), 2),
+            }
+        return out
+
+    clean_res = eval_heading(spiky=False)
+    spiky_res = eval_heading(spiky=True)
+    _ = rng  # keep seed signature clean
+
+    result = {
+        "seed": seed,
+        "scenario_a_clean_gaussian": clean_res,
+        "scenario_b_ferromagnetic_spikes": spiky_res,
+    }
+
+    if as_json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"NeckCompass v{__version__} -- Quick Head-to-Head Benchmark (120 s @ 50 Hz, seed={seed})")
+        print("-" * 82)
+        print(
+            f"{'Estimator':<28} | {'Clean RMSE (deg)':>16} | {'Spiky RMSE (deg)':>16} | {'Spiky P95 (deg)':>15}"
+        )
+        print("-" * 82)
+        labels = [
+            ("NeckCompass (E-PG 16w)", "neckcompass"),
+            ("2-State Circular EKF", "ekf"),
+            ("Complementary IMU+Mag", "complementary"),
+            ("Gyro Dead-Reckoning", "gyro_dr"),
+        ]
+        for label, key in labels:
+            c_rmse = clean_res[key]["rmse_deg"]
+            s_rmse = spiky_res[key]["rmse_deg"]
+            s_p95 = spiky_res[key]["p95_deg"]
+            print(f"{label:<28} | {c_rmse:>16.2f} | {s_rmse:>16.2f} | {s_p95:>15.2f}")
+        print("-" * 82)
+        print(
+            "Note: Under ideal Gaussian noise, 2-State EKF is minimum-variance optimal; "
+            "under 115-135 deg ferromagnetic spikes, NeckCompass rejects off-basin outliers."
+        )
+    return result
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="neckcompass",
+        description="NeckCompass: Drosophila Central Complex ring-attractor compass & GPS-denied navigator.",
+    )
+    parser.add_argument("--version", action="version", version=f"neckcompass {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_demo = sub.add_parser("demo", help="Run GPS-denied outbound + PFL3 homebound navigation demo")
+    p_demo.add_argument("--seed", type=int, default=42, help="Random seed (default: 42)")
+    p_demo.add_argument("--wedges", type=int, default=16, choices=[16, 32], help="Ring wedges (16 or 32)")
+    p_demo.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+
+    p_bench = sub.add_parser(
+        "benchmark-quick",
+        help="Run fast head-to-head comparison (Clean Gaussian vs Ferromagnetic Spikes)",
+    )
+    p_bench.add_argument("--seed", type=int, default=101, help="Random seed (default: 101)")
+    p_bench.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "demo":
+        _run_demo(seed=args.seed, n_wedges=args.wedges, as_json=args.json)
+        return 0
+    if args.command == "benchmark-quick":
+        _run_quick_benchmark(seed=args.seed, as_json=args.json)
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

neckcompass/path_integrator.py

@@ -0,0 +1,233 @@
+"""Central Complex Fan-Shaped Body (CPU4 / hDelta) path integrator and PFL3 steering.
+
+Biophysical inspirations:
+- Stone et al. (Current Biology, 2017): anatomically constrained Central Complex path
+  integration and homebound steering in bee/insect brain
+- Lyu, Abbott & Maimon (Nature, 2022): 2D vector arithmetic via sinusoidal activity bumps
+  in the *Drosophila* Fan-Shaped Body
+- Mussells Pires et al. (Nature, 2024) & Westeinde et al. (Nature, 2024): PFL3 (+/-67.5 deg
+  phase-shifted left/right steering) + PFL2 (180 deg anti-goal turn boost)
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Optional
+
+import numpy as np
+
+from .ring_attractor import RingCompass, wrap_angle
+
+
+class FanBodyNavigator:
+    """N-column opponent CPU4 vector path integrator and PFL3/PFL2 homebound controller.
+
+    Maintains ``n_columns`` (default 16) opponent Fan-Shaped Body memory columns that
+    accumulate translational speed along the current E-PG compass heading during
+    GPS-denied outbound navigation, continuously encoding the metric displacement vector
+    from origin ``(0, 0)`` and generating neural PFL3/PFL2 yaw-rate commands to steer
+    straight back home during complete GPS blackouts.
+    """
+
+    def __init__(
+        self,
+        n_columns: int = 16,
+        compass: Optional[RingCompass] = None,
+        *,
+        leak_rate: float = 0.0,
+        steering_gain: float = 2.2,
+        pfl2_boost_gain: float = 2.5,
+        arrival_radius_m: float = 1.5,
+    ) -> None:
+        if n_columns < 8 or (n_columns % 2) != 0:
+            raise ValueError(f"n_columns must be an even integer >= 8, got {n_columns}")
+        if leak_rate < 0.0:
+            raise ValueError("leak_rate must be >= 0")
+        if arrival_radius_m <= 0.0:
+            raise ValueError("arrival_radius_m must be > 0")
+
+        self.n_columns: int = int(n_columns)
+        self.compass: Optional[RingCompass] = compass
+        self.leak_rate: float = float(leak_rate)
+        self.steering_gain: float = float(steering_gain)
+        self.pfl2_boost_gain: float = float(pfl2_boost_gain)
+        self.arrival_radius_m: float = float(arrival_radius_m)
+
+        self.thetas: np.ndarray = -math.pi + (
+            2.0 * math.pi * np.arange(self.n_columns, dtype=np.float64)
+        ) / self.n_columns
+        self._cos_thetas: np.ndarray = np.cos(self.thetas)
+        self._sin_thetas: np.ndarray = np.sin(self.thetas)
+
+        # Opponent CPU4 column memories (excitatory PFN drive vs 180-deg hDelta opponent)
+        self._cpu4_pos: np.ndarray = np.zeros(self.n_columns, dtype=np.float64)
+        self._cpu4_neg: np.ndarray = np.zeros(self.n_columns, dtype=np.float64)
+        self._last_heading_rad: float = compass.heading_rad if (compass and compass.initialized) else 0.0
+
+    def reset(self) -> None:
+        """Zero the CPU4 path-integrator memory (marks current location as new home origin)."""
+        self._cpu4_pos.fill(0.0)
+        self._cpu4_neg.fill(0.0)
+
+    @property
+    def cpu4_columns(self) -> np.ndarray:
+        """Net opponent CPU4 column activity ``(n_columns,)`` encoding outbound displacement."""
+        return self._cpu4_pos - self._cpu4_neg
+
+    @property
+    def cpu4_rates(self) -> tuple[np.ndarray, np.ndarray]:
+        """Return copies of ``(cpu4_pos, cpu4_neg)`` non-negative opponent column accumulators."""
+        return self._cpu4_pos.copy(), self._cpu4_neg.copy()
+
+    def _resolve_heading(self, heading_rad: Optional[float]) -> float:
+        if heading_rad is not None:
+            return float(wrap_angle(heading_rad))
+        if self.compass is not None and self.compass.initialized:
+            return self.compass.heading_rad
+        return self._last_heading_rad
+
+    def update(
+        self,
+        speed_m_s: float,
+        dt: float,
+        heading_rad: Optional[float] = None,
+    ) -> tuple[float, float]:
+        """Integrate forward velocity ``speed_m_s`` for ``dt`` seconds along ``heading_rad``.
+
+        If ``heading_rad`` is omitted, reads the current heading from the attached
+        ``RingCompass`` (if any). Returns ``(distance_m, home_bearing_rad)``.
+        """
+        if dt < 0.0:
+            raise ValueError(f"dt must be non-negative, got {dt}")
+
+        psi = self._resolve_heading(heading_rad)
+        self._last_heading_rad = psi
+
+        if dt > 0.0:
+            if self.leak_rate > 0.0:
+                decay = math.exp(-self.leak_rate * dt)
+                self._cpu4_pos *= decay
+                self._cpu4_neg *= decay
+
+            ds = float(speed_m_s) * float(dt)
+            proj = np.cos(self.thetas - psi)
+            # Push-pull opponent accumulation across the 16 Fan-Shaped Body columns
+            pos_drive = np.maximum(0.0, proj)
+            neg_drive = np.maximum(0.0, -proj)
+            if ds >= 0.0:
+                self._cpu4_pos += ds * pos_drive
+                self._cpu4_neg += ds * neg_drive
+            else:
+                self._cpu4_pos += (-ds) * neg_drive
+                self._cpu4_neg += (-ds) * pos_drive
+
+            # Subtract common-mode baseline between paired columns to prevent saturation on long runs
+            common = np.minimum(self._cpu4_pos, self._cpu4_neg)
+            self._cpu4_pos -= common
+            self._cpu4_neg -= common
+
+        return self.home_vector()
+
+    def step_with_compass(
+        self,
+        omega_rad_s: float,
+        speed_m_s: float,
+        dt: float,
+        mag_heading_rad: Optional[float] = None,
+        sun_heading_rad: Optional[float] = None,
+        mag_confidence: float = 1.0,
+        sun_confidence: float = 1.0,
+    ) -> tuple[float, float, float]:
+        """Update the attached ``RingCompass`` and integrate path in one step.
+
+        Returns ``(heading_rad, distance_m, home_bearing_rad)``.
+        """
+        if self.compass is None:
+            raise RuntimeError("FanBodyNavigator has no attached RingCompass; pass compass=... or call update()")
+        heading = self.compass.update(
+            omega_rad_s=omega_rad_s,
+            dt=dt,
+            mag_heading_rad=mag_heading_rad,
+            sun_heading_rad=sun_heading_rad,
+            mag_confidence=mag_confidence,
+            sun_confidence=sun_confidence,
+        )
+        dist_m, home_bearing = self.update(speed_m_s=speed_m_s, dt=dt, heading_rad=heading)
+        return heading, dist_m, home_bearing
+
+    @property
+    def displacement_xy_m(self) -> tuple[float, float]:
+        """Decoded outbound Cartesian displacement ``(x_m, y_m)`` from home origin."""
+        net = self.cpu4_columns
+        x_m = (2.0 / self.n_columns) * float(np.dot(net, self._cos_thetas))
+        y_m = (2.0 / self.n_columns) * float(np.dot(net, self._sin_thetas))
+        return x_m, y_m
+
+    def home_vector(self) -> tuple[float, float]:
+        """Compute ``(distance_m, home_bearing_rad)`` pointing from current position to origin."""
+        x_m, y_m = self.displacement_xy_m
+        dist_m = float(math.hypot(x_m, y_m))
+        if dist_m <= 1e-9:
+            return 0.0, 0.0
+        home_bearing = float(wrap_angle(math.atan2(-y_m, -x_m)))
+        return dist_m, home_bearing
+
+    def pfl3_columns(
+        self, current_heading_rad: Optional[float] = None
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """Compute ``(pfl3_left, pfl3_right, pfl2_boost)`` column firing rates.
+
+        Implements the *Drosophila* +/-67.5 deg (3*pi/8) PFL3 phase shift and 180 deg
+        PFL2 anti-goal boost across the Fan-Shaped Body columns.
+        """
+        psi = self._resolve_heading(current_heading_rad)
+        dist_m, _ = self.home_vector()
+        if dist_m <= 1e-9:
+            zeros = np.zeros(self.n_columns, dtype=np.float64)
+            return zeros, zeros.copy(), zeros.copy()
+
+        # hDelta 180-deg inverted CPU4 profile normalized to unit vector amplitude
+        hdelta_home = -self.cpu4_columns / dist_m
+
+        phi_shift = 3.0 * math.pi / 8.0  # 67.5 deg biological PFL3 shift
+        epg_left = np.cos(self.thetas - (psi - phi_shift))
+        epg_right = np.cos(self.thetas - (psi + phi_shift))
+        epg_anti = np.cos(self.thetas - (psi + math.pi))
+
+        pfl3_left = np.square(np.maximum(0.0, 0.5 * (hdelta_home + epg_left)))
+        pfl3_right = np.square(np.maximum(0.0, 0.5 * (hdelta_home + epg_right)))
+        pfl2_boost = np.square(np.maximum(0.0, 0.5 * (hdelta_home + epg_anti)))
+        return pfl3_left, pfl3_right, pfl2_boost
+
+    def steering_cmd(
+        self,
+        max_turn_rate: float = 1.0,
+        current_heading_rad: Optional[float] = None,
+    ) -> float:
+        """Compute bounded PFL3/PFL2 homebound yaw-rate command in ``[-max_turn_rate, +max_turn_rate]``."""
+        if max_turn_rate <= 0.0:
+            raise ValueError("max_turn_rate must be > 0")
+
+        dist_m, home_bearing = self.home_vector()
+        if dist_m <= 1e-6:
+            return 0.0
+
+        psi = self._resolve_heading(current_heading_rad)
+        pfl3_left, pfl3_right, pfl2_boost = self.pfl3_columns(psi)
+
+        # Normalized PFL3 lateralized motor drive in Lateral Accessory Lobe (LAL)
+        phi_shift = 3.0 * math.pi / 8.0
+        norm_factor = 0.5 * self.n_columns * math.sin(phi_shift)
+        raw_asym = float(np.sum(pfl3_right) - np.sum(pfl3_left)) / max(norm_factor, 1e-9)
+
+        # PFL2 boosts turning when facing away from home (resolves 180-deg anti-goal saddle; max mean = 0.25)
+        anti_drive = float(np.mean(pfl2_boost))
+        if abs(raw_asym) < 1e-4 and anti_drive > 0.18:
+            # Break exact 180-deg symmetry deterministically using shortest signed wrap
+            err = float(wrap_angle(home_bearing - psi))
+            raw_asym = math.copysign(0.25, err if err != 0.0 else 1.0)
+
+        boosted = raw_asym * (1.0 + self.pfl2_boost_gain * anti_drive)
+        arrival_taper = min(1.0, dist_m / self.arrival_radius_m)
+        cmd = max_turn_rate * arrival_taper * math.tanh(self.steering_gain * boosted)
+        return float(np.clip(cmd, -max_turn_rate, max_turn_rate))

neckcompass/ring_attractor.py

@@ -0,0 +1,453 @@
+"""Central Complex Ellipsoid Body (E-PG) ring attractor and plastic R-neuron compass.
+
+Biophysical inspirations:
+- Seelig & Jayaraman (Nature, 2015): single-bump E-PG landmark + angular velocity dynamics
+- Turner-Evans et al. (eLife, 2017) & Green et al. (Nature, 2017): P-EN angular velocity shifters
+- Fisher et al. (Nature, 2019) & Kim et al. (Nature, 2019): Hebbian/anti-Hebbian R-neuron -> E-PG
+  associative plasticity for warped visual/magnetic landmark scenes
+- Lyu, Abbott & Maimon (Nature, 2022): phasor harmonic arithmetic across Central Complex columns
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+from typing import Optional
+
+import numpy as np
+
+
+def wrap_angle(angle_rad: float | np.ndarray) -> float | np.ndarray:
+    """Wrap angle(s) in radians cleanly into (-pi, pi] with zero discontinuity."""
+    wrapped = (np.asarray(angle_rad) + math.pi) % (2.0 * math.pi) - math.pi
+    if np.ndim(angle_rad) == 0:
+        # Map -pi to +pi consistently if desired, or keep standard [-pi, pi)
+        val = float(wrapped)
+        return math.pi if val == -math.pi else val
+    return wrapped
+
+
+def circular_error_rad(est_rad: float | np.ndarray, truth_rad: float | np.ndarray) -> float | np.ndarray:
+    """Signed shortest circular angular difference (est - truth) in (-pi, pi]."""
+    return wrap_angle(np.asarray(est_rad) - np.asarray(truth_rad))
+
+
+@dataclass(frozen=True)
+class CompassDiagnostics:
+    """Snapshot of internal neural state from a RingCompass update step."""
+
+    heading_rad: float
+    bump_amplitude: float
+    estimated_gyro_bias_rad_s: float
+    mag_gate: float
+    sun_gate: float
+
+
+class RingCompass:
+    """Topological N-wedge E-PG ring attractor compass with P-EN angular-velocity shifters.
+
+    Maintains a localized activity bump across ``n_wedges`` (default 16, matching the
+    16 Ellipsoid Body wedges of *Drosophila*; also supports ``n_wedges=32`` or any
+    even ``N >= 8``). Recurrent E-PG excitation and global Delta7 inhibition sustain
+    a single constant-amplitude bump, while asymmetric Left/Right P-EN projections
+    rotate the bump proportionally to ``omega_rad_s * dt``.
+
+    External cues (``mag_heading_rad``, ``sun_heading_rad``) excite localized von-Mises
+    Ring-Neuron (R2 / R4d) receptive fields gated by cooperative dendritic coincidence
+    with the active E-PG bump. Cues within the attractor basin (~30 deg) smoothly pull
+    the bump and adapt a slow homeostatic P-EN bias trim; transient 60-160 deg
+    ferromagnetic ship-hull or motor-cable spikes fall onto Delta7-inhibited wedges
+    and are naturally rejected without yanking the heading or corrupting bias state.
+    """
+
+    def __init__(
+        self,
+        n_wedges: int = 16,
+        initial_heading_rad: Optional[float] = None,
+        *,
+        cue_kappa: float = 4.0,
+        basin_sigma: float = 0.14,
+        mag_gain: float = 1.6,
+        sun_gain: float = 3.2,
+        bias_adapt_rate: float = 0.55,
+        max_bias_rad_s: float = 0.15,
+        inhibition_threshold: float = 0.0,
+        reanchor_seconds: Optional[float] = 15.0,
+    ) -> None:
+        if n_wedges < 8 or (n_wedges % 2) != 0:
+            raise ValueError(f"n_wedges must be an even integer >= 8, got {n_wedges}")
+        if cue_kappa <= 0.0:
+            raise ValueError("cue_kappa must be positive")
+        if basin_sigma <= 0.0:
+            raise ValueError("basin_sigma must be positive")
+
+        self.n_wedges: int = int(n_wedges)
+        self.cue_kappa: float = float(cue_kappa)
+        self.basin_sigma: float = float(basin_sigma)
+        self.mag_gain: float = float(mag_gain)
+        self.sun_gain: float = float(sun_gain)
+        self.bias_adapt_rate: float = float(bias_adapt_rate)
+        self.max_bias_rad_s: float = float(max_bias_rad_s)
+        self.inhibition_threshold: float = float(inhibition_threshold)
+        self.reanchor_seconds: Optional[float] = (
+            None if reanchor_seconds is None else float(reanchor_seconds)
+        )
+
+        # Preferred wedge angles uniformly tiling [-pi, pi)
+        self.thetas: np.ndarray = -math.pi + (2.0 * math.pi * np.arange(self.n_wedges, dtype=np.float64)) / self.n_wedges
+        self._cos_thetas: np.ndarray = np.cos(self.thetas)
+        self._sin_thetas: np.ndarray = np.sin(self.thetas)
+
+        self._rates: np.ndarray = np.zeros(self.n_wedges, dtype=np.float64)
+        self._initialized: bool = False
+        self._pen_bias_rad_s: float = 0.0
+
+        # Track sustained kinematically coherent off-basin cue (for genuine cold re-orientation)
+        self._prev_mag_rad: Optional[float] = None
+        self._coherent_offbasin_time: float = 0.0
+        self._last_mag_gate: float = 0.0
+        self._last_sun_gate: float = 0.0
+
+        if initial_heading_rad is not None:
+            self.reset(initial_heading_rad)
+
+    def _shape_bump_from_angle(self, angle_rad: float) -> np.ndarray:
+        """Construct the canonical Delta7-inhibited E-PG bump centered at ``angle_rad``."""
+        raw = np.maximum(0.0, np.cos(self.thetas - angle_rad) - self.inhibition_threshold)
+        peak = float(np.max(raw))
+        return raw / peak if peak > 1e-12 else raw
+
+    def reset(self, heading_rad: float = 0.0, *, reset_bias: bool = True) -> None:
+        """Seed or reset the E-PG compass bump to ``heading_rad``."""
+        wrapped = float(wrap_angle(heading_rad))
+        self._rates = self._shape_bump_from_angle(wrapped)
+        self._initialized = True
+        if reset_bias:
+            self._pen_bias_rad_s = 0.0
+        self._prev_mag_rad = None
+        self._coherent_offbasin_time = 0.0
+
+    @property
+    def initialized(self) -> bool:
+        """Whether the E-PG ring bump has been seeded."""
+        return self._initialized
+
+    @property
+    def wedges(self) -> np.ndarray:
+        """Copy of current N-wedge non-negative E-PG firing rates."""
+        return self._rates.copy()
+
+    @property
+    def heading_rad(self) -> float:
+        """Decoded circular population-vector heading in (-pi, pi]."""
+        if not self._initialized:
+            return 0.0
+        c1 = float(np.dot(self._rates, self._cos_thetas))
+        s1 = float(np.dot(self._rates, self._sin_thetas))
+        if abs(c1) < 1e-15 and abs(s1) < 1e-15:
+            return 0.0
+        return float(wrap_angle(math.atan2(s1, c1)))
+
+    @property
+    def heading_deg(self) -> float:
+        """Decoded heading in degrees within (-180, 180]."""
+        return math.degrees(self.heading_rad)
+
+    @property
+    def bump_amplitude(self) -> float:
+        """First-harmonic phasor coherence of the E-PG activity bump in [0, 1]."""
+        if not self._initialized:
+            return 0.0
+        total = float(np.sum(self._rates))
+        if total <= 1e-12:
+            return 0.0
+        c1 = float(np.dot(self._rates, self._cos_thetas))
+        s1 = float(np.dot(self._rates, self._sin_thetas))
+        return float(math.hypot(c1, s1) / total)
+
+    @property
+    def estimated_gyro_bias_rad_s(self) -> float:
+        """Homeostatic P-EN angular-velocity bias estimate in rad/s."""
+        return self._pen_bias_rad_s
+
+    def diagnostics(self) -> CompassDiagnostics:
+        """Return a structured diagnostic snapshot of the latest compass state."""
+        return CompassDiagnostics(
+            heading_rad=self.heading_rad,
+            bump_amplitude=self.bump_amplitude,
+            estimated_gyro_bias_rad_s=self._pen_bias_rad_s,
+            mag_gate=self._last_mag_gate,
+            sun_gate=self._last_sun_gate,
+        )
+
+    def _von_mises_profile(self, cue_angle_rad: float) -> np.ndarray:
+        """Localized R-neuron afferent excitation profile normalized to match E-PG 1st harmonic."""
+        # Raised cosine (degree <= 3) has zero harmonic aliasing on N >= 8 rings while staying localized
+        prof = np.power(0.5 * (1.0 + np.cos(self.thetas - cue_angle_rad)), 3)
+        # Match 1st-harmonic norm to half-wave rectified E-PG bump (which has 1st harmonic = N/4)
+        c1 = abs(float(np.dot(prof, np.cos(self.thetas - cue_angle_rad))))
+        target_c1 = 0.25 * self.n_wedges
+        return prof * (target_c1 / max(c1, 1e-12))
+
+    def _basin_coincidence_gate(self, cue_angle_rad: float, pred_heading_rad: float) -> float:
+        """Cooperative dendritic coincidence gate between R-neuron input and E-PG bump."""
+        dist = 1.0 - math.cos(cue_angle_rad - pred_heading_rad)
+        ratio = dist / self.basin_sigma
+        return math.exp(-(ratio * ratio))
+
+    def update(
+        self,
+        omega_rad_s: float,
+        dt: float,
+        mag_heading_rad: Optional[float] = None,
+        sun_heading_rad: Optional[float] = None,
+        mag_confidence: float = 1.0,
+        sun_confidence: float = 1.0,
+    ) -> float:
+        """Advance the E-PG ring attractor by ``dt`` seconds and return ``heading_rad``.
+
+        Parameters
+        ----------
+        omega_rad_s:
+            Body yaw angular velocity in rad/s (positive = counter-clockwise).
+        dt:
+            Timestep in seconds (must be >= 0).
+        mag_heading_rad:
+            Optional raw/calibrated magnetic heading cue in radians.
+        sun_heading_rad:
+            Optional sky-polarization / sun / visual azimuth cue in radians.
+        mag_confidence:
+            Scalar confidence multiplier in [0, 1] for ``mag_heading_rad``.
+        sun_confidence:
+            Scalar confidence multiplier in [0, 1] for ``sun_heading_rad``.
+        """
+        if dt < 0.0:
+            raise ValueError(f"dt must be non-negative, got {dt}")
+
+        mag_conf = float(np.clip(mag_confidence, 0.0, 1.0))
+        sun_conf = float(np.clip(sun_confidence, 0.0, 1.0))
+
+        # Auto-seed bump on the very first step if not yet initialized
+        if not self._initialized:
+            if sun_heading_rad is not None and sun_conf > 0.0:
+                self.reset(float(sun_heading_rad), reset_bias=False)
+            elif mag_heading_rad is not None and mag_conf > 0.0:
+                self.reset(float(mag_heading_rad), reset_bias=False)
+            else:
+                self.reset(float(omega_rad_s) * float(dt), reset_bias=False)
+            if mag_heading_rad is not None:
+                self._prev_mag_rad = float(wrap_angle(mag_heading_rad))
+            return self.heading_rad
+
+        # 1. Delta7 first-harmonic readout + P-EN asymmetric velocity shift
+        c1 = (2.0 / self.n_wedges) * float(np.dot(self._rates, self._cos_thetas))
+        s1 = (2.0 / self.n_wedges) * float(np.dot(self._rates, self._sin_thetas))
+        norm1 = math.hypot(c1, s1)
+        if norm1 <= 1e-12:
+            c1, s1, norm1 = 1.0, 0.0, 1.0
+
+        dphi = (float(omega_rad_s) - self._pen_bias_rad_s) * float(dt)
+        cos_dphi = math.cos(dphi)
+        sin_dphi = math.sin(dphi)
+
+        c_rot = (c1 * cos_dphi - s1 * sin_dphi) / norm1
+        s_rot = (c1 * sin_dphi + s1 * cos_dphi) / norm1
+        pred_heading = float(wrap_angle(math.atan2(s_rot, c_rot)))
+
+        # Reconstruct P-EN shifted recurrent E-PG excitation
+        rec_drive = c_rot * self._cos_thetas + s_rot * self._sin_thetas
+        u_ring = np.maximum(0.0, rec_drive - self.inhibition_threshold)
+        u_peak = float(np.max(u_ring))
+        if u_peak > 1e-12:
+            u_ring = u_ring / u_peak
+
+        # 2. Multi-cue R-neuron afferent injection with attractor-basin gating
+        self._last_mag_gate = 0.0
+        self._last_sun_gate = 0.0
+        net_innovation = 0.0
+        net_gate_weight = 0.0
+
+        if sun_heading_rad is not None and sun_conf > 0.0:
+            sun_ang = float(wrap_angle(sun_heading_rad))
+            sun_gate = self._basin_coincidence_gate(sun_ang, pred_heading)
+            self._last_sun_gate = sun_gate
+            eff_sun = self.sun_gain * sun_conf * sun_gate * dt
+            if eff_sun > 0.0:
+                u_ring = u_ring + eff_sun * self._von_mises_profile(sun_ang)
+                sun_err = float(wrap_angle(sun_ang - pred_heading))
+                net_innovation += (self.sun_gain * sun_conf * sun_gate) * sun_err
+                net_gate_weight += self.sun_gain * sun_conf * sun_gate
+
+        if mag_heading_rad is not None and mag_conf > 0.0:
+            mag_ang = float(wrap_angle(mag_heading_rad))
+            mag_gate = self._basin_coincidence_gate(mag_ang, pred_heading)
+            self._last_mag_gate = mag_gate
+
+            # Check long-horizon kinematic coherence for genuine cold re-anchoring
+            if (
+                self.reanchor_seconds is not None
+                and mag_gate < 0.05
+                and sun_heading_rad is None
+                and dt > 0.0
+            ):
+                if self._prev_mag_rad is not None:
+                    d_mag = float(wrap_angle(mag_ang - self._prev_mag_rad))
+                    rate_mismatch = abs(d_mag - (float(omega_rad_s) - self._pen_bias_rad_s) * dt) / max(dt, 1e-6)
+                    if rate_mismatch < 0.25:  # < ~14 deg/s discrepancy -> kinematically coherent field
+                        self._coherent_offbasin_time += dt
+                    else:
+                        self._coherent_offbasin_time = 0.0
+                if self._coherent_offbasin_time >= self.reanchor_seconds:
+                    self.reset(mag_ang, reset_bias=False)
+                    self._prev_mag_rad = mag_ang
+                    return self.heading_rad
+            else:
+                self._coherent_offbasin_time = 0.0
+
+            self._prev_mag_rad = mag_ang
+
+            eff_mag = self.mag_gain * mag_conf * mag_gate * dt
+            if eff_mag > 0.0:
+                u_ring = u_ring + eff_mag * self._von_mises_profile(mag_ang)
+                mag_err = float(wrap_angle(mag_ang - pred_heading))
+                net_innovation += (self.mag_gain * mag_conf * mag_gate) * mag_err
+                net_gate_weight += self.mag_gain * mag_conf * mag_gate
+
+        # 3. Winner-take-all Delta7 divisive/subtractive sharpening back onto canonical bump manifold
+        c_new = float(np.dot(u_ring, self._cos_thetas))
+        s_new = float(np.dot(u_ring, self._sin_thetas))
+        new_heading = float(wrap_angle(math.atan2(s_new, c_new)))
+        self._rates = self._shape_bump_from_angle(new_heading)
+
+        # 4. Slow homeostatic P-EN bias adaptation (only when cues coherently overlap the bump!)
+        # If omega_meas = omega_true + bias (bias > 0), pred_heading drifts positive, so
+        # cue_err = (cue - pred_heading) < 0; thus bias estimate increases with (-cue_err).
+        if dt > 0.0 and net_gate_weight > 1e-6 and self.bias_adapt_rate > 0.0:
+            weighted_err = net_innovation / max(self.mag_gain, self.sun_gain, 1.0)
+            self._pen_bias_rad_s -= self.bias_adapt_rate * weighted_err * dt
+            self._pen_bias_rad_s = float(
+                np.clip(self._pen_bias_rad_s, -self.max_bias_rad_s, self.max_bias_rad_s)
+            )
+
+        return self.heading_rad
+
+
+class PlasticLandmarkRing:
+    """Hebbian / anti-Hebbian R-neuron -> E-PG plastic ring mapping for warped magnetic scenes.
+
+    Models associative synaptic plasticity between ``n_ring_neurons`` circularly tuned
+    sensory Ring Neurons (R2/R4d) and the ``n_wedges`` Ellipsoid Body E-PG compass wedges
+    (Fisher et al., *Nature* 2019; Kim et al., *Nature* 2019).
+
+    Around steel docks, harbors, or indoor rooms where soft-iron and hard-iron effects
+    nonlinearly warp magnetic azimuth (e.g. ``+25 deg * sin(2*psi)``), the plastic
+    ``W_r_to_epg`` weight matrix learns the inverse distortion online from either:
+    1. A clean intermittent reference cue (``reference_heading_rad``, e.g. sun/sky/visual), or
+    2. Self-supervised rotational consistency with IMU yaw rate ``omega_rad_s`` across turns.
+    """
+
+    def __init__(
+        self,
+        n_wedges: int = 16,
+        n_ring_neurons: int = 32,
+        *,
+        learning_rate: float = 4.0,
+        r_kappa: float = 56.0,
+        prior_strength: float = 0.25,
+        compass: Optional[RingCompass] = None,
+    ) -> None:
+        if n_ring_neurons < 8:
+            raise ValueError("n_ring_neurons must be >= 8")
+        self.n_wedges: int = int(n_wedges)
+        self.n_ring_neurons: int = int(n_ring_neurons)
+        self.learning_rate: float = float(learning_rate)
+        self.r_kappa: float = float(r_kappa)
+
+        self.compass: RingCompass = (
+            compass if compass is not None else RingCompass(n_wedges=self.n_wedges)
+        )
+        if self.compass.n_wedges != self.n_wedges:
+            raise ValueError("compass.n_wedges must match PlasticLandmarkRing.n_wedges")
+
+        self.r_thetas: np.ndarray = -math.pi + (
+            2.0 * math.pi * np.arange(self.n_ring_neurons, dtype=np.float64)
+        ) / self.n_ring_neurons
+        self.epg_thetas: np.ndarray = self.compass.thetas.copy()
+        self._cos_epg: np.ndarray = np.cos(self.epg_thetas)
+        self._sin_epg: np.ndarray = np.sin(self.epg_thetas)
+        self._prev_raw_ang: Optional[float] = None
+
+        # Initialize R -> E-PG synaptic matrix with weak topographic identity prior
+        diff = self.epg_thetas[:, None] - self.r_thetas[None, :]
+        self.weights: np.ndarray = float(prior_strength) * np.cos(diff)
+
+    def encode_r_neurons(self, raw_angle_rad: float) -> np.ndarray:
+        """Compute L2-normalized R-neuron population vector for ``raw_angle_rad``."""
+        act = np.exp(self.r_kappa * (np.cos(self.r_thetas - float(raw_angle_rad)) - 1.0))
+        norm = float(np.linalg.norm(act))
+        return act / norm if norm > 1e-12 else act
+
+    def map_raw_heading(self, raw_mag_heading_rad: float) -> tuple[float, float]:
+        """Map a warped raw magnetic angle through ``W_r_to_epg`` -> ``(corrected_rad, confidence)``."""
+        r_act = self.encode_r_neurons(raw_mag_heading_rad)
+        epg_drive = self.weights @ r_act
+        c1 = (2.0 / self.n_wedges) * float(np.dot(epg_drive, self._cos_epg))
+        s1 = (2.0 / self.n_wedges) * float(np.dot(epg_drive, self._sin_epg))
+        amp = float(math.hypot(c1, s1))
+        if amp <= 1e-9:
+            return float(wrap_angle(raw_mag_heading_rad)), 0.0
+        corrected = float(wrap_angle(math.atan2(s1, c1)))
+        conf = float(np.clip(amp, 0.0, 1.0))
+        return corrected, conf
+
+    def update(
+        self,
+        omega_rad_s: float,
+        dt: float,
+        raw_mag_heading_rad: float,
+        *,
+        reference_heading_rad: Optional[float] = None,
+        learn: bool = True,
+        anchor_gain_scale: float = 0.25,
+    ) -> float:
+        """Advance compass, decode plastic landmark heading, and apply Hebbian/anti-Hebbian learning.
+
+        When ``reference_heading_rad`` is None (self-supervised mode), ``anchor_gain_scale``
+        keeps magnetic pull gentle so accurate short-term P-EN gyro integration sweeps smoothly
+        across soft-iron warps while learning their inverse into ``self.weights``.
+        """
+        raw_ang = float(wrap_angle(raw_mag_heading_rad))
+        if not self.compass.initialized:
+            seed = float(reference_heading_rad) if reference_heading_rad is not None else raw_ang
+            self.compass.reset(seed)
+            heading = self.compass.heading_rad
+        else:
+            corr_mag, map_conf = self.map_raw_heading(raw_ang)
+            eff_mag_conf = (
+                map_conf if reference_heading_rad is None else 0.0
+            ) * float(np.clip(anchor_gain_scale, 0.0, 1.0))
+
+            heading = self.compass.update(
+                omega_rad_s=omega_rad_s,
+                dt=dt,
+                mag_heading_rad=corr_mag if eff_mag_conf > 0.0 else None,
+                sun_heading_rad=reference_heading_rad,
+                mag_confidence=eff_mag_conf,
+                sun_confidence=1.0,
+            )
+
+        if learn and dt > 0.0:
+            r_act = self.encode_r_neurons(raw_ang)
+            target_epg = np.cos(self.epg_thetas - heading)
+            pred_epg = self.weights @ r_act
+            # Movement-gated Hebbian / anti-Hebbian update (uniform exposure in R-neuron space)
+            if self._prev_raw_ang is None:
+                d_raw = abs(float(omega_rad_s)) * dt
+            else:
+                d_raw = abs(float(wrap_angle(raw_ang - self._prev_raw_ang)))
+            self._prev_raw_ang = raw_ang
+            step_rate = min(0.95, self.learning_rate * max(d_raw, 0.05 * dt))
+            self.weights += step_rate * np.outer(target_epg - pred_epg, r_act)
+            np.clip(self.weights, -8.0, 8.0, out=self.weights)
+
+        return heading

neckcompass-1.0.0.dist-info/METADATA

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: neckcompass
+Version: 1.0.0
+Summary: NeckCompass: Drosophila Central Complex ring-attractor compass and GPS-denied path integrator with natural ferromagnetic spike rejection
+Author: Amandeep Singh Bains
+License: MIT
+Project-URL: Homepage, https://github.com/indian-aman/neckcompass
+Project-URL: Repository, https://github.com/indian-aman/neckcompass
+Project-URL: Releases, https://github.com/indian-aman/neckcompass/releases
+Project-URL: Issues, https://github.com/indian-aman/neckcompass/issues
+Project-URL: Documentation, https://github.com/indian-aman/neckcompass#readme
+Keywords: neckcompass,necklink,ring-attractor,central-complex,drosophila,compass,ahrs,magnetometer,imu,path-integration,gps-denied,robotics,usv,auv,esp32
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: matplotlib>=3.7; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# NeckCompass (`neckcompass` v1.0.0)
+
+**Biophysical *Drosophila* Central Complex ring-attractor compass and GPS-denied path integrator with natural ferromagnetic spike rejection — in Python and zero-heap, zero-float ANSI C99 (`316 B` RAM, `~1 us`/step).**
+
+[![PyPI](https://img.shields.io/pypi/v/neckcompass?style=flat-square&logo=pypi&logoColor=white&label=PyPI%20neckcompass&color=3775A9)](https://pypi.org/project/neckcompass/)
+[![Release](https://img.shields.io/badge/release-v1.0.0-0EA5E9?style=flat-square)](https://github.com/indian-aman/neckcompass/releases/tag/v1.0.0)
+[![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/neckcompass/)
+[![ANSI C99](https://img.shields.io/badge/C99-zero--heap%20%7C%20zero--float%20%7C%20316%20B%20RAM-00599C?style=flat-square&logo=c&logoColor=white)](csrc/)
+[![C99 Self-Tests](https://img.shields.io/badge/C99%20Q15%20tests-6%2F6%20passed-10B981?style=flat-square)](csrc/tools/neckcompass_selftest.c)
+[![Pytest](https://img.shields.io/badge/pytest-19%2F19%20passed-10B981?style=flat-square)](tests/test_neckcompass.py)
+[![License: MIT](https://img.shields.io/badge/license-MIT-F59E0B?style=flat-square)](LICENSE)
+
+[**30-Second Quick Start**](#-30-second-quick-start) ·
+[**Plastic Harbor Calibration**](#2-online-soft-iron--harbor-distortion-learning-plasticlandmarkring) ·
+[**Zero-Float ANSI C99 MCU Core**](#3-zero-heap-zero-float-ansi-c99-core-csrc) ·
+[**Honest Benchmarks**](#-honest-empirical-benchmarks-5-seeds--50-hz) ·
+[**When to Use (and When Not To)**](#-when-to-use-neckcompass--and-when-not-to)
+
+</div>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/indian-aman/neckcompass/main/assets/neckcompass_benchmarks.png" alt="NeckCompass v1.0.0 Ring Attractor & Path Integrator Benchmarks" width="100%">
+</p>
+
+---
+
+## Why NeckCompass?
+
+Marine USVs, inspection drones, subsea rovers, and factory AGVs operate around steel ship hulls, sheet-pile docks, high-current motor leads, and buried power cables that inject intermittent **`70°–150°` ferromagnetic heading spikes** lasting `0.5–2.0 s`. Standard linear-Gaussian estimators break down in this regime:
+
+- **Gyro Dead-Reckoning** ignores magnetic anomalies completely, but MEMS gyro bias (`~0.8–1.5°/s`) drifts unboundedly (`50°–100°+` within minutes).
+- **2-State Circular Extended Kalman Filters (`[heading, gyro_bias]`)** are minimum-variance optimal under textbook Gaussian noise, **but** a `120°` ferromagnetic anomaly feeds through the Kalman cross-covariance straight into the **gyro bias state**, causing both massive heading yanks (`45°+` P95) and post-spike bias hangovers.
+
+**NeckCompass** ports the neural navigation circuit of the fruit-fly (*Drosophila melanogaster*) **Central Complex** into a deterministic software and microcontroller library — **Product #3** in the **[NeckLink](https://github.com/indian-aman/necklink)** fruit-fly brain engineering family:
+
+1. **Ellipsoid Body (`E-PG`) Ring Attractor + `Delta7` Inhibition + `P-EN` Shifters (`RingCompass`)**: Maintains a single topological activity bump across `N=16` (or `N=32`) circular wedges with **zero `-π ↔ +π` wrap-around discontinuity** (`< 10⁻¹⁵ rad` harmonic aliasing on even-`N` rings). Asymmetric Left/Right `P-EN` projections integrate IMU yaw rate (`omega_rad_s * dt`), while localized `R-neuron` sensory cues (`mag_heading_rad`, `sun_heading_rad`) undergo cooperative dendritic coincidence gating against the active `E-PG` bump — smoothly anchoring gyro drift inside the attractor basin while naturally shunting **`70°–150°` ferromagnetic spikes** (`10.2×` lower RMSE than 2-State EKF).
+2. **Associative `R-Neuron → E-PG` Synaptic Plasticity (`PlasticLandmarkRing`)**: Movement-gated Hebbian / anti-Hebbian ring weight matrix that learns warped local soft-iron and hard-iron magnetic distortion tables online around steel harbors or indoor rooms — with or without an external sun/visual reference.
+3. **Fan-Shaped Body `CPU4` Path Integrator + `PFL3`/`PFL2` Steering (`FanBodyNavigator`)**: `N=16` push-pull opponent memory columns integrate translational speed along the live `E-PG` compass bump with common-mode cancellation, computing exact `(distance_m, home_bearing_rad)` and `±67.5°` phase-shifted `PFL3` + `180°` `PFL2` motor yaw commands to steer straight home during complete **GPS blackouts** (`0.84 m` miss after a `1,125 m` spiky mission).
+4. **Zero-Heap, Zero-Float ANSI C99 Core (`csrc/`)**: Pure `Q15` / `int32_t` 16-wedge ring attractor + `CPU4`/`PFL3` navigator using **`316 bytes` of struct RAM** (`576 bytes` total including `260 B` Flash LUTs), **zero `malloc`**, **zero floating-point instructions**, and **`~1.0 us` per update** — ready for `$4` `ESP32`, `STM32`, `RP2040`, and flight controllers.
+
+```mermaid
+flowchart LR
+    IMU["IMU Gyro Yaw Rate (omega_rad_s)"] --> PEN["P-EN Left/Right Velocity Shifters"]
+    PEN --> EPG["16-Wedge E-PG Ring Attractor + Delta7 Inhibition"]
+    MAG["Spiky Magnetometer / Sun Azimuth"] --> RN["R2 / R4d Ring Neurons (Plastic W + Basin Gate)"]
+    RN -->|"Coherent cues anchor drift; 70-150 deg spikes shunted"| EPG
+    EPG --> CPU4["16 Opponent CPU4 Memory Columns (+ Speed)"]
+    CPU4 --> PFL3["PFL3 (+/-67.5 deg) + PFL2 (180 deg) Steering"]
+    PFL3 --> HOME["GPS-Denied Homebound Yaw Command"]
+```
+
+---
+
+## ⚡ 30-Second Quick Start
+
+### 1. Python (`pip install neckcompass`)
+
+```bash
+pip install neckcompass
+# Or directly from source:
+pip install git+https://github.com/indian-aman/neckcompass.git
+```
+
+Fuse a biased IMU gyro with a spiky magnetometer and steer home through a complete GPS blackout in 14 lines:
+
+```python
+import math
+from neckcompass import RingCompass, FanBodyNavigator
+
+compass = RingCompass(n_wedges=16, initial_heading_rad=0.0)
+nav = FanBodyNavigator(n_columns=16, compass=compass)
+
+# Outbound step @ 50 Hz (dt = 0.02 s): 125-deg hull spike is rejected automatically!
+heading_rad, dist_m, home_bearing_rad = nav.step_with_compass(
+    omega_rad_s=0.15,
+    speed_m_s=1.5,
+    dt=0.02,
+    mag_heading_rad=math.radians(125.0),  # Transient ferromagnetic spike -> gated out
+)
+
+# During GPS blackout, generate bounded [-0.8, +0.8] rad/s yaw command back to (0, 0):
+yaw_rate_cmd = nav.steering_cmd(max_turn_rate=0.8)
+```
+
+Run the built-in CLI demo or head-to-head quick benchmark from your terminal:
+
+```bash
+neckcompass demo
+neckcompass benchmark-quick
+```
+
+---
+
+### 2. Online Soft-Iron / Harbor Distortion Learning (`PlasticLandmarkRing`)
+
+When operating repeatedly inside a steel marina slip or indoor robot bay with static nonlinear magnetic warp (`+20° sin(ψ) + 16° sin(2ψ)`), `PlasticLandmarkRing` learns the `R-neuron → E-PG` unwarping matrix online:
+
+```python
+from neckcompass import PlasticLandmarkRing
+
+plastic = PlasticLandmarkRing(n_wedges=16, n_ring_neurons=32)
+
+# Self-supervised during normal turns (or pass reference_heading_rad=sun_rad when sky is visible)
+corrected_heading = plastic.update(
+    omega_rad_s=imu_gz,
+    dt=0.02,
+    raw_mag_heading_rad=raw_mag_rad,
+    learn=True,
+)
+unwarped_mag_rad, confidence = plastic.map_raw_heading(raw_mag_rad)
+```
+
+---
+
+### 3. Zero-Heap, Zero-Float ANSI C99 Core (`csrc/`)
+
+Drop [`csrc/neckcompass.h`](csrc/neckcompass.h) and [`csrc/neckcompass.c`](csrc/neckcompass.c) into any `ESP32`, `STM32`, `RP2040`, ArduPilot, or bare-metal firmware project (`-std=c99 -Wall -Wextra -pedantic -Werror`, zero FPU, zero `malloc`):
+
+```bash
+make -C csrc clean all test
+```
+
+```c
+#include "neckcompass.h"
+
+nc_compass_t comp;
+nc_navigator_t nav;
+
+void autopilot_init(void) {
+    nc_compass_init(&comp);
+    nc_compass_reset(&comp, nc_cdeg_to_bam(0));
+    nc_navigator_init(&nav, 1500); /* 1.5 m smooth arrival taper */
+}
+
+/* 50 Hz deterministic fixed-point loop (~1.0 us on desktop, < 8 us on ESP32) */
+int32_t autopilot_step_50hz(int32_t gyro_cdeg_s, int32_t mag_cdeg, int32_t speed_mm_s) {
+    nc_bam_t heading = nc_compass_update(
+        &comp,
+        nc_cdeg_to_bam(gyro_cdeg_s),
+        20u,                           /* dt = 20 ms */
+        nc_cdeg_to_bam(mag_cdeg), 1u, NC_Q15_ONE,
+        0, 0u, 0                       /* optional sun/sky sensor */
+    );
+    nc_navigator_update(&nav, speed_mm_s, 20u, heading);
+    return nc_navigator_steering_cmd(&nav, heading, nc_cdeg_to_bam(4500));
+}
+```
+
+---
+
+## 📊 Honest Empirical Benchmarks (5 Seeds @ `50 Hz`)
+
+Reproduce all numbers and regenerate [`assets/neckcompass_benchmarks.png`](assets/neckcompass_benchmarks.png) + [`results/benchmark_summary.json`](results/benchmark_summary.json) locally:
+
+```bash
+python scripts/benchmark_neckcompass.py
+```
+
+All four estimators receive the **exact same** `50 Hz` sensor streams across 5 seeds (`101–105`): realistic MEMS gyro bias (`~0.9°/s` initial offset + `0.08°/s/√s` random walk + `1.5°/s` white noise) and `3.0°` Gaussian magnetometer noise. The **2-State Circular EKF** is given the exact true clean discrete-time process and measurement noise covariances `(Q, R)` with zero handicap.
+
+### 1. Heading Accuracy: Clean Gaussian Noise vs. `70°–150°` Ferromagnetic Spikes
+
+Mean ± std across 5 seeds (`180 s` trajectories @ `50 Hz`):
+
+| Estimator | **Scenario A: Clean Gaussian RMSE** | **Scenario A: P95** | **Scenario B: Spiky Mag RMSE** | **Scenario B: Spiky Mag P95** | **Scenario B: Max Error** |
+| :--- | :---: | :---: | :---: | :---: | :---: |
+| **`NeckCompass` (`E-PG` 16w)** | `0.43° ± 0.02°` | `0.86° ± 0.03°` | **`1.70° ± 0.18°`** | **`4.27° ± 0.37°`** | **`10.55° ± 1.88°`** |
+| **`2-State Circular EKF`** | **`0.39° ± 0.02°`** *(wins)* | **`0.77° ± 0.03°`** | `17.42° ± 0.93°` | `45.28° ± 2.63°` | `82.53° ± 7.50°` |
+| **`Complementary IMU+Mag`** | `3.64° ± 1.54°` | `5.34° ± 1.80°` | `11.80° ± 0.54°` | `27.77° ± 1.30°` | `47.45° ± 4.87°` |
+| **`Gyro Dead-Reckoning`** | `90.22° ± 32.41°` | `141.70° ± 46.28°` | `84.80° ± 30.74°` | `139.91° ± 53.31°` | `145.98° ± 55.90°` |
+
+### 2. Scenario C: `600 s` Outbound Survey + Blind GPS-Blackout Return (`~1,125 m` Total Path)
+
+A USV / rover executes a `10-minute` (`900 m`) multi-leg survey in complete GPS blackout (`2%` wheel/water-speed noise + biased MEMS gyro + intermittent `70°–150°` ferromagnetic spikes), then autonomously steers back to `(0, 0)`:
+
+| Navigation Stack | **Return-to-Home Miss (`m`)** | **Miss `%` of `1.12 km` Path** | **RAM / State Footprint** | **Step Latency** |
+| :--- | :---: | :---: | :---: | :---: |
+| **`NeckCompass` (C99 `Q15` Core)** | **`0.32 m`** *(158 m selftest)* | **`0.20%`** | **`316 B` RAM (`576 B` w/ LUT)** | **`~1.04 us / step`** |
+| **`NeckCompass` (Python `E-PG + CPU4`)** | **`0.84 ± 0.23 m`** | **`0.07% ± 0.02%`** | `3,143 B` | `171.26 us / step` |
+| **`Complementary IMU+Mag + DR`** | `13.31 ± 3.08 m` | `1.19% ± 0.28%` | `~256 B` | `~6.5 us / step` |
+| **`2-State Circular EKF + DR`** | `14.29 ± 6.95 m` | `1.28% ± 0.63%` | `5,792 B` *(Py)* | `13.58 us / step` *(Py)* |
+| **`Gyro Dead-Reckoning`** | `256.74 ± 52.38 m` | `24.16% ± 5.69%` | `~128 B` | `~2.0 us / step` |
+
+---
+
+## 🎯 When to Use NeckCompass — and When Not To
+
+> [!TIP]
+> **Reach for NeckCompass when:**
+> - **Operating near steel, motors, docks, ship hulls, or power cables**: Intermittent `60°–160°` ferromagnetic spikes yank standard complementary filters and corrupt EKF gyro-bias states; `RingCompass` shunts off-basin anomalies naturally (`1.70°` vs `17.42°` RMSE).
+> - **Surviving GPS blackouts, jamming, or subsea/indoor dropouts**: `FanBodyNavigator` (`CPU4` + `PFL3`/`PFL2`) maintains a bounded, common-mode-cancelled home vector and smooth return controller over `10+ minute` (`> 1 km`) dead-reckoning missions.
+> - **Deploying on tiny FPU-less or ultra-low-power microcontrollers (`$1–$4` MCUs)**: `csrc/neckcompass.c` uses `316 bytes` of RAM, `0` heap allocations, `0` floats, and `~1 us` per step.
+> - **Learning warped harbor or indoor magnetic scenes online**: `PlasticLandmarkRing` unwarps repeatable soft-iron / hard-iron distortions continuously without offline ellipsoid-fitting batch scripts.
+
+> [!NOTE]
+> **Stick with a classical EKF / Factor Graph when:**
+> - **Sensors are clean, pre-calibrated, and strictly Gaussian (e.g. open-air UAV far from iron/high-current leads)**: As shown in Scenario A, a properly tuned 2-State Circular EKF achieves slightly lower steady-state RMSE (`0.39°` vs `NeckCompass` `0.43°`) because linear Kalman filtering is minimum-variance optimal under pure Gaussian noise.
+> - **Pure Python ultra-high-rate (`> 10 kHz`) loops without C bindings**: Scalar 2-State Python EKF runs in `~14 us/step` vs `~171 us/step` for 16-wedge NumPy vector ops (`~5.8 kHz`). For `> 5 kHz` embedded or C/C++ loops, compile [`csrc/neckcompass.c`](csrc/neckcompass.c) (`~1.0 us/step`).
+> - **Full 6-DOF visual-inertial SLAM (`SE(3)` pose graphs + loop closure)**: `NeckCompass` is a lightweight 2D/yaw heading & home-vector module (`SO(2)` + `R²`), not a replacement for full 3D LiDAR/camera SLAM when rich 3D visual features and GPU/CPU compute are available.
+
+---
+
+## 🗂️ Repository Layout
+
+| Path | Contents |
+| :--- | :--- |
+| [`neckcompass/ring_attractor.py`](neckcompass/ring_attractor.py) | `RingCompass` (`N=16`/`32` `E-PG` ring attractor + `P-EN` shifters + multi-cue basin gating) & `PlasticLandmarkRing` (`R-neuron → E-PG` Hebbian/anti-Hebbian distortion learner) |
+| [`neckcompass/path_integrator.py`](neckcompass/path_integrator.py) | `FanBodyNavigator` (`N=16` opponent `CPU4` vector memory + `PFL3`/`PFL2` GPS-denied homebound steering) |
+| [`neckcompass/cli.py`](neckcompass/cli.py) | `neckcompass` CLI (`neckcompass demo`, `neckcompass benchmark-quick`) |
+| [`csrc/`](csrc/) | Zero-heap, zero-float ANSI C99 fixed-point `Q15` core (`neckcompass.h`, `neckcompass.c`, `Makefile`, and `6/6` `neckcompass_selftest.c`) |
+| [`scripts/benchmark_neckcompass.py`](scripts/benchmark_neckcompass.py) | Reproducible 5-seed empirical benchmark & 3-panel hero chart generator |
+| [`results/benchmark_summary.json`](results/benchmark_summary.json) | Exact 5-seed benchmark metrics and C99/Python latency & memory measurements |
+| [`tests/test_neckcompass.py`](tests/test_neckcompass.py) | `19`-test `pytest` suite covering wrap-around continuity, spike rejection, soft-iron plasticity, GPS-denied return, and CLI |
+
+---
+
+## 📚 Scientific Foundations
+
+1. **Seelig, J. D. & Jayaraman, V.** (2015). Neural dynamics for landmark orientation and angular path integration. *Nature*, 521, 186–191.
+2. **Stone, T. et al.** (2017). An anatomically constrained model for path integration in the bee brain. *Current Biology*, 27(20), 3069–3085.
+3. **Turner-Evans, D. et al.** (2017). Angular velocity integration in a fly heading circuit. *eLife*, 6, e23496.
+4. **Fisher, Y. E., Lu, J., D'Alessandro, I. & Wilson, R. I.** (2019). Sensorimotor experience remaps visual input to a heading network. *Nature*, 576, 121–125.
+5. **Kim, S. S., Hermundstad, A. M., Romani, S., Abbott, L. F. & Jayaraman, V.** (2019). Generation of stable heading representations in diverse visual scenes. *Nature*, 576, 126–131.
+6. **Lyu, C., Abbott, L. F. & Maimon, G.** (2022). Building an allocentric travelling direction signal via vector computation. *Nature*, 601, 92–97.
+7. **Westeinde, E. A. et al.** (2024). Transforming a head direction signal into a goal-oriented steering command. *Nature*, 626, 819–826.
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE). Copyright (c) 2026 Amandeep Singh Bains.

neckcompass-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+neckcompass/__init__.py,sha256=5yZy-r_Hb_UHwcQiZlKUMWsT2Z5kS3RAM4zlgOqqwQE,481
+neckcompass/__main__.py,sha256=kBwyrlDlO5l5tZ2ubsXpCgOgZ09awszyXUyTo7JzieQ,127
+neckcompass/cli.py,sha256=243Psgro8D0j15JFsn8uFx2XrsDiVMIJAH2R0EOmGMA,11767
+neckcompass/path_integrator.py,sha256=y5ynWIgHDBicqj2urfh5OulJlEgcAMT7zOpulxE2_Ck,9946
+neckcompass/ring_attractor.py,sha256=TPfg3T-5Flb9oYIc8UG-MRHGxGLQEuJRE62IeZ_zawo,20396
+neckcompass-1.0.0.dist-info/licenses/LICENSE,sha256=NSiGDGV_78IuijtD5CKRPFs9pxFunuXeu5leb0Y7_TE,1077
+neckcompass-1.0.0.dist-info/METADATA,sha256=i1asAqvkdi1h0Ik6sjjuMrYKEXkWzdPaRu5nsASi-5A,17637
+neckcompass-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+neckcompass-1.0.0.dist-info/entry_points.txt,sha256=MLxrRlqc7EVHZmmrUPzTRnYHonOVz2amY91M7_3kuG0,53
+neckcompass-1.0.0.dist-info/top_level.txt,sha256=hEcfbJr-svkIC2be1Pb3u2x-SX3cb9ZxNWtsas6F_vs,12
+neckcompass-1.0.0.dist-info/RECORD,,

neckcompass-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

neckcompass-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+neckcompass = neckcompass.cli:main

neckcompass-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amandeep Singh Bains
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neckcompass-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+neckcompass