README.md

---
license: cc-by-nc-4.0
tags:
- pong
- spiking-neural-network
- connectome
- drosophila
- rsnn
---

# CentralComplex_Pong v1

Synaptic weights for the Pong game of **[BeatTheFly](https://phclab.github.io/BeatTheFly/pong/)** -- *A Smart Fruit Fly is playing Pong against you*:
a spiking network wired as the real *Drosophila* central complex connectome that moves a Pong paddle in real time.

**The anatomical connectome gives you wiring, not synaptic strengths. Ours are trained.**

Synaptic weights trained with PHCSSM parallel-scan mode, deployment in sequential RSNN mode ([PHCSSM](https://arxiv.org/abs/2604.01295)).

made by Po-Han Chiang @ NYCU

## What the central complex does in the fly
The central complex is the fly's navigation and steering centre: it keeps track of heading and turns it into steering commands. Its plasticity gate is driven by 123 neuromodulatory cells — dopamine, serotonin and octopamine — over 793 real synapses, and what they write into the fast weight fades within about two frames. In the real fly, the central complex keeps track of heading with a ring-shaped “internal compass”, integrates the path travelled, and steers where the fly goes next.

## Architecture
* **Wiring:** MaleCNS v1.0 central complex -- 2,950 neurons (Ring neurons (ER, ExR) 308; PFN columnar neurons 456; PFL output neurons 50; Other central-complex neurons 2,136) and 439,500
  neuron-to-neuron connections. The connectivity mask is fixed to the connectome; 360,336 connections
  carry a nonzero weight and 0 weights lie off the connectome.
* **Dale's law:** one sign per presynaptic neuron from predicted neurotransmitters (excitatory 1,873,
  inhibitory 918, modulatory 159); 0 weights violate it.
* **Input:** each frame provides 6 numbers seen from the fly's side of the court: the ball's position and
  velocity and the positions of both paddles. A linear encoder with LayerNorm drives only the input population:
  764 ER ring (landmark/visual) + PFN (self-motion via NO) + ExR.
* **Neurons:** leaky integrate-and-fire with per-neuron leak, threshold and reset; synaptic delay of one step.
* **Readout:** linear map from the membrane voltage of the output population only, 50 PFL1/2/3 (steering -> LAL),
  to 3 paddle commands (stay, up, down).
* **Neuromodulatory gate:** 123 of this region's own known-neuromodulator cells (dopamine+octopamine+serotonin) gate the
  current into the output population, masked to the 793 real gate-cell -> output synapses in the connectome.
* **Fast weight:** a value written onto the 1,556 real input -> output synapses, gated by the same cells, read
  back into the output neurons' voltages. It is read with the current frame's input spikes and written with the same
  frame's, and it decays: one trainable factor per output neuron, a decay time constant of about 1.80 frames (30.0 ms at 60 fps).
* **Deployment:** sequential RSNN mode, one timestep per frame at 60 frames per second, with the neuron state carried
  across the whole game.

## Data sources
Data source: actions of a scripted Pong player.

## Evaluation
20 games to 11 points against each scripted player, the fly playing its top command every frame:

| opponent | games won | point share | fly's return rate |
|---|---|---|---|
| a noisy scripted player | 11 / 20 | 0.520 | 88.2% |
| a weak scripted player | 20 / 20 | 0.880 | 91.9% |
| a perfect scripted player | 0 / 20 | 0.000 | 91.7% |

On 131,072 held-out frames the fly's choice matches the scripted player's action on 97.1% in sequential RSNN mode, and the parallel-scan and sequential modes choose the same action on 99.68% of frames.

## Files
* `manifest.json` -- every tensor (file, dtype, shape, bytes), the model scalars and a connectome audit.
* `info.json` -- neuron metadata used by the page (cell classes, hemispheres, soma coordinates).
* `selfcheck_<precision>.json` -- reference observations and logits that the page replays when it loads.
* `fp16/`, `fp32/` -- raw little-endian arrays.

Two precisions are listed in the manifest: `fp16w32` (default, 2.4 MB: float16 for the
readout matrix `dec_w`, float32 for the recurrent weights and all other tensors) and
`fp16` (1.7 MB, recurrent weights in float16 as well).

The recurrent weight matrix W[dst, src] is stored in CSC order by source neuron (`W_colptr`, `W_rowidx`, `W_vals`):
each step multiplies W by a sparse binary spike vector, so the engine visits only the columns of the neurons that
spiked. `in_idx` lists the input population and `out_idx` the output population. `enc_obs_T` [6, H] is the
observation encoder and `dec_w` [3, 50] is read against the output population's voltage.

| name | file | dtype | shape |
|---|---|---|---|
| `enc_obs_T` | `fp32/enc_obs_T.bin` | float32 | 6x2950 |
| `enc_obs_b` | `fp32/enc_obs_b.bin` | float32 | 2950 |
| `ln_obs_w` | `fp32/ln_obs_w.bin` | float32 | 2950 |
| `ln_obs_b` | `fp32/ln_obs_b.bin` | float32 | 2950 |
| `teach_T` | `fp32/teach_T.bin` | float32 | 6x123 |
| `teach_b` | `fp32/teach_b.bin` | float32 | 123 |
| `W_gate` | `fp32/W_gate.bin` | float32 | 50x123 |
| `W_val` | `fp32/W_val.bin` | float32 | 50x123 |
| `gate_idx` | `fp32/gate_idx.bin` | int32 | 123 |
| `fw_in` | `fp32/fw_in.bin` | int32 | 1556 |
| `fw_out` | `fp32/fw_out.bin` | int32 | 1556 |
| `gamma` | `fp32/gamma.bin` | float32 | 50 |
| `dec_w` | `fp16/dec_w.bin` | float16 | 3x50 |
| `dec_b` | `fp32/dec_b.bin` | float32 | 3 |
| `alpha_exc` | `fp32/alpha_exc.bin` | float32 | 2950 |
| `alpha_inh` | `fp32/alpha_inh.bin` | float32 | 2950 |
| `v_th` | `fp32/v_th.bin` | float32 | 2950 |
| `reset_weight` | `fp32/reset_weight.bin` | float32 | 2950 |
| `in_idx` | `fp32/in_idx.bin` | int32 | 764 |
| `out_idx` | `fp32/out_idx.bin` | int32 | 50 |
| `W_colptr` | `fp32/W_colptr.bin` | uint32 | 2951 |
| `W_rowidx` | `fp32/W_rowidx.bin` | uint16 | 360336 |
| `W_vals` | `fp32/W_vals.bin` | float32 | 360336 |

**Numerical check:** 0 of 27,281,600 spike bits differ from the reference on the same weights (2,048 held-out frames and a 7,200-frame closed-loop game).

## Limitations
The fly learned by copying a scripted player: it gets no reward and does not plan ahead. It has been tested only in
this simulator and only against scripted players, and it loses every game to a perfect one.

## License and attribution
Weights: [CC-BY-NC-4.0](https://creativecommons.org/licenses/by-nc/4.0/). They are derived from the MaleCNS v1.0 connectome (Janelia FlyEM and
collaborators, https://male-cns.janelia.org/, [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/)) and trained with PHCSSM (https://arxiv.org/abs/2604.01295);
please credit both.

## Citation
PHCSSM: https://arxiv.org/abs/2604.01295