Skulitom/ganglion-haltere-cursor

Ganglion — cursor readouts on a frozen connectome

Two cursor-control checkpoints built on Haltere's frozen, flight-trained 30,000-neuron recurrent network. A learned linear readout maps motor-neuron activity to two-dimensional velocity. It is fitted by ridge regression to a proportional-controller teacher on synthetic episodes, then refined with DAgger.

The supervised system includes a deterministic controller. Ganglion accepts the learned proposal only when it satisfies its control envelope; otherwise the reference controller acts. Reported supervised results describe that combined system. Neither checkpoint has demonstrated a standalone advantage over the reference.

Use v6 for the documented supervised configuration, or v3b to study stronger standalone settling. Use the new *-portable.pt copies for a fresh setup: the original checkpoint files contain a machine-specific graph path. The portable files preserve all parameter tensors and training metadata, changing only the two graph-path fields.

Code · Base model · Quickstart · Evaluation · Files and reports

Choose a checkpoint

Checkpoint	Configuration	Interpretation
cursor-readout-v6-portable.pt	Sensory adapter 5, goal scale 0.1, all 3,913 selected motor neurons, three DAgger rounds	Recommended for reproducing the supervised configuration. Standalone static-target success: 0/32.
cursor-readout-v3b-portable.pt	Sensory adapter 3, all selected motor neurons, one further DAgger round	Standalone static-target success: 19/32. Under supervision: 32/32.
cursor-readout-v6.pt, cursor-readout-v3b.pt	Original exports	Retained unchanged so the historical reports' checkpoint hashes remain verifiable.
mlp-baseline-v6.pt, mlp-baseline-v3b.pt	Corresponding cursor-suite MLP baselines	Use the baseline matching the checkpoint's sensory adapter and goal scale. These are not Haltere's flight MLP.

The model filename's version and the sensory-adapter version are separate identifiers. All performance claims below come from one Windows 11 / RTX 4090 setup; they are not hardware-independent guarantees of 100 Hz operation.

Quickstart

These commands use Windows PowerShell, Python 3.13 and PyTorch 2.11.0 with CUDA 12.8. Install uv and Git first. An NVIDIA GPU with a compatible driver is required: both HaltereCursor and the full suite reject a CPU-only setup. This quickstart loads models and runs synthetic evaluations; it does not start desktop control.

mkdir ganglion-cursor-demo
cd ganglion-cursor-demo
uv venv --python 3.13 .venv
uv pip install --python .venv/Scripts/python.exe torch==2.11.0 --index-url https://download.pytorch.org/whl/cu128
uv pip install --python .venv/Scripts/python.exe "haltere @ git+https://github.com/skulitom/haltere@94c3e53c12ae0a1aa4cf9cdc6657d08d652d9829" "ganglion @ git+https://github.com/skulitom/Ganglion@7e5bcaa333931fc1b4b33376b70d11cd3b37aaf3" huggingface_hub
.venv/Scripts/python.exe -c "from huggingface_hub import hf_hub_download; from shutil import copyfile; copyfile(hf_hub_download('Skulitom/ganglion-haltere-cursor', 'download_assets.py'), 'download_assets.py')"
.venv/Scripts/python.exe download_assets.py
.venv/Scripts/python.exe -c "from ganglion.brain.haltere_cursor import HaltereCursor; m = HaltereCursor('artifacts/cursor-readout-v6-portable.pt'); print(m.metadata['neurons'], m.metadata['adapter_version'], m.metadata['device'])"

The load check should report 30000 neurons, adapter 5 and a CUDA device. It is an installation check, not a performance evaluation. The helper reads config.json, resolves one Hub revision, verifies SHA-256 hashes and produces:

ganglion-cursor-demo/
  artifacts/cursor-readout-v6-portable.pt
  artifacts/mlp-baseline-v6.pt
  data/built/flight.npz
  data/built/flight.nodes.parquet
  data/built/flight.meta.json

The graph is downloaded from a pinned revision of Skulitom/haltere. Run the following commands from the bundle root. The pinned code versions are versions checked for loading/evaluation compatibility, not recovered training commits.

Run the synthetic suite

.venv/Scripts/python.exe -m ganglion.train.suite --checkpoint artifacts/cursor-readout-v6-portable.pt --mlp artifacts/mlp-baseline-v6.pt --out runs/suite-v6 --steps 2000 --seconds 900 --max-gpu-temp 65

This evaluates the reference, MLP, standalone connectome and supervised connectome on four synthetic tasks. It writes report.json and table.md under the output directory, which must not already exist. The time and temperature limits can stop the run early; choose a new output directory for a rerun. Measurements can vary across hardware and software versions.

To load and evaluate v3b instead:

.venv/Scripts/python.exe download_assets.py --checkpoint cursor-readout-v3b-portable.pt
.venv/Scripts/python.exe -m ganglion.train.suite --checkpoint artifacts/cursor-readout-v3b-portable.pt --mlp artifacts/mlp-baseline-v3b.pt --out runs/suite-v3b --steps 2000 --seconds 900 --max-gpu-temp 65

For live application integration, follow the Ganglion runtime documentation. Loading a readout does not give it independent authority to control an application.

What is learned

The connectome core is frozen. Ridge regression fits a motor readout on synthetic cursor episodes with varying delay, gain and speed, and DAgger adds examples from the student's own rollouts. The runtime encodes the goal error; v6 uses sensory adapter 5 and goal scale 0.1. The readout proposes a velocity in units of the intent's speed. The supervising envelope checks the proposal and uses the deterministic reference for rejected ticks.

The Hub's reinforcement-learning task category is broad: this release's actual learning procedure is imitation, ridge regression and DAgger, not a claim that the core was trained by a reward-based RL algorithm.

Evaluation

The following values are transcribed from the original v6 suite report and v3b suite report. “Accepted” is the fraction of ticks on which the learned proposal was accepted by the envelope. It is a diagnostic of controller participation, not a success rate or evidence of model advantage.

Checkpoint	Task	Standalone success	Supervised success	Accepted model proposals
v6	settle	0/32	32/32	94.3%
v6	jump	2/256	256/256	80.1%
v6	pursuit	2/32	31/32	50.9%
v6	camera	2/32	32/32	41.7%
v3b	settle	19/32	32/32	98.1%
v3b	jump	106/256	241/256	93.9%
v3b	pursuit	10/32	24/32	93.9%
v3b	camera	1/32	18/32	81.0%

For static settling, success requires remaining within 6 pixels through the end of the episode for at least the final 50 ticks (0.5 s). The separate settled_episodes field counts any terminal interval within tolerance, including shorter intervals. This is why the v6 report can have seven such intervals while its success count is zero. Jump success counts individual reaches; the other rows count episodes.

In the original supervised suite, v6's median static settling time is 335 ms, pursuit error 5.1 px and camera error 3.7 px; v3b's median static settling time is 375 ms. These results include the supervisor's contribution.

Release validation — 19 September 2026

A separate environment with Python 3.13.2 and PyTorch 2.11.0+cu128 successfully downloaded and loaded both portable checkpoints. The full 2,000-tick v6 suite completed using the pinned source revisions and published baseline on an RTX 4090. Supervised success was 32/32 for settling, 255/256 for jumps, 31/32 for pursuit and 32/32 for camera tracking. The historical jump result above was 256/256. Some other numerical details also differ; this validates the setup path, not exact numerical reproduction of every historical result.

The new validation report records these results, the portable checkpoint and baseline hashes, the source revisions and the environment. The historical reports are retained unchanged. No live Half-Life or Liftoff run was repeated for this release.

Live comparisons and caveats

• Under supervision, the reported live Half-Life tests did not detect a statistically significant difference between v6 and the reference controller on the measured outcomes. These tests do not establish equivalence. With both sides' steps limited in length to the same 1,200 px/s (42 model trials against 45 of the reference, one grunt, alternating blocks in two sessions): first shot 0.94 against 1.14 s at the median (p 0.28), fired on 61% against 68% of align intents (p 0.08 on per-trial shares), tracking error 152 against 161 px (p 0.70). An earlier result here (fewer intents fired, 58% against 75%) was withdrawn: repeated, it reversed, the reference alone moved from 75% to 60% between sessions, and the reference had been allowed up to 41% more speed than the model by a per-axis step clamp.
• Alone, no checkpoint here beats the reference. v3b meets the static-target success criterion in 19/32 episodes; v6 meets it in 0/32. A linear readout of this network can hold speed or stop, not both: the network answers a reversal of the goal direction in 60 to 70 ms and its state after a fast approach is not linearly distinguishable from its state during it.
• Every live trial before 15:00 on 2026-09-18 ran with a stray virtual controller holding a move-backward input in the game; the comparisons between conditions stand, the absolute figures describe a fight fought against a wall.

See TRAINING.md and HALFLIFE.md for the experiment details. This is experimental control research; the findings do not establish a general advantage over simpler controllers or transfer to arbitrary applications.

Provenance and portability

The flight-trained base is Haltere ftPath2_best.pt. The original cursor checkpoints and report-*.json files remain unchanged. The reports contain checkpoint hashes, seeds and configuration, but do not record source-code commit IDs. Original training-code revisions are therefore unspecified.

portable-checkpoints.json records the original and portable hashes, the path-only transformation and the source revisions used for compatibility checks. All checkpoint contents other than graph and config.train.graph are verified unchanged. The historical reports retain the original checkpoint hashes; a newly run report will identify the portable export's hash.

The v3b baseline matches the SHA-256 recorded in its historical suite report. The v6 baseline was recovered from the local artifact path named by its report, which did not record a baseline hash; its newly computed hash is documented without claiming historical hash verification.

The code/checkpoint release is MIT. The shared graph is a derived subgraph of the Janelia male CNS connectome v1.0; see the base model's data attribution.