necklink-cns 2.0.0__py3-none-any.whl

necklink_cns/__init__.py

@@ -0,0 +1,41 @@
+"""
+NeckLink CNS (`necklink_cns` v2.0.0) — Unified Adult Drosophila Whole-CNS Edge Autonomy Stack.
+"""
+
+from .cns import CNSOutputs, NeckLinkCNS
+from .connectome import BANC_V888_PRIORS, ConnectomeArbitrator, DescendingState
+from .mavlink import (
+    MavFrame,
+    MavHeartbeat,
+    MavLink2Codec,
+    MavLink2Parser,
+    MavLinkUdpBridge,
+    MavManualControl,
+    MavObstacleDistance,
+    MavScaledImu,
+    MavStatusText,
+)
+from .ros2_node import NeckLinkROS2Adapter, TwistCommand, create_ros2_node
+
+__version__ = "2.0.0"
+
+__all__ = [
+    "__version__",
+    "BANC_V888_PRIORS",
+    "CNSOutputs",
+    "ConnectomeArbitrator",
+    "DescendingState",
+    "MavFrame",
+    "MavHeartbeat",
+    "MavLink2Codec",
+    "MavLink2Parser",
+    "MavLinkUdpBridge",
+    "MavManualControl",
+    "MavObstacleDistance",
+    "MavScaledImu",
+    "MavStatusText",
+    "NeckLinkCNS",
+    "NeckLinkROS2Adapter",
+    "TwistCommand",
+    "create_ros2_node",
+]

necklink_cns/banc_v888_priors.json

@@ -0,0 +1,215 @@
+{
+  "dataset": "Female Adult Drosophila Whole-CNS Connectome (BANC v888)",
+  "total_neurons": 157789,
+  "total_synapses": 23553107,
+  "total_directed_edges": 3036600,
+  "male_cns_v1_neurons": 167565,
+  "cell_counts": {
+    "EPG": 50,
+    "PEN": 42,
+    "Delta7": 40,
+    "PFL3": 25,
+    "PFL2": 12,
+    "T4": 4196,
+    "T5": 4682,
+    "LPLC2": 181,
+    "LC4": 114,
+    "LPLC1": 124,
+    "DNp01": 2,
+    "DNa01": 2,
+    "DNa02": 2,
+    "MDN": 4,
+    "DNp09": 2,
+    "APL": 2,
+    "ORN": 3006,
+    "Chordotonal": 2132,
+    "ALPN": 699,
+    "ALLN": 429,
+    "KC_all": 4553,
+    "KC_gamma": 2057,
+    "KC_alphabeta": 1943,
+    "KC_apbp": 122,
+    "MBON_all": 104,
+    "DAN_all": 301,
+    "DN_all": 1316,
+    "AN_all": 1849,
+    "MN_all": 805,
+    "MN_leg": 393,
+    "MN_wing": 62,
+    "MN_haltere": 25
+  },
+  "pathways": {
+    "T4->LPLC2": {
+      "edges": 897,
+      "synapses": 3330
+    },
+    "T5->LPLC2": {
+      "edges": 1748,
+      "synapses": 6586
+    },
+    "T4->LC4": {
+      "edges": 31,
+      "synapses": 173
+    },
+    "T5->LC4": {
+      "edges": 91,
+      "synapses": 305
+    },
+    "T4->LPLC1": {
+      "edges": 815,
+      "synapses": 3205
+    },
+    "T5->LPLC1": {
+      "edges": 1134,
+      "synapses": 4535
+    },
+    "LPLC2->DNp01": {
+      "edges": 84,
+      "synapses": 403
+    },
+    "LC4->DNp01": {
+      "edges": 21,
+      "synapses": 71
+    },
+    "LPLC2->DN_all": {
+      "edges": 529,
+      "synapses": 2896
+    },
+    "LC4->DN_all": {
+      "edges": 226,
+      "synapses": 1108
+    },
+    "LPLC1->DN_all": {
+      "edges": 182,
+      "synapses": 945
+    },
+    "EPG->Delta7": {
+      "edges": 901,
+      "synapses": 6998
+    },
+    "Delta7->EPG": {
+      "edges": 336,
+      "synapses": 4646
+    },
+    "EPG->PEN": {
+      "edges": 491,
+      "synapses": 6151
+    },
+    "PEN->EPG": {
+      "edges": 521,
+      "synapses": 7998
+    },
+    "EPG->PFL3": {
+      "edges": 91,
+      "synapses": 1442
+    },
+    "Delta7->PFL3": {
+      "edges": 249,
+      "synapses": 6066
+    },
+    "EPG->PFL2": {
+      "edges": 57,
+      "synapses": 1071
+    },
+    "Delta7->PFL2": {
+      "edges": 132,
+      "synapses": 3712
+    },
+    "PFL3->DNa02": {
+      "edges": 23,
+      "synapses": 259
+    },
+    "PFL3->DN_all": {
+      "edges": 169,
+      "synapses": 1772
+    },
+    "PFL2->DN_all": {
+      "edges": 44,
+      "synapses": 1047
+    },
+    "ORN->ALPN": {
+      "edges": 13678,
+      "synapses": 190238
+    },
+    "ORN->ALLN": {
+      "edges": 19599,
+      "synapses": 107521
+    },
+    "ALLN->ALPN": {
+      "edges": 17450,
+      "synapses": 170732
+    },
+    "ALPN->KC_all": {
+      "edges": 15844,
+      "synapses": 159648
+    },
+    "KC_all->APL": {
+      "edges": 3290,
+      "synapses": 18468
+    },
+    "APL->KC_all": {
+      "edges": 3311,
+      "synapses": 21486
+    },
+    "KC_all->MBON_all": {
+      "edges": 3121,
+      "synapses": 12544
+    },
+    "KC_gamma->MBON_all": {
+      "edges": 1393,
+      "synapses": 5645
+    },
+    "KC_alphabeta->MBON_all": {
+      "edges": 1533,
+      "synapses": 6110
+    },
+    "DAN_all->KC_all": {
+      "edges": 89,
+      "synapses": 304
+    },
+    "DAN_all->MBON_all": {
+      "edges": 115,
+      "synapses": 817
+    },
+    "MBON_all->DN_all": {
+      "edges": 149,
+      "synapses": 2008
+    },
+    "DNp01->MN_all": {
+      "edges": 6,
+      "synapses": 28
+    },
+    "DNa02->MN_all": {
+      "edges": 56,
+      "synapses": 775
+    },
+    "DNa01->MN_all": {
+      "edges": 38,
+      "synapses": 354
+    },
+    "MDN->MN_all": {
+      "edges": 0,
+      "synapses": 0
+    },
+    "DN_all->MN_all": {
+      "edges": 9068,
+      "synapses": 143565
+    }
+  },
+  "derived_biophysical_ratios": {
+    "optic_t5_to_t4_lplc2_off_dominance": 1.9778,
+    "optic_lplc2_dn_share": 0.5852,
+    "optic_lc4_dn_share": 0.2239,
+    "optic_lplc1_dn_share": 0.1909,
+    "cx_pfl2_to_pfl3_antigoal_ratio": 0.48,
+    "cx_delta7_to_epg_inhibition_ratio": 0.6639,
+    "mb_alpn_to_kc_claws_mean": 3.92,
+    "mb_alpn_to_kc_claws_median": 4.0,
+    "mb_kc_gamma_fast_fraction": 0.5142,
+    "mb_kc_alphabeta_ltm_fraction": 0.4858,
+    "neck_an_to_dn_ratio": 1.405,
+    "neck_bottleneck_fraction": 0.02006,
+    "cns_excitatory_fraction": 0.669,
+    "cns_inhibitory_fraction": 0.331
+  }
+}

necklink_cns/cli.py

@@ -0,0 +1,74 @@
+"""CLI entrypoint for `necklink-cns` (`v2.0.0`)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import numpy as np
+
+from . import __version__
+from .cns import NeckLinkCNS
+from .connectome import BANC_V888_PRIORS
+
+
+def run_demo() -> dict:
+    cns = NeckLinkCNS(vehicle="usv_t200", grid_size=32)
+    yy, xx = np.mgrid[0:32, 0:32]
+    bg = 150.0 + 15.0 * np.sin(xx * 0.4) * np.cos(yy * 0.4)
+
+    out = None
+    dodged = False
+    for step in range(24):
+        frame = bg.copy()
+        if step >= 6:
+            hw = 1 + (step - 6) // 3
+            frame[:, max(0, 9 - hw) : min(32, 9 + hw + 1)] = 10.0  # Left pole looming
+        fb = cns._last_cmds.copy()
+        if step >= 8:
+            fb[1] *= 0.10  # 90% weed-fouled thruster #1
+        out = cns.step(
+            dt=0.02,
+            speed_m_s=1.5,
+            gyro_xyz=np.array([0.05, -0.03, 0.0]),
+            accel_xyz=np.array([0.8, -0.6, 9.75]),
+            mag_xyz=np.array([0.42, 0.0, 0.90]),
+            camera_frame=frame,
+            feedback_thrust=fb,
+        )
+        if out.descending.behavior_mode in ("DODGE_LOOM", "MOONWALK_REVERSE"):
+            dodged = True
+
+    assert out is not None
+    return {
+        "version": __version__,
+        "banc_v888_neurons": BANC_V888_PRIORS["total_neurons"],
+        "thin_pole_dodged": dodged,
+        "final_mode": out.descending.behavior_mode,
+        "fouled_thruster1_health": round(float(out.actuator_health[1]), 3),
+        "cervical_4b_hex": "0x" + out.cervical_wire_4b.hex().upper(),
+        "mavlink_v2_bytes": len(out.mavlink_manual_pkt),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="necklink-cns", description="NeckLink Unified Whole-CNS Autonomy CLI")
+    parser.add_argument("--version", action="store_true", help="Print package version")
+    sub = parser.add_subparsers(dest="cmd")
+    sub.add_parser("demo", help="Run closed-loop 4-organ + MAVLink v2 survival demo")
+    sub.add_parser("priors", help="Print empirical BANC v888 connectome priors")
+
+    args = parser.parse_args(argv)
+    if args.version:
+        print(f"necklink-cns {__version__}")
+        return 0
+    if args.cmd == "priors":
+        print(json.dumps(BANC_V888_PRIORS["derived_biophysical_ratios"], indent=2))
+        return 0
+    res = run_demo()
+    print(json.dumps(res, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

necklink_cns/cns.py

@@ -0,0 +1,278 @@
+"""
+Unified Adult Drosophila Whole-CNS Python Controller (`necklink_cns.cns`).
+
+Integrates all four `v2.0.0` organs (`NeckSight`, `NeckCompass`, `NeckSense`, `NeckCord`)
+with empirical `BANC v888` descending action selection, 4-byte CRC-4 cervical framing,
+and wire-valid `MAVLink v2` packet generation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import neckcompass
+import neckcord
+import necksense
+import necksight
+import numpy as np
+
+from .connectome import BANC_V888_PRIORS, ConnectomeArbitrator, DescendingState
+from .mavlink import MavLink2Codec, MavManualControl
+
+
+@dataclass
+class CNSOutputs:
+    """Complete per-tick readout across all four CNS organs + cervical bottleneck."""
+
+    heading_rad: float
+    home_distance_m: float
+    home_bearing_rad: float
+    loom_score: float
+    thin_loom_score: float
+    loom_triggered: bool
+    avoid_x: float
+    avoid_y: float
+    novelty_score: float
+    whiff_rate: float
+    vib_novelty_score: float
+    predicted_class: Optional[int]
+    descending: DescendingState
+    cervical_wire_4b: bytes
+    actuator_commands: np.ndarray
+    actuator_health: np.ndarray
+    cord_min_health: float
+    mavlink_manual_pkt: bytes
+
+
+class NeckLinkCNS:
+    """
+    Closed-loop 4-organ *Drosophila* Whole-CNS controller supporting:
+      - `vehicle="usv_t200"` (4-thruster asymmetric BlueRobotics T200 USV)
+      - `vehicle="hexacopter"` (6-rotor unidirectional `[0, u_max]` hexacopter)
+      - `vehicle="octocopter"` (8-rotor unidirectional `[0, u_max]` octocopter)
+      - `vehicle="hexapod"` (6-limb, 18-servo legged hexapod with 3-DOF IK)
+    """
+
+    def __init__(
+        self,
+        vehicle: str = "usv_t200",
+        grid_size: int = 32,
+        n_chem_channels: int = 8,
+        enable_plastic_mag: bool = False,
+        seed: int = 42,
+    ) -> None:
+        self.vehicle = vehicle
+        self.grid_size = int(grid_size)
+        self.enable_plastic_mag = bool(enable_plastic_mag)
+
+        # 1. Optic Lobe (NeckSight v2.0.0)
+        self.sight = necksight.NeckSightPipeline(
+            grid_size=self.grid_size,
+            threshold=0.045,
+            enable_lc4_bar=True,
+        )
+
+        # 2. Central Complex (NeckCompass v2.0.0)
+        self.compass = neckcompass.RingCompass(n_wedges=16, initial_heading_rad=0.0)
+        self.plastic_compass = neckcompass.PlasticLandmarkRing(n_wedges=16) if enable_plastic_mag else None
+        self.navigator = neckcompass.FanBodyNavigator(n_columns=16, compass=self.compass)
+
+        # 3. Antennal Lobe, Chordotonal Organ & Mushroom Body (NeckSense v2.0.0)
+        self.vib_fe = necksense.VibrationFrontEnd()
+        self.chem_nov = necksense.MushroomNoveltyDetector(
+            n_inputs=n_chem_channels,
+            antennal=True,
+            stateful_antennal=True,
+            n_kc=512,
+            seed=seed,
+        )
+        self.vib_nov = necksense.MushroomNoveltyDetector(
+            n_inputs=necksense.NS_VIB_CHANNELS,
+            antennal=True,
+            stateful_antennal=False,
+            n_kc=512,
+            seed=seed + 1,
+        )
+        self.chem_clf = necksense.MushroomValenceClassifier(
+            n_inputs=n_chem_channels,
+            antennal=True,
+            stateful_antennal=False,
+            n_kc=512,
+            ltm_alpha_beta=True,
+            seed=seed + 2,
+        )
+        self._has_learned_classes = False
+
+        # 4. Descending Arbitrator & Ventral Nerve Cord (NeckCord v2.0.0)
+        self.arbitrator = ConnectomeArbitrator()
+        if vehicle == "hexacopter":
+            self.cord = neckcord.ShuntingThrusterCord.multicopter_hex_6()
+        elif vehicle == "octocopter":
+            self.cord = neckcord.ShuntingThrusterCord.multicopter_octo_8()
+        else:
+            self.cord = neckcord.ShuntingThrusterCord.usv_t200_vectored_4()
+
+        self.esc_obs = neckcord.ESCObserver(
+            n_actuators=self.cord.n_actuators,
+            u_nom=self.cord.u_max,
+            rpm_max=9000.0,
+        )
+        self.cpg = neckcord.SegmentalCPGCord(adapt_to_damage=True)
+        self.mav = MavLink2Codec(sysid=42, compid=191)
+        self._seq = 0
+        self._last_cmds = np.zeros(self.cord.n_actuators, dtype=np.float64)
+
+    def learn_chemical(self, vec: np.ndarray, class_id: int, consolidate: bool = True) -> None:
+        self.chem_clf.learn(np.asarray(vec, dtype=np.float64), int(class_id))
+        if consolidate:
+            self.chem_clf.consolidate()
+        self._has_learned_classes = True
+
+    def step(
+        self,
+        *,
+        dt: float = 0.02,
+        speed_m_s: float = 1.0,
+        cruise_speed: float = 0.65,
+        return_home: bool = True,
+        gyro_xyz: Optional[np.ndarray] = None,
+        accel_xyz: Optional[np.ndarray] = None,
+        mag_xyz: Optional[np.ndarray] = None,
+        camera_frame: Optional[np.ndarray] = None,
+        chemical_vec: Optional[np.ndarray] = None,
+        vibration_window: Optional[np.ndarray] = None,
+        feedback_thrust: Optional[np.ndarray] = None,
+        esc_rpm: Optional[np.ndarray] = None,
+        esc_current_a: Optional[np.ndarray] = None,
+    ) -> CNSOutputs:
+        g = np.zeros(3, dtype=np.float64) if gyro_xyz is None else np.asarray(gyro_xyz, dtype=np.float64).reshape(3)
+        a = np.array([0.0, 0.0, 9.81], dtype=np.float64) if accel_xyz is None else np.asarray(accel_xyz, dtype=np.float64).reshape(3)
+
+        # 1. Central Complex 9-DOF Tilt-Compensated Heading + CPU4 Homing
+        if mag_xyz is not None:
+            m = np.asarray(mag_xyz, dtype=np.float64).reshape(3)
+            hdg, dist_m, home_brg = self.navigator.step_with_compass_9dof(
+                float(g[0]), float(g[1]), float(g[2]),
+                float(a[0]), float(a[1]), float(a[2]),
+                float(m[0]), float(m[1]), float(m[2]),
+                speed_m_s=float(speed_m_s),
+                dt=float(dt),
+            )
+        else:
+            hdg, dist_m, home_brg = self.navigator.step_with_compass(
+                omega_rad_s=float(g[2]),
+                speed_m_s=float(speed_m_s),
+                dt=float(dt),
+            )
+
+        cx_turn = float(self.navigator.steering_cmd(max_turn_rate=1.0)) if return_home else 0.0
+        hdg_err = float(neckcompass.wrap_angle(home_brg - hdg)) if return_home else 0.0
+
+        # 2. Optic Lobe 3-DOF Derotation + LPLC2 / LC4 Looming
+        loom_score = 0.0
+        bar_score = 0.0
+        loom_trig = False
+        avoid_x = 0.0
+        avoid_y = 0.0
+        focus_x_norm = 0.0
+        if camera_frame is not None:
+            ego = necksight.imu_to_ego_motion(
+                yaw_rate_rad_s=float(g[2]),
+                pitch_rate_rad_s=float(g[1]),
+                roll_rate_rad_s=float(g[0]),
+                dt=float(dt),
+                grid_width=self.grid_size,
+            )
+            trig = self.sight.step(np.asarray(camera_frame), dt=float(dt), ego_shift_px=ego)
+            loom_score = float(trig.looming_score)
+            bar_score = float(trig.bar_score)
+            loom_trig = bool(trig.triggered)
+            avoid_x = float(trig.avoid_x)
+            avoid_y = float(trig.avoid_y)
+            # Note: in ConnectomeArbitrator, focus_x < 0 => obstacle on left => evade right (avoid_x > 0)
+            focus_x_norm = -avoid_x if abs(avoid_x) > 1e-3 else (float(trig.focus_xy[0]) / max(1.0, self.grid_size - 1.0)) * 2.0 - 1.0
+
+        # 3. Antennal Lobe, Chordotonal Vibration & Mushroom Body
+        nov_score = 0.0
+        whiff_rate = 0.0
+        pred_cls: Optional[int] = None
+        if chemical_vec is not None:
+            cvec = np.asarray(chemical_vec, dtype=np.float64).ravel()
+            nov_score = float(self.chem_nov.update_and_score(cvec))
+            if self.chem_nov.antennal is not None:
+                whiff_rate = float(getattr(self.chem_nov.antennal, "whiff_rate", 0.0))
+            if self._has_learned_classes:
+                pred_cls = int(self.chem_clf.predict(cvec))
+
+        vib_score = 0.0
+        if vibration_window is not None:
+            v_feat = self.vib_fe.extract(np.asarray(vibration_window, dtype=np.float64))
+            vib_score = float(self.vib_nov.update_and_score(v_feat))
+
+        # 4. BANC v888 Descending Neck Bottleneck Arbitration
+        min_h = float(np.min(self.cord.health))
+        desc = self.arbitrator.arbitrate(
+            cruise_speed=cruise_speed,
+            cx_turn_cmd=cx_turn,
+            heading_err_rad=hdg_err,
+            loom_score=loom_score,
+            thin_loom_score=bar_score,
+            loom_focus_x=focus_x_norm,
+            mb_novelty=nov_score,
+            vib_fault_score=vib_score,
+            cord_min_health=min_h,
+            dt=dt,
+        )
+
+        dframe = neckcord.DescendingFrame(
+            drive_fwd=desc.drive_fwd,
+            turn_yaw=desc.turn_yaw,
+            strafe_lat=desc.strafe_lat,
+            gait_mode=int(neckcord.GaitMode.AUTO),
+            freeze_reflex=desc.freeze_reflex,
+            seq=self._seq & 0x03,
+        )
+        self._seq += 1
+        wire_4b = neckcord.encode_descending_4b(dframe)
+
+        # 5. Ventral Nerve Cord Allocation / ESC Proprioception
+        fb = feedback_thrust
+        if fb is None and esc_rpm is not None and esc_current_a is not None:
+            esc_res = self.esc_obs.update(self._last_cmds, esc_rpm, esc_current_a, dt=dt)
+            fb = esc_res.estimated_thrust
+
+        alloc = self.cord.step(wire_4b, feedback_thrust=fb, dt=dt)
+        self._last_cmds = alloc.commands.copy()
+
+        mav_pkt = self.mav.encode_manual_control(
+            MavManualControl(
+                x=int(round(desc.drive_fwd * 1000.0)),
+                y=int(round(desc.strafe_lat * 1000.0)),
+                z=500,
+                r=int(round(desc.turn_yaw * 1000.0)),
+                buttons=(1 if loom_trig else 0),
+                target=1,
+            )
+        )
+
+        return CNSOutputs(
+            heading_rad=float(hdg),
+            home_distance_m=float(dist_m),
+            home_bearing_rad=float(home_brg),
+            loom_score=loom_score,
+            thin_loom_score=bar_score,
+            loom_triggered=loom_trig,
+            avoid_x=avoid_x,
+            avoid_y=avoid_y,
+            novelty_score=nov_score,
+            whiff_rate=whiff_rate,
+            vib_novelty_score=vib_score,
+            predicted_class=pred_cls,
+            descending=desc,
+            cervical_wire_4b=wire_4b,
+            actuator_commands=alloc.commands,
+            actuator_health=alloc.health,
+            cord_min_health=float(np.min(alloc.health)),
+            mavlink_manual_pkt=mav_pkt,
+        )