Publish full-brain CUDA odor gain and recovery experiment

docs/development-goal.md

@@ -7,11 +7,13 @@ real optional CUDA support, reusable demo kits and a more open architecture.
 The current design proposal is [RFC 0001](rfcs/0001-open-runtime-and-demo-kits.zh-CN.md).
 RFC signatures remain proposals unless listed in the current API guide.
 Implemented slices now include the open Python API, real model, JS CPU circuit
-lab, standalone HTML templates and verified browser-to-Python replay. CUDA,
-additional engine adapters, streaming audio and learning remain open.
+lab, standalone HTML templates and verified browser-to-Python replay. Current source
+also contains actual-device-tested CUDA and Godot. Additional engine adapters,
+streaming audio and validated biological learning remain future work.
 The live browser game now shares the JS CPU core and is checked against Python feedback.
 Basic composable sessions, recorded dodge/sonification kits and full feedback replay
-are implemented; CUDA remains a separate draft awaiting hardware validation.
+are implemented. CUDA passed actual A16 validation and merged into main, while
+the last tagged release (v0.4.0a4) remains CPU-only.
 
 Acceptance criteria:
 
@@ -46,4 +48,15 @@ checkpoints. Headless conformance covers toy and real models. Native macOS run/p
 save/restore, file-dialog cancellation and disconnect/reset checks passed on
 2026-09-11. See its README for usage and verification.
 
-Current evidence and remaining release gates: [delivery audit](completion-audit-2026-09-10.md).
+User steering also requested the full FlyWire graph on GPU in a voxel food-odor
+environment. [That recorded experiment](validation/flywire-voxel-a16.md) now exists:
+all 139,255 neurons and source rows, sensory input, a fixed motor readout, a silenced
+control and exact joint checkpoint replay. Movement occurs but food contact does
+not. A recorded negative outcome is not evidence of learned or reliable foraging.
+
+The [historical delivery audit](completion-audit-2026-09-10.md) predates CUDA
+validation. Current evidence is in [CUDA](cuda.md), [full-brain validation](fullbrain-validation.md)
+and [synaptic dynamics](synaptic-dynamics.md). The remaining delivery gate is an
+integrated release with final packaging, clean-install and public-site verification.
+The [odor gain pilot](odor-calibration-pilot.md) is a separately documented research
+experiment, not a substitute for that release gate.

docs/odor-calibration-pilot.md

@@ -0,0 +1,84 @@
+# Full-brain odor gain pilot: protocol before results
+
+**Executed on A16 on 2026-09-13:** [all eight results and hardware evidence](validation/odor-gain-pilot-a16.md).
+The protocol below was published in commit
+`433c77f6c6da3b25c10996847b788d0bca871b4d` before execution and was not changed
+in response to the results. No gain or behavioral default was selected.
+
+This protocol tests whether changing recurrent contact strength alters transient
+side responses and post-stimulus spiking in the experimental synaptic engine.
+It does **not** test banana identification, flight, learning or food seeking.
+There is no environment, fitted action decoder or target position in this pilot.
+The source commit should be published before the GPU run; publish every result,
+including non-responsive, persistently active or failed conditions.
+
+## Why this experiment
+
+The [previous full-brain odor experiment](validation/flywire-synaptic-odor-a16.md)
+showed a cumulative left DNa02 bias under either stimulus side. Its time series
+also contains an early right DNa02 response to right input. The
+[post-stimulus counts](validation/synaptic-post-stimulus.json) show actual new
+downstream spikes during the observed recovery window. Cumulative counts alone
+hide timing; an exponentially smoothed rate alone cannot prove continued firing.
+
+## Fixed design
+
+- All 139,255 FlyWire v783 neurons and all 16,847,997 source aggregate edges.
+  The official source files and annotation mapping must pass their pinned checksums.
+  No edge pruning, incoming normalization, added background drive or rescue reflex.
+- Four contact strengths: **0.05, 0.10, 0.175, 0.275 mV/contact**. Excitatory and
+  inhibitory contacts scale together. These are exploratory values, not measured
+  biological parameters. All other [synaptic settings](synaptic-dynamics.md) stay fixed.
+- Each strength uses both **left → right** and **right → left** input order,
+  making eight runs. JSON state is restored only between runs.
+- Each run: 50 ms silent baseline → 150 ms first odor → 200 ms recovery →
+  150 ms other-side odor → 250 ms recovery. No state reset between these phases.
+- Fixed `dt = 0.1 ms`, seed `20260914`, NumPy PCG64. Both sides' random draws are
+  consumed at every tick, even if their input is disabled, preserving matched
+  per-neuron input sequences across gains and orders. Left/right populations have
+  different sizes and independently sampled events; they are not identical copies.
+- Only the pinned 35 left and 33 right DM1 ORNs receive input. Bernoulli probability
+  is `150 Hz × dt / 1000`; each event supplies a 68.75 mV input jump. This jump
+  **does not scale with recurrent contact strength**. The physiological accuracy
+  of this single-channel odor adapter has not been established.
+
+## Prespecified measurements
+
+Each phase records actual per-neuron spike totals, first-50-ms counts, group totals,
+and group spike counts in its last 100 ms (the initial rest is only 50 ms).
+An additional 10 ms trace records smoothed mean rates for visualization.
+
+For each stimulus, report DNa02 **ipsilateral minus contralateral** firing rate
+separately for the first 50 ms and the remaining 100 ms, plus cumulative
+right-minus-left spike count. The pinned mapping contains one DNa02 cell per side.
+Positive ipsilateral difference is descriptive; it is not an established action
+label. Compare the same side when presented first versus second.
+
+For each recovery, report **new spikes** in its final 100 ms in DM1 ORNs, ALPNs,
+MBONs, descending neurons and DNa02. A quiet finite window does not establish
+long-term stability; persistent activity alone does not establish memory.
+
+Report all four strengths and both orders without choosing a winner automatically.
+A candidate from this one-seed pilot requires independently specified multiple-seed
+and held-out stimulus validation before changing a public behavioral preset.
+Changing the gain must not be described as restoring validated biological behavior.
+
+## Reproduce on an actual GPU
+
+Install the repository with dataset support, pytest and a compatible CuPy CUDA
+installation, and download the same pinned data files used by the
+[full-brain odor experiment](validation/flywire-synaptic-odor-a16.md).
+
+```sh
+python scripts/validate_synaptic_cuda.py --output results/hardware-gate.json
+python scripts/calibrate_fullbrain_odor.py \
+  --data-dir data --annotations data/annotations.tsv \
+  --output results/odor-gain-pilot.json
+FLYBRAIN_REQUIRE_CUDA=1 python -m pytest -q
+```
+
+The hardware gate must report five executed passing GPU cases and zero skips.
+There is no CPU fallback in this experiment. Retain the full output JSON, hardware
+report, test results, source hashes and dependency versions. Incomplete JSON is
+marked `running` or `failed`; only all eight finished runs may be `completed`.
+The ordinary CPU SDK remains usable without CUDA.

docs/olfactory-experiment.md

@@ -1,7 +1,12 @@
 # Full-brain food-odor experiment
 
-**GPU probe completed; navigation not demonstrated.**
-See the [negative result and parameter diagnosis](validation/flywire-odor-a16.md). The full FlyWire graph has
+**Two GPU probes completed with different dynamics; navigation not demonstrated.**
+The historical dimensionless benchmark could not propagate sensory-only input;
+see its [negative result and parameter diagnosis](validation/flywire-odor-a16.md).
+The separate [synaptic mV probe](validation/flywire-synaptic-odor-a16.md) did produce
+ALPN, MBON and descending spikes. Its [voxel recording](validation/flywire-voxel-a16.md)
+shows movement but no food contact. Do not transfer a result between these presets.
+The full FlyWire graph has
 passed the [CUDA numerical benchmark](fullbrain-validation.md). This experiment
 adds anatomically identified sensory input. It does not establish that the fly
 recognizes a banana, seeks food, or flies. No CUDA is needed to build the mapping,
@@ -32,7 +37,7 @@ member participates in this particular odor response.
 
 ## Reproduce the mapping and GPU probe
 
-Start with the CUDA development branch and the full-brain data/environment
+Use a pinned repository commit containing the CUDA engines and the full-brain data/environment
 instructions in [fullbrain-validation.md](fullbrain-validation.md). Download the
 annotation file into your experiment folder, outside the repository:
 
@@ -61,6 +66,10 @@ separate source/license metadata in the full-brain data instructions.
 
 ## Sensory and world assumptions
 
+The following `OlfactoryDrive` adapter and `probe_fullbrain_odor.py` command describe
+the **historical dimensionless engine**. They are not the mV input used in the
+newer GPU recording.
+
 `flybrain.olfaction.OlfactoryDrive` takes two local antenna concentration samples.
 It injects only the selected sensory neurons. It receives no banana coordinates,
 target bearing, desired turn or reward. Its stateless response is
@@ -71,15 +80,30 @@ channels can be added explicitly by creating additional adapters and summing
 their vectors. There is intentionally no scientifically unqualified `banana`
 preset.
 
+For the **synaptic mV voxel experiment**, each antenna's dimensionless local sample
+is instead mapped to `rate_hz = 180 * concentration / (0.2 + concentration)`.
+At every 0.1 ms tick, each selected ORN independently receives an input event with
+probability `rate_hz * 0.1 / 1000`. Each event adds 68.75 mV to that input cell's
+membrane voltage under the [engine's documented update order](synaptic-dynamics.md).
+The 150 Hz fixed-input odor probe uses the same event mechanism. These rates and
+voltage jumps approximate receptor transduction; they are not measured banana
+dose-response curves. The generated events enter only the 68 selected ORNs,
+while all 139,255 neurons and source edges participate in the simulation.
+
 `sample_odor(antenna_xyz, source_xyz)` is a game-side isotropic Gaussian field.
 Sample it separately at each antenna. It models neither turbulent plumes nor
 obstacle-induced airflow. The body/world owns spatial coordinates; the neural
-controller receives concentrations only. The initial world will be a kinematic
+controller receives concentrations only. The recorded world uses a kinematic
 body in a voxel scene, not a reconstruction of flight musculature or a full
 ventral nerve cord. FlyWire v783 is a whole-brain dataset, not the whole animal's
 nervous system.
 
-## Falsifiable first gate
+## Falsifiable first gate and next calibration
+
+The five-condition gate below was run for both engines. The
+[prespecified gain pilot](odor-calibration-pilot.md) now asks how recurrent strength
+affects transient side responses, later bias and recovery, before selecting a
+behavioral preset. Its design is separate from the completed five-condition results.
 
 Five conditions reset to the identical resting checkpoint: no odor, left odor,
 right odor, bilateral odor, and bilateral odor with the 68 ORNs silenced. Each

docs/roadmap.md

@@ -1,5 +1,23 @@
 # Roadmap
 
+## Verified in current source; next release pending
+
+- Optional CUDA backend passed actual NVIDIA A16 conformance checks. CPU remains
+  the default and does not require CuPy. See [CUDA evidence](cuda.md).
+- Full FlyWire v783 numerical benchmark: all 139,255 neurons and source edges,
+  CPU/GPU comparison, checkpoint replay and stability measurement. Not real time.
+- Separate synaptic mV engine matches an independent Brian2 oracle and actual
+  GPU tests. Sensory-only input reaches downstream groups; biological behavior
+  is not established. See [synaptic dynamics](synaptic-dynamics.md).
+- Full-brain GPU voxel recording with an input-silenced control and paired
+  brain/world/input-RNG replay. The untrained readout moves but does not reach food.
+- [Odor gain pilot protocol](odor-calibration-pilot.md) separates transient side
+  responses from persistent activity before further behavioral calibration.
+
+The released v0.4.0a4 remains CPU-only. An integrated CUDA release still requires
+packaging and clean-install verification at its final release commit. Raw full-brain
+loading remains a research-script workflow, not a `FlyBrain.load()` catalog entry.
+
 ## Available in 0.4.0a4
 
 - Actual Godot 4 CPU scene, offline toy and optional real MaleCNS model.
@@ -29,7 +47,7 @@
 - [Integration guide](demo-kits.md) and a gallery with a silenced-output comparison.
 
 Still open: additional engine adapters, streaming audio and learned readouts.
-CUDA implementation is in a separate draft PR pending actual-device validation.
+CUDA subsequently passed actual-device validation; see the current-source section above.
 
 ## Available in 0.3.0a1
 
@@ -38,8 +56,8 @@ CUDA implementation is in a separate draft PR pending actual-device validation.
 - Standalone editable HTML export and browser command recordings replayed in Python.
 - [Browser guide](browser-lab.md) with exact semantics and current limitations.
 
-Next: optional CUDA tested on hardware, additional game adapters, then audio and
-rhythm demo kits sharing the open core. Browser WASM remains a separate backend.
+Later versions added Godot and audio demo kits; current source includes hardware-tested
+CUDA. Browser WASM remains a separate, unimplemented backend.
 
 ## Available in 0.2.0a1
 
@@ -49,7 +67,8 @@ rhythm demo kits sharing the open core. Browser WASM remains a separate backend.
 - The previous alpha API and schema-1 checkpoint reader remain supported.
 
 The circuit lab shipped in 0.3; basic game/audio sessions, the live game and Godot
-adapter shipped in 0.4. Streaming audio, trained rhythm templates and validated CUDA remain open. See [RFC 0001](rfcs/0001-open-runtime-and-demo-kits.zh-CN.md) for the
+adapter shipped in 0.4. Streaming audio and trained rhythm templates remain open.
+CUDA has since passed hardware checks. See [RFC 0001](rfcs/0001-open-runtime-and-demo-kits.zh-CN.md) for the
 proposed architecture; proposal-only APIs are not current API documentation.
 
 
@@ -73,7 +92,7 @@ proposed architecture; proposal-only APIs are not current API documentation.
 - Extend Godot, add Unity and richer game examples.
 - Compact sparse-array model/checkpoint format for large graphs.
 - WASM reference implementation and TypeScript package.
-- Optional CUDA backend, only after cross-backend conformance tests.
+- Publish the integrated optional CUDA release after clean-install checks.
 - Explore learning/plasticity separately from the fixed-connectome MVP.
 
 Open issues and propose focused milestones; these are directions, not release-date promises.

docs/synaptic-dynamics.md

@@ -11,6 +11,10 @@ it is not yet exposed by `FlyBrain.load()` or a model catalog entry. It requires
 explicit millivolt weights and rejects dimensionless weight units. The original
 benchmark is retained as a reproducible historical numerical test.
 
+The [completed odor gain pilot](validation/odor-gain-pilot-a16.md) compares four contact
+strengths and both stimulus orders to separate early side responses from sustained
+bias and recovery spiking. All eight GPU runs completed; no behavioral preset was selected.
+
 ## Model and source
 
 Nominal equations and parameters follow [Shiu et al., Nature (2024)](https://www.nature.com/articles/s41586-024-07763-9)

docs/validation/odor-gain-cuda-a16.json

@@ -0,0 +1,25 @@
+{
+  "status": "passed",
+  "python": "3.12.3",
+  "source_sha256": {
+    "src/flybrain/experimental/__init__.py": "570d34f551fd63b33bff564c022ad01fc463b0e1649d9f7035e361b421533bd5",
+    "src/flybrain/experimental/synaptic.py": "4c3b7b48e659314a1dd839819ddce4bdd1622d21dd8753400035c1df8deaa726",
+    "src/flybrain/experimental/synaptic_cuda.py": "8b0bc40f8bf0075e6d81caadf3393673110aa48b66415303a08020cb9055dfa8",
+    "src/flybrain/experimental/voxel_arena.py": "d358df33830ca4d96fe8c5c8549cef383760213d00f8e153f64e2b9c5e7484b3",
+    "tests/test_synaptic_cuda_hardware.py": "70761bdbb7cbd4fdaa82ea85b40494a84fb532d9d6af350449aa33e46219bb1e",
+    "scripts/validate_synaptic_cuda.py": "7f51e7147d8c51d879a663e85841077197196851648e780d05fb86eceaf13c80"
+  },
+  "device": {
+    "name": "NVIDIA A16-8Q",
+    "cupy": "14.2.0",
+    "memory_bytes": 8394047488,
+    "driver": 12040,
+    "runtime": 12090
+  },
+  "cases": {
+    "tests": 5,
+    "skipped": 0,
+    "errors": 0,
+    "failures": 0
+  }
+}

docs/validation/odor-gain-gpu-active.csv

@@ -0,0 +1,2 @@
+timestamp, name, utilization.gpu [%], memory.used [MiB], memory.total [MiB]
+2026/09/13 04:03:01.738, NVIDIA A16-8Q, 87 %, 289 MiB, 8192 MiB